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

Persistent shared memory infrastructure for AI coding agents.

AI coding agents forget everything between sessions. Every new conversation starts from zero — past decisions, bug fixes, architectural choices, and learned patterns are lost. You waste time re-explaining context, and agents repeat the same mistakes.

Engram fixes this by keeping only the memory primitives that proved reliable in production: explicit issues, documents, memories, behavioral rules, credentials, and API tokens. One server, multiple workstations, zero context loss.

In v5.0.0, session-start inject is simplified to a static composite payload: open issues, always-inject behavioral rules, and recent memories. The old dynamic relevance, graph, reranking, and extraction stack is gone from the main product path.

A reduced static-first MCP surface remains for the surviving entity model, keeping context usage lean while preserving the workflows that actually worked.

See Releases for full changelog.

Engram v6 separates two credential tiers, each pinned to a single host class:

Operator keys NEVER appear on workstations. Worker keycards NEVER appear on the server host. There is no OR-fallback between the two names — the daemon ignores the admin name; the server ignores the workstation name. Workstation startup with ENGRAM_URL set but ENGRAM_TOKEN empty exits non-zero with an actionable error. Keycard issuance requires a browser admin session — bearer callers get 403 on /api/auth/tokens.

Migration from v5.x: open <server-url>/tokens, log in as admin, generate a keycard, paste it via /engram:setup. See CHANGELOG.md for full migration steps.

Single server on port 37777 serves the HTTP REST API, gRPC service (via cmux), Vue 3 dashboard, and the static storage/query surface. Each workstation runs a local daemon that connects to the server via gRPC. Multiple Claude Code sessions share one daemon.

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 -- "stdio / gRPC" --> Server
    H_B -- "stdio / gRPC" --> Server

    subgraph "Engram Server :37777"
        Server[Worker]
        Server --> |HTTP API| API[REST Endpoints]
        Server --> |gRPC| GRPC[Static session-start + tool bridge]
        Server --> |Web| Dash["Vue 3 Dashboard"]
    end

    Server --> PG[(PostgreSQL 17)]

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

• PostgreSQL 17
• Worker — HTTP API, gRPC, Vue 3 dashboard, static entity stores

Client (each workstation):

• Hooks — session-start, session-end, and related Claude Code lifecycle integrations
• MCP Plugin — connects Claude Code to the local daemon / server bridge
• Slash commands — /setup, /doctor, /restart and memory-related workflows

• Static session-start payload — issues + behavioral rules + memories via gRPC GetSessionStartContext
• Project-scoped memory recall — simple SQL-backed retrieval for static memories
• Document search — versioned documents and collection-backed search remain available

• Memories — explicit project-scoped notes in the memories table
• Behavioral rules — always-inject guidance in the behavioral_rules table
• Versioned documents — collections with history and comments
• Encrypted vault — AES-256-GCM credential storage with scoped access
• Cross-project issues — explicit operational coordination between agents/projects

• Session-start cache fallback — ${ENGRAM_DATA_DIR}/cache/session-start-{project-slug}.json is used when the server is temporarily unavailable
• Version negotiation — explicit major-version compatibility checks on the session-start path
• Config hot-reload — change settings without restart
• Graceful daemon restart — binary swap and control socket flow remain in place

• Vue 3 dashboard — focused on the surviving static entity surface
• Lifecycle hooks — session-start / session-end and related integrations remain installed
• Multi-workstation support — one server, multiple local daemons, shared static memory surface

• Context continuity — start a new session and receive a static session-start block with active issues, behavioral rules, and recent memories
• Offline fallback — if the server is temporarily unavailable, the client can reuse the last successful session-start payload with a visible staleness banner
• Architectural memory — query explicit memories and documents before making design changes
• Operational coordination — agents file and resolve cross-project issues explicitly
• Credential management — store and retrieve API keys and secrets without .env files
• Multi-workstation sharing — multiple local daemons connect to one shared Engram server

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

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

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

Then install the plugin in Claude Code:

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

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

Restart Claude Code. Memory is now active.

The plugin registers the MCP server, hooks, and slash commands automatically.

# Set environment variables first
ENGRAM_URL=http://your-server:37777/mcp
ENGRAM_AUTH_ADMIN_TOKEN=your-admin-token

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

Restart Claude Code. Everything is configured.

git clone https://github.com/thebtf/engram.git && cd engram
cp .env.example .env   # edit DATABASE_DSN, tokens, embedding config
docker compose up -d

Existing PostgreSQL? Run only the server container:

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

Download the engram daemon binary from GitHub Releases:

# Linux (amd64)
curl -L https://github.com/thebtf/engram/releases/latest/download/engram-linux-amd64 -o engram
chmod +x engram && sudo mv engram /usr/local/bin/

# macOS (Apple Silicon)
curl -L https://github.com/thebtf/engram/releases/latest/download/engram-darwin-arm64 -o engram
chmod +x engram && sudo mv engram /usr/local/bin/

# Windows (amd64) — download engram-windows-amd64.exe, add to PATH

Set environment variables:

export ENGRAM_URL=http://your-server:37777
export ENGRAM_API_TOKEN=your-token

Verify: echo '{"jsonrpc":"2.0","id":1,"method":"ping"}' | engram

The daemon starts automatically on first use. Multiple Claude Code sessions share one daemon.

If not using the plugin, configure MCP directly in ~/.claude/settings.json:

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "env": {
        "ENGRAM_URL": "http://your-server:37777",
        "ENGRAM_AUTH_ADMIN_TOKEN": "${ENGRAM_AUTH_ADMIN_TOKEN}"
      }
    }
  }
}

Requires Go 1.25+ and Node.js (for dashboard).

git clone https://github.com/thebtf/engram.git && cd engram
make build    # builds dashboard + daemon + release assets
make install  # installs plugin + starts daemon

v5.0.0 is a breaking cleanup release.

What changed:

• Engram now uses a static-only storage model for its primary runtime path
• session-start inject is based on static issues + behavioral rules + memories
• the old dynamic learning / graph / reranking / extraction stack is no longer part of the main product path
• client and server now negotiate major-version compatibility for the session-start path

Upgrade steps:

1. upgrade the plugin to 5.0.0
2. upgrade the daemon to v5.0.0
3. restart Claude Code and the daemon
4. verify plugin update detection and session-start cache fallback

Docker image: Pull the latest from ghcr.io/thebtf/engram:latest. Database migrations run automatically on startup.

Engram exposes a reduced static-first MCP surface for the surviving entity model.

Primary categories in v5:

• issues / issue comments
• memories / behavioral rules
• documents
• credentials / vault
• loom background tasks The old dynamic search / graph / learning-oriented tool surface is no longer the primary v5 path.

21 actions including: bulk_delete, bulk_supersede, tag, graph, stats, trends, quality, export, maintenance, scoring, consolidation, and more.

Reports status of all subsystems: database, embeddings, reranker, LLM, vault, graph, consolidation.

# Verify connection
check_system_health()

# Search memories
recall(query="authentication architecture")

# Preset queries
recall(action="preset", preset="decisions", query="caching strategy")

# Check file history before editing
recall(action="by_file", files="internal/search/hybrid.go")

# Store an observation
store(content="Switched from Redis to in-memory cache for dev environments", title="Cache strategy change", tags=["architecture", "caching"])

# Extract observations from raw content
store(action="extract", content="<paste raw session notes or code review>")

# Rate a memory
feedback(action="rate", id=123, rating="useful")

# Store a credential
vault(action="store", name="OPENAI_KEY", value="sk-...")

# Retrieve a credential
vault(action="get", name="OPENAI_KEY")

Server logs are available at http://your-server:37777/api/logs.

make build            # Build dashboard + all Go binaries
make test             # Run tests with race detector
make test-coverage    # Coverage report
make dev              # Run worker in foreground
make install          # Build + install plugin + start worker
make uninstall        # Remove plugin
make clean            # Clean build artifacts

cmd/
  worker/             HTTP API + MCP + dashboard entry point
  mcp/                Standalone MCP server
  mcp-stdio-proxy/    stdio -> SSE bridge
  engram-cli/         CLI client
internal/
  chunking/           AST-aware document chunking
  collections/        YAML collection config
  config/             Configuration with hot-reload
  consolidation/      Decay, associations, forgetting
  crypto/             AES-256-GCM vault encryption
  db/gorm/            PostgreSQL stores + migrations
  embedding/          REST embedding provider + resilience layer
  graph/              In-memory CSR + FalkorDB
  instincts/          Instinct parser and import
  learning/           Self-learning, LLM client
  maintenance/        Background tasks (summarizer, pattern insights)
  mcp/                MCP protocol, 7 primary tool handlers
  privacy/            Secret detection and redaction
  reranking/          Cross-encoder reranker
  scoring/            Importance + relevance scoring
  search/             Hybrid retrieval + RRF fusion
  sessions/           JSONL parser + indexer
  vector/pgvector/    pgvector client
  worker/             HTTP handlers, middleware, service
    sdk/              Observation extraction, reasoning detection
pkg/
  models/             Domain models + relation types
  strutil/            Shared string utilities
plugin/
  engram/             Claude Code plugin (hooks, commands)
ui/                   Vue 3 dashboard SPA

Server:

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

Client (plugin):

/plugin uninstall engram

MIT

Originally based on claude-mnemonic by Lukasz Raczylo.