MCP Tools

Complete reference for Engram’s 14 Model Context Protocol tools

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

Tool	Profile	Description	Use Case
mem_save	agent	Save a structured observation	After bugfixes, decisions, discoveries
mem_search	agent	Full-text search across memories	Find past work, decisions, patterns
mem_context	agent	Get recent memory context	Session startup, post-compaction recovery
mem_session_summary	agent	Save end-of-session summary	Mandatory before session ends
mem_session_start	agent	Register session start	Track session lifecycle
mem_session_end	agent	Mark session completed	Close active session
mem_get_observation	agent	Get full observation content	Drill into search results
mem_suggest_topic_key	agent	Suggest stable topic key	Before saving evolving topics
mem_capture_passive	agent	Extract learnings from text	Automatic knowledge capture
mem_save_prompt	agent	Save user prompts	Record user intent for future sessions
mem_update	agent	Update observation by ID	Correct existing memories
mem_delete	admin	Delete observation	Manual curation, cleanup
mem_stats	admin	Memory system statistics	Dashboard, monitoring
mem_timeline	admin	Chronological context around observation	Progressive 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

mem_search

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:

1. mem_search

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.

Related

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