| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 3 | 10 | 6 | 16% |
| Commands | 0 | 0 | 5 | 0% |
| Section tags | 7 | 1 | 1 | 78% |
What each file covers
Sections
3 shared · 10 only in A · 6 only in B- − Second Brain — Windsurf Rules
- − Project Overview
- − Monorepo
- − Coding Rules
- − Always
- − Never
- − Backend Patterns
- − Frontend Patterns
- − Testing
- − Documentation
- + GitHub Copilot Instructions — Second Brain
- + Project
- + Conventions
- + DO
- + DON'T
- + Monorepo Structure
- Tech Stack
- Commands
- Data Model
Commands
0 shared · 0 only in A · 5 only in B- + pnpm install
- + pnpm build
- + pnpm test
- + pnpm check-types
- + pnpm dev
Section tags
7 shared · 1 only in A · 1 only in B- − docs
- + agent-behaviour
- setup
- test
- code-style
- architecture
- types
- monorepo
- do-not
Line diff
thangaram611/second-brain · .windsurfrules
@@ −1 @@
1# Second Brain — Windsurf Rules
2
3## Project Overview
4
5Developer knowledge graph — pnpm monorepo with Turborepo. Node.js 22+, TypeScript 5.8+ strict mode, ESM only.
6
7For full architecture: see docs/architecture.md
8For agent instructions: see AGENTS.md
9
10## Tech Stack
11
12- Runtime: Node.js 22+, ESM only ("type": "module")
13- Language: TypeScript 5.8+ strict mode
14- Database: SQLite (better-sqlite3) + Drizzle ORM, WAL mode
15- Search: FTS5 (BM25) + sqlite-vec (cosine KNN), Reciprocal Rank Fusion
16- Validation: Zod v4
17- Testing: Vitest, in-memory SQLite
18- Build: tsdown (ESM), tsc (type-check)
19- Frontend: React 19, Zustand, Cytoscape.js, Tailwind CSS, Radix UI
20- Sync: Yjs CRDTs via Hocuspocus relay
21- IDs: ULIDs (ulidx). Never UUID
22- Timestamps: ISO 8601 strings. Never unix timestamps
23
24## Monorepo
25
26packages/types — Shared TypeScript types
27packages/core — Knowledge graph engine (Brain class in src/brain.ts)
28packages/collectors — Data collectors + streaming providers
29packages/ingestion — LLM extraction + embedding pipeline
30packages/sync — Yjs CRDT sync bridge
31packages/mcp-server — MCP tools (32 tools, stdio + HTTP)
32apps/server — Express 5 REST API + WebSocket (port 7430)
33apps/ui — React 19 + Cytoscape.js (port 5173)
34apps/relay — Hocuspocus CRDT relay (port 7421)
35tools/cli — brain CLI (Commander.js)
36
37## Commands
38
39pnpm install, pnpm build, pnpm test, pnpm check-types, pnpm dev
40
41## Coding Rules
42
43### Always
44- ESM only. Named exports. Re-export from index.ts
45- Use workspace imports: @second-brain/core, @second-brain/types
46- Zod schemas for all external input validation
47- ULIDs for IDs (via ulidx)
48- ISO 8601 for timestamps
49- Namespace field on all entities/relations
50- In-memory SQLite for tests
51- Try-catch with descriptive errors
52- batchUpsert for bulk operations
53
54### Never
55- Use `any` type
56- Use path aliases
57- Use UUIDs
58- Use unix timestamps or Date objects in storage
59- Write to entities_fts directly (auto-maintained via triggers)
60- Mutate stored confidence (decay is read-side only)
61- Sync 'personal' namespace
62- Import from package internals (use public API)
63
64## Backend Patterns
65
66- Drizzle ORM for queries (schema in packages/core/src/schema/)
67- Brain class is main facade (packages/core/src/brain.ts)
68- Relations: unique constraint on (sourceId, targetId, type)
69- Use createOrGet for idempotent relations
70- WebSocket broadcast after mutations
71- MCP tools: packages/mcp-server/src/tools/
72
73## Frontend Patterns
74
75- React 19 functional components
76- Zustand stores (one per feature in apps/ui/src/store/)
77- Cytoscape.js with diff-based rendering
78- Tailwind dark theme (zinc-950 bg)
79- REST client: apps/ui/src/lib/api.ts
80- WebSocket: apps/ui/src/lib/ws.ts (auto-reconnect)
81- HashRouter (React Router 7)
82
83## Testing
84
85- Vitest with globals (no imports for describe/it/expect)
86- In-memory SQLite for all DB tests
87- Co-located: __tests__/*.test.ts
88- Use Brain class directly (not HTTP)
89- Test happy path + error cases
90
91## Data Model
92
93Entity types (15): concept, decision, pattern, person, file, symbol, event, tool, fact, conversation, reference, implementation, pull_request, merge_request, branch
94
95Relation 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
96
97## Documentation
98
99- docs/architecture.md — Full technical architecture
100- docs/getting-started.md — Usage guide
101- docs/api-reference.md — REST API + MCP + CLI reference
102- AGENTS.md — Detailed agent instructions
103
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
@@ −1 +1 @@
1−# Second Brain — Windsurf Rules
1+# GitHub Copilot Instructions — Second Brain
22
3−## Project Overview
3+## Project
44
55 Developer knowledge graph — pnpm monorepo with Turborepo. Node.js 22+, TypeScript 5.8+ strict mode, ESM only.
66
7−For full architecture: see docs/architecture.md
8−For agent instructions: see AGENTS.md
7+For full architecture details, see [docs/architecture.md](../docs/architecture.md).
8+For agent-level instructions, see [AGENTS.md](../AGENTS.md).
99
1010 ## Tech Stack
1111
12−- Runtime: Node.js 22+, ESM only ("type": "module")
13−- Language: TypeScript 5.8+ strict mode
14−- Database: SQLite (better-sqlite3) + Drizzle ORM, WAL mode
15−- Search: FTS5 (BM25) + sqlite-vec (cosine KNN), Reciprocal Rank Fusion
16−- Validation: Zod v4
17−- Testing: Vitest, in-memory SQLite
18−- Build: tsdown (ESM), tsc (type-check)
19−- Frontend: React 19, Zustand, Cytoscape.js, Tailwind CSS, Radix UI
20−- Sync: Yjs CRDTs via Hocuspocus relay
21−- IDs: ULIDs (ulidx). Never UUID
22−- Timestamps: ISO 8601 strings. Never unix timestamps
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
2323
24−## Monorepo
24+## Conventions
2525
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+```
2648 packages/types — Shared TypeScript types
27−packages/core — Knowledge graph engine (Brain class in src/brain.ts)
49+packages/core — Knowledge graph engine (Brain class)
2850 packages/collectors — Data collectors + streaming providers
2951 packages/ingestion — LLM extraction + embedding pipeline
3052 packages/sync — Yjs CRDT sync bridge
3153 packages/mcp-server — MCP tools (32 tools, stdio + HTTP)
3254 apps/server — Express 5 REST API + WebSocket (port 7430)
33−apps/ui — React 19 + Cytoscape.js (port 5173)
55+apps/ui — React 19 + Cytoscape.js web app (port 5173)
3456 apps/relay — Hocuspocus CRDT relay (port 7421)
3557 tools/cli — brain CLI (Commander.js)
58+```
3659
3760 ## Commands
3861
39−pnpm install, pnpm build, pnpm test, pnpm check-types, pnpm dev
62+```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
68+```
4069
41−## Coding Rules
42−
43−### Always
44−- ESM only. Named exports. Re-export from index.ts
45−- Use workspace imports: @second-brain/core, @second-brain/types
46−- Zod schemas for all external input validation
47−- ULIDs for IDs (via ulidx)
48−- ISO 8601 for timestamps
49−- Namespace field on all entities/relations
50−- In-memory SQLite for tests
51−- Try-catch with descriptive errors
52−- batchUpsert for bulk operations
53−
54−### Never
55−- Use `any` type
56−- Use path aliases
57−- Use UUIDs
58−- Use unix timestamps or Date objects in storage
59−- Write to entities_fts directly (auto-maintained via triggers)
60−- Mutate stored confidence (decay is read-side only)
61−- Sync 'personal' namespace
62−- Import from package internals (use public API)
63−
64−## Backend Patterns
65−
66−- Drizzle ORM for queries (schema in packages/core/src/schema/)
67−- Brain class is main facade (packages/core/src/brain.ts)
68−- Relations: unique constraint on (sourceId, targetId, type)
69−- Use createOrGet for idempotent relations
70−- WebSocket broadcast after mutations
71−- MCP tools: packages/mcp-server/src/tools/
72−
73−## Frontend Patterns
74−
75−- React 19 functional components
76−- Zustand stores (one per feature in apps/ui/src/store/)
77−- Cytoscape.js with diff-based rendering
78−- Tailwind dark theme (zinc-950 bg)
79−- REST client: apps/ui/src/lib/api.ts
80−- WebSocket: apps/ui/src/lib/ws.ts (auto-reconnect)
81−- HashRouter (React Router 7)
82−
83−## Testing
84−
85−- Vitest with globals (no imports for describe/it/expect)
86−- In-memory SQLite for all DB tests
87−- Co-located: __tests__/*.test.ts
88−- Use Brain class directly (not HTTP)
89−- Test happy path + error cases
90−
9170 ## Data Model
9271
93−Entity types (15): concept, decision, pattern, person, file, symbol, event, tool, fact, conversation, reference, implementation, pull_request, merge_request, branch
94−
95−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
96−
97−## Documentation
98−
99−- docs/architecture.md — Full technical architecture
100−- docs/getting-started.md — Usage guide
101−- docs/api-reference.md — REST API + MCP + CLI reference
102−- AGENTS.md — Detailed agent instructions
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)
10377
