| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 3 | 6 | 10 | 16% |
| Commands | 0 | 5 | 0 | 0% |
| Section tags | 7 | 1 | 1 | 78% |
What each file covers
Sections
3 shared · 6 only in A · 10 only in B- − GitHub Copilot Instructions — Second Brain
- − Project
- − Conventions
- − DO
- − DON'T
- − Monorepo Structure
- + Second Brain — Windsurf Rules
- + Project Overview
- + Monorepo
- + Coding Rules
- + Always
- + Never
- + Backend Patterns
- + Frontend Patterns
- + Testing
- + Documentation
- Tech Stack
- Commands
- Data Model
Commands
0 shared · 5 only in A · 0 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- − agent-behaviour
- + docs
- setup
- test
- code-style
- architecture
- types
- monorepo
- do-not
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 · .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
@@ −1 +1 @@
1−# GitHub Copilot Instructions — Second Brain
1+# Second Brain — Windsurf Rules
22
3−## Project
3+## Project Overview
44
55 Developer knowledge graph — pnpm monorepo with Turborepo. Node.js 22+, TypeScript 5.8+ strict mode, ESM only.
66
7−For full architecture details, see [docs/architecture.md](../docs/architecture.md).
8−For agent-level instructions, see [AGENTS.md](../AGENTS.md).
7+For full architecture: see docs/architecture.md
8+For agent instructions: see AGENTS.md
99
1010 ## Tech Stack
1111
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
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
2323
24−## Conventions
24+## Monorepo
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−```
4826 packages/types — Shared TypeScript types
49−packages/core — Knowledge graph engine (Brain class)
27+packages/core — Knowledge graph engine (Brain class in src/brain.ts)
5028 packages/collectors — Data collectors + streaming providers
5129 packages/ingestion — LLM extraction + embedding pipeline
5230 packages/sync — Yjs CRDT sync bridge
5331 packages/mcp-server — MCP tools (32 tools, stdio + HTTP)
5432 apps/server — Express 5 REST API + WebSocket (port 7430)
55−apps/ui — React 19 + Cytoscape.js web app (port 5173)
33+apps/ui — React 19 + Cytoscape.js (port 5173)
5634 apps/relay — Hocuspocus CRDT relay (port 7421)
5735 tools/cli — brain CLI (Commander.js)
58−```
5936
6037 ## Commands
6138
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−```
39+pnpm install, pnpm build, pnpm test, pnpm check-types, pnpm dev
6940
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+
7091 ## Data Model
7192
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)
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
77103
