Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/xantorres/engram/llms.txt

Use this file to discover all available pages before exploring further.

Engram’s MCP server exposes two tools that agents can call during a session. remember stages a new fact about the user for later human review; recall retrieves the set of already-promoted memories, ranked by relevance to an optional query. Both tools operate on the same local store as the CLI.

​
remember

Stages a durable fact about the user into the pending queue. The fact is not immediately visible to recall — it must be promoted by the human operator via the CLI (or auto-promoted if your config enables it for low-risk kinds). Return value: A plain string confirming the staged memory ID, kind, and fact text. 
staged mem-0042: [tooling] I prefer pnpm over npm

​
Parameters

​
fact
string
required
The assertion to store. Write facts in the first person from the user’s perspective — concise, declarative statements work best.Examples:
  • "I prefer pnpm over npm"
  • "My production Postgres runs on port 5433"
  • "I'm allergic to shellfish"
​
kind
string
default:"preference"
Semantic category of the fact. Determines the risk tier and whether the memory can be auto-promoted. Must be one of the ten valid kind values listed in the table below.
ValueDescriptionRisk tier
preferencePersonal style and tool choices1 — auto
toolingLanguage, framework, and build-tool decisions1 — auto
projectProject names, goals, and architectural choices1 — auto
infraInfrastructure topology, ports, hostnames1 — auto
identityName, handles, pronouns, biographical facts3 — curated
fiscalBilling, pricing, budget, financial preferences3 — curated
peopleContacts, teammates, relationships3 — curated
constraintHard requirements and non-negotiable rules3 — curated
locationPhysical or geographic context3 — curated
healthMedical, dietary, or wellness information3 — curated
Tier 3 (curated) kinds are never auto-promoted, even when autopromote = true. They always wait in the review queue for explicit CLI approval.
​
confidence
float
default:"0.6"
The agent’s confidence that this fact is accurate and durable, expressed as a value between 0.0 and 1.0. Lower values surface the memory to human review sooner; high-confidence facts from a reliable source can be set closer to 1.0.Typical ranges:
  • 0.5 – 0.7 — inferred from context, should be verified
  • 0.8 – 0.9 — user stated explicitly, likely stable
  • 1.0 — definitively confirmed, unlikely to change

​
Usage example

# Pseudo-code showing how an agent would invoke the tool
result = mcp.call_tool("remember", {
    "fact": "I prefer pnpm over npm",
    "kind": "tooling",
    "confidence": 0.9
})
# → "staged mem-0017: [tooling] I prefer pnpm over npm"
The returned ID (e.g. mem-0017) can be used in CLI commands to approve, reject, or inspect the specific pending memory: engram approve mem-0017.

​
recall

Returns the user’s promoted memories, ranked by relevance. Pending, rejected, and stale memories are excluded. Pass a query string to focus the results on a specific topic; omit it to receive the most globally relevant memories up to the limit. Return value: A JSON array of memory objects, ordered from most to least relevant.

​
Parameters

​
query
string
default:"\"\""
A free-text search string used to rank and filter the returned memories. When empty, all promoted memories are returned sorted by a default relevance heuristic (recency + confidence). When non-empty, memories are re-ranked by token overlap with the query, and low-scoring results are filtered out.Examples:
  • "database configuration" — surfaces infra and project memories about databases
  • "my name" — surfaces identity memories about the user’s name
  • "" — returns all promoted memories up to the limit
​
limit
integer
default:"20"
Maximum number of memories to return. The server applies this cap after ranking; the actual count may be lower if fewer promoted memories exist or if the query filters most results out.

​
Return format

Each element in the returned array is a flat object with four fields:
​
id
string
Unique memory identifier assigned at staging time, e.g. "mem-0001".
​
fact
string
The stored assertion, exactly as submitted via remember or harvested from a transcript.
​
kind
string
One of the ten kind values (preference, tooling, project, infra, identity, fiscal, people, constraint, location, health). See the Schema reference for full descriptions.
​
confidence
float
Confidence score between 0.0 and 1.0 as set at capture time.

​
Usage example

# Retrieve up to 5 memories relevant to "package manager"
memories = mcp.call_tool("recall", {
    "query": "package manager",
    "limit": 5
})

# Example response:
# [
#   {"id": "mem-0017", "fact": "I prefer pnpm over npm", "kind": "tooling", "confidence": 0.9},
#   {"id": "mem-0023", "fact": "Node projects use Volta for version pinning", "kind": "tooling", "confidence": 0.8}
# ]

# Retrieve all promoted memories (no filter)
all_memories = mcp.call_tool("recall", {})

# Returns up to 20 memories sorted by default relevance
For bulk context loading at the start of a session, prefer the memory://recall resource over the recall tool. The resource returns a pre-rendered text block that many clients can attach to the system prompt automatically without a tool call round-trip. See MCP Resources.

Build docs developers (and LLMs) love

Get started for freeTalk to us