MCP tool reference

One start command.
Clear memory tools.

Run setup once and restart your AI tool. Engram then appears as MCP tools with startup guidance; you can inspect the focused tools below when needed.

Start with a free npm trial

No email or API key is needed for the npm client. With permission to edit your AI client's configuration, run setup, restart the client, then describe your actual repository and task. Add --dry-run to preview setup first. Keep an existing Engram workspace connected.

npx -y engram-tools@latest --setup

Call engram_start, save one confirmed project decision with engram_store, then recall it in a new session.

The first memory call starts your 7-day trial: 25 private memories, 20 calls/day and 100 calls total.

To keep the same workspace, run npx -y engram-tools@latest connect later and verify your email.

Remote OAuth connections, such as marketplace connections, verify email when connecting.

Or create an email-owned workspace

Step 1

Enter your email

Start free with 100 private workspace memories, 1 developer, and the 100,000-memory public bank. No credit card required.

Step 2

Verify the OTP code

We send a 6-digit code first, so nobody can create accounts with someone else's email.

Step 3

Receive your API key

After verification, Engram creates your workspace automatically and emails your setup key.

Where do I get an API key?

Create a free workspace and verify your email. Engram sends your personal API key and ready-to-run setup command in the welcome email. Already registered? Use the same email again to receive your current key.

Get a free API key
Step 4

Start your agent

Run npx engram-tools@latest --setup with your API key, restart your AI tool, and describe the project and task normally. Engram guides the agent through MCP automatically.

npx -y engram-tools@latest --setup

Check your connection and first useful memory

Describe your project and task to the agent. After real work, ask it to remember a durable decision. In a new session, ask it to recover that decision. Installing alone does not create private project memory.

npx -y engram-tools@latest --doctor
  • Tools missing? Fully quit and reopen the AI client, then check Node.js 20+ and npx. Reinstalling the client is usually unnecessary.
  • Wrong memories? Each client has its own config. Run the read-only check below, then use --setup --client codex (or your client) with the intended workspace key. --update preserves existing bindings.
  • Gemini may require folder trust and MCP consent. Setup does not grant trust. Invite teammates from the dashboard so each gets their own key for the same shared workspace.

Troubleshooting config formats

Normal setup writes these automatically. Use this section only when a client does not show Engram tools after restart and you need to inspect the file shape.

Antigravity

Google's current Gemini flow may route users into Antigravity. Engram writes both the shared Gemini config and Antigravity-specific config files.

// ~/.gemini/config/mcp_config.json
// ~/.gemini/antigravity/mcp_config.json
{
"mcpServers": {
"engram": {
"command": "npx",
"args": ["-y", "engram-tools@latest", "mcp"]
}
}
}

OpenCode

OpenCode uses a command array instead of the standard mcpServers shape. The setup command writes that format automatically.

// ~/.config/opencode/opencode.json
{
"mcp": {
"engram": {
"type": "local",
"command": ["npx", "-y", "engram-tools@latest", "mcp"],
"enabled": true
}
}
}

Codex

Codex uses TOML. Engram replaces only the engram table and preserves the rest of your Codex config.

# ~/.codex/config.toml
[mcp_servers.engram]
type = "stdio"
command = "npx"
args = ["-y", "engram-tools@latest", "mcp"]
Optional first-session prompt

Engram also guides agents through MCP. This prompt makes the first session explicit and helps the agent use recall, cross-pollination, and rehydrate at the right moments.

The welcome email includes this too. Docs keep it here as a fallback when an AI client ignores MCP startup guidance.

Call engram_start with this project context:
project: <product or client>
repo: <repo slug>
role: <what you are doing>
market: <domain or market>
stack: <main technologies>
task: <current task>
Before choosing an approach, call engram_recall.
If another repo may have solved this pattern, call engram_cross_pollinate.
If this chat was compacted or resumed, call engram_rehydrate before continuing.

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_start

Workspace briefing and relevant memory

Answer one concrete question

engram_recall

Ranked memories for that question

Change task with context intact

engram_smarter

A new task briefing

Resume after lost context

engram_rehydrate

Safe journal recovery and current-memory fallback

Checkpoint a milestone

engram_reflect

A 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.

Tools

Select one tool to inspect

Core loop

Tools agents use in normal coding flow, plus recovery after compaction.

Advanced and checkpoints

Keep these available, but use them only when their trigger is real.

Select one tool to inspect
engram_start

Call first after setup/restart, before the agent starts making product or code decisions.

engram_start

Start a new agent session with one canonical call.

Call first after setup/restart, before the agent starts making product or code decisions.

session_id
optional
string

Exact journal id from start/rehydrate/list_sessions. Disambiguates parallel work; writing requires your active session. Rehydrate may read shared or closed history.

agent_tool
optional
string

Calling client name for attribution, e.g. codex, claude-code, cursor, or gemini. Omit if unknown.

project
recommended
string

Product/project name for session context. Start/setup use it as the repository hint when repo is omitted.

repo
recommended
string

Repository slug, e.g. engram or billing-api, within the authenticated workspace. This is a memory filter, not a filesystem path or workspace selector.

role
optional
string

Agent responsibility used in task context, e.g. backend engineer. Start/setup default to implementation agent.

market
optional
string

Business/domain context, e.g. fintech or education; not a geographic access setting.

task
recommended
string

Concrete current goal or decision, e.g. diagnose checkout retries; used to focus context and session recovery.

stack
optional
string[]

Project technologies used to focus context; omit when unknown.

context
optional
string

Optional full task context; overrides the query generated from project, role, market, stack and task.

new_session
optional
boolean

Default false reuses one eligible active journal. True creates a separate journal for parallel work; retries can create another session. Keep the returned session_id.

include_skills
optional
boolean

Include relevant procedural checklists. If omitted, the server infers this from task/context keywords; false suppresses checklists.

limit
optional
number

Maximum retrieved memories, 1–30. Omitted defaults: focused=8, deep=16; explicit values override these defaults.

depth
optional
focused | deep

Default focused uses a small retrieval budget; deep expands it when focused results are insufficient. An explicit limit overrides the default budget.

pending_feedback
optional
object[]

Batch feedback for earlier retrieval_ids, committed independently before this action. Requires outcome:write; same actual-use feedback is safe to retry. No extra call quota. Omit unassessed results.

Keep reading

What is MCP?

The standard that makes Engram possible.

πŸ“‘

An open standard by Anthropic

MCP (Model Context Protocol) is an open standard created by Anthropic. It lets AI agents connect to external tools and data sources through a simple, universal interface.

πŸ”Œ

USB for AI

Think of it like USB for AI: one standard, every tool works. No custom integrations, no proprietary SDKs, no vendor lock-in. If your tool speaks MCP, it just works.

🧠

Engram is an MCP server

Any MCP-compatible AI tool can connect to Engram. Claude Code, Cursor, Gemini, Antigravity, Copilot, OpenCode, Windsurf, Devin. If it supports MCP, it supports Engram.

⚑

Zero integration effort

No SDK needed. No custom integration code. Just add Engram to your agent's MCP config and it gets Engram memory tools instantly.

How it connects

Your Agent

Claude, Cursor, etc.

MCP
➞

Engram

MCP Server

store/recall
➞

Team Memory

PostgreSQL + pgvector

Workspaces are your team boundary

Use one workspace for a team. Repos organize project memory inside it. Invite teammates from the dashboard so everyone gets their own key.

Frontend repo

Tools

Claude CodeCursorCopilot
Memories45

API repo

Tools

Claude CodeWindsurf
Memories128

Mobile repo

Tools

CursorDevin
Memories67

What a workspace means

  • βœ“The workspace is the private memory boundary for one team or company.
  • βœ“Repos and projects organize memories inside that boundary.
  • βœ“Teammates should be invited from the dashboard so each person has a separate key.
  • βœ“Agents in the same workspace can reuse private lessons across repos.
  • βœ“Different workspaces stay isolated; public memory can still enrich results.
workspace-sync.sh
$ engram_get_context({ repo: "api-backend" })

Start ahead, not from scratch

Every new workspace starts with 100,000 source-aware public memories across agent tools, MCP, RAG/search, security, ops, engineering docs, and product/devex.

100K
Public memories
7
Source families
20
Skill guides
πŸ”„
Agent
Patterns
Proven approaches
Patterns

Proven approaches for common tasks. Example: "API route pattern: try-catch wrapper, validate input, check auth, then business logic." Patterns tell you HOW to do something the right way.

πŸ“
MCP
Conventions
Team rules and standards
Conventions

Team rules and coding standards. Example: "Always use Prisma migrations, never raw SQL ALTER TABLE." Conventions keep your codebase consistent.

⚠️
Risk
Gotchas
Traps and surprises
Gotchas

Things that break or surprise you. Example: "async/await inside forEach does NOT work as expected. Use for...of instead." Gotchas save you hours of debugging.

πŸ”§
Ops
Solutions
Battle-tested fixes
Solutions

Battle-tested fixes for common problems. Example: "Hydration mismatch in Next.js: use useEffect for client-only logic." Solutions give you the answer, not just the hint.

πŸ“¦
Stack
Dependencies
Framework-specific
Dependencies

Version-specific knowledge for frameworks. Example: "Prisma 7 requires PrismaPg adapter pattern." Dependencies prevent upgrade surprises.

πŸŽ“
20
Skill Guides
Step-by-step guides
Skill Guides

Step-by-step guides for complex tasks. Example: "Code Review Skill: 15 steps from pulling the branch to approving." Skills give your agent expertise on demand.

Sourced from: Covering: React, Next.js, Vue, Angular, Python, Go, Rust, TypeScript, PostgreSQL, Docker, Kubernetes, AWS, and 25+ more technologies. Plus business skills: Product Management, Sales, Marketing, HR, Legal, Finance, and more.

Other agents start empty. Yours starts with 100,000 source-aware public memories, 20 step-by-step guides, and a private workspace bank that compounds from day one.

Two memory banks. One smart agent.

Public knowledge for everyone. Private knowledge for your team.

🌍
100K

Public Memory Bank

  • βœ“100,000 source-aware public memories
  • βœ“Agent tools, MCP, RAG/search, security, ops, and devex
  • βœ“20 step-by-step guides
  • βœ“Best-practice patterns, gotchas, solutions, and evidence checks
  • βœ“Updates as the public bank grows
  • βœ“Available to every Engram user
FREE for all plans
πŸ”’
isolated

Private Memory Bank

  • βœ“Your team's proprietary knowledge
  • βœ“Conventions specific to your codebase
  • βœ“Internal architecture decisions
  • βœ“Incident learnings and post-mortems
  • βœ“Never shared outside your workspace
  • βœ“Isolated, encrypted, workspace-scoped
Your competitive edge
Agent recalls
↓
Searches Private first
↓
Enriches with Public
↓
Best combined results
Combined recall

Private memory first. Public knowledge fills the gaps.

Engram searches your workspace knowledge first, then adds source-aware public practices and guides when they help.

engram_start

Support Loop

Help us make Engram sharper

If setup is confusing, a tool behaves strangely, or a pricing limit feels wrong, send it here. The message lands directly with us.

Feedback

Tell us what is missing

Bugs, confusing setup steps, pricing questions, and product ideas go straight to the Engram team.

Verify your email before your feedback reaches our team. This does not create an account.

10 more characters needed0/4000