Configuration

Engram can be configured via the CLI (`engram configure set <key> <value>`) or through environment variables. The CLI persists settings in ~/.engram/config.json and passes them to the server automatically on `engram start`.

Environment variables

CLI configuration

The easiest way to configure Engram:

# Set the database path
engram configure set dbPath ~/.engram/engram.db

# Change the API port
engram configure set port 4901

# Scope memory to a namespace
engram configure set namespace my-project

# View current config
engram configure show

Reflection needs no configuration — Engram runs no LLM. When a reflection cycle is due, the AI connected over MCP does the reasoning via request_reflection → store_reflection.

All settings are persisted in ~/.engram/config.json and passed to the server as environment variables when you run `engram start`.

Starting with environment variables

Alternatively, pass variables inline or export them before starting the server:

# Inline — start with a custom DB path
PORT=4901 ENGRAM_DB_PATH=/data/engram/prod.db node apps/server/dist/index.js

# Or export first
export PORT=4901
export ENGRAM_DB_PATH=/var/lib/engram/engram.db
export NODE_ENV=production
node apps/server/dist/index.js

Running with PM2 (production)

PM2 keeps Engram alive across restarts and provides log management. Create an ecosystem.config.js or pass env vars directly:

# Install PM2 globally
npm install -g pm2

# Start with environment variables
pm2 start server.js --name engram \
  --env PORT=4901 \
  --env ENGRAM_DB_PATH=/var/lib/engram/engram.db \
  --env NODE_ENV=production

# Or use an ecosystem file
# ecosystem.config.js
module.exports = {
  apps: [{
    name: 'engram',
    script: 'server.js',
    env: {
      PORT: 4901,
      ENGRAM_DB_PATH: '/var/lib/engram/engram.db',
      NODE_ENV: 'production',
    },
  }],
}

# Then start with:
pm2 start ecosystem.config.js
pm2 save        # persist across reboots
pm2 startup     # generate system startup script

Running with systemd

For servers managed by systemd, create a unit file:

# /etc/systemd/system/engram.service
[Unit]
Description=Engram Memory Server
After=network.target

[Service]
Type=simple
User=engram
WorkingDirectory=/opt/engram
ExecStart=/usr/bin/node server.js
Restart=on-failure
RestartSec=5

Environment=PORT=4901
Environment=ENGRAM_DB_PATH=/var/lib/engram/engram.db
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable engram
sudo systemctl start engram

# Check status and logs
sudo systemctl status engram
journalctl -u engram -f

Database defaults

Engram uses SQLite with the following pragmas applied automatically at startup. These are hardcoded for optimal performance and cannot be changed.

A passive WAL checkpoint runs automatically before stats queries to ensure read consistency when concurrent writes are active.

The default embedding model is Xenova/all-MiniLM-L6-v2 (384 dimensions, FP16 storage). Override with ENGRAM_EMBEDDING_MODEL. After switching models, use the re-embedding pipeline to update existing vectors.

PostgreSQL (not implemented)

Use the default SQLite backend. If you have provisioned a compatible schema yourself, the unsupported escape hatch ENGRAM_PG_SCHEMA_READY=true lets the server start at your own risk. Proper PostgreSQL support (a pgTable schema, a PostgreSQL Drizzle config, a migrator run at connect time and BYTEA embedding storage) is on the roadmap.

Internal scoring algorithm

When recalling memories, Engram ranks results using a weighted composite score. These weights are hardcoded in the core scoring engine and provided here for reference.

Recall defaults

Decay & garbage collection

Engram includes an automatic memory decay and garbage collection system inspired by the Ebbinghaus forgetting curve. Memories that are old, rarely accessed, and low-importance are progressively decayed and eventually archived.

Retention score formula

retentionScore = importance × recencyFactor × accessFactor

Where:
  recencyFactor = exp(−ln(2) × daysSinceLastTouch / halfLifeDays)
  accessFactor  = min(1.0, 0.3 + 0.7 × log10(accessCount + 1) / 3)

When retentionScore < archiveThreshold → memory is archived (soft-deleted)

Default decay policy

Protection rules

The following memories are never archived by the decay engine, regardless of their retention score:

• Semantic memories with importance ≥ 0.8
• Procedural memories with confidence ≥ 0.9
• Memories accessed in the last 24 hours
• Memories tagged with "pinned" or "protected"
• Memories whose source is exactly claude-code, ollama or rest-api — the rule is an exact match, so other client identifiers (for example cursor or windsurf) are not protected

Auto-consolidation

After each decay sweep, Engram can automatically consolidate clusters of old episodic memories into semantic summaries. This is enabled by default and only runs on episodes older than 24 hours with at least 3 similar memories (similarity ≥ 0.6).

Contradiction detection

When a new memory is stored, Engram checks for conflicts with existing memories using vector similarity and content analysis (negation, value changes, temporal overrides, opposite sentiment). Configuration is managed at runtime via the API:

Update at runtime: PUT /api/contradictions/config

Index persistence

Engram persists the in-memory vector index to disk on shutdown and reloads it on startup. This enables fast incremental startup — only new memories since the last save are loaded from the database.

With a persisted index, startup for 1k memories goes from ~1.2s to ~45ms (27x faster). Use POST /api/index/rebuild to force a full rebuild if the index becomes stale.

Webhooks

Subscribe external systems to memory events. Configure via the API:

curl -X POST http://localhost:4901/api/webhooks \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.slack.com/...","events":["stored","contradiction"]}'

Events: stored, forgotten, decayed, consolidated, contradiction, reflected. Deliveries include HMAC-SHA256 signing when a secret is configured. Failed deliveries retry 3 times with exponential backoff. After 10 consecutive failures, the webhook is auto-disabled. Delivery to loopback and private addresses is rejected unless ENGRAM_WEBHOOK_ALLOW_PRIVATE=true.

Plugins

Extend Engram with lifecycle hooks. Plugins run in-process and fire at 6 lifecycle points: onStore, onRecall, onForget, onDecay, onStartup, onShutdown.

// Register a plugin programmatically
brain.registerPlugin({
  id: 'my-org/logger',
  name: 'Memory Logger',
  version: '1.0.0',
  hooks: {
    onStore: async (ctx) => console.log('Stored:', ctx.memory.id),
  },
});

Plugin errors are isolated — a failing plugin never breaks core operations. See the Plugin API for the full manifest format.