engram

English | Русский | 中文

Engram

Persistent shared memory infrastructure for Claude Code workstations.

Engram captures observations from coding sessions, stores them in PostgreSQL with pgvector, and exposes 48 MCP tools — hybrid search, knowledge graph, memory consolidation, and session indexing across multiple workstations.

Architecture

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

graph TB
    subgraph "Workstation A"
        CC_A[Claude Code]
        H_A[Hooks / MCP Plugin]
        CC_A --> H_A
    end

    subgraph "Workstation B"
        CC_B[Claude Code]
        H_B[Hooks / MCP Plugin]
        CC_B --> H_B
    end

    H_A -- "Streamable HTTP / SSE" --> Server
    H_B -- "Streamable HTTP / SSE" --> Server

    subgraph "Engram Server :37777"
        Server[Worker]
        Server --> |HTTP API| API[REST Endpoints]
        Server --> |MCP| MCP_T["SSE + Streamable HTTP"]
        Server --> |Web| Dash["Dashboard *"]
    end

    Server --> PG[(PostgreSQL 17\n+ pgvector)]

    style Dash stroke-dasharray: 5 5

* Dashboard is a placeholder — planned for a future release.

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 Plugin — connects Claude Code to the remote server via Streamable HTTP or SSE

Features

Quick Start

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

Then configure MCP (see Installation below).

Installation

Plugin Install (recommended)

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

# Set environment variables (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_AUTH_ADMIN_TOKEN=your-admin-token   # or ENGRAM_API_TOKEN (deprecated)

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

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

Manual MCP Configuration

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

Streamable HTTP (recommended)

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_AUTH_ADMIN_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_AUTH_ADMIN_TOKEN}"}}' -s user

SSE Transport

Use http://your-server:37777/sse as the URL:

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

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

Client Binaries (optional)

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

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

Hooks are JavaScript and come pre-configured with the plugin. No build needed.

Configuration

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 Installation).

MCP Tools (48)

44 always-available tools, 4 conditional (require document store), plus import_instincts (always available, uses embeddings for dedup).

Memory Consolidation

Importance Score (write-time)

Each observation receives an importance score when created:

importance = typeWeight * (1 + conceptBonus + feedbackBonus + retrievalBonus + utilityBonus)

Type weights: discovery=0.9, decision=0.85, pattern=0.8, insight=0.75, guidance=0.7, observation=0.5, question=0.4

Relevance Score (consolidation)

The consolidation scheduler recalculates relevance periodically:

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

Where decay = exp(-0.01 * daysSinceCreation).

Consolidation Cycles

Forgetting protections — observations are never archived if:

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

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.

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-stdio-proxy/    stdio -> SSE bridge (client-side)
  worker/             HTTP API + MCP SSE + MCP Streamable HTTP + dashboard
  engram-cli/         CLI client for engram operations
internal/
  chunking/           AST-aware document chunking (Markdown, Go)
  collections/        YAML collection config + context routing
  instincts/          Instinct parser and import
  config/             Configuration management
  consolidation/      Decay, associations, forgetting
  db/gorm/            PostgreSQL stores + auto-migrations
  embedding/          OpenAI-compatible REST embedding provider
  graph/              In-memory CSR graph traversal
  mcp/                MCP protocol (server, SSE, Streamable HTTP)
  reranking/          API-based cross-encoder reranker
  scoring/            Importance + relevance scoring
  search/             Hybrid retrieval + RRF fusion
  sessions/           JSONL parser + indexer
  vector/pgvector/    pgvector client + sync
  worker/             HTTP handlers, middleware, service
pkg/
  models/             Domain models + relation types
  strutil/            Shared string utilities
plugin/               Claude Code plugin definition + marketplace

Platform Support

Uninstall

Server:

docker compose down       # stop containers
docker compose down -v    # stop containers and remove data

Client (plugin):

/plugin uninstall engram

Client (script install, 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.