| name | memory |
| description | Use when you want to explicitly store or recall knowledge across sessions. Prefer engram store/recall over file-based memory for decisions, patterns, insights, and cross-project knowledge. Also use when searching memories from previous coding sessions. |
Engram Memory
Overview
Engram is persistent shared memory for Claude Code. Hooks automatically capture observations from your coding sessions. Your job is to use that knowledge — search it, build on it, and keep it clean.
Core principle: Hooks handle automatic capture. You handle retrieval, explicit storage, and curation.
Connection Check
Do NOT check environment variables. The MCP server may be configured in different ways. The only reliable test is calling a tool:
Tool: check_system_health()
- Success → Engram is connected. Use the tools below.
- Failure / tool not found → Engram MCP is not available in this session.
What Hooks Do Automatically
| Hook | Fires When | Captures |
|---|
| SessionStart | Conversation begins | Injects relevant project memories into context |
| UserPromptSubmit | User sends a message | Searches for relevant memories and injects them as <relevant-memory> context |
| PostToolUse | Any tool completes | Captures tool usage patterns and outcomes |
| SubagentStop | Subagent finishes | Notifies system of subagent completion |
| Stop | Session ends | Generates session summary, stores key observations |
Mandatory Workflow
BEFORE every task:
recall(query="...") — check what is already known about this topic.recall(query="file:path/to/file") — before modifying any file.recall(query="prior decisions about ...") — before architectural decisions.
AFTER every task:
4. store(content="...", title="...", tags=["..."]) — save decisions, discoveries, patterns, lessons learned.
5. feedback(action="outcome", session_id="<claude-session-id>", outcome="success") — record session outcome.
Steps 4-5 are NOT optional. Every completed task produces knowledge. Store it or it is lost.
9 Primary Tools
| Tool | Purpose | Key Actions |
|---|
recall | Search & retrieve memories | search (default) |
store | Save memories, edit, import | create (default), edit, import |
feedback | Suppress low-quality memories, record outcomes | suppress, outcome |
issues | Cross-project issue tracking between agents | create, list, get, update, comment, reopen, close |
vault | Credentials — encrypted AES-256-GCM | store, get, list, delete, status |
settings | Model settings used by recall | set, get, list, delete |
docs | Documents — versioned docs & collections | create, read, list, history, comment, collections, documents, get_doc, remove, ingest |
admin | Administrative telemetry | stats; purge_project when enabled |
check_system_health | Health check of all subsystems | (no params) |
Credential Management
Engram provides encrypted credential storage via AES-256-GCM vault. Credentials may be project-scoped or global, are encrypted at rest, and never appear in search results or context injection.
Use: "Store my project OpenAI API key"
Tool: vault(action="store", name="openai_api_key", value="sk-...", scope="project", project="my-project")
Use: "Store a global OpenAI API key"
Tool: vault(action="store", name="openai_api_key", value="sk-...", scope="global")
Use: "Get my project OpenAI key"
Tool: vault(action="get", name="openai_api_key", project="my-project")
Use: "Get the global OpenAI key"
Tool: vault(action="get", name="openai_api_key")
Use: "Check vault status"
Tool: vault(action="status")
Key source priority: ENGRAM_ENCRYPTION_KEY env var > ENGRAM_ENCRYPTION_KEY_FILE > auto-generated vault.key.
Recall Tool
The recall tool searches memories using SQL filtering. The search action (default) filters by project and optionally applies a substring match on content.
Use: "What do we know about our caching choices?"
Tool: recall(query="caching strategy", project="my-project")
Use: "What authentication decisions were made?"
Tool: recall(query="authentication decisions", project="my-project", limit=10)
For file-related context, include the relevant path in the ordinary query: recall(query="path/to/file").
Store Tool
The store tool creates and manages memories.
Use: "Remember that we chose Redis over Memcached for caching"
Tool: store(content="Chose Redis over Memcached for caching layer due to persistence and pub/sub support", title="Redis caching decision", type="decision", tags=["caching", "infrastructure"])
Use: "Edit a memory"
Tool: store(action="edit", id=42, narrative="Updated content", tags=["updated"])
Use: "Import prepared instinct files"
Tool: store(action="import", files=[{"name":"caching.md","content":"---\n...\n---\n"}])
Types: decision, bugfix, feature, refactor, discovery, change, guidance, credential, entity, wiki, pitfall, operational, timeline.
Issues — Cross-Project Agent Coordination
The issues tool tracks bugs, feature requests, and tasks between agents across projects.
Do NOT use store or docs for issues. Issues have lifecycle management — status, priority, comments, auto-injection.
| Action | Usage |
|---|
| Create | issues(action="create", title="...", body="...", priority="high", target_project="other-project") |
| List | issues(action="list", project="<your-project>", status="open,acknowledged,reopened") |
| Comment | issues(action="comment", id=N, body="...") |
| Resolve | issues(action="update", id=N, status="resolved", body="Fixed in commit abc123") |
| Reopen | issues(action="reopen", id=N, body="Still broken after fix") |
When to use issues vs store:
- Bug in the CURRENT project →
store(type="discovery") — it's knowledge about a fix
- Bug/task for ANOTHER project →
issues(action="create") — it's an actionable work item
Expanded Tools
Provider-backed tools are advertised only when their store and feature gate are active. Inspect tools/list with include_all: true for the current working surface. Do not call names that are absent from the advertised list; retired compatibility aliases are not dispatched.
Workflow Patterns
Starting work: Context is auto-injected by hooks. Use recall(query="...") for deeper search.
Before modifying code: recall(query="path/to/file") to find file-related memories.
After completing a feature: store(content="...", title="...", type="decision") — capture what was built and why.
After fixing a bug: store(content="...", title="...", type="discovery") — capture root cause and fix.
After research: store(content="...", title="...", type="discovery") — capture findings.
Found a bug in another project: issues(action="create", title="...", target_project="...", priority="high") — NOT store.
Secrets: vault(action="store") for API keys. Never store secrets in observations.
Engram vs Claude Code File Memory
| Engram (store) | Claude Code (file memory) |
|---|
| Storage | PostgreSQL (server) | Markdown files (local) |
| Search | SQL + substring filter | Loaded into context at session start |
| Cross-project | Yes — global scope visible everywhere | No — per-project only |
| Cross-machine | Yes — shared server | No — local files |
| Best for | Decisions, patterns, insights, anything searchable | User preferences, project config, behavioral instructions |
Rule of thumb: If you'd search for it later → store. If it's a static instruction → file memory.
Common Mistakes
| Mistake | Fix |
|---|
| Checking ENGRAM_URL / env vars | Call check_system_health() instead |
| Not storing important insights | Use store for decisions, patterns, and preferences |
| Ignoring injected context | Read <engram-context> and <relevant-memory> blocks |
| Not searching before re-exploring | recall(query="...") first |
Using recall(action="by_file", ...) | That action was removed in v5; use recall(query="file:...") |
Using store for cross-project bugs | Use issues(action="create") — it has lifecycle and auto-injection |
