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

# CLI Commands

> Complete reference for all Engram CLI commands

Engram provides a comprehensive command-line interface for managing persistent memory. All commands interact with the local SQLite database at `~/.engram/engram.db`.

## Installation

After installing Engram, the binary is available at `$GOPATH/bin/engram` (typically `~/go/bin/engram`).

## Usage

```bash theme={null}
engram <command> [arguments]
```

## Core Commands

### serve

Start the HTTP API server for agent integrations.

```bash theme={null}
engram serve [port]
```

<ParamField path="port" type="number" optional>
  Port number for the HTTP server. Default: `7437` (ENGR on phone keypad).
</ParamField>

**Examples:**

```bash theme={null}
# Start on default port 7437
engram serve

# Start on custom port
engram serve 8080

# Use environment variable to set port
ENGRAM_PORT=9000 engram serve
```

**Output:**

```
Engram HTTP server listening on http://127.0.0.1:7437
```

***

### mcp

Start the MCP (Model Context Protocol) server for AI agent integrations.

```bash theme={null}
engram mcp [--tools=PROFILE]
```

<ParamField path="--tools" type="string" optional>
  Filter which tools to expose. Options:

  * `agent` - 11 tools for AI coding agents
  * `admin` - 3 tools for manual curation (delete, stats, timeline)
  * `all` - All 14 tools (default)
  * Comma-separated profiles: `agent,admin`
  * Individual tool names: `mem_save,mem_search`
</ParamField>

**Tool Profiles:**

* **agent** (11 tools): `mem_save`, `mem_search`, `mem_context`, `mem_session_summary`, `mem_session_start`, `mem_session_end`, `mem_get_observation`, `mem_suggest_topic_key`, `mem_capture_passive`, `mem_save_prompt`, `mem_update`
* **admin** (3 tools): `mem_delete`, `mem_stats`, `mem_timeline`

**Examples:**

```bash theme={null}
# All tools (default)
engram mcp

# Only agent tools (recommended for production)
engram mcp --tools=agent

# Combine profiles
engram mcp --tools=agent,admin

# Specific tools only
engram mcp --tools=mem_save,mem_search,mem_context
```

**MCP Configuration Example:**

Add to your agent's config file:

```json theme={null}
{
  "mcp": {
    "engram": {
      "type": "stdio",
      "command": "engram",
      "args": ["mcp", "--tools=agent"]
    }
  }
}
```

***

### tui

Launch the interactive terminal UI for browsing memories.

```bash theme={null}
engram tui
```

**Features:**

* Browse sessions and observations
* Full-text search with FTS5
* View timelines and context
* Vim-style navigation (`j`/`k`, `Enter`, `Esc`)
* Catppuccin Mocha color scheme

**Output:**

```
┌─ Engram Memory ─────────────────────────┐
│ Sessions:     12                        │
│ Observations: 47                        │
│ Prompts:      23                        │
│ Projects:     my-app, api-server        │
└─────────────────────────────────────────┘
```

***

## Search & Retrieval

### search

Search memories using FTS5 full-text search.

```bash theme={null}
engram search <query> [--type TYPE] [--project PROJECT] [--scope SCOPE] [--limit N]
```

<ParamField path="query" type="string" required>
  Search query - natural language or keywords. Multiple words are automatically combined.
</ParamField>

<ParamField path="--type" type="string" optional>
  Filter by observation type: `decision`, `architecture`, `bugfix`, `pattern`, `config`, `discovery`, `learning`, `manual`
</ParamField>

<ParamField path="--project" type="string" optional>
  Filter by project name
</ParamField>

<ParamField path="--scope" type="string" optional>
  Filter by scope: `project` or `personal`
</ParamField>

<ParamField path="--limit" type="number" optional>
  Maximum results to return (default: 10)
</ParamField>

**Examples:**

```bash theme={null}
# Basic search
engram search "JWT authentication"

# Search with filters
engram search "bug fix" --type bugfix --project my-app

# Search across all projects
engram search "database migration" --limit 20

# Search personal scope only
engram search "learning golang" --scope personal
```

**Output:**

```
Found 3 memories:

[1] #42 (decision) — Switched to JWT tokens
    **What**: Replaced session-based auth with JWT
    **Why**: Better scalability for microservices
    **Where**: src/auth/middleware.ts
    2024-03-01 14:23:15 | project: my-app | scope: project

[2] #38 (bugfix) — Fixed token expiration bug
    **What**: Tokens were expiring too quickly
    **Why**: Misconfigured expiry time (1h instead of 24h)
    **Where**: config/jwt.go:15
    2024-02-28 09:15:42 | project: my-app | scope: project
```

***

### context

Show recent context from previous sessions.

```bash theme={null}
engram context [project]
```

<ParamField path="project" type="string" optional>
  Filter context by project name. If omitted, shows all recent context.
</ParamField>

**Examples:**

```bash theme={null}
# All recent context
engram context

# Project-specific context
engram context my-app
```

**Output:**

```
=== Recent Sessions ===

Session: my-app (2024-03-01 14:00:00)
Summary: Implemented JWT authentication and user profile endpoints

=== Recent Prompts ===

- "Add JWT authentication to the API"
- "Create user profile endpoint"

=== Recent Observations ===

#42 [decision] Switched to JWT tokens
#41 [architecture] REST API structure for user management
```

***

### timeline

Show chronological context around a specific observation.

```bash theme={null}
engram timeline <observation_id> [--before N] [--after N]
```

<ParamField path="observation_id" type="number" required>
  ID of the observation to center the timeline on
</ParamField>

<ParamField path="--before" type="number" optional>
  Number of observations to show before the target (default: 5)
</ParamField>

<ParamField path="--after" type="number" optional>
  Number of observations to show after the target (default: 5)
</ParamField>

**Examples:**

```bash theme={null}
# Default timeline (5 before, 5 after)
engram timeline 42

# Custom range
engram timeline 42 --before 10 --after 3
```

**Output:**

```
Session: my-app (2024-03-01 14:00:00) — JWT auth implementation
Total observations in session: 8

─── Before ───
  #40 [pattern] REST endpoint naming convention — Use plural nouns for resources
  #41 [architecture] User management API structure — Separate auth from user CRUD

>>> #42 [decision] Switched to JWT tokens <<<
    **What**: Replaced session-based auth with JWT
    **Why**: Better scalability for microservices  
    **Where**: src/auth/middleware.ts
    2024-03-01 14:23:15

─── After ───
  #43 [config] JWT secret environment variable — Added JWT_SECRET to .env
  #44 [bugfix] Fixed token parsing in middleware — Missing Bearer prefix check
```

***

## Memory Management

### save

Save a memory from the command line.

```bash theme={null}
engram save <title> <content> [--type TYPE] [--project PROJECT] [--scope SCOPE] [--topic TOPIC_KEY]
```

<ParamField path="title" type="string" required>
  Short, searchable title for the memory
</ParamField>

<ParamField path="content" type="string" required>
  Memory content. Use the structured format with **What**, **Why**, **Where**, **Learned**
</ParamField>

<ParamField path="--type" type="string" optional>
  Observation type: `decision`, `architecture`, `bugfix`, `pattern`, `config`, `discovery`, `learning` (default: `manual`)
</ParamField>

<ParamField path="--project" type="string" optional>
  Project name to associate with this memory
</ParamField>

<ParamField path="--scope" type="string" optional>
  Scope: `project` (default) or `personal`
</ParamField>

<ParamField path="--topic" type="string" optional>
  Topic key for upserts (e.g., `architecture/auth-model`). Memories with the same topic\_key in the same project+scope are updated instead of creating duplicates.
</ParamField>

**Examples:**

```bash theme={null}
# Basic save
engram save "JWT middleware" "**What**: Added JWT auth middleware\n**Why**: Required for API security" --type decision --project my-app

# Save with topic for upserts
engram save "API architecture" "**What**: REST API design\n**Why**: Scalability" --topic architecture/api --project my-app

# Personal scope memory
engram save "Golang learning" "**Learned**: Channels are typed" --scope personal
```

**Output:**

```
Memory saved: #42 "JWT middleware" (decision)
```

***

### stats

Show memory system statistics.

```bash theme={null}
engram stats
```

**Output:**

```
Engram Memory Stats
  Sessions:     12
  Observations: 47
  Prompts:      23
  Projects:     my-app, api-server, docs-site
  Database:     /Users/username/.engram/engram.db
```

***

## Import & Export

### export

Export all memories to JSON.

```bash theme={null}
engram export [filename]
```

<ParamField path="filename" type="string" optional>
  Output filename (default: `engram-export.json`)
</ParamField>

**Examples:**

```bash theme={null}
# Export to default file
engram export

# Export to custom filename
engram export backup-2024-03-01.json
```

**Output:**

```
Exported to engram-export.json
  Sessions:     12
  Observations: 47
  Prompts:      23
```

**Export Format:**

```json theme={null}
{
  "sessions": [
    {
      "id": "session-abc",
      "project": "my-app",
      "started_at": "2024-03-01T14:00:00Z",
      "summary": "Implemented JWT auth"
    }
  ],
  "observations": [
    {
      "id": 42,
      "session_id": "session-abc",
      "type": "decision",
      "title": "Switched to JWT tokens",
      "content": "**What**: Replaced sessions with JWT..."
    }
  ],
  "prompts": [
    {
      "id": 1,
      "session_id": "session-abc",
      "content": "Add JWT authentication"
    }
  ]
}
```

***

### import

Import memories from a JSON export file.

```bash theme={null}
engram import <filename>
```

<ParamField path="filename" type="string" required>
  JSON file to import (created by `engram export`)
</ParamField>

**Examples:**

```bash theme={null}
engram import engram-export.json
engram import backup-2024-03-01.json
```

**Output:**

```
Imported from engram-export.json
  Sessions:     12
  Observations: 47
  Prompts:      23
```

<Note>
  Import uses `INSERT OR IGNORE` for sessions to skip duplicates. All operations run in a single atomic transaction.
</Note>

***

## Git Sync

### sync

Export and import memories using Git-based chunked sync.

```bash theme={null}
engram sync [--import] [--status] [--project NAME] [--all]
```

<ParamField path="--import" type="boolean" optional>
  Import new chunks from `.engram/` directory into local database
</ParamField>

<ParamField path="--status" type="boolean" optional>
  Show sync status (local vs remote chunks, pending imports)
</ParamField>

<ParamField path="--project" type="string" optional>
  Filter export to a specific project. Default: current directory name
</ParamField>

<ParamField path="--all" type="boolean" optional>
  Export ALL projects (ignore directory-based filter)
</ParamField>

**Examples:**

```bash theme={null}
# Export new memories for current project
engram sync

# Export all projects
engram sync --all

# Export specific project
engram sync --project my-app

# Import chunks from .engram/
engram sync --import

# Check sync status
engram sync --status
```

**Export Output:**

```
Exporting memories for project "my-app"...
Created chunk a3f8c1d2
  Sessions:     2
  Observations: 8
  Prompts:      5

Add to git:
  git add .engram/ && git commit -m "sync engram memories"
```

**Import Output:**

```
Imported 3 new chunk(s) from .engram/
  Sessions:     4
  Observations: 15
  Prompts:      7
  Skipped:      2 (already imported)
```

**Status Output:**

```
Sync status:
  Local chunks:    5
  Remote chunks:   8
  Pending import:  3
```

**Directory Structure:**

```
.engram/
├── manifest.json          # Index of all chunks
├── chunks/
│   ├── a3f8c1d2.jsonl.gz # Chunk 1 (gzipped JSONL)
│   ├── b7d2e4f1.jsonl.gz # Chunk 2
│   └── ...
└── engram.db              # Local working DB (gitignored)
```

<Info>
  Each `sync` creates a new chunk file - old chunks are never modified. This prevents merge conflicts when multiple developers sync to the same repository.
</Info>

***

## Agent Setup

### setup

Install Engram plugin for AI coding agents.

```bash theme={null}
engram setup [agent]
```

<ParamField path="agent" type="string" optional>
  Agent name: `opencode`, `claude-code`, `gemini-cli`, or `codex`. If omitted, shows interactive selection.
</ParamField>

**Supported Agents:**

* **opencode** - Installs to `~/.config/opencode/plugins/engram.ts`
* **claude-code** - Installs to `~/.claude/plugins/`
* **gemini-cli** - Configures `~/.gemini/settings.json`
* **codex** - Configures `~/.codex/config.toml`

**Examples:**

```bash theme={null}
# Interactive setup
engram setup

# Direct installation
engram setup opencode
```

**Interactive Output:**

```
engram setup — Install agent plugin

Which agent do you want to set up?

  [1] OpenCode (install to ~/.config/opencode/plugins/)
  [2] Claude Code (install to ~/.claude/plugins/)
  [3] Gemini CLI (install to ~/.gemini/)
  [4] Codex (install to ~/.codex/)

Enter choice (1-4): 1

Installing OpenCode plugin...
✓ Installed opencode plugin (2 files)
  → /Users/username/.config/opencode/plugins/engram.ts

Next steps:
  1. Restart OpenCode — plugin + MCP server are ready
  2. Run 'engram serve &' for session tracking (HTTP API)
```

***

## Utility Commands

### version

Print Engram version.

```bash theme={null}
engram version
# or
engram --version
# or
engram -v
```

**Output:**

```
engram 0.1.0
```

***

### help

Show help message.

```bash theme={null}
engram help
# or
engram --help
# or
engram -h
```

**Output:**

```
engram v0.1.0 — Persistent memory for AI coding agents

Usage:
  engram <command> [arguments]

Commands:
  serve [port]       Start HTTP API server (default: 7437)
  mcp [--tools=PROFILE] Start MCP server (stdio transport)
  tui                Launch interactive terminal UI
  search <query>     Search memories
  save <title> <msg> Save a memory
  timeline <obs_id>  Show chronological context
  context [project]  Show recent context
  stats              Show memory statistics
  export [file]      Export to JSON
  import <file>      Import from JSON
  sync               Git-based sync
  setup [agent]      Install agent integration
  version            Print version
  help               Show this help
...
```

***

## Exit Codes

* `0` - Success
* `1` - Error (invalid command, missing arguments, operation failed)

## Error Handling

All commands print errors to stderr:

```bash theme={null}
$ engram search
usage: engram search <query> [--type TYPE] [--project PROJECT] [--scope SCOPE] [--limit N]

$ engram import missing.json
engram: read missing.json: no such file or directory

$ engram unknown
unknown command: unknown
```