Documentation

Quickstart

Get Engram running in under 5 minutes. No account required for local mode.

Installation

Engram requires Python 3.13. Install via pip:

pip install engram

Verify the install:

engram --version

Python version note: Engram requires Python 3.13. Python 3.14+ is not yet supported due to a dependency on sqlite-vec. If you have multiple Python versions, use python3.13 -m pip install engram.

Initialize a project

Each codebase or domain gets its own project. Projects are isolated memory stores — facts from one don't leak into another.

engram init my-project

This creates ~/.engram/projects/my-project/ with an empty knowledge graph. You can have as many projects as your plan allows.

One-click onboarding

If you've been using Claude Code and want to import your existing sessions, engram onboard auto-discovers recent sessions and imports them in one step:

engram onboard my-project

This scans your Claude Code session history, presents a menu of recent sessions, and extracts facts from whichever ones you select. Most users see their graph populated in under two minutes.

Extract memory from a session

Engram reads conversation transcripts or markdown files and extracts structured facts — decisions, constraints, implementation details, and open questions.

# Extract from a plain-text transcript
engram extract my-project transcript.txt

# Extract from a MEMORY.md, CLAUDE.md, or spec doc
engram extract my-project MEMORY.md

# Run a second verification pass to catch missed facts
engram extract my-project transcript.txt --verify

# Preview what would be extracted without writing to the graph
engram extract my-project transcript.txt --dry-run

The extractor calls your configured LLM (Gemini 2.5 Flash by default) and merges the resulting nodes into the graph. Duplicate or superseded facts are handled automatically — if the same decision is restated, the newer version replaces the older one.

Configuring the extraction model

Set your preferred model in ~/.engram/config.yaml:

# Recommended — fast, accurate, low cost
llm:
  model: gemini-2.5-flash
  api_key: YOUR_GEMINI_API_KEY   # or set GEMINI_API_KEY env var

# Alternative: OpenAI
# llm:
#   model: gpt-4o-mini
#   api_key: YOUR_OPENAI_API_KEY

# Alternative: local model via Ollama
# llm:
#   base_url: http://localhost:11434/v1
#   model: qwen2.5:32b

See the full configuration reference for all available options.

Query your memory

Retrieve the facts most relevant to a question or task. Engram scores nodes by semantic similarity, temporal recency, and node type — returning the highest-signal facts first.

engram query my-project "what auth approach did we decide on?"
engram query my-project "database schema decisions"
engram query my-project "open questions about the API layer"

Output is plain text, formatted for direct injection into an AI editor's context window.

Connecting to your AI editor

The fastest way to use Engram continuously is via the MCP server, which makes Engram's tools available inside Claude Code, Cursor, Windsurf, and any MCP-compatible client — automatically, without manual extraction steps.

engram mcp-serve

See the MCP Server docs for editor-specific configuration.

What gets extracted?

Engram extracts eight node types from sessions. See the Concepts page for full descriptions.

  • decision — architectural and implementation choices
  • constraint — hard requirements, platform restrictions, deadlines
  • implementation — how something was built or configured
  • transition — evolution from one approach to another ("moved from X to Y")
  • preference — user preferences, style, and recurring patterns
  • process — repeatable workflows and team protocols
  • question — open items and unresolved decisions
  • lesson_learned — things that didn't work and why

Next steps