You are an AI agent.
This is your memory API.
Engram gives you persistent memory via 17 MCP tools. Store what you learn, load smart context, cross-pollinate across repos, prove usage, and close the loop with reflection.
# 1. Start a free trial; no email or API key needed npx -y engram-tools@latest --setup # 2. Restart Claude, Codex, Cursor, Gemini or Antigravity, Windsurf, or VS Code # 3. Paste these as agent instructions, not shell commands Call engram_start with project, repo, role, market, stack, and task. Before choosing an approach, call engram_recall. If another repo may have solved it, use engram_cross_pollinate. If context was compacted or resumed, call engram_rehydrate before continuing. Use engram_reflect as a milestone checkpoint after meaningful phases, task switches, several used memories, or before handoff.
Setup for your tool
// ~/.claude/mcp.json{"mcpServers": {"engram": {"command": "npx","args": ["-y", "engram-tools@latest", "mcp"],"env": {"ENGRAM_API_URL": "https://api.engram.tools"}}}}
Can an agent try Engram without email?
The npm package starts an isolated free trial automatically. Remote HTTP connections through directories such as Glama use OAuth and email verification. Run connect later to claim your npm trial and keep its memories. A human approves paid upgrades.
Make your next session remember
Try one real project decision across two sessions.
With permission to install tools, run npx -y engram-tools@latest --setup for a free npm trial. No email or API key is needed. Keep any existing Engram workspace.
Reconnect your coding client. Call engram_start with this repository and the task you are actually working on.
As you work, use engram_store to save one confirmed project decision and why you made it. Keep secrets out of memory.
Open a new session in the same repository. Ask the agent to use engram_recall for that decision and its reason.
Check the source memory against the current project. Use engram_report_outcome to report whether it helped.
When you want to keep the trial workspace, run npx -y engram-tools@latest connect and verify your email. Your memories stay in the same workspace.
First session
Use Engram on this repository and my current task. Call engram_start with the actual repo and task. Work on my task, then use engram_store to save one confirmed project decision and why we made it. Keep the existing workspace and do not store secrets or invent a demonstration fact.
Next session
Use engram_recall to find the project decision and its reason from our previous session in this repository. Show the source memory, check it against current project evidence, then continue my task. Report whether the recalled memory helped.
// When to use each tool
Do not fill a human form. Teach the memory loop.
When a memory helps, is stale, or is wrong-context, report that through the tools. That signal is more useful than a generic feedback message because it trains future ranking.
Cross-Session Learning
You fix a tricky bug in session 1. Session 2, the same bug pattern appears in a different file. You recall the fix instantly.
Team Knowledge Transfer
A Cursor agent on the frontend discovers that the API expects snake_case. A Claude Code agent on the backend learns this without anyone telling it.
Convention Enforcement
Before writing code, you recall project conventions. "Use Zod for validation, not Joi." You follow the team standard automatically.
Memory, freshness and feedback
The practical contract behind the tools. Parameter tables come from the MCP schema. Response examples are sanitized HTTP payload excerpts. MCP returns JSON, Markdown or compact acknowledgements through text/format; check format before parsing.
Choose the right entry point
Begin repository work
engram_startWorkspace briefing and relevant memory
Answer one concrete question
engram_recallRanked memories for that question
Change task with context intact
engram_smarterA new task briefing
Resume after lost context
engram_rehydrateSafe journal recovery and current-memory fallback
Checkpoint a milestone
engram_reflectA checkpoint; the session stays open
The npm client can start an isolated free trial without email or an API key. Remote OAuth connections verify email. Never invent credentials. A repo is a filter inside the authenticated workspace, not permission to access another workspace.
Use engram_start when beginning repository work, engram_recall for one concrete question, engram_smarter when changing tasks, and engram_rehydrate after compaction or interruption. Smarter searches durable memory for the new task; it does not reconstruct the prior journal. Both tools can record session events. Rehydrate can read closed or teammate history but cannot reopen or write into it. engram_reflect leaves the session open; engram_close_session is an explicit finish.
Focused defaults are start=8, recall=5, smarter=5 and cross_pollinate=5. Deep defaults are 16, 12, 12 and 12 respectively. Explicit limits override the default budget within each tool's maximum. Matching skills are inferred from task keywords unless include_skills is explicitly true or false.
Rehydrate uses a separate journal-detail budget: depth=brief returns up to 12 events and 2 summaries; standard up to 30 and 4; full up to 60 and 8. It does not accept limit or the retrieval values focused/deep.
If recall returns count=0, say no matching memory was found. Check the repo and query, then rephrase or use depth=deep if appropriate. A larger result budget does not make unrelated information relevant. Use cross_pollinate when another repository is likely to hold a transferable lesson; get_context is for deliberate category inspection, not the automatic next step after every empty search.
Keep rules and changing facts separate
Prefer one independently maintainable fact per memory. A permission rule and a deployed-state observation should have separate ids. For a single item, use type, content and optional claim; alternatively use claims for 1β32 independent units, each with type, content and claim. Do not mix the two input forms. Old untyped memories remain legacy_unassessed; recording metadata does not prove a note contains only one fact.
type is the searchable category, such as CONVENTION or SOLUTION; claim.kind describes what may change: rule, decision, state, lesson or reference. Only state has a stage: proposed, implemented, tested or deployed. State requires observed_at as an ISO timestamp with a timezone, no more than one minute ahead of the server's clock. UTC or explicit timezone offsets are accepted; keep the caller's clock synchronized. tested/deployed also require evidence. Evidence is supplied by the agent, not independently verified by Engram. review_after is optional, cannot precede observed_at, and is an informational review date, not automatic expiration or permission to retire a rule.
A kind=rule label does not give an agent human authority or override current instructions. Use supersedes_memory_ids and change_reason only for a verified replacement. A legacy split uses split_from with memory_id and content_sha256; preview is the default. Apply only with dry_run=false and the exact returned split:<id>:<plan_hash> confirmation. Historical pieces stay historical; do not copy one item's success votes into unrelated new facts.
Example: replace placeholders with actual returned values.
{
"claims": [
{
"type": "CONVENTION",
"content": "Deployment requires explicit owner approval.",
"claim": {
"kind": "rule"
}
},
{
"type": "SOLUTION",
"content": "The OAuth callback fix passed the isolated test suite.",
"claim": {
"kind": "state",
"stage": "tested",
"observed_at": "2026-11-15T09:00:00Z",
"evidence": "Commit abc1234; isolated OAuth regression receipt"
}
}
]
}Review an old mixed note without losing its valid rule
If a note combines a valid approval rule with an obsolete release status, do not withdraw the whole note just to hide the status. Review every independent fact first. Keep the rule active and mark only the obsolete piece historical in the proposed claims. Splitting is available to the source's creator or a human owner; the source must be private, active and not already a declared claim.
For the preview, send claims and split_from together. Compute content_sha256 from the exact retained source text, not a shortened display or a paraphrase. Preview writes no memories. Check the returned claims, active_claims and historical_claims before applying. The example below is MCP SDK pseudocode: source is the actual retained memory, and claims is your reviewed claim array, with historical:true only on obsolete pieces.
Resend the unchanged source and claim plan with dry_run=false and the preview's confirmation verbatim. Never construct a confirmation yourself. A changed source or claim plan requires another preview. The original remains historical; new units get separate ids without inherited votes. A preview proves the proposed write shape, not the truth of your review.
Example: replace placeholders with actual returned values.
const plan = {
split_from: {
memory_id: source.id,
content_sha256: sha256(source.content) // SHA-256 hex of exact text
},
claims // reviewed independent units; obsolete pieces use historical: true
};
const result = await client.callTool({ name: "engram_store", arguments: plan });
if (result.isError) throw new Error("Split preview failed");
if (result.structuredContent?.format !== "json") throw new Error("Expected JSON preview");
const preview = JSON.parse(result.structuredContent.text);
// Review preview.claims, active_claims and historical_claims before applying.
await client.callTool({
name: "engram_store",
arguments: { ...plan, dry_run: false, confirmation: preview.confirmation }
});Useful is different from verified and current
success=true means the memory helped the task. It does not establish current factual truth, a live deployment, or the correctness of every sentence in an old mixed note. trust=validated and confidence are compatibility labels for reported usefulness, not independent verification. Read claim.stage, observed_at, evidence and last_outdated_report_at, then verify critical facts against current code or runtime evidence.
Initial relevance is relevant, irrelevant or uncertain. Actual usefulness is helpful, unhelpful, not_used or not_evaluated. Only helpful/unhelpful creates an outcome vote and affects confidence. A result can be irrelevant and not_used without a failure vote. Missing feedback remains unjudged. Relevance notes and actual-use evidence are kept separately.
Product-quality feedback, such as useful/noisy/stale/missing_context/too_long in engram_reflect.feedback or POST /api/v1/feedback, evaluates Engram itself. It is separate from per-memory outcomes and does not update an individual memory's confidence.
Tie feedback to the exact query and handle retries
retrieval_id identifies the committed result-list exposure; session_id identifies a journal. Keep the retrieval_id with each result list, especially when the same memory appeared in parallel queries. Null retrieval_id means exact attribution is unavailable for that response. Old or closed sources can still receive explicit feedback if the receipt, memory and caller remain accessible; do not reopen the source journal.
Use engram_report_outcome with memory_id, success and retrieval_id for one actual use; use outcomes for a batch of up to 20 unique retrieval/memory pairs. Or attach the same entries as pending_feedback on your next start, recall, smarter, store, reflect, cross_pollinate, get_context, skill or report_outcome call. Pending feedback needs outcome:write and consumes no additional call quota. Omit results you cannot evaluate rather than invent a judgment.
Resend the same retrieval_id, memory_id and actual-use fields for an identical explicit retry. Engram acknowledges it with duplicate=true in the response and adds no extra vote; duplicate is not an input and there is no retry flag. This is not a 409 error. Only an attempt to change an already recorded actual-use vote returns 409. A legacy report without retrieval_id instead selects the newest recorded exposure containing that memory for the authenticated member/workspace within 24 hours; supplying session_id narrows that search to the selected journal. Legacy retries can add another vote, so do not treat this inferred attribution as exact. A new genuine use should have a new retrieval exposure.
A feedback batch commits before the main action. Check feedback_receipt even if that action fails: feedback may have succeeded. Both remote MCP and the npm client preserve the acknowledgement on errors. A receipt-backed failure is not automatically retried. The main action may still be non-idempotent. In reflect.used_memories, provide retrieval_id on every item for one atomic exact batch of at most 20; keep legacy items in a separate reflection. Later learning/checkpoint work can fail after that batch commits, with feedback_receipt showing the accepted outcomes.
Example: replace placeholders with actual returned values.
{
"repo": "example",
"query": "Which deployment rule applies?",
"pending_feedback": [
{
"retrieval_id": "<id from the previous result list>",
"memory_id": "<memory in that list>",
"relevance": "irrelevant",
"usefulness": "not_used"
}
]
}Preferred: exact reflection outcomes (engram_reflect arguments)
{
"store": false,
"summary": "Applied the recalled approval rule.",
"used_memories": [
{
"retrieval_id": "<id from that result list>",
"memory_id": "<memory in that list>",
"success": true,
"detail": "Checked owner approval before releasing."
}
]
}Compatibility only: a separate legacy reflection (engram_reflect arguments)
{
"store": false,
"summary": "Reported a use without a retained query receipt.",
"used_memories": [
{
"memory_id": "<accessible memory id>",
"success": true,
"detail": "This use has inferred attribution, not an exact query link."
}
]
}Withdrawal, deletion and safe session recovery
engram_retract_memory reversibly withdraws private knowledge; its creator or a human workspace owner can do it. engram_restore_memory requires a retained retracted record and checks quota and confirmed replacements. Neither storing the same text nor rehydrate silently restores it. Erased records cannot be restored.
An OAuth token cannot preview or execute permanent deletion, even when its member is an OWNER. Both operations require the separate human workspace OWNER API-credential path. Do not obtain or substitute an owner key to bypass an OAuth connection's restrictions. engram_delete_memory defaults to an impact preview; execute only with dry_run=false and confirmation=delete:<exact memory_id>. It removes the live memory, linked known copies and affected journal free text. Prior client context, independent records, unlinked paraphrases, providers and backups are outside that targeted live erasure.
Session discovery hides task text tied to withdrawn, expired or erased knowledge. If a journal cannot be safely reconstructed, use the safe current-memory fallback or start a clean journal with engram_start(new_session=true); do not bypass suppression. Restoring a retained source can make its safe retained history available again.
API Reference
Complete documentation for all 17 MCP tools.
engram_startStart every session in one call. Loads setup guidance, relevant memories, and matching skill guides.
{"agent_tool": "codex","project": "English.cash","repo": "english.cash","role": "full-stack product engineer","market": "English learning","task": "fix guest practice so it uses the same API path as paid practice","stack": ["Next.js", "TypeScript", "PostgreSQL", "LLM router"]}
engram_rehydrateRecover the working map after context compaction, resume, summary, truncation, or missing chat history.
{"agent_tool": "codex","project": "Engram","repo": "engram","task": "continue mobile Safari chat fix after context compaction","reason": "chat was compacted and only a short summary remains","depth": "standard"}
engram_smarterLoad task-specific memories and matching skill guides when switching tasks.
{"context": "Next.js 16 mobile Safari chat widget overflows when keyboard opens","repo": "engram","file": "web/src/components/ChatWidget.tsx","include_skills": true}
engram_cross_pollinateFind reusable lessons from other repos in your workspace.
{"target_repo": "skillbridge-monorepo","context": "Add team invite flow with owner/admin permissions and email delivery","source_repos": ["engram", "evimibul"],"include_public": true,"limit": 5}
engram_storeStore a learned convention, pattern, gotcha, or solution.
{"type": "SOLUTION","content": "Mobile Safari chat panels should not autofocus inputs. Size the fixed panel from visualViewport, use 16px input text, and assert bounds after typing.","tags": ["ios", "safari", "mobile", "chat-widget"],"repo": "engram","agent_tool": "codex","context": {"file": "web/src/components/ChatWidget.tsx","platform": "ios-safari"}}
engram_recallRecall relevant memories by semantic query, filtered by repo, type, or tags.
{"query": "Stripe checkout succeeded but workspace plan still free after webhook","repo": "engram","type": "SOLUTION","limit": 3}
engram_report_outcomeReport whether a recalled memory helped. With retrieval_id, identical retries succeed as duplicates; changing a committed vote returns 409. Omitting retrieval_id uses legacy inference within 24 hours and retries may add votes. Usefulness is not factual verification.
{"retrieval_id": "retrieval_id_from_that_recall","memory_id": "cmqstripeplan123","success": true,"detail": "The recalled webhook transaction pattern fixed the dashboard plan mismatch in production."}
engram_reflectSave a milestone checkpoint, report used memories, and store durable learnings. Leaves the session open; close_session optionally finishes it.
{"repo": "engram","task": "Fix mobile Safari chat overflow and close behavior","summary": "Chat panel now sizes from visualViewport, avoids mobile autofocus, uses 16px input text, and close restores the launcher.","used_memories": [{"memory_id": "cmqioschat123","success": true,"detail": "The iOS visualViewport gotcha pointed to the correct fix."}],"learnings": [{"type": "SOLUTION","content": "For mobile fixed panels, compute bounds from visualViewport and verify after focusing an input; CSS dvh alone may not catch layout viewport offset.","tags": ["mobile", "safari", "visualViewport"]}]}
engram_get_contextGet relevant memories for a repository in one call. Use when switching repos or when you need a focused repo dump.
{"repo": "engram","task": "Polish localized documentation without breaking rendered pages"}
engram_skillLoad a complete skill guide for complex tasks like migrations, reviews, deployment, and debugging.
{"skill": "security-audit"}
engram_proofReturn product proof: memory-bank size, learning loop, usage, activation, and benchmark recipe.
engram_proof()
engram_setupReturn workspace info, available tools, and best-practice guidance.
{"agent_tool": "claude-code"}
engram_list_sessionsList bounded session metadata to choose an exact journal. Defaults to mine; scope=workspace discovers teammates. Requires memory:read. Use next_cursor for more results.
{ "repo": "engram", "scope": "mine", "limit": 20 }
engram_close_sessionOptionally close an exact session at finish or handoff. Unlike reflect, makes history read-only. Final checkpoint and close are atomic; retries return the original receipt. Requires session:write and ownership; human owners may close team sessions. Keeps memories and history.
{ "session_id": "example-session", "summary": "Tests passed; deployment awaits approval." }
engram_retract_memoryReversibly withdraw an exact private memory when its advice is no longer valid. Unlike store, needs no replacement. Creator or human owner only; memory:write. Keeps content; retrieval hides it and dependent patterns, while recovery suppresses referencing journals. Repeating is idempotent.
{ "memory_id": "example-memory", "reason": "This advice needs revalidation." }
engram_restore_memoryExplicitly restore retracted knowledge after revalidation. Unlike store, retains the original ID/content. Creator or human owner only; memory:write. Quota and confirmed-replacement checks apply. Erased records cannot be restored; already active is a no-op.
{ "memory_id": "example-memory" }
engram_delete_memoryHuman workspace OWNER only; OAuth agents cannot erase. Defaults to preview. Inspect affected records before executing with dry_run=false and confirmation=delete:<id>. Removes live memory, known derived copies and affected journalsβ full free text. Keeps a minimal receipt/fingerprint. Independent records, unlinked paraphrases, prior client context, providers and backups are outside its scope. Execution is irreversible; retry returns the original receipt.
{ "memory_id": "example-memory", "dry_run": true }
Memory Types
CONVENTIONCoding standards and team rules
"Always use Prisma migrations"
PATTERNRecurring approaches and templates
"API routes use cached() wrapper"
GOTCHAThings that break or surprise
"Neon requires SSL in production"
SOLUTIONFixes that worked
"Fix: add pooler to connection string"
ARCHITECTURESystem design decisions
"Search uses Haversine + bbox"
DEPENDENCYLibrary info and versions
"Prisma 7 needs adapter pattern"
// Machine-readable endpoint
GET https://engram.tools/api/v1/capabilitiesReturns JSON with supported tools, memory types, rate limits, and pricing - designed for programmatic consumption.