> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Gentleman-Programming/engram/llms.txt
> Use this file to discover all available pages before exploring further.

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

<ParamField path="ENGRAM_DATA_DIR" type="string" default="~/.engram">
  Path to data directory. Will be created if it doesn't exist.
</ParamField>

**Usage:**

```bash theme={null}
# 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.

<ParamField path="ENGRAM_PORT" type="number" default="7437">
  Port number for HTTP API server (1024-65535)
</ParamField>

**Usage:**

```bash theme={null}
# 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

<ParamField path="Journal Mode" type="string" default="WAL">
  Write-Ahead Logging for concurrent reads during writes
</ParamField>

<ParamField path="Busy Timeout" type="number" default="5000">
  Milliseconds to wait before timing out on locked database (5 seconds)
</ParamField>

<ParamField path="Synchronous" type="string" default="NORMAL">
  Balance between safety and performance
</ParamField>

<ParamField path="Foreign Keys" type="boolean" default="ON">
  Enforce referential integrity constraints
</ParamField>

<ParamField path="FTS5" type="boolean" default="enabled">
  Full-text search enabled on observations and prompts
</ParamField>

**Schema Details:**

```sql theme={null}
-- 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:

<ParamField path="agent" type="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
</ParamField>

<ParamField path="admin" type="profile">
  **3 tools** for manual curation:

  * `mem_delete` - Delete observations
  * `mem_stats` - System statistics
  * `mem_timeline` - Timeline view
</ParamField>

<ParamField path="all" type="profile">
  All 14 tools (agent + admin)
</ParamField>

**Usage:**

```bash theme={null}
# 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`

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

**Install:**

```bash theme={null}
engram setup opencode
```

***

### Claude Code

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

**MCP Config:** `~/.claude/mcp.json`

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

**Permissions:** `~/.claude/settings.json`

```json theme={null}
{
  "permissions": {
    "allow": [
      "engram:mem_save",
      "engram:mem_search",
      "engram:mem_context"
    ]
  }
}
```

**Install:**

```bash theme={null}
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`

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

**System Prompt:** `~/.gemini/system.md`

**Compaction Recovery:** `~/.gemini/.env`

**Install:**

```bash theme={null}
engram setup gemini-cli
```

***

### Codex

**Config Location:** `~/.codex/config.toml`

```toml theme={null}
[mcp_servers.engram]
command = "engram"
args = ["mcp", "--tools=agent"]

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

**Install:**

```bash theme={null}
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`:

```gitignore theme={null}
# 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:**

```bash theme={null}
# 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:**

```bash theme={null}
# 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

<ParamField path="Host" type="string" default="127.0.0.1">
  Server only accepts local connections
</ParamField>

<ParamField path="Port" type="number" default="7437">
  Configurable via `ENGRAM_PORT` or command-line argument
</ParamField>

<ParamField path="CORS" type="boolean" default="false">
  Not enabled - local access only
</ParamField>

### Health Check

```bash theme={null}
curl http://localhost:7437/health
```

**Response:**

```json theme={null}
{
  "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:**

```bash theme={null}
# 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:**

```javascript theme={null}
// 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:

```bash theme={null}
# 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

```bash theme={null}
# Check what's using the port
lsof -i :7437

# Use different port
engram serve 8080
```

### Data Directory Permissions

```bash theme={null}
# Ensure directory is writable
chmod 755 ~/.engram
chmod 644 ~/.engram/engram.db
```

### Sync Conflicts

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

```bash theme={null}
# 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:**

```bash theme={null}
engram setup [agent]
```