Claude Engram

What 20alexl/claude-engram MCP server does

20alexl/claude-engram MCP server keeps a local, searchable record of development activity for Claude Code. It can capture edits, error events, test results, session events, and decisions expressed in prompts. Session history is mined for decisions, mistakes, recurring problems, and related context so earlier work can be surfaced in later sessions.

The project also maintains project-oriented context. It can identify known-good test commands, check imports before edits, show potential edit impact, orient the agent before reads, and separate information belonging to different sub-projects. These features are implemented through Claude Code hooks, background session mining, and an MCP server for on-demand operations.

How it works

Claude Engram uses a hook process to observe Claude Code tool calls, a mining subsystem for background and live session analysis, and a scorer daemon for embeddings and hook dispatch. The MCP server exposes operations that the agent can request when background behavior is not enough. Ollama supplies the local language model used by selected operations, including semantic search, memory consolidation, and reflective session mining.

Before compaction, the system can create a checkpoint and re-inject information afterward. Manual checkpoints can record current work and remaining tasks for more deliberate recovery. A live mining interval can also process the active session. Search covers stored history and can be scoped to the relevant project or sub-project.

Setup and configuration

Install from the repository by creating a Python virtual environment, installing the project, optionally adding the semantic extra, and running python install.py. The installer sets up hooks, the MCP server, the /engram skill, and migrations. A project can then be configured by running the setup command for that project or copying the generated .mcp.json into its root.

The semantic extra adds an embedding model for vector search and scoring. Ollama must be available for the configured local model. Configuration is optional and can be supplied through environment variables or ~/.claude_engram/config.json. Important settings include the Ollama model, embedding model and dimension, compute device, live-mining interval, storage directory, session retention, and scorer timeout. The default storage directory is ~/.claude_engram.

Tools and capabilities

Available on-demand MCP operations include:

• memory for working with stored memories and consolidation operations.
• session_mine for searching or processing session history, including reindexing and reflective operations.
• work and context for work-state and context checkpoints.
• deps_map for dependency mapping.
• impact_analyze for examining likely edit impact.
• scout_search for project code or context search.

The installed /engram skill provides a reference for using these tools. Automatic behavior includes relevant-memory injection before file edits, warnings for known repeated mistakes, recurring-error fix injection, edit-loop detection, compaction checkpoints, and session mining.

Limitations and notes

20alexl/claude-engram MCP server provides its complete hook and session-mining behavior in Claude Code. The project runs locally and uses Ollama rather than a hosted model service.

Embedding models require local resources; the documented default is about 1.1 GB of scorer RAM, while all-MiniLM-L6-v2 is described as a smaller alternative with lower accuracy. Search indexes can be rebuilt with the supplied reindex script or through session_mine(operation="reindex", mode="bootstrap"). The repository describes the software as work in progress and licenses it under MIT.