engram

Engram

Persistent shared memory infrastructure for Claude Code workstations.

Engram captures observations from coding sessions, stores them in PostgreSQL + pgvector, and exposes 40 MCP tools through the nia server — hybrid search, knowledge graph, memory consolidation, and session indexing across multiple workstations.

Architecture

Single server port (37777) serves HTTP API, MCP transports, and web dashboard.

  Workstation A                 Workstation B
  ┌──────────────┐              ┌──────────────┐
  │  Claude Code  │              │  Claude Code  │
  │  ┌─────────┐  │              │  ┌─────────┐  │
  │  │  Hooks  │  │              │  │  Hooks  │  │
  │  │MCP Proxy│  │              │  │MCP Proxy│  │
  │  └────┬────┘  │              │  └────┬────┘  │
  └───────┼───────┘              └───────┼───────┘
          │ HTTP                         │ HTTP
          └──────────┐    ┌──────────────┘
                     ▼    ▼
            ┌─────────────────────┐
            │   Engram Server     │
            │  ┌───────────────┐  │
            │  │ Worker :37777 │  │
            │  │  HTTP API     │  │
            │  │  MCP SSE      │  │
            │  │  MCP HTTP     │  │
            │  │  Dashboard    │  │
            │  └───────┬───────┘  │
            │          │          │
            │  ┌───────▼───────┐  │
            │  │  PostgreSQL   │  │
            │  │  + pgvector   │  │
            │  └───────────────┘  │
            └─────────────────────┘

Server (Docker on remote host / Unraid / NAS):

• PostgreSQL 17 with pgvector extension
• Worker — HTTP API, MCP SSE, MCP Streamable HTTP (POST /mcp), dashboard, consolidation scheduler

Client (each workstation):

• Hooks — capture observations from Claude Code sessions
• MCP Stdio Proxy — bridges Claude Code's stdio MCP to the remote server

Quick Start

1. Deploy the Server

git clone https://github.com/thebtf/engram.git
cd engram

# Configure
cp .env.example .env   # edit with your settings

docker compose up -d

This starts PostgreSQL 17 + pgvector and the Engram server at http://your-server:37777.

Verify:

curl http://your-server:37777/health

Existing PostgreSQL? Run only the server container and set DATABASE_DSN:

DATABASE_DSN="postgres://user:pass@your-pg:5432/engram?sslmode=disable" \
  docker compose up -d server

2. Configure MCP

With Plugin (recommended)

The plugin registers the MCP server automatically via .mcp.json. Set two environment variables and install:

# Set environment variables (these are read by Claude Code at runtime)
# Linux/macOS: add to shell profile; Windows: set as System Environment Variables
ENGRAM_URL=http://your-server:37777/mcp
ENGRAM_API_TOKEN=your-api-token

/plugin marketplace add thebtf/engram-marketplace
/plugin install engram

Restart Claude Code. The plugin provides hooks, skills, and MCP connection — all configured.

Without Plugin (manual)

If not using the plugin, configure MCP directly. Engram exposes three transports on the same port:

Streamable HTTP — add to ~/.claude/settings.json (user scope) or .claude/settings.json (project scope):

{
  "mcpServers": {
    "engram": {
      "type": "url",
      "url": "http://your-server:37777/mcp",
      "headers": {
        "Authorization": "Bearer ${ENGRAM_API_TOKEN}"
      }
    }
  }
}

Claude Code expands ${VAR} references from your environment at runtime. You can also use literal values.

CLI shortcut:

claude mcp add-json engram '{"type":"http","url":"http://your-server:37777/mcp","headers":{"Authorization":"Bearer ${ENGRAM_API_TOKEN}"}}' -s user

SSE Transport — use http://your-server:37777/sse as the URL instead.

Stdio Proxy (legacy) — for clients that only support stdio. Requires mcp-stdio-proxy binary:

{
  "mcpServers": {
    "engram": {
      "command": "/path/to/mcp-stdio-proxy",
      "args": ["--url", "http://your-server:37777", "--token", "your-api-token"]
    }
  }
}

3. Install Client Binaries (optional)

Only needed if using the stdio proxy or hooks. Streamable HTTP / SSE transports work without any client-side binaries.

Plugin Install

/plugin marketplace add thebtf/engram-marketplace
/plugin install engram

Script Install (macOS / Linux)

curl -sSL https://raw.githubusercontent.com/thebtf/engram/main/scripts/install.sh | bash

Build from Source (Windows PowerShell)

git clone https://github.com/thebtf/engram.git && cd engram

$env:CGO_ENABLED = "1"
go build -tags fts5 -ldflags "-s -w" -o bin\mcp-stdio-proxy.exe .\cmd\mcp-stdio-proxy
go build -tags fts5 -ldflags "-s -w" -o bin\hooks\session-start.exe .\cmd\hooks\session-start
go build -tags fts5 -ldflags "-s -w" -o bin\hooks\user-prompt.exe .\cmd\hooks\user-prompt
go build -tags fts5 -ldflags "-s -w" -o bin\hooks\post-tool-use.exe .\cmd\hooks\post-tool-use
go build -tags fts5 -ldflags "-s -w" -o bin\hooks\stop.exe .\cmd\hooks\stop

Features

MCP Tools (40)

Memory Consolidation

The consolidation scheduler runs three automated cycles:

Relevance Decay (daily)

relevance = decay * (0.3 + 0.3*access) * relations * (0.5 + importance) * (0.7 + 0.3*confidence)

Creative Associations (weekly)

Samples observations, computes embedding similarity, discovers relations:

Forgetting (quarterly, opt-in)

Archives observations below relevance threshold. Protected:

• Importance score >= 0.7
• Age < 90 days
• Type: decision or discovery

Configuration

All server variables use the ENGRAM_ prefix. Config file: ~/.engram/settings.json.

Server

Client (hooks only)

These variables are used by the client-side hooks, not for MCP transport configuration. MCP connection is configured in settings.json (see Configure MCP above).

Development

make build            # Build all binaries
make test             # Run tests with race detector
make test-coverage    # Coverage report
make dev              # Run worker in foreground
make install          # Install plugin, register MCP
make uninstall        # Remove plugin
make clean            # Clean build artifacts

cmd/
  mcp/                MCP stdio server (local direct access)
  mcp-sse/            MCP SSE HTTP server (standalone)
  mcp-stdio-proxy/    stdio → SSE bridge (client-side)
  worker/             HTTP API + MCP SSE + MCP Streamable HTTP + dashboard
  hooks/              Claude Code lifecycle hooks
internal/
  chunking/           AST-aware document chunking (md, Go, Python, TS)
  collections/        YAML collection config + context routing
  config/             Configuration management
  consolidation/      Decay, associations, forgetting
  db/gorm/            PostgreSQL stores + auto-migrations
  embedding/          ONNX BGE + OpenAI REST providers
  graph/              In-memory CSR graph traversal
  mcp/                MCP protocol (server, SSE, Streamable HTTP)
  scoring/            Importance + relevance scoring
  search/             Hybrid retrieval + RRF fusion
  sessions/           JSONL parser + indexer
  vector/pgvector/    pgvector client + sync
  worker/             HTTP handlers, middleware, service
pkg/
  hooks/              Hook event client
  models/             Domain models + relation types
plugin/               Claude Code plugin definition + marketplace

Session Indexing

Sessions are indexed from Claude Code JSONL files with workstation isolation:

workstation_id = sha256(hostname + machine_id)[:8]
project_id     = sha256(cwd_path)[:8]
session_id     = UUID from JSONL filename
composite_key  = workstation_id:project_id:session_id

Multiple workstations sharing one server keep sessions isolated while search works across all of them.

Platform Support

Uninstall

Server: docker compose down (add -v to remove data)

Client (macOS/Linux):

curl -sSL https://raw.githubusercontent.com/thebtf/engram/main/scripts/install.sh | bash -s -- --uninstall

Client (Windows):

Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\plugins\marketplaces\engram"

License

MIT

Originally based on claude-mnemonic by Lukasz Raczylo