Memory Engine MCP

[Version] [License: MIT] [Python] [MCP Registry Ready] [Docker]

[Memory Engine Logo]

🧠 Memory Engine MCP

Local-first, graph-aware long-term memory for AI assistants.
SQLite + semantic search + knowledge graph + MCP tools for agents that need continuity.

Works with Claude Desktop · Claude Code · Cursor · Cline · Windsurf · OpenClaw · any MCP client

Why Memory Engine?

Most MCP memory servers are either simple key-value stores or plain text search wrappers.

Memory Engine is different: it models memory as typed atoms connected by typed bonds, then retrieves context with a hybrid ranking pipeline that combines:

• full-text search (SQLite FTS5)
• semantic similarity via local Ollama embeddings
• confidence, recency, and weight
• graph expansion from related memories

The goal is not just storage. The goal is a memory system that can recall, connect, decay, curate, and learn over time.

Highlights

• Local-first — SQLite database, optional local embeddings via Ollama, no required cloud API.
• MCP-native — exposes 35 tools through FastMCP.
• Graph-aware recall — expands top hits through bidirectional bonds for richer context.
• Semantic search — meaning-based retrieval with nomic-embed-text.
• Markdown coexistence — import existing notes one-way without replacing your human-readable memory.
• Error memory — remembers mistakes and corrections, with auto-promotion to preferences after repeated failures.
• Cognitive curator — non-destructive maintenance pass for compaction, bond suggestions, duplicate detection, and isolated atom classification.
• Session watcher — canonical OpenClaw SQLite ingestion (schema 17), reset-aware digests, and JSONL legacy fallback.
• Backup & restore — full SQLite snapshots, JSON export/import, verified restores with automatic safety backups.
• Auth & hardening — optional API token, secure bind, input validation, rate limiting.
• Test suite — 144 tests covering CRUD, ranking, migrations, auth, backup, concurrency, and transcript ingestion.
• Benchmark — CLI recall quality suite with Precision@K, MRR, latency percentiles.

Architecture

AI assistant / MCP client        │        ▼FastMCP server — 35 tools        │        ▼Memory engine — hybrid ranking, graph recall, decay, learning        │        ├── SQLite — atoms, bonds, FTS5, JSON metadata, versions        ├── Ollama — optional local embeddings        ├── Curator — conservative maintenance        └── Session watcher — OpenClaw SQLite + JSONL fallback

MCP Tools

Memory

Knowledge graph

Learning and maintenance

Error memory and preferences

Import and introspection

Backup, restore & export

Web UI (optional)

Memory Engine includes an optional web UI for graph exploration, atom inspection, contradiction browsing, and impact analysis.

# In docker-compose.yml, add:#   environment:#     - MEM_UI_PORT=6000#   expose:#     - "6000"

Or run standalone:

python3 web_ui.py# Open http://localhost:6000

[Memory Engine Web UI — graph explorer]
Web UI: interactive graph, atom details, contradiction browser, stats dashboard

Quick start with Docker

Option A — Use the pre-built image (recommended)

# docker-compose.ymlservices:  memory-engine:    image: ghcr.io/simoneb79/memory-engine-mcp:2.1.0    ports:      - "8085:8085"    volumes:      - memory-data:/data    restart: unless-stopped
volumes:  memory-data:

docker compose up -d

Pin the version. Use an explicit tag like :1.7.0 in production. Avoid :latest — it can change without notice.

Option B — Build from source

git clone https://github.com/SimoneB79/memory-engine-mcp.gitcd memory-engine-mcpcp docker-compose.yml docker-compose.local.yml# Edit volume paths in docker-compose.local.yml if neededdocker compose -f docker-compose.local.yml up -d --build

Default endpoint:

http://localhost:8085/sse

Example MCP client config:

{  "mcpServers": {    "memory-engine": {      "url": "http://localhost:8085/sse",      "transport": "sse"    }  }}

See docs/INSTALL.md for Docker, local Python, Claude Desktop, Cursor, and OpenClaw examples.

Local Python

python -m venv .venvsource .venv/bin/activatepip install -r requirements.txtpython server.py

Configuration

Main configuration file: config.json

Important environment variables:

For the SQLite mount, WAL/SHM handling, filtering, and security boundary, see OpenClaw transcript ingestion.

Semantic search requires Ollama reachable from the container or host. Default:

{  "ollama": {    "enabled": true,    "host": "http://ollama:11434",    "model": "nomic-embed-text"  }}

If you do not use Ollama, set ollama.enabled to false; FTS recall still works.

Memory model

Atoms have:

• title
• body
• type: fact, decision, event, preference, log, procedure, note, etc.
• domain: project or topic namespace
• confidence
• weight
• tags
• optional TTL

Bonds connect atoms with relation types:

is_a · part_of · depends_on · contradicts · refines · derived_from · detail_of · related_to

Example usage

remember(    title="Use PostgreSQL for analytics",    body="SQLite is kept for local memory, PostgreSQL is used for multi-user analytics.",    type="decision",    domain="project:analytics",    confidence=0.9,    tags=["database", "architecture"])

recall(query="what database did we choose for analytics?", limit=5)

working_set(    query="continue the analytics backend work",    domain="project:analytics",    limit=8,    graph_depth=1)

Security

By default, Memory Engine runs in open mode (no auth) — safe for stdio or trusted local environments.

To enable API token auth:

// config.json{  "security": {    "api_token": "your-secret-token",    "allow_remote": false  }}

Or via environment variable:

MEMORY_API_TOKEN=your-secret-token

When auth is enabled:

• MCP SSE requests must include Authorization: Bearer <token>
• Web UI API endpoints require ?token=<token> or Bearer header
• Server binds to 127.0.0.1 unless allow_remote: true
• Input validation (title/body size limits) and rate limiting are always active

See CHANGELOG.md for the full list of security features.

Publishing and registries

This repository is prepared for MCP discovery:

• MCP Registry name: io.github.simoneb79/memory-engine-mcp
• Registry metadata: server.json
• Docker/OCI verification label: included in Dockerfile
• Client config example: mcp.json

See docs/PUBLISHING.md for the publication checklist.

Repository status

• Public GitHub repository: https://github.com/SimoneB79/memory-engine-mcp
• Existing listing: https://mcpmarket.com/server/memory-engine
• License: MIT

License

MIT — see LICENSE.

Made with 🧠 by SimoneB79