| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 3 | 6 | 3 | 25% |
| Commands | 0 | 5 | 1 | 0% |
| Section tags | 6 | 2 | 1 | 67% |
What each file covers
Sections
3 shared · 6 only in A · 3 only in B- − GitHub Copilot Instructions — Second Brain
- − Project
- − Tech Stack
- − DO
- − DON'T
- − Monorepo Structure
- + Second Brain — Agent Instructions
- + Monorepo Map
- + Docs
- Conventions
- Commands
- Data Model
Commands
0 shared · 5 only in A · 1 only in B- − pnpm install
- − pnpm build
- − pnpm test
- − pnpm check-types
- − pnpm dev
- + pnpm install / build / test / check-types / lint / dev / clean
Section tags
6 shared · 2 only in A · 1 only in B- − architecture
- − do-not
- + docs
- setup
- test
- code-style
- types
- monorepo
- agent-behaviour
Line diff
thangaram611/second-brain · .github/copilot-instructions.md
@@ −1 @@
1# GitHub Copilot Instructions — Second Brain
2
3## Project
4
5Developer knowledge graph — pnpm monorepo with Turborepo. Node.js 22+, TypeScript 5.8+ strict mode, ESM only.
6
7For full architecture details, see [docs/architecture.md](../docs/architecture.md).
8For agent-level instructions, see [AGENTS.md](../AGENTS.md).
9
10## Tech Stack
11
12- **Runtime**: Node.js 22+, ESM modules only (`"type": "module"`)
13- **Language**: TypeScript 5.8+ (strict mode, explicit return types, no `any`)
14- **Database**: SQLite via better-sqlite3 + Drizzle ORM, WAL mode
15- **Search**: FTS5 (BM25) + sqlite-vec (cosine KNN), fused via Reciprocal Rank Fusion
16- **Validation**: Zod v4 for all external inputs
17- **Testing**: Vitest with in-memory SQLite (`:memory:`), globals enabled
18- **Build**: tsdown (ESM bundler), tsc (type-check only)
19- **Frontend**: React 19, Zustand, Cytoscape.js, Tailwind CSS, Radix UI
20- **Sync**: Yjs CRDTs via Hocuspocus relay
21- **IDs**: ULIDs (via ulidx). Never UUID
22- **Timestamps**: ISO 8601 strings. Never unix timestamps
23
24## Conventions
25
26### DO
27- Use named exports, re-export from package index.ts
28- Use workspace imports: `@second-brain/core`, `@second-brain/types`
29- Use Zod schemas for request validation in routes
30- Write tests with Vitest using in-memory SQLite
31- Use `batchUpsert` for bulk operations (merges observations/tags on conflict)
32- Keep observations as atomic, concise facts (string arrays)
33- Use try-catch with descriptive error messages
34
35### DON'T
36- Use path aliases (rely on workspace resolution)
37- Use `any` type
38- Import from package internals (use public API via index.ts)
39- Use UUIDs (use ULIDs from ulidx)
40- Use Date objects or unix timestamps in storage
41- Manually write to entities_fts table (auto-maintained via triggers)
42- Sync the 'personal' namespace
43- Mutate stored confidence values (decay is read-side only)
44
45## Monorepo Structure
46
47```
48packages/types — Shared TypeScript types
49packages/core — Knowledge graph engine (Brain class)
50packages/collectors — Data collectors + streaming providers
51packages/ingestion — LLM extraction + embedding pipeline
52packages/sync — Yjs CRDT sync bridge
53packages/mcp-server — MCP tools (32 tools, stdio + HTTP)
54apps/server — Express 5 REST API + WebSocket (port 7430)
55apps/ui — React 19 + Cytoscape.js web app (port 5173)
56apps/relay — Hocuspocus CRDT relay (port 7421)
57tools/cli — brain CLI (Commander.js)
58```
59
60## Commands
61
62```bash
63pnpm install # Install dependencies
64pnpm build # Build all packages
65pnpm test # Run all tests
66pnpm check-types # Type-check everything
67pnpm dev # Start dev servers
68```
69
70## Data Model
71
72- **Entity types** (15): concept, decision, pattern, person, file, symbol, event, tool, fact, conversation, reference, implementation, pull_request, merge_request, branch
73- **Relation types** (20): 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
74- Every entity/relation has a `namespace` field
75- Bitemporal: eventTime + ingestTime
76- Confidence with time-based decay (read-side only)
77
thangaram611/second-brain · AGENTS.md
@@ +1 @@
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
@@ −1 +1 @@
1−# GitHub Copilot Instructions — Second Brain
1+# Second Brain — Agent Instructions
22
3−## Project
3+Developer 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.
44
5−Developer knowledge graph — pnpm monorepo with Turborepo. Node.js 22+, TypeScript 5.8+ strict mode, ESM only.
5+Each package/app has its own AGENTS.md with package-specific instructions.
66
7−For full architecture details, see [docs/architecture.md](../docs/architecture.md).
8−For agent-level instructions, see [AGENTS.md](../AGENTS.md).
7+## Monorepo Map
98
10−## Tech Stack
11−
12−- **Runtime**: Node.js 22+, ESM modules only (`"type": "module"`)
13−- **Language**: TypeScript 5.8+ (strict mode, explicit return types, no `any`)
14−- **Database**: SQLite via better-sqlite3 + Drizzle ORM, WAL mode
15−- **Search**: FTS5 (BM25) + sqlite-vec (cosine KNN), fused via Reciprocal Rank Fusion
16−- **Validation**: Zod v4 for all external inputs
17−- **Testing**: Vitest with in-memory SQLite (`:memory:`), globals enabled
18−- **Build**: tsdown (ESM bundler), tsc (type-check only)
19−- **Frontend**: React 19, Zustand, Cytoscape.js, Tailwind CSS, Radix UI
20−- **Sync**: Yjs CRDTs via Hocuspocus relay
21−- **IDs**: ULIDs (via ulidx). Never UUID
22−- **Timestamps**: ISO 8601 strings. Never unix timestamps
23−
24−## Conventions
25−
26−### DO
27−- Use named exports, re-export from package index.ts
28−- Use workspace imports: `@second-brain/core`, `@second-brain/types`
29−- Use Zod schemas for request validation in routes
30−- Write tests with Vitest using in-memory SQLite
31−- Use `batchUpsert` for bulk operations (merges observations/tags on conflict)
32−- Keep observations as atomic, concise facts (string arrays)
33−- Use try-catch with descriptive error messages
34−
35−### DON'T
36−- Use path aliases (rely on workspace resolution)
37−- Use `any` type
38−- Import from package internals (use public API via index.ts)
39−- Use UUIDs (use ULIDs from ulidx)
40−- Use Date objects or unix timestamps in storage
41−- Manually write to entities_fts table (auto-maintained via triggers)
42−- Sync the 'personal' namespace
43−- Mutate stored confidence values (decay is read-side only)
44−
45−## Monorepo Structure
46−
479 ```
48−packages/types — Shared TypeScript types
49−packages/core — Knowledge graph engine (Brain class)
50−packages/collectors — Data collectors + streaming providers
51−packages/ingestion — LLM extraction + embedding pipeline
52−packages/sync — Yjs CRDT sync bridge
53−packages/mcp-server — MCP tools (32 tools, stdio + HTTP)
54−apps/server — Express 5 REST API + WebSocket (port 7430)
55−apps/ui — React 19 + Cytoscape.js web app (port 5173)
56−apps/relay — Hocuspocus CRDT relay (port 7421)
57−tools/cli — brain CLI (Commander.js)
10+packages/types → Shared TS types
11+packages/core → Graph engine (SQLite + Drizzle + FTS5 + sqlite-vec)
12+packages/collectors → Data collectors + streaming providers
13+packages/ingestion → LLM extraction + embedding pipeline
14+packages/sync → Yjs CRDT sync bridge
15+packages/mcp-server → MCP tools (32 tools, stdio + HTTP)
16+apps/server → Express 5 REST + WebSocket (:7430)
17+apps/ui → React 19 + Cytoscape.js + Zustand (:5173)
18+apps/relay → Hocuspocus CRDT relay (:7421)
19+tools/cli → brain CLI (Commander.js)
5820 ```
5921
6022 ## Commands
6123
6224 ```bash
63−pnpm install # Install dependencies
64−pnpm build # Build all packages
65−pnpm test # Run all tests
66−pnpm check-types # Type-check everything
67−pnpm dev # Start dev servers
25+pnpm install / build / test / check-types / lint / dev / clean
6826 ```
6927
28+Per-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+
7043 ## Data Model
7144
72−- **Entity types** (15): concept, decision, pattern, person, file, symbol, event, tool, fact, conversation, reference, implementation, pull_request, merge_request, branch
73−- **Relation types** (20): 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
74−- Every entity/relation has a `namespace` field
75−- Bitemporal: eventTime + ingestTime
76−- Confidence with time-based decay (read-side only)
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+
48+Defined 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
7755
