# 20alexl/claude-engram [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/20alexl/claude-engram  
**GitHub Stars:** 16  
**Views:** 8  
**Installs:** 0  
**Upvotes:** 1  
**Directory Page:** https://allmcps.com/mcp/20alexl-claude-engram

## Description
Persistent memory and session intelligence for Claude Code. Auto-tracks mistakes, decisions, and context via hooks. Mines session history for patterns and cross-session search. Loop detection, pre-edit warnings, context compaction survival. Runs locally with Ollama.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "claude-engram": {
    "command": "npx",
    "args": ["-y","20alexl-claude-engram"]
  }
}
```

## Documentation

## 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. Cursor, Windsurf, Continue.dev, Zed, and other MCP clients can access the MCP tools, but the README states that those clients do not receive the hooks. 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.

_Full upstream README: https://allmcps.com/mcp/20alexl-claude-engram/readme_