Configuration

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

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

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

# 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

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

# 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

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

engram setup opencode

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

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

engram setup claude-code

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

engram setup gemini-cli

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

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

engram setup codex

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

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

# 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

# Pull latest chunks
git pull

# Import new chunks
engram sync --import

curl http://localhost:7437/health

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

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

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

// 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]"

# Check for running instances
ps aux | grep engram

# Kill stale processes
kill <pid>

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

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

# Use different port
engram serve 8080

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

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

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

engram setup [agent]