MCP tools

Engram registers 28 MCP tools. Both deployment profiles (lite and standard) expose the full set; the tools marked admin in the table below additionally require MCP_ADMIN_TOKEN.

Tool	Auth	Scope	Description
ping	public	—	Test connectivity to ENGRAM server
create_memory	identity	memories:write	Create a new memory in short-term or long-term storage
get_memory	identity	memories:read	Retrieve memory by ID
list_memories	identity	memories:read	List memories with pagination and filtering
update_memory	identity	memories:write	Update an existing memory. expectedVersion is required (optimistic concurrency): pass the version returned by get_memory or a prior read. Blind updates are rejected, and a stale version fails with a CONFLICT error — re-read the memory and retry with the fresh version.
delete_memory	identity	memories:delete	Delete memory by ID
bulk_delete_memories	identity	memories:delete	Delete up to 100 memories in a single call, returning a per-item report of deleted ids and failures. STM/LTM routing and scope isolation are inherited per id.
promote_memory	identity	memories:write	Promote short-term memory to long-term storage
reembed_memory	identity	memories:write	Regenerate the vector for a long-term memory’s current content and clear its embeddingStale flag. Repairs recall drift left by a content edit made while the embeddings provider was unavailable.
restore_memory	identity	memories:write	Recreate a hard-deleted memory from its most recent delete audit snapshot, preserving its original id. Requires the audit trail.
get_memory_audit	identity	memories:read	Read the append-only audit history (update/delete/promote/reembed/restore) for a memory, newest first.
recall	identity	memories:read	Semantically recall the most relevant long-term memories for a natural-language query — the primary retrieval tool; reach for it before starting any task the user may have stored context on. Embeds the query and searches the pgvector index, re-ranking hits by blended similarity, recency, and importance. Superseded memories never resurface. Supports scope, tag, and created-date filters; use list_memories instead for exact, non-semantic listing.
export_memories	identity	memories:read	Export a user’s memories as an Obsidian-compatible markdown vault (YAML frontmatter + [[wikilinks]] preserving inter-memory relationships). Bounded exports return documents + manifest inline; larger exports return a server path reference.
import_agent_memory	admin	—	Import agent memory files (Claude/Copilot/Cursor/Codex/Gemini/markdown) from a server-side path into long-term memory, preserving inter-memory links. Admin-gated; idempotent; supports dryRun and a secrets policy. Never overwrites a memory edited inside ENGRAM since its last import: such facts are skipped and counted as skippedConcurrentEdit in the summary (CAS-skip).
reindex_memories	admin	—	Rebuild the vector store from Postgres (admin/maintenance). Backfills embeddings for one user or all users; idempotent and cursor-resumable. Run it after changing the embedding model/provider (set reuseExistingEmbeddings=false and recreate=true so the index is rebuilt at the new dimensionality), or losing/corrupting the vector index. Synchronous — blocks until the pass completes and returns the processed/indexed/skipped/failed summary; prefer queue_reindex_memories for large corpora.
queue_reindex_memories	admin	—	Queue an asynchronous vector reindex and return a jobId immediately — the right choice for large corpora or any rebuild you should not block on. Supports the same options as reindex_memories, including recreate for embedding model/dimension changes. Jobs persist progress (with a resume cursor) in Postgres and run strictly one at a time. Poll with get_reindex_status; cancel_reindex_job / retry_reindex_job manage the job from its persisted cursor.
get_reindex_status	admin	—	Get status and progress for a queued reindex job (queued/running/completed/failed). Pass the jobId returned by queue_reindex_memories; the report includes per-item progress counts and the persisted resume cursor.
cancel_reindex_job	admin	—	Cancel a queued/running reindex job and preserve progress cursor
retry_reindex_job	admin	—	Retry a failed/cancelled reindex job from its last persisted cursor
consolidate_memories	admin	—	Trigger a synchronous STM→LTM consolidation pass (admin). Promotes short-term memories that meet the access-count and importance thresholds into long-term storage; a scheduled pass already runs every STM_CONSOLIDATION_INTERVAL_MS (default 5 min), so call this only when promotion must happen now — e.g. before an export, migration, or shutdown. Idempotent (already-promoted rows are skipped). NOT corpus consolidation — near-duplicate merging is consolidate_corpus.
consolidate_corpus	admin	—	Corpus consolidation (admin): cluster NEAR-duplicate long-term memories in the [MEMORY_CONSOLIDATION_MERGE_THRESHOLD, MEMORY_DUPLICATE_THRESHOLD) similarity band, keep one canonical per cluster (highest importance, most recent on ties), union tags onto it, and mark the rest superseded + linked. NOT consolidate_memories (the unrelated STM→LTM promotion pass). Review-gated: dryRun defaults to TRUE and reports would-be merges without mutating — pass dryRun=false explicitly to merge. Idempotent and cursor-resumable.
remember	identity	memories:write	Smart create: auto-detects short-term vs long-term storage from content heuristics, deduplicates against existing memories, and returns the stored memory with routing metadata. The preferred write path for agents — store durable facts as you learn them; re-storing a known fact is safe (absorbed by dedup). Use create_memory only when you must control the tier explicitly.
forget	identity	memories:delete	Smart delete: find memories by natural-language concept and optionally delete them. Dry-run by default — review the matches, then pass confirm=true to execute deletion. Use it when the user asks to remove or redact something described conceptually rather than by id; delete_memory removes a single known id.
reflect	identity	memories:read	Synthesise structured insights across all memories semantically relevant to a query. Returns a plain-text summary, extracted themes, source memory IDs, and date range. Use it for thematic questions (“what do we know about X?”) and periodic reviews where a synthesis beats a raw hit list — recall returns the individual memories instead.
compress_context	identity	memories:read	Retrieve memories most relevant to a query and format them into a compact, context-window-ready block within a character budget. Use it to inject task-specific background under a size limit measured in characters; prompt_context is the token-budgeted variant, and load_context primes a session when there is no query yet.
load_context	identity	memories:read	Load a session-priming context block by blending the most recent memories with the highest-importance memories. Needs no query — call it once at session start, before any task context exists, to inject into the session-opening prompt; switch to recall or compress_context once you have a concrete topic.
ingest_conversation	identity	memories:write	Bulk-ingest a conversation as per-turn long-term memories. Handles chunking for large turns, controls embedding back-pressure via concurrency, and is idempotent: re-submitting the same conversation returns the existing memory IDs.
prompt_context	identity	memories:read	Assemble a token-budgeted context block from memories most relevant to a query. Greedy-packs ranked memories within the token budget (1 token ≈ 4 chars) and returns the formatted block plus token accounting metadata. Use it when filling a fixed token allowance in a prompt template; compress_context is the character-budgeted variant.