> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Gentleman-Programming/engram/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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
```

<Note>
  **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.
</Note>

## 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**:

```json theme={null}
{
  "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"
}
```

<Tip>
  **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
</Tip>

**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**:

```bash theme={null}
mem_search(query="auth middleware", type="decision", limit=5)
```

<Info>
  FTS5 query sanitization wraps each word in quotes to avoid syntax errors. Query "fix auth bug" becomes `"fix" "auth" "bug"`.
</Info>

### 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**:

```markdown theme={null}
## 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]
```

<Warning>
  **This is NOT optional.** Call `mem_session_summary` before ending a session or saying "done". If you skip this, the next session starts blind.
</Warning>

## 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**:

```text theme={null}
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)

<Note>
  Use `mem_update` when you have an exact observation ID to correct. For evolving topics, prefer `mem_save` with `topic_key` (upsert pattern).
</Note>

### 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**:

```markdown theme={null}
## 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](#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

<CardGroup cols={2}>
  <Card title="Terminal UI" icon="terminal" href="/features/terminal-ui">
    Browse memories interactively with the TUI
  </Card>

  <Card title="Git Sync" icon="git-alt" href="/features/git-sync">
    Share memories across machines and team members
  </Card>

  <Card title="Privacy" icon="shield" href="/features/privacy">
    Redact sensitive data with privacy tags
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Install and configure Engram
  </Card>
</CardGroup>