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

engram <command> [arguments]

Core Commands

serve

Start the HTTP API server for agent integrations.

engram serve [port]

port

number

Port number for the HTTP server. Default: 7437 (ENGR on phone keypad).

Examples:

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

engram mcp [--tools=PROFILE]

--tools

string

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

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:

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

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

tui

Launch the interactive terminal UI for browsing memories.

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.

engram search <query> [--type TYPE] [--project PROJECT] [--scope SCOPE] [--limit N]

query

string

required

Search query - natural language or keywords. Multiple words are automatically combined.

--type

string

Filter by observation type: decision, architecture, bugfix, pattern, config, discovery, learning, manual

--project

string

Filter by project name

--scope

string

Filter by scope: project or personal

--limit

number

Maximum results to return (default: 10)

Examples:

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

engram context [project]

project

string

Filter context by project name. If omitted, shows all recent context.

Examples:

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

engram timeline <observation_id> [--before N] [--after N]

observation_id

number

required

ID of the observation to center the timeline on

--before

number

Number of observations to show before the target (default: 5)

--after

number

Number of observations to show after the target (default: 5)

Examples:

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

engram save <title> <content> [--type TYPE] [--project PROJECT] [--scope SCOPE] [--topic TOPIC_KEY]

title

string

required

Short, searchable title for the memory

content

string

required

Memory content. Use the structured format with What, Why, Where, Learned

--type

string

Observation type: decision, architecture, bugfix, pattern, config, discovery, learning (default: manual)

--project

string

Project name to associate with this memory

--scope

string

Scope: project (default) or personal

--topic

string

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.

Examples:

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

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.

engram export [filename]

filename

string

Output filename (default: engram-export.json)

Examples:

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

{
  "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.

engram import <filename>

filename

string

required

JSON file to import (created by engram export)

Examples:

engram import engram-export.json
engram import backup-2024-03-01.json

Output:

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

Import uses INSERT OR IGNORE for sessions to skip duplicates. All operations run in a single atomic transaction.

Git Sync

sync

Export and import memories using Git-based chunked sync.

engram sync [--import] [--status] [--project NAME] [--all]

--import

boolean

Import new chunks from .engram/ directory into local database

--status

boolean

Show sync status (local vs remote chunks, pending imports)

--project

string

Filter export to a specific project. Default: current directory name

--all

boolean

Export ALL projects (ignore directory-based filter)

Examples:

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

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

Agent Setup

setup

Install Engram plugin for AI coding agents.

engram setup [agent]

agent

string

Agent name: opencode, claude-code, gemini-cli, or codex. If omitted, shows interactive selection.

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:

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

engram version
# or
engram --version
# or
engram -v

Output:

engram 0.1.0

help

Show help message.

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:

$ 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

Get Started

Core Concepts

Agent Setup

Features

CLI Reference

Installation

Usage

Core Commands

serve

mcp

tui

Search & Retrieval

search

context

timeline

Memory Management

save

stats

Import & Export

export

import

Git Sync

sync

Agent Setup

setup

Utility Commands

version

help

Exit Codes

Error Handling

Build docs developers (and LLMs) love

Get Started

Core Concepts

Agent Setup

Features

CLI Reference

​Installation

​Usage

​Core Commands

​serve

​mcp

​tui

​Search & Retrieval

​search

​context

​timeline

​Memory Management

​save

​stats

​Import & Export

​export

​import

​Git Sync

​sync

​Agent Setup

​setup

​Utility Commands

​version

​help

​Exit Codes

​Error Handling

Build docs developers (and LLMs) love

Installation

Usage

Core Commands

serve

mcp

tui

Search & Retrieval

search

context

timeline

Memory Management

save

stats

Import & Export

export

import

Git Sync

sync

Agent Setup

setup

Utility Commands

version

help

Exit Codes

Error Handling