Skip to main content
Engram exposes 14 MCP tools via stdio transport, making persistent memory available to any MCP-compatible AI agent — Claude Code, OpenCode, Gemini CLI, Codex, VS Code, Antigravity, Cursor, Windsurf, and more.

​
Tool Profiles

Engram supports tool profiles to load only the tools you need: 
engram mcp                    # all 14 tools (default)
engram mcp --tools=agent      # 11 tools agents actually use
engram mcp --tools=admin      # 3 tools for TUI/CLI (delete, stats, timeline)
engram mcp --tools=agent,admin # combine profiles
engram mcp --tools=mem_save,mem_search # individual tool names
Agent profile includes tools referenced in skill files and memory protocol instructions across all 4 supported agents (Claude Code, OpenCode, Gemini CLI, Codex).Admin profile contains tools only used in the TUI and CLI, not referenced in any agent instructions.

​
All Tools Overview

ToolProfileDescriptionUse Case
mem_saveagentSave a structured observationAfter bugfixes, decisions, discoveries
mem_searchagentFull-text search across memoriesFind past work, decisions, patterns
mem_contextagentGet recent memory contextSession startup, post-compaction recovery
mem_session_summaryagentSave end-of-session summaryMandatory before session ends
mem_session_startagentRegister session startTrack session lifecycle
mem_session_endagentMark session completedClose active session
mem_get_observationagentGet full observation contentDrill into search results
mem_suggest_topic_keyagentSuggest stable topic keyBefore saving evolving topics
mem_capture_passiveagentExtract learnings from textAutomatic knowledge capture
mem_save_promptagentSave user promptsRecord user intent for future sessions
mem_updateagentUpdate observation by IDCorrect existing memories
mem_deleteadminDelete observationManual curation, cleanup
mem_statsadminMemory system statisticsDashboard, monitoring
mem_timelineadminChronological context around observationProgressive disclosure pattern

​
Core Memory Tools

​
mem_save

Purpose: Save structured observations proactively after significant work. Parameters:
  • title (required): Short, searchable title (e.g. “JWT auth middleware”, “Fixed N+1 query”)
  • content (required): Structured content using **What**, **Why**, **Where**, **Learned** format
  • type: Category — decision, architecture, bugfix, pattern, config, discovery, learning (default: manual)
  • session_id: Session ID to associate with (default: manual-save-{project})
  • project: Project name
  • scope: project (default) or personal
  • topic_key: Optional topic identifier for upserts (e.g. architecture/auth-model)
Example: 
{
  "title": "Switched from sessions to JWT",
  "type": "decision",
  "content": "**What**: Replaced express-session with jsonwebtoken for auth\n**Why**: Session storage doesn't scale across multiple instances\n**Where**: src/middleware/auth.ts, src/routes/login.ts\n**Learned**: Must set httpOnly and secure flags on the cookie, refresh tokens need separate rotation logic",
  "scope": "project"
}
When to save (mandatory — not optional):
  • ✅ Bug fix completed
  • ✅ Architecture or design decision made
  • ✅ Non-obvious discovery about the codebase
  • ✅ Configuration change or environment setup
  • ✅ Pattern established (naming, structure, convention)
  • ✅ User preference or constraint learned
Memory Hygiene:
  • Exact duplicates are deduplicated in a rolling 15-minute window using normalized content hash + project + scope + type + title
  • When topic_key is provided, mem_save upserts the latest observation in the same project + scope + topic_key, incrementing revision_count
  • Different topics must use different keys so they never overwrite each other
Purpose: Full-text search across all sessions using SQLite FTS5. Parameters:
  • query (required): Search query — natural language or keywords
  • type: Filter by type (e.g. bugfix, decision, architecture)
  • project: Filter by project name
  • scope: Filter by scope (project or personal)
  • limit: Max results (default: 10, max: 20)
Returns: Compact results with IDs, titles, content preview (~100 tokens each). Example: 
mem_search(query="auth middleware", type="decision", limit=5)
FTS5 query sanitization wraps each word in quotes to avoid syntax errors. Query “fix auth bug” becomes "fix" "auth" "bug".

​
mem_context

Purpose: Get recent memory context from previous sessions. Shows recent sessions and observations. Parameters:
  • project: Filter by project (omit for all projects)
  • scope: Filter observations by scope — project (default) or personal
  • limit: Number of observations to retrieve (default: 20)
When to use:
  • Session startup (recover previous work)
  • After compaction or context reset (mandatory recovery step)
  • When user asks “what were we working on?“

​
mem_session_summary

Purpose: Save comprehensive end-of-session summary using structured format. Parameters:
  • content (required): Full session summary using Goal/Instructions/Discoveries/Accomplished/Files format
  • session_id: Session ID (default: manual-save-{project})
  • project (required): Project name
Required Format: 
## Goal
[One sentence: what were we building/working on in this session]

## Instructions
[User preferences, constraints, or context discovered during this session. Skip if nothing notable.]

## Discoveries
- [Technical finding, gotcha, or learning 1]
- [Technical finding 2]
- [Important API behavior, config quirk, etc.]

## Accomplished
- ✅ [Completed task 1 — with key implementation details]
- ✅ [Completed task 2 — mention files changed]
- 🔲 [Identified but not yet done — for next session]

## Relevant Files
- path/to/file.ts — [what it does or what changed]
- path/to/other.go — [role in the architecture]
This is NOT optional. Call mem_session_summary before ending a session or saying “done”. If you skip this, the next session starts blind.

​
Progressive Disclosure Tools

Token-efficient memory retrieval pattern — don’t dump everything, drill in: Find relevant observations (compact results with IDs).

​
2. mem_timeline

Drill into chronological neighborhood of a specific result. Parameters:
  • observation_id (required): The observation ID to center the timeline on
  • before: Number of observations to show before the focus (default: 5)
  • after: Number of observations to show after the focus (default: 5)
Returns: Timeline showing observations before/after the focus, session info, and total observations in range.

​
3. mem_get_observation

Get full untruncated content of a specific observation. Parameters:
  • id (required): The observation ID to retrieve
Returns: Complete observation with full content, metadata, duplicate count, revision count, and topic key.

​
Topic Key Workflow

Use this when a topic evolves over time (architecture, long-running feature decisions, etc.):

​
mem_suggest_topic_key

Purpose: Suggest a stable topic_key for memory upserts before saving. Parameters:
  • type: Observation type/category (e.g. architecture, decision, bugfix)
  • title: Observation title (preferred input for stable keys)
  • content: Observation content (fallback if title is empty)
Returns: Suggested topic key using family heuristics:
  • architecture/* for architecture/design/ADR-like changes
  • bug/* for fixes, regressions, errors, panics
  • decision/*, pattern/*, config/*, discovery/*, learning/* when detected
Example workflow: 
1. mem_suggest_topic_key(type="architecture", title="Auth architecture")
   → "architecture-auth-architecture"

2. mem_save(..., topic_key="architecture-auth-architecture")
   → Creates new observation

3. Later change on same topic:
   mem_save(..., topic_key="architecture-auth-architecture")
   → Updates existing observation (revision_count++)

​
Session Lifecycle Tools

​
mem_session_start

Purpose: Register the start of a new coding session. Parameters:
  • id (required): Unique session identifier
  • project (required): Project name
  • directory: Working directory

​
mem_session_end

Purpose: Mark a session as completed with optional summary. Parameters:
  • id (required): Session identifier to close
  • summary: Summary of what was accomplished

​
Additional Tools

​
mem_update

Purpose: Update an existing observation by ID. Supports partial updates. Parameters:
  • id (required): Observation ID to update
  • title: New title
  • content: New content
  • type: New type/category
  • project: New project value
  • scope: New scope (project or personal)
  • topic_key: New topic key (normalized internally)
Use mem_update when you have an exact observation ID to correct. For evolving topics, prefer mem_save with topic_key (upsert pattern).

​
mem_save_prompt

Purpose: Save user prompts — records what the user asked so future sessions have context about user goals. Parameters:
  • content (required): The user’s prompt text
  • session_id: Session ID to associate with (default: manual-save-{project})
  • project: Project name

​
mem_capture_passive

Purpose: Extract and save structured learnings from text output automatically. Parameters:
  • content (required): Text containing a ## Key Learnings: section with numbered or bulleted items
  • session_id: Session ID (default: manual-save-{project})
  • project: Project name
  • source: Source identifier (e.g. subagent-stop, session-end)
How it works:
  • Looks for sections like ## Key Learnings: or ## Aprendizajes Clave:
  • Extracts numbered or bulleted items
  • Each item is saved as a separate observation
  • Duplicates are automatically detected and skipped
Example: 
## Key Learnings:

1. bcrypt cost=12 is the right balance for our server performance
2. JWT refresh tokens need atomic rotation to prevent race conditions

​
Admin Tools

These tools are NOT referenced in any agent skill or memory protocol. They’re used by the TUI, CLI, and manual curation.

​
mem_delete

Purpose: Delete an observation by ID. Parameters:
  • id (required): Observation ID to delete
  • hard_delete: If true, permanently deletes the observation (default: false for soft-delete)
Behavior:
  • Soft-delete (default): Sets deleted_at timestamp. Observation is excluded from search, context, and recent lists.
  • Hard-delete: Permanently removes the observation from the database.

​
mem_stats

Purpose: Show memory system statistics. Returns: Total sessions, observations, prompts, and list of projects tracked.

​
mem_timeline

See Progressive Disclosure Tools above.

​
Server Instructions

Engram’s MCP server includes instructions that help MCP clients (especially Claude Code’s Tool Search) know when to search for these tools:
Engram provides persistent memory that survives across sessions and context compactions. Search these tools when you need to: save decisions, bugs, architecture choices, or discoveries to memory; recall or search past work from previous sessions; manage coding session lifecycle (start, end, summarize); recover context after compaction. Key tools: mem_save, mem_search, mem_context, mem_session_summary, mem_get_observation, mem_suggest_topic_key.

Terminal UI

Browse memories interactively with the TUI

Git Sync

Share memories across machines and team members

Privacy

Redact sensitive data with privacy tags

Quickstart

Install and configure Engram

Build docs developers (and LLMs) love

Get started for freeTalk to us