AGENTS.md

1# @second-brain/sync — Agent Instructions
2 
3Yjs CRDT sync layer for real-time collaborative knowledge graphs.
4 
5## Entry Point
6 
7`src/sync-manager.ts` → `SyncManager` coordinates sync state.
8 
9## Key Files
10 
11| File | Purpose |
12|------|---------|
13| `src/sync-manager.ts` | Main sync orchestrator |
14| `src/crdt/` | Yjs document bridge (entity ↔ Y.Map) |
15| `src/provider/` | Sync transport providers |
16| `src/relay/` | Relay server helpers |
17 
18## Architecture
19 
20- Uses **Yjs** CRDTs for conflict-free merging
21- Bridge converts between `Entity`/`Relation` objects and Yjs documents
22- Each namespace gets its own Yjs document
23- **`'personal'` namespace is never synced** — stays local only
24- JWT auth for relay connections
25- `.ystate` files for persistence
26 
27## Conventions
28 
29- Namespace isolation: one Yjs doc per namespace
30- Session namespaces use `'session:<id>'` prefix
31- File-based persistence via `.ystate` directory
32