macro-agent 0.1.1 → 0.1.2

package/references/minimem/.sudocode/specs.jsonl

@@ -0,0 +1 @@
+{"id":"s-2wx5","uuid":"f2e6f765-0ff1-40ee-b93c-4ea832231e94","title":"Git Sync System for Memory Directories","file_path":"specs/s-2wx5_git_sync_system_for_memory_directories.md","content":"# Git Sync System for Memory Directories\n\n## Context\n\nminimem stores memories as plain Markdown files which are inherently git-friendly. However, users need a way to sync memories across machines and collaborate with others. The SQLite database with embeddings is **not** the source of truth and should never be committed—it's rebuilt locally via `minimem sync`.\n\nUsers have two distinct use cases:\n1. **Project-bound memories** - embedded directly in code repos alongside source code\n2. **Standalone memories** - scattered directories that should sync to a central repository\n3. **Hybrid** - project memories that are ALSO synced to a central repo for aggregation\n\n## Out of Scope\n\n- Real-time collaborative editing (not Google Docs)\n- Full git client replacement (we use git, not replace it)\n- Remote repository hosting (user provides their own)\n- Encryption at rest (use git-crypt or similar if needed)\n\n## Requirements\n\n### Must Have\n\n- [ ] CLI commands to configure sync mappings between local directories and central repo paths\n- [ ] Auto-detection of directory type (project-bound, standalone, hybrid)\n- [ ] Push/pull commands to sync directories with central repo\n- [ ] Configurable merge resolution strategies\n- [ ] Support for multiple directories syncing to one central repo\n- [ ] Path collision validation on init\n- [ ] Graceful sync failure recovery with atomic operations\n\n### Should Have\n\n- [ ] Daemon for automatic sync with file watching\n- [ ] Git hooks integration in central repo (post-pull triggers local sync)\n- [ ] Merge resolver hook for custom conflict resolution tools\n- [ ] Sync state registry in central repo to detect collisions\n\n### Nice to Have\n\n- [ ] Integration with MCP server (daemon runs alongside)\n- [ ] Periodic sync fallback when file watching unavailable\n- [ ] Status command showing sync state across all configured directories\n\n## Design\n\n### Directory Types\n\n| Type | Detection | Git Management | Sync Behavior |\n|------|-----------|----------------|---------------|\n| **Project-bound** | Inside git repo, no sync config | User handles git | No sync |\n| **Standalone** | Has sync config, not in project git | minimem manages | Full sync |\n| **Hybrid** | Inside git repo AND has sync config | User handles project git | Also syncs to central |\n| **Unmanaged** | No git repo, no sync config | None | Prompt to set up |\n\n### Auto-Detection Logic\n\n```\nIs there a sync config in .minimem/config.json?\n├─ Yes: \n│   └─ Is directory inside a git repo?\n│       ├─ Yes → Hybrid (user manages project git, minimem syncs to central)\n│       └─ No  → Standalone (minimem manages sync)\n└─ No:\n    └─ Is directory inside a git repo?\n        ├─ Yes → Project-bound (user manages everything)\n        └─ No  → Unmanaged (prompt to set up sync?)\n```\n\n### Configuration\n\n**Global config** (`~/.config/minimem/config.json`):\n```json\n{\n  \"centralRepo\": \"~/memories-repo\",\n  \"sync\": {\n    \"conflictStrategy\": \"keep-both\",\n    \"autoSync\": true,\n    \"autoCommit\": false\n  }\n}\n```\n\n**Per-directory config** (`.minimem/config.json`):\n```json\n{\n  \"sync\": {\n    \"enabled\": true,\n    \"path\": \"global/\",\n    \"include\": [\"MEMORY.md\", \"memory/**/*.md\"],\n    \"exclude\": [\"memory/drafts/**\"]\n  }\n}\n```\n\n**Default sync scope:** `MEMORY.md` + `memory/**/*.md`\n\n### Central Repo Registry\n\nThe central repo maintains a registry to prevent path collisions:\n\n**`.minimem-registry.json`** (in central repo root):\n```json\n{\n  \"mappings\": [\n    {\n      \"path\": \"global/\",\n      \"localPath\": \"~/.minimem\",\n      \"machineId\": \"macbook-pro-a1b2\",\n      \"lastSync\": \"2024-01-15T10:30:00Z\"\n    },\n    {\n      \"path\": \"work/\",\n      \"localPath\": \"~/work/memories\",\n      \"machineId\": \"macbook-pro-a1b2\",\n      \"lastSync\": \"2024-01-15T10:30:00Z\"\n    }\n  ]\n}\n```\n\n**Collision detection:**\n- On `sync init`: check registry, block if path already mapped by different local path\n- Daemon: periodically validate registry, warn on conflicts\n- Same machine can remap (update), different machine with same path = collision\n\n### CLI Commands\n\n```bash\n# === Central Repo Setup ===\n\n# Use existing repo as central\nminimem config set centralRepo ~/existing-memories-repo\n\n# Initialize new central repo\nminimem sync init-central ~/new-memories-repo\n# Creates repo structure, .gitignore, registry file\n\n# === Directory Sync Setup ===\n\n# Initialize sync for current directory\nminimem sync init --path global/\n# Validates path not already mapped, updates registry\n\n# Explicit paths\nminimem sync init --local ~/work/memories --path work/\n\n# List all sync mappings (from registry)\nminimem sync list\n\n# Remove mapping\nminimem sync remove\n# Removes from local config and registry\n\n# === Sync Operations ===\n\nminimem push              # local → central repo\nminimem pull              # central repo → local\nminimem sync status       # show sync state for all directories\n```\n\n### Conflict Detection (Hybrid: Hash + Shadow)\n\n**Sync state tracking** (`.minimem/sync-state.json`):\n```json\n{\n  \"lastSync\": \"2024-01-15T10:30:00Z\",\n  \"files\": {\n    \"MEMORY.md\": {\n      \"localHash\": \"abc123\",\n      \"remoteHash\": \"abc123\",\n      \"lastSyncedHash\": \"abc123\"\n    },\n    \"memory/2024-01-15.md\": {\n      \"localHash\": \"def456\",\n      \"remoteHash\": \"def456\",\n      \"lastSyncedHash\": \"def456\"\n    }\n  }\n}\n```\n\n**Detection algorithm:**\n```\nFor each file:\n  localHash = hash(local file)\n  remoteHash = hash(central repo file)\n  baseHash = lastSyncedHash from sync-state.json\n  \n  if localHash == remoteHash:\n    → No change, skip\n  elif localHash == baseHash:\n    → Only remote changed, pull\n  elif remoteHash == baseHash:\n    → Only local changed, push\n  else:\n    → Both changed, CONFLICT\n    → Create shadow copy for 3-way merge\n    → Apply merge strategy\n```\n\n**Shadow copies** (created only on conflict):\n- `.minimem/shadows/{filename}.base` - last synced version\n- Used as merge base for 3-way merge\n- Cleaned up after resolution\n\n### Merge Resolution Strategies\n\n| Strategy | Behavior | Use Case |\n|----------|----------|----------|\n| `merge` | Git-style 3-way merge | Technical content |\n| `keep-both` | Append both versions with separator | **Default for memories** |\n| `manual` | Fail, open in merge tool | Critical content |\n| `last-write-wins` | Overwrite with latest timestamp | Low-stakes |\n\n**Keep-both format:**\n```markdown\n<<<<<<< LOCAL (2024-01-15 10:30)\nLocal version of content\n=======\nRemote version of content\n>>>>>>> REMOTE (2024-01-15 09:45)\n```\n\nMerge resolver hook:\n```json\n{\n  \"sync\": {\n    \"conflictStrategy\": \"manual\",\n    \"mergeResolver\": \"code --wait --merge\"\n  }\n}\n```\n\n### Sync Failure Recovery (Atomic + Quarantine)\n\n**Atomic sync process:**\n```\n1. Create staging: .minimem/staging/{timestamp}/\n2. Copy files to staging\n3. Validate all files copied successfully\n4. On success: move staging → final destination\n5. On failure: \n   - Leave staging intact\n   - Log error to .minimem/sync.log\n   - Notify user\n```\n\n**Quarantine for conflicts:**\n```\n.minimem/\n├── conflicts/\n│   └── 2024-01-15T10-30-00/\n│       ├── MEMORY.md.local\n│       ├── MEMORY.md.remote\n│       └── MEMORY.md.base\n└── staging/\n    └── {in-progress sync files}\n```\n\n**Recovery commands:**\n```bash\nminimem sync recover          # retry failed sync\nminimem sync conflicts        # list unresolved conflicts\nminimem sync resolve <file>   # manually resolve conflict\n```\n\n### Daemon Architecture\n\n```\n                    ┌─────────────────┐\n                    │     Daemon      │\n                    └────────┬────────┘\n                             │\n         ┌───────────────────┼───────────────────┐\n         │                   │                   │\n         ▼                   ▼                   ▼\n   Watch local dirs    Watch central repo    Validate registry\n   (file changes)      (git pull detected)   (detect collisions)\n         │                   │                   │\n         ▼                   ▼                   ▼\n   Debounce + Push     Pull to local dirs    Warn on conflicts\n```\n\n**Daemon responsibilities:**\n- Watch configured directories for file changes\n- Debounce rapid changes (e.g., 2 second delay)\n- Trigger push on local changes (if autoSync enabled)\n- Watch central repo for pulls (git hooks or polling)\n- Periodically validate registry for path collisions\n- Stage changes only by default (autoCommit: false)\n\nDaemon modes:\n- Standalone: `minimem daemon`\n- Integrated: runs with MCP server\n- System service: launchd/systemd\n\n### Bootstrap Flows\n\n**Flow A: Fresh central repo**\n```bash\nminimem sync init-central ~/memories-repo\n# Creates:\n#   ~/memories-repo/\n#   ├── .git/\n#   ├── .gitignore          # ignores *.db, staging/, conflicts/\n#   ├── .minimem-registry.json\n#   └── README.md\n\nminimem config set centralRepo ~/memories-repo\n```\n\n**Flow B: Existing repo as central**\n```bash\nminimem config set centralRepo ~/existing-repo\n# Validates repo exists\n# Creates .minimem-registry.json if missing\n# Warns if structure looks unusual\n```\n\n**Flow C: Add directory to sync**\n```bash\ncd ~/.minimem\nminimem sync init --path global/\n# Checks registry for collision\n# Updates .minimem/config.json\n# Registers in central repo\n# Initial sync (pull or push based on state)\n```\n\n**Flow D: Clone setup on new machine**\n```bash\ngit clone <central-repo> ~/memories-repo\nminimem config set centralRepo ~/memories-repo\nminimem sync list  # shows all registered paths\nminimem sync init --local ~/.minimem --path global/\n# Links local directory to existing central path\n# Updates registry with new machine ID\n# Pulls content from central\n```\n\n### Central Repo Structure\n\n```\nmemories-repo/                    # git repo\n├── .git/\n├── .gitignore\n├── .minimem-registry.json        # path collision prevention\n├── global/                       # maps to ~/.minimem/\n│   ├── MEMORY.md\n│   └── memory/\n├── work/                         # maps to ~/work/memories/\n│   ├── MEMORY.md\n│   └── memory/\n└── projects/\n    └── projectA/                 # hybrid: also in project repo\n        ├── MEMORY.md\n        └── memory/\n```\n\n## Success Criteria\n\n- [ ] User can configure a central repo and map multiple directories to it\n- [ ] `minimem push/pull` correctly syncs files between local and central\n- [ ] Conflicts are detected using hash comparison and resolved with keep-both strategy\n- [ ] Path collisions are prevented via registry validation on init\n- [ ] Auto-detection correctly identifies all four directory types\n- [ ] Sync failures are recoverable via atomic operations and quarantine\n- [ ] Daemon watches for changes and syncs automatically when enabled\n- [ ] Daemon detects and warns about registry conflicts\n\n## Technical Considerations\n\n- Use `chokidar` for cross-platform file watching\n- Git operations via `simple-git` library\n- Debounce file changes (2 second default) before sync\n- Content hashing with SHA-256 for conflict detection\n- Machine ID from `os.hostname()` + random suffix on first run\n- Store machine ID in global config\n- Central repo only contains `.md` files, registry, and gitignore\n\n## Decisions Made\n\n| Question | Decision | Rationale |\n|----------|----------|-----------|\n| Daemon auto-commit? | Configurable, default off | User controls when to commit |\n| Conflict strategy default? | `keep-both` | Never lose memory data |\n| Lock mechanism? | Atomic staging | Simpler than locks, same safety |\n| Path collision handling? | Registry + validation on init | Prevent rather than recover |\n","priority":1,"archived":0,"archived_at":null,"created_at":"2026-02-02 06:36:19","updated_at":"2026-02-02 23:50:18","parent_id":null,"parent_uuid":null,"relationships":[],"tags":["cli","daemon","git","sync"]}

package/references/minimem/CLAUDE.md

@@ -0,0 +1,310 @@
+# CLAUDE.md
+
+This file provides context for AI agents working on the minimem codebase.
+
+## Project Overview
+
+**minimem** is a file-based memory system with vector search for AI agents. It lets users store memories as Markdown files and search them semantically using embeddings.
+
+**Key value props:**
+- Plain Markdown files (git-friendly, human-readable)
+- Semantic search via embeddings (OpenAI, Gemini, or local)
+- Hybrid search combining vectors + full-text (BM25)
+- MCP server for Claude Desktop/Cursor integration
+- CLI for command-line usage
+
+## Architecture
+
+```
+src/
+├── minimem.ts          # Main Minimem class - core logic
+├── internal.ts         # Utilities: chunking, hashing, file listing
+├── index.ts            # Public exports
+├── cli/                # CLI implementation
+│   ├── index.ts        # Entry point, command registration
+│   ├── config.ts       # Config loading, directory resolution
+│   └── commands/       # Individual command implementations
+├── db/                 # Database layer
+│   ├── schema.ts       # SQLite schema creation (v4)
+│   └── sqlite-vec.ts   # Vector extension loading
+├── embeddings/         # Embedding providers
+│   ├── embeddings.ts   # Provider factory and interfaces
+│   ├── batch-openai.ts # OpenAI batch embedding
+│   └── batch-gemini.ts # Gemini batch embedding
+├── search/             # Search implementation
+│   ├── hybrid.ts       # Hybrid vector+FTS search, BM25
+│   ├── search.ts       # Knowledge-filtered search helpers
+│   └── graph.ts        # Knowledge graph traversal (BFS)
+└── server/             # MCP server
+    ├── mcp.ts          # MCP protocol implementation
+    └── tools.ts        # Tool definitions for LLM integration
+```
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/minimem.ts` | Core class with search, sync, append, knowledge methods |
+| `src/internal.ts` | `chunkMarkdown()`, `hashText()`, `listMemoryFiles()` |
+| `src/session.ts` | Frontmatter parsing/serialization (incl. knowledge fields) |
+| `src/cli/commands/search.ts` | Multi-directory search implementation |
+| `src/embeddings/embeddings.ts` | `createEmbeddingProvider()` factory |
+| `src/search/hybrid.ts` | `mergeHybridResults()`, BM25 scoring |
+| `src/search/search.ts` | `buildKnowledgeFilterSql()` for metadata filtering |
+| `src/search/graph.ts` | `getLinksFrom()`, `getLinksTo()`, `getNeighbors()`, `getPathBetween()` |
+| `src/server/mcp.ts` | MCP server for Claude Desktop integration |
+| `src/server/tools.ts` | MCP tool definitions (memory + knowledge) |
+
+## Development Commands
+
+```bash
+npm run build          # Build library and CLI
+npm run dev            # Watch mode
+npm run test           # Unit tests (vitest)
+npm run test:cli       # CLI command tests
+npm run test:integration  # E2E integration tests
+npm run test:all       # All tests
+```
+
+## Testing
+
+Tests are in `__tests__/` directories alongside source:
+
+- `src/__tests__/minimem.integration.test.ts` - Full E2E with mock embeddings
+- `src/__tests__/knowledge.test.ts` - Knowledge frontmatter parsing + graph traversal
+- `src/cli/__tests__/commands.test.ts` - CLI command tests
+- `src/embeddings/__tests__/` - Embedding provider tests
+- `src/search/__tests__/` - Hybrid search tests
+- `src/server/__tests__/` - MCP server + knowledge tool tests
+
+**Mock embeddings:** Tests use deterministic embeddings based on keyword presence (no API calls needed). See `createDeterministicEmbedding()` in test files.
+
+## Build System
+
+- **tsup** for bundling (ESM only, Node 22+)
+- Library: `dist/index.js` with types
+- CLI: `dist/cli/index.js` (bundled with shebang)
+- **postbuild** script fixes `node:sqlite` import (esbuild strips `node:` prefix)
+
+## Important Patterns
+
+### Memory Path Validation
+Only `MEMORY.md` and `memory/*.md` files are indexed. The `validateMemoryPath()` method enforces this.
+
+### Embedding Cache
+Embeddings are cached by content hash in SQLite. Same content = same embedding, even across files.
+
+### Hybrid Search
+Default weights: 70% vector similarity, 30% BM25 text search. Configurable via `hybrid.vectorWeight` and `hybrid.textWeight`.
+
+### Multi-Directory Search
+The search command can query multiple directories:
+```bash
+minimem search "query" --dir ~/a --dir ~/b --global
+```
+Results are merged and sorted by score.
+
+## Common Tasks
+
+### Adding a new CLI command
+
+1. Create `src/cli/commands/newcmd.ts`:
+```typescript
+export type NewCmdOptions = { dir?: string; global?: boolean; };
+
+export async function newcmd(options: NewCmdOptions): Promise<void> {
+  const memoryDir = resolveMemoryDir({ dir: options.dir, global: options.global });
+  // ... implementation
+}
+```
+
+2. Export from `src/cli/commands/index.ts`
+
+3. Register in `src/cli/index.ts`:
+```typescript
+program
+  .command("newcmd")
+  .description("Description")
+  .option("-d, --dir <path>", "Memory directory")
+  .action(newcmd);
+```
+
+4. Add tests in `src/cli/__tests__/commands.test.ts`
+
+### Adding a new embedding provider
+
+1. Add provider type to `EmbeddingProviderOptions` in `src/embeddings/embeddings.ts`
+2. Implement in `createEmbeddingProvider()` switch statement
+3. Add batch function in `src/embeddings/batch-{provider}.ts` if needed
+4. Update `auto` provider detection logic
+
+### Modifying the database schema
+
+1. Update `createSchema()` in `src/db/schema.ts` (currently at SCHEMA_VERSION 4)
+2. Consider migration strategy (currently: recreate on schema change)
+3. Update relevant queries in `src/minimem.ts`
+4. If adding knowledge-related columns, update `indexKnowledgeMetadata()` in `src/minimem.ts`
+
+## Gotchas
+
+1. **node:sqlite is experimental** - Requires Node 22+, shows warning on every run
+2. **sqlite-vec may not load** - Falls back to FTS-only search if extension fails
+3. **CLI bundle strips node: prefix** - postbuild script fixes this
+4. **Commander.js is CJS** - Must be external in CLI bundle, not inlined
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `OPENAI_API_KEY` | OpenAI embeddings |
+| `GOOGLE_API_KEY` | Gemini embeddings |
+| `GEMINI_API_KEY` | Alternative Gemini key |
+| `MEMORY_DIR` | Default memory directory |
+
+## File Structure Convention
+
+```
+project/
+├── MEMORY.md           # Main memory (required for init)
+├── memory/             # Additional memories
+│   ├── YYYY-MM-DD.md   # Daily logs (from append)
+│   └── *.md            # Topic files
+└── .minimem/
+    ├── config.json     # User config
+    ├── index.db        # SQLite with vectors
+    └── .gitignore      # Ignores index.db
+```
+
+## MCP Integration
+
+The MCP server exposes 5 tools over stdio, compatible with Claude Desktop and Cursor:
+
+| Tool | Purpose |
+|------|---------|
+| `memory_search` | General semantic search across all memory files |
+| `memory_get_details` | Retrieve full content of a specific memory file |
+| `knowledge_search` | Search knowledge notes with domain/entity/confidence/type filters |
+| `knowledge_graph` | Traverse knowledge graph relationships from a note |
+| `knowledge_path` | Find shortest path between two knowledge notes via graph links |
+
+The 3 `knowledge_*` tools are additive — they only return results when knowledge-formatted notes (with the frontmatter convention below) are present. Without knowledge notes, they return empty results.
+
+Config location for Claude Desktop:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+## Claude Code Plugin
+
+The `claude-plugin/` directory contains a ready-to-use Claude Code plugin:
+
+```
+claude-plugin/
+├── .claude-plugin/
+│   └── plugin.json      # Plugin manifest
+├── .mcp.json            # MCP server definition (uses npx minimem mcp)
+├── skills/
+│   └── memory/
+│       └── SKILL.md     # Auto-invoked memory skill
+└── commands/
+    ├── remember.md      # /minimem:remember command
+    └── recall.md        # /minimem:recall command
+```
+
+### Testing the Plugin
+
+```bash
+claude --plugin-dir ./claude-plugin
+```
+
+### Plugin Commands
+
+- `/minimem:remember <text>` - Store information in memory
+- `/minimem:recall <query>` - Search for stored memories
+
+## Knowledge Frontmatter Convention
+
+minimem can index structured knowledge notes produced by external systems (e.g., cognitive-core). This is a **file-format convention only** — minimem does not import or depend on any external package.
+
+When a memory file's YAML frontmatter contains knowledge-specific fields, minimem parses them and populates metadata columns in the `chunks` table and edges in the `knowledge_links` table.
+
+### Supported fields
+
+All fields are optional. If absent, the file is treated as a regular memory note.
+
+```yaml
+---
+id: k-abc123                     # Unique knowledge node ID
+type: observation                # observation | entity | domain-summary
+domain: [database, devops]       # Domain tags
+entities: [prisma, postgres]     # Referenced entities
+confidence: 0.85                 # Confidence score (0.0–1.0)
+source:                          # Provenance metadata
+  origin: extracted              # extracted | agent-authored
+  trajectories: [t-001, t-002]  # Source trajectory IDs
+  agentId: agent-v1             # Authoring agent
+links:                           # Graph edges to other knowledge nodes
+  - target: k-other
+    relation: related-to         # related-to | depends-on | supports | etc.
+    layer: semantic              # semantic | temporal | causal | entity
+  - target: k-dep
+    relation: depends-on
+created: 2025-01-15T10:00:00Z
+updated: 2025-01-15T12:00:00Z
+supersedes: k-old                # ID of note this replaces
+tags: [migration, patterns]
+---
+# Note Title
+
+Body content in Markdown.
+```
+
+### How it works
+
+1. **Indexing** (`indexFile()`): When a file is indexed, frontmatter is parsed via `parseFrontmatter()`. If `type` is present, the chunk row gets `knowledge_type`, `knowledge_id`, `domains` (JSON), `entities` (JSON), and `confidence` populated. If `links` is present, rows are upserted into `knowledge_links`.
+
+2. **Filtered search** (`knowledgeSearch()`): Accepts `domain`, `entities`, `minConfidence`, and `knowledgeType` filters. Uses `json_each()` SQL for array column matching. Falls back to regular search when no filters are provided.
+
+3. **Graph traversal** (`src/search/graph.ts`): Operates on the `knowledge_links` table. Supports outgoing/incoming edge queries, BFS neighbor discovery (configurable depth), and shortest-path finding.
+
+4. **Re-indexing**: When a file changes, old `knowledge_links` for that file are deleted before new ones are inserted, keeping the graph consistent.
+
+### Independence guarantee
+
+- minimem defines its own types (`KnowledgeSource`, `KnowledgeLink`, `MemoryFrontmatter`) locally in `src/session.ts`
+- Zero imports from cognitive-core or any external knowledge system
+- All knowledge columns are nullable — regular memory files index without them
+- The `knowledge_links` table only gets rows when frontmatter contains `links`
+- All knowledge MCP tools (`knowledge_search`, `knowledge_graph`, `knowledge_path`) are additive alongside existing tools
+
+### Database schema (v4)
+
+Knowledge-related additions to the schema:
+
+```sql
+-- Added columns on chunks table (all nullable)
+knowledge_type TEXT      -- 'observation', 'entity', 'domain-summary'
+knowledge_id TEXT        -- Note ID from frontmatter
+domains TEXT             -- JSON array of domain strings
+entities TEXT            -- JSON array of entity strings
+confidence REAL          -- 0.0–1.0
+
+-- New table for graph edges
+CREATE TABLE knowledge_links (
+  from_id TEXT NOT NULL,
+  to_id TEXT NOT NULL,
+  relation TEXT NOT NULL,
+  layer TEXT,                     -- semantic, temporal, causal, entity
+  weight REAL DEFAULT 0.5,
+  source_path TEXT,
+  created_at INTEGER DEFAULT (unixepoch()),
+  PRIMARY KEY (from_id, to_id, relation)
+);
+```
+
+## Code Style
+
+- TypeScript with strict mode
+- ESM modules (no CommonJS)
+- Async/await for all I/O
+- Types exported alongside implementations
+- Tests use Node.js native test runner (not vitest) for integration tests