Skip to main content
The 3ngram MCP server exposes the following memory tools. Every entry is generated from the tool’s source signature and docstring, so this page never drifts from the backend.
Required parameters are marked with the required attribute. Optional parameters show their default value.

​
archive_memories

Archive Memories · writes · destructive · idempotent · closed-world Bulk-archive memories (sets status=‘archived’; removed from default search_memories results). Pass include_archived=True or status=‘archived’ to search_memories to see them again. Returns: str Source: backend/src/engram/mcp/tools/memory/lifecycle.py

​
Parameters

​
memory_ids
list[int]
required
List of memory IDs to archive

​
batch_reclassify

Batch Reclassify (deprecated) · writes · non-destructive · idempotent · closed-world Deprecated alias for batch_reclassify_memories — bulk memory_type update. Forwards to batch_reclassify_memories without modification. This alias is kept for backward compatibility with managed-agents allowlists and external clients that pinned the legacy name; it will be removed in a future release. New callers should use batch_reclassify_memories. Returns: str Source: backend/src/engram/mcp/tools/memory/lifecycle.py

​
Parameters

​
memory_ids
list[int]
required
List of memory IDs to reclassify
​
new_type
str
required
The new memory type (decision, commitment, blocker, preference, pattern, note). Legacy alias: context

​
batch_reclassify_memories

Batch Reclassify Memories · writes · non-destructive · idempotent · closed-world Bulk-change memory_type for many memories in one call. Content is not modified. For a single memory use reclassify_memory. Returns: str Source: backend/src/engram/mcp/tools/memory/lifecycle.py

​
Parameters

​
memory_ids
list[int]
required
List of memory IDs to reclassify
​
new_type
str
required
The new memory type (decision, commitment, blocker, preference, pattern, note). Legacy alias: context

​
configure_scope

Configure Scope · writes · non-destructive · idempotent · closed-world Bind a project name to a scope (‘work’ or ‘personal’) with optional aliases. Future memories auto-inherit this scope when tagged with the project or an alias. User-configured mappings take precedence over the default scope config. Aliases are alternative project names that resolve to this project. For example, aliases=[“dev”, “engineering”] with project=“consulting” means memories tagged with project “dev” or “engineering” inherit the scope configured for “consulting”. Returns: str Source: backend/src/engram/mcp/tools/memory/lifecycle.py

​
Parameters

​
project
str
required
Project name (case-insensitive, will be lowercased)
​
scope
str
required
Life context scope — ‘work’ or ‘personal’
​
aliases
list[str] | None
default:"None"
Optional list of alias names that should resolve to this project

​
reapply_scope_mappings

Reapply Scope Mappings · writes · non-destructive · idempotent · closed-world Re-apply the current scope→project mapping to existing memories whose scope is stale. Useful after adding or changing scope mappings via configure_scope. Returns: str Source: backend/src/engram/mcp/tools/memory/lifecycle.py This tool takes no parameters.

​
reclassify_memory

Reclassify Memory · writes · non-destructive · idempotent · closed-world Change a single memory’s memory_type (e.g., note → decision). Does not modify content. For many at once use batch_reclassify_memories. Returns: str Source: backend/src/engram/mcp/tools/memory/lifecycle.py

​
Parameters

​
memory_id
int
required
The ID of the memory to reclassify
​
new_type
str
required
The new memory type (decision, commitment, blocker, preference, pattern, note). Legacy alias: context

​
remember

Remember · writes · non-destructive · non-idempotent · closed-world Persist a new memory (decision, commitment, blocker, preference, pattern, or note) for retrieval across future sessions. Writes a fresh memory — to search existing memories use search_memories; to change an existing memory’s type use reclassify_memory. Returns: str Source: backend/src/engram/mcp/tools/memory/remember.py

​
Parameters

​
topic
str
required
Short topic label (e.g., ‘Engram architecture’, ‘User preference’)
​
content
str
required
The memory content to persist
​
tags
list[str] | None
default:"None"
Optional tags for categorization
​
memory_type
str
default:"'note'"
One of: decision, commitment, blocker, preference, pattern, note. Legacy alias: context
​
project
str | None
default:"None"
Optional project name to associate with this memory
​
urgency
str | None
default:"None"
Optional urgency level
​
expires_at
str | None
default:"None"
Optional ISO 8601 expiration timestamp (e.g., ‘2026-03-01T00:00:00Z’)
​
due_date
str | None
default:"None"
Optional due date for commitments (ISO 8601 date, e.g., ‘2026-03-01’)
​
scope
str | None
default:"None"
Optional life context (‘personal’ or ‘work’). Auto-derived from project if omitted.
​
source
str
default:"'mcp'"
Memory origin. Defaults to ‘mcp’ since this tool is called by AI agents (Claude, Cursor, etc.) via the MCP protocol. Other values: ‘manual’ (user typed it into the dashboard), ‘hook’ (PostToolUse auto-capture), ‘integration’ (third-party sync), ‘onboarding’ (setup flow). Reserved: ‘auto’ (system only).
​
status
str
default:"'open'"
Initial status: ‘open’ (default), ‘waiting’, or ‘scheduled’. Use ‘waiting’ for commitments blocked on external input, ‘scheduled’ for intentionally deferred work.
​
recurrence
str | None
default:"None"
Optional JSON for recurring commitments. Keys: frequency, interval, end_date
​
mode
str
default:"'auto'"
Consolidation intent. One of: ‘auto’ (default, current behaviour), ‘merge’ (force merge when above similarity threshold), ‘cluster’ (skip merge; link via cluster_members instead when similar in-recency match exists), ‘new’ (skip both merge and cluster, always create a fresh memory). Hash-dedup within the 60-second window still applies to every mode.
​
atomic
bool
default:"False"
Mark this memory as a standing reference that should be retrieved as one unit rather than treated as chunkable source material.
​
promoted_from_chunk_id
int | None
default:"None"
Optional content_chunks.id when this memory is a curated promotion of an indexed chunk. Implies atomic=True.
​
entity_id
int | None
default:"None"
Required for fact writes unless entity_name is provided.
​
entity_name
str | None
default:"None"
Required for fact writes unless entity_id is provided.
​
attribute
str | None
default:"None"
Fact attribute for explicit fact writes.
​
value
Any
default:"None"
Fact value for explicit fact writes.
​
valid_from
datetime | None
default:"None"
Optional fact validity start for explicit fact writes.
​
valid_until
datetime | None
default:"None"
Optional fact validity end for explicit fact writes.
​
immutable
bool
default:"False"
Mark a fact as immutable so it cannot be superseded automatically.

​
search_memories

Search Memories · read-only · non-destructive · idempotent · closed-world Semantic search over stored memories (commitments, decisions, preferences, blockers, patterns, notes) — not indexed documents. Use search_content for documents. Response shape: the raw function returns formatted markdown for human consumption; when invoked via MCP, the transport layer attaches a structuredContent payload matching SearchMemoriesResponse ({results, cluster_siblings, total, resolved_sort, query, embedding_model}) so agent hosts can parse results deterministically. Each hit carries both raw similarity (float in [0,1]) and a corpus-relative relevance label ("high" / "medium" / "low"). Prefer branching on relevance — raw cosine values are not portable across environments (prod and staging corpora differ). high means “top of this query’s distribution”, low means “tail noise for this query”. Returns: str Source: backend/src/engram/mcp/tools/memory/recall.py

​
Parameters

​
topic
str
required
What you’re looking for (natural language)
​
limit
int
default:"5"
Max memories to return (default 5)
​
memory_type
str | None
default:"None"
Filter by type (decision, commitment, blocker, preference, pattern, note). Legacy alias: context
​
project
str | None
default:"None"
Filter by project name
​
status
str | None
default:"None"
Filter by status (open, waiting, scheduled, resolved, expired, overdue, archived). Default returns all active (open + waiting + scheduled).
​
created_after
str | None
default:"None"
ISO 8601 timestamp — only return memories created on or after this date
​
due_before
str | None
default:"None"
ISO 8601 date — only return memories with due_date on or before this date
​
scope
str | None
default:"None"
Optional life context filter (‘personal’ or ‘work’)
​
source
str | None
default:"None"
Filter by memory origin (‘manual’, ‘hook’, ‘auto’)
​
tag
str | None
default:"None"
Filter by tag (exact match, e.g. ‘deploy’ returns memories tagged with ‘deploy’)
​
brief
bool
default:"False"
If True, return compact one-line-per-memory format for scanning
​
sort_by
Literal['auto', 'relevance', 'similarity', 'recency', 'recent', 'hybrid', 'updated']
default:"'auto'"
Sort order. Finite set:
  • ‘relevance’ (alias ‘similarity’) — pure cosine similarity ranking with recall boost + temporal decay. Best default for topical queries.
  • ‘recency’ (alias ‘recent’) — newest first. Filters by similarity_floor then sorts by created_at DESC, so “recent matches” means exactly that (not “globally newest with weak relevance bias”).
  • ‘hybrid’ — 0.7cosine + 0.3BM25 keyword blend. Use when topic contains specific proper nouns that embeddings alone miss.
  • ‘updated’ — legacy; ORDER BY updated_at DESC.
  • ‘auto’ (default) — detect temporal keywords in topic (today, recent, last week, …) and route to ‘recency’; otherwise ‘relevance’.
​
include_archived
bool
default:"False"
If True, include archived memories in results (default False)
​
atomic_only
bool
default:"False"
If True, return only memories marked atomic (standing references such as protocols, playbooks, and routines).
​
expand_clusters
Literal['always', 'auto', 'never']
default:"'auto'"
Cluster-sibling expansion policy.
  • ‘auto’ (default) — expand only when fewer than 3 primary results survive the similarity_floor. Prevents sibling flood on dense queries while still helping sparse ones.
  • ‘always’ — always append cluster siblings of top matches.
  • ‘never’ — skip sibling expansion entirely. Expanded rows are marked via_cluster: true for the caller.
​
similarity_floor
float
default:"0.3"
Drop results whose similarity is below this threshold, applied before ordering. Range [0.0, 1.0], default 0.3. Zero disables the filter. Returning an empty set here is meaningful: it signals “no relevant matches” (vs. silently cluster-expanding).
​
explain
bool
default:"False"
If True, include retrieval metadata (similarity scores, index used, re-ranking details, embedding stats) for each result