AGENTS.md

1# Second Brain — Agent Instructions
2 
3Developer knowledge graph — shared engineering memory for teams ("git remembers the code; Second Brain remembers why"). pnpm monorepo, Turborepo, Node.js 24+, TypeScript 5.8+ strict, ESM only.
4 
5Each package/app has its own AGENTS.md with package-specific instructions.
6 
7## Monorepo Map
8 
9```
10packages/types      → Shared TS types
11packages/core       → Graph engine (SQLite + Drizzle + FTS5 + sqlite-vec)
12packages/collectors → Data collectors + streaming providers
13packages/ingestion  → LLM extraction + embedding pipeline
14packages/sync       → Yjs CRDT sync bridge
15packages/mcp-server → MCP tools (32 tools, stdio + HTTP)
16apps/server         → Express 5 REST + WebSocket (:7430)
17apps/ui             → React 19 + Cytoscape.js + Zustand (:5173)
18apps/relay          → Hocuspocus CRDT relay (:7421)
19tools/cli           → brain CLI (Commander.js)
20```
21 
22## Commands
23 
24```bash
25pnpm install / build / test / check-types / lint / dev / clean
26```
27 
28Per-package: `cd <pkg> && pnpm test|build|dev`
29 
30## Conventions
31 
32- ESM only (`"type": "module"`), `.mjs`/`.d.mts` output, `tsdown` for builds
33- ULIDs via `ulidx` for IDs — never UUID
34- ISO 8601 strings for timestamps — never unix/Date
35- SQLite (better-sqlite3) + Drizzle ORM, WAL mode
36- Zod v4 for external input validation
37- Namespace on all entities/relations: `'personal'` = local, project ID = synced
38- Vitest + in-memory SQLite (`:memory:`) for tests
39- Named exports, re-export from package `index.ts`
40- Workspace imports (`@second-brain/core`, `@second-brain/types`)
41- Strict mode, no `any`, no path aliases
42 
43## Data Model
44 
45- **15 entity types**: concept, decision, pattern, person, file, symbol, event, tool, fact, conversation, reference, pull_request, merge_request, branch, review
46- **20 relation types**: relates_to, depends_on, implements, supersedes, contradicts, derived_from, authored_by, decided_in, uses, tests, contains, co_changes_with, preceded_by, blocks, reviewed_by, merged_in_mr, merged_in_pr, touches_file, owns, parallel_with
47 
48Defined in `packages/types/src/entity.ts` and `packages/types/src/relation.ts`.
49 
50## Docs
51 
52- [docs/architecture.md](./docs/architecture.md) — Full technical architecture
53- [docs/getting-started.md](./docs/getting-started.md) — Usage guide
54- [docs/api-reference.md](./docs/api-reference.md) — REST API + MCP + CLI reference
55