AGENTS.md

1# @second-brain/core — Agent Instructions
2 
3Knowledge graph engine. SQLite + Drizzle ORM + FTS5 + sqlite-vec.
4 
5## Entry Point
6 
7`src/brain.ts` → `Brain` class — the single facade for all operations.
8 
9## Key Classes
10 
11| Class | File | Responsibility |
12|-------|------|---------------|
13| `Brain` | `src/brain.ts` | Top-level facade wrapping all managers |
14| `EntityManager` | `src/storage/` | CRUD for entities (ULID generation) |
15| `RelationManager` | `src/storage/` | CRUD for relations (ULID generation) |
16| `GraphTraversal` | `src/graph/` | Path-finding, neighborhoods, connected components |
17| `SearchEngine` | `src/search/` | FTS5 full-text + sqlite-vec vector search |
18| `BitemporalQueries` | `src/temporal/` | Point-in-time and history queries |
19| `DecayEngine` | `src/temporal/` | Confidence decay (read-side only) |
20| `ContradictionDetector` | `src/temporal/` | Finds contradicting observations |
21| `EmbeddingStore` | `src/embeddings/` | Optional vector storage |
22 
23## Schema
24 
25Drizzle schema: `src/schema/entities.ts`
26SQLite initializer: `src/storage/schema-init.ts`
27 
28## Architecture Decisions
29 
30- **Confidence decay is read-side only** — never mutate stored values
31- **FTS5 triggers auto-maintain `entities_fts`** — never write to it directly
32- **Relations have unique constraint** on `(sourceId, targetId, type)`
33- **`batchUpsert`** merges observations/tags on conflict
34- **Vector search is opt-in** — pass `embeddingDimensions` to Brain constructor
35- **Sync never touches `'personal'` namespace**
36- **Session namespaces** use `'session:<id>'` prefix
37 
38## Testing
39 
40```bash
41pnpm test              # Run all core tests
42```
43 
44Tests use in-memory SQLite (`:memory:`). Instantiate `Brain` directly — no HTTP layer.
45