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]

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]

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]

string

required

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

string

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

string

Filter by project name

string

Filter by scope: project or personal

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]

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]

number

required

ID of the observation to center the timeline on

number

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

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]

string

required

Short, searchable title for the memory

string

required

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

string

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

string

Project name to associate with this memory

string

Scope: project (default) or personal

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]

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>

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]

boolean

Import new chunks from .engram/ directory into local database

boolean

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

string

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

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]

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

​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

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