Skip to main content
Get Engram up and running with your AI coding agent in 5 minutes.

​
Prerequisites

  • macOS, Linux, or Windows (x86_64 or ARM64)
  • An AI coding agent that supports MCP (OpenCode, Claude Code, Gemini CLI, Codex, VS Code, etc.)
  • Go 1.25+ (only if building from source)

​
Installation

brew install gentleman-programming/tap/engram
Verify installation:
engram version

​
Agent Setup

Connect Engram to your AI coding agent using the one-command setup: 
engram setup opencode
For other agents (Antigravity, Cursor, Windsurf) or manual configuration, see Agent Setup.

​
First Memory

Let’s verify everything works by saving your first memory using the CLI:
1

Save a memory

engram save "First memory" "Testing Engram memory system. This is my first saved observation."
You should see:
Saved observation (ID: 1)
2

Search for it

engram search "first memory"
You should see your observation in the results with FTS5 ranking.
3

View statistics

engram stats
You should see:
{
  "total_sessions": 1,
  "total_observations": 1,
  "total_prompts": 0,
  "projects": ["default"]
}

​
Using with Your Agent

Now that Engram is set up, your agent can use memory tools automatically.

​
Example: Saving a Memory

When you complete significant work in your coding session, the agent will call mem_save: 
{
  "title": "Fixed N+1 query in UserList component",
  "type": "bugfix",
  "content": `
**What**: Added eager loading for user relationships in UserList query

**Why**: List page was making N+1 queries (1 for users + N for each user's profile). Caused 500ms+ page loads with 50+ users.

**Where**: 
- src/components/UserList.tsx (line 45)
- src/api/users.ts (added include: ['profile', 'settings'])

**Learned**: Next.js data fetching doesn't auto-optimize joins. Always check Network tab for N+1 patterns.
  `
}

​
Example: Searching Memory

When you ask “How did we fix the N+1 query?”, the agent will:
1

Call mem_search

{
  "query": "N+1 query fix",
  "limit": 5
}
2

Get compact results

Results include title, type, project, and a content preview with observation IDs.
3

Call mem_get_observation (if needed)

{
  "id": 42
}
Gets the full untruncated content.

​
Explore the TUI

Launch the interactive terminal UI to browse your memories: 
engram tui
Navigate with j/k (vim keys), Enter to drill in, t for timeline, / to search, Esc to go back.See Terminal UI for full navigation reference.

​
What’s in Your Database?

Engram stores all data in a single SQLite database: 
~/.engram/engram.db
On Windows: 
%USERPROFILE%\.engram\engram.db
You can inspect it with any SQLite browser or the TUI.

​
Next Steps

How It Works

Understand the memory system and session lifecycle

Memory Protocol

Learn when agents should save and search memories

MCP Tools

Explore all 13 memory tools

Git Sync

Share memories across machines and teams

​
Troubleshooting

Ensure the binary is in your PATH.macOS/Linux:
echo $PATH
which engram
If installed via Homebrew, it should be in /opt/homebrew/bin/engram (Apple Silicon) or /usr/local/bin/engram (Intel).Windows:
$env:PATH
where.exe engram
Verify the MCP server is configured:OpenCode:
cat ~/.config/opencode/opencode.json
Should contain:
{
  "mcp": {
    "engram": {
      "type": "local",
      "command": ["engram", "mcp"],
      "enabled": true
    }
  }
}
Restart your agent after configuration changes.
Another Engram process may be running.macOS/Linux:
ps aux | grep engram
Windows:
Get-Process | Where-Object {$_.ProcessName -like "*engram*"}
Kill the process and try again.

Build docs developers (and LLMs) love

Get started for freeTalk to us