engram-mcp: Instructions file for Claude Code

Engram MCP

MCP server for AI agent persistent memory. Crate name: engram_mcp (binaries: engram, engram-cli). SQLite + local embeddings (mdbr-leaf-ir q8, 256-dim MRL).

engram is the MCP server only: JSON-RPC over stdio, no subcommands. It serves when stdin is a pipe (or with --stdio/--serve); any argument or a terminal on stdin prints a usage notice pointing at engram-cli instead (exit 0 for --help, 2 for an unsupported argument). All human/agent CLI use goes through engram-cli.

Development Rules

• Always run cargo clippy before committing and fix all warnings
• Run cargo test to verify changes
• Use cargo build --release for production binaries

Structure

src/
  main.rs      - MCP server entry, stdio transport, resources, prompts
  cli.rs       - CLI binary (engram-cli)
  lib.rs       - module exports
  db.rs        - SQLite ops (memories, embeddings, relationships, batch ops)
  memory.rs    - Memory, MemoryType, MergeSource, MemoryCluster, Relationship, RelationType, ProjectStats, ProjectSummary
  embedding.rs - mdbr-leaf-ir ONNX wrapper (256-dim MRL vectors)
  decay.rs     - relevance decay algorithm (single source of truth; registered as the RELEVANCE() SQL function)
  tools.rs     - MCP tool handlers + dedup + clustering
  format.rs    - human-readable output formatting for MCP results
  summarize.rs - extractive summarization for large content
  export.rs    - import/export JSON format
  error.rs     - MemoryError enum
  hooks/       - Claude Code lifecycle hook handlers: dispatch, filter, redact, install, payload structs
  db/status.rs   - retrieval status: supersession map (from edges) + dead flags
  db/todos.rs    - todo lifecycle sidecar (status/reason/closed_at)
  tools/todo.rs  - todo op batch, duplicate reporting, open-todo lookup for resume
  db/trash.rs    - recoverable snapshots for every destructive operation
  tools/curation.rs - applying supersession/dead status to a ranked result set

Key Types

• MemoryType: fact, decision, preference, pattern, debug, entity, handoff, adr, todo
• RelationType: relates_to, supersedes, derived_from
• Memory: id, project_id, content, tags, importance, relevance_score, timestamps, branch, merged_from
• MergeSource: id, content_preview, content (full text of the consumed memory), merged_at
• MemoryCluster: id, project_id, summary, member_count, centroid, timestamps
• TodoItem: id, project_id, text, status, reason, branch, tags, importance, timestamps, closed_at
• TodoStatus: open, done, dropped
• MemoryError: Database, Json, Embedding, NotFound, InvalidType, InvalidRelation, UnknownTool, UnknownProject, InvalidArguments, Io