Engram

🚀 Engram

Event-sourced memory system for AI agents. No LLM in the write path — just reliable episode storage with semantic search.

🚀 Quick Start

Prerequisites

• Ollama running locally (or remotely) with an embedding model
• Go 1.25+ (only if building from source)

Install

Option A: Download a pre-built binary

Download from the releases page for your platform:

# macOS/Linux: make it executable
chmod +x engram-*
mv engram-* engram

Option B: Build from source

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

# Using just (recommended — install from https://github.com/casey/just)
just setup    # install deps, pull embedding model, build

# Or manually
go build -o engram ./cmd/engram/main.go

Pull the embedding model

ollama pull nomic-embed-text

Run

export DUCKDB_PATH="./engram.duckdb"
export OLLAMA_URL="http://localhost:11434"
export EMBEDDING_MODEL="nomic-embed-text"

./engram

✨ Features

• Semantic search — results ranked by relevance using vector similarity, not recency
• Graceful fallback — works even when the embedding service is unavailable
• Fast queries — DuckDB HNSW indexing for sub-100ms vector search
• Zero external APIs — all embeddings generated locally via Ollama
• Single binary — portable across Linux, macOS, and Windows
• MCP native — integrates directly with Claude Desktop, Claude Code, and Cursor

📚 Documentation

• MCP Integration Guide - Client setup, available tools, troubleshooting
• Deployment Guide - Docker Compose, Kubernetes, production deployment
• Architecture - Technical deep dive into system design

📦 Installation

Configure via environment variables:

See for a template.

💻 Usage Examples

MCP Client Integration

Engram integrates with Claude Desktop, Claude Code, and Cursor via the Model Context Protocol (MCP).

Quick Setup (Local)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "engram-memory": {
      "command": "/absolute/path/to/engram",
      "args": [],
      "env": {
        "DUCKDB_PATH": "/absolute/path/to/engram.duckdb",
        "OLLAMA_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "nomic-embed-text"
      }
    }
  }
}

💡 Usage Tip

Use absolute paths. On macOS, run realpath engram to get the full path.

For detailed integration instructions, remote deployment, available MCP tools, and troubleshooting, see docs/mcp-integration.md.

Docker & Deployment

Quick Start (Development)

# macOS/Windows
just docker-up

# Linux
just docker-up-linux

For detailed deployment instructions including Docker Compose, Kubernetes, and production configurations, see docs/deployment.md.

🔧 Technical Details

engram/
├── cmd/engram/          # Entry point
├── internal/
│   ├── db/              # DuckDB operations + VSS
│   ├── embedding/       # Ollama client
│   ├── mcp/             # MCP server implementation
│   └── models/          # Data models
├── scripts/             # Build and test scripts
├── .github/workflows/   # CI/CD (build + release)
└── Dockerfile           # Container image

• Go service using the official MCP SDK (mark3labs/mcp-go)
• DuckDB with VSS extension for vector similarity search (HNSW indexing)
• Ollama for local embedding generation (768-dimensional, nomic-embed-text)
• stdio transport for MCP client integration

For a deeper dive into the architecture, see .

📄 License

MIT

📈 Design Principles

1. Writes never fail (if the database is up)
2. No LLM in the write path — embeddings only, and those are retryable
3. Episode log is source of truth — everything else is derived
4. Simple over clever — vector search covers 80% of use cases
5. Portable — single binary, single database file

🧪 Testing

The project includes comprehensive unit tests:

# Run all tests
just test

# Run with coverage
just test-coverage

🤝 Contributing

See CONTRIBUTING.md for development setup, code style, and how to submit pull requests.