Engrim

What timgordontg/engrim MCP server does

Engrim gives coding agents a shared, project-scoped memory store that survives chat resets and model changes. Records are kept in a local SQLite database at ~/.engrim/memory.db, allowing environments such as Claude Code, Cursor, Codex CLI, Google Antigravity, GitHub Copilot CLI, OpenCode, and Windsurf to work from the same accumulated context.

The memory model is episodic rather than transcript-based. Architectural decisions, constraints, feedback, facts, references, and current state can be retained without replaying an entire conversation. At startup, Engrim prepares a small prioritized context pack of about 4,000 characters, including a [▶ RESUME HERE] section, instead of restoring a large chat history.

How it works

Search combines SQLite FTS5 lexical retrieval with BM25 ranking and static model2vec embeddings. Reciprocal Rank Fusion merges those result types for hybrid recall, while the local CPU embedding model keeps the system usable without a hosted inference service.

Agent lifecycle adapters capture information at startup, prompt, stop, and session events where the host supports those hooks. MCP provides an explicit capture path through engrim_add, and stored records track their originating agent. A flight recorder also logs turns and action lines.

All data remains in the local SQLite store, which uses WAL mode and POSIX 0600 permissions. The project describes the design as having no cloud sync, telemetry, or tracking.

Setup and configuration

Install the Python package with:

pip install engrim

Run engrim setup without arguments to detect installed agent environments and configure the corresponding hooks, MCP registration, plugins, skills, or guidance files. The generated configuration differs by host: Cursor receives MCP configuration, Claude Code receives lifecycle hooks and project guidance, and Codex CLI receives native command hooks with optional MCP registration.

Use the diagnostic command to inspect the database, embedding coverage, and configured integrations:

engrim doctor
engrim doctor --fix
engrim doctor --json

--fix repairs stale hook paths and supports cross-platform path recovery. --json is intended for CI or health-monitoring workflows.

Tools and capabilities

• Stores durable project memories in SQLite.
• Adds memories explicitly through the engrim_add MCP operation.
• Retrieves relevant records through combined lexical and vector search.
• Injects prioritized boot context within a fixed character budget.
• Tracks the agent that originated a memory.
• Configures multiple coding-agent environments through setup and lifecycle adapters.
• Checks database integrity, semantic recall coverage, and hook health with engrim doctor.

Limitations and notes

Engrim is designed around local coding-agent workflows and a stdio MCP transport. Its shared state depends on access to the same local database, so separate machines do not automatically share memories. Some hosts use optional MCP registration alongside native hooks or plugins, and the setup behavior varies by environment. The embedding model runs locally on CPU and is an 8MB static model2vec model.