Configuration

Environment variables and configuration options for Engram

Engram can be configured using environment variables and follows XDG conventions for storing data.

Environment Variables

ENGRAM_DATA_DIR

Override the default data directory where Engram stores the SQLite database and related files.

ENGRAM_DATA_DIR · string · default: "~/.engram"

Path to data directory. Will be created if it doesn’t exist.

Usage:

# Use custom data directory
export ENGRAM_DATA_DIR="/opt/engram-data"
engram serve

# Or inline
ENGRAM_DATA_DIR="/tmp/engram-test" engram stats

Directory Structure:

~/.engram/
├── engram.db          # SQLite database (WAL mode)
├── engram.db-shm      # Shared memory file
└── engram.db-wal      # Write-ahead log

---

ENGRAM_PORT

Override the default HTTP server port.

ENGRAM_PORT · number · default: "7437"

Port number for HTTP API server (1024-65535)

Usage:

# Use custom port
export ENGRAM_PORT=8080
engram serve

# Or inline
ENGRAM_PORT=9000 engram serve

# Command-line argument takes precedence
ENGRAM_PORT=9000 engram serve 7000  # Listens on 7000

Port Precedence:

1. Command-line argument: engram serve 8080
2. Environment variable: ENGRAM_PORT=8080
3. Default: 7437

---

Database Configuration

Engram uses SQLite with the following built-in configuration:

SQLite Settings

Journal Mode · string · default: "WAL"

Write-Ahead Logging for concurrent reads during writes

Busy Timeout · number · default: "5000"

Milliseconds to wait before timing out on locked database (5 seconds)

Synchronous · string · default: "NORMAL"

Balance between safety and performance

Foreign Keys · boolean · default: "ON"

Enforce referential integrity constraints

FTS5 · boolean · default: "enabled"

Full-text search enabled on observations and prompts

Schema Details:

-- Sessions
CREATE TABLE sessions (
  id TEXT PRIMARY KEY,
  project TEXT,
  directory TEXT,
  started_at DATETIME,
  ended_at DATETIME,
  summary TEXT,
  status TEXT
);

-- Observations with FTS5
CREATE TABLE observations (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  session_id TEXT,
  type TEXT,
  title TEXT,
  content TEXT,
  project TEXT,
  scope TEXT,
  topic_key TEXT,
  created_at DATETIME,
  FOREIGN KEY (session_id) REFERENCES sessions(id)
);

CREATE VIRTUAL TABLE observations_fts USING fts5(
  title, content, tool_name, type, project
);

---

MCP Server Configuration

Tool Profiles

Control which MCP tools are exposed to agents:

agent · profile

11 tools for AI coding agents:

• mem_save - Save observations
• mem_search - Search memories
• mem_context - Recent context
• mem_session_summary - Session summaries
• mem_session_start - Start sessions
• mem_session_end - End sessions
• mem_get_observation - Get full content
• mem_suggest_topic_key - Topic key suggestions
• mem_capture_passive - Passive learning extraction
• mem_save_prompt - Save user prompts
• mem_update - Update observations

admin · profile

3 tools for manual curation:

• mem_delete - Delete observations
• mem_stats - System statistics
• mem_timeline - Timeline view

all · profile

All 14 tools (agent + admin)

Usage:

# Agent tools only (recommended)
engram mcp --tools=agent

# All tools
engram mcp --tools=all
engram mcp  # same as --tools=all

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

# Individual tools
engram mcp --tools=mem_save,mem_search,mem_context

---

Agent Configuration Files

Engram integrates with various AI coding agents through their configuration files.

OpenCode

Plugin Location: ~/.config/opencode/plugins/engram.ts

MCP Config: ~/.config/opencode/opencode.json

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

Install:

engram setup opencode

---

Claude Code

Plugin Location: ~/.claude/plugins/engram/

MCP Config: ~/.claude/mcp.json

{
  "engram": {
    "type": "local",
    "command": ["engram", "mcp", "--tools=agent"],
    "enabled": true
  }
}

Permissions: ~/.claude/settings.json

{
  "permissions": {
    "allow": [
      "engram:mem_save",
      "engram:mem_search",
      "engram:mem_context"
    ]
  }
}

Install:

engram setup claude-code

The installer offers to automatically add Engram tools to the permissions allowlist to prevent repeated permission prompts.

---

Gemini CLI

Config Location: ~/.gemini/settings.json

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

System Prompt: ~/.gemini/system.md

Compaction Recovery: ~/.gemini/.env

Install:

engram setup gemini-cli

---

Codex

Config Location: ~/.codex/config.toml

[mcp_servers.engram]
command = "engram"
args = ["mcp", "--tools=agent"]

model_instructions_file = "~/.codex/system.md"
experimental_compact_prompt_file = "~/.codex/.env"

Install:

engram setup codex

---

Git Sync Configuration

Sync Directory Structure

.engram/
├── manifest.json          # Chunk index (git-tracked)
├── chunks/                # Compressed chunks (git-tracked)
│   ├── a3f8c1d2.jsonl.gz
│   └── b7d2e4f1.jsonl.gz
└── engram.db              # Local database (gitignored)

.gitignore

Add to your project’s .gitignore:

# Engram local database (not synced)
.engram/engram.db
.engram/engram.db-shm
.engram/engram.db-wal

# Keep manifest and chunks
!.engram/manifest.json
!.engram/chunks/

Sync Workflow

Export:

# Current project only (default)
engram sync

# All projects
engram sync --all

# Specific project
engram sync --project my-app

# Commit and push
git add .engram/
git commit -m "sync engram memories"
git push

Import:

# Pull latest chunks
git pull

# Import new chunks
engram sync --import

Auto-Import:

The OpenCode plugin automatically runs engram sync --import at startup if .engram/manifest.json exists.

---

HTTP API Configuration

The HTTP server binds to 127.0.0.1 (localhost only) for security.

Server Details

Host · string · default: "127.0.0.1"

Server only accepts local connections

Port · number · default: "7437"

Configurable via ENGRAM_PORT or command-line argument

CORS · boolean · default: "false"

Not enabled - local access only

Health Check

curl http://localhost:7437/health

Response:

{
  "status": "ok",
  "service": "engram",
  "version": "0.1.0"
}

---

Privacy Configuration

Private Tag Stripping

Engram strips <private> tags at two levels:

1. Plugin layer (TypeScript) - Before sending to HTTP API
2. Store layer (Go) - Inside AddObservation() and AddPrompt()

Example:

# Input
engram save "API Setup" "Set up API with <private>sk-abc123</private>" --project my-app

# Stored as
"Set up API with [REDACTED]"

Usage in MCP:

// Agent saves this
mem_save({
  title: "Database Config",
  content: "**What**: Configured database\n**Where**: <private>postgres://user:pass@host</private>"
});

// Stored as
"**What**: Configured database\n**Where**: [REDACTED]"

---

Performance Tuning

Database Optimization

Engram uses SQLite’s WAL mode for optimal performance:

• Concurrent reads during writes
• Checkpoint automatic background
• Page size 4096 bytes (default)

Search Performance

FTS5 query optimization:

• Queries are sanitized and quoted automatically
• Search limited to 20 results max
• Indexes on session_id, project, scope, created_at

Memory Usage

Typical memory footprint:

• Binary size: ~15MB (includes SQLite)
• Runtime memory: ~10-20MB (idle)
• Database size: ~1KB per observation (compressed)

---

Troubleshooting

Database Locked

If you see “database is locked” errors:

# Check for running instances
ps aux | grep engram

# Kill stale processes
kill <pid>

# Or restart with longer timeout
# (currently hardcoded to 5000ms)

Port Already in Use

# Check what's using the port
lsof -i :7437

# Use different port
engram serve 8080

Data Directory Permissions

# Ensure directory is writable
chmod 755 ~/.engram
chmod 644 ~/.engram/engram.db

Sync Conflicts

Chunks are content-hashed and never conflict. If manifest conflicts:

# Accept both changes (chunks are independent)
git add .engram/manifest.json
git commit

# Re-import to process any new chunks
engram sync --import

---

Default Values Reference

Setting	Default	Override Method
Data Directory	~/.engram	ENGRAM_DATA_DIR
HTTP Port	7437	ENGRAM_PORT or CLI arg
Search Limit	10	--limit flag
Timeline Before	5	--before flag
Timeline After	5	--after flag
MCP Tools	All (14)	--tools flag
Scope	project	--scope flag
SQLite Busy Timeout	5000ms	Not configurable
WAL Checkpoint	Automatic	Not configurable

---

Configuration Files Location Summary

Agent	Plugin Path	MCP Config Path
OpenCode	~/.config/opencode/plugins/engram.ts	~/.config/opencode/opencode.json
Claude Code	~/.claude/plugins/engram/	~/.claude/mcp.json
Gemini CLI	N/A (MCP only)	~/.gemini/settings.json
Codex	N/A (MCP only)	~/.codex/config.toml

Install any agent:

engram setup [agent]