mcp-memory-engine 0.3.0

A general-purpose neuro-symbolic MCP memory engine for AI assistants.

🧠 MCP Memory Engine v2

AI memory that learns — not just stores.

An agent-agnostic cognitive memory layer, delivered as an MCP server. Works with Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client — no framework lock-in, no vendor dependency.

Most AI memory is "embed text, cosine similarity, return top-k." This one is modeled on how human cognition actually works: it forms abstract principles from accumulated observations, detects contradictions, knows what it doesn't know, and remembers to remind you about things you deferred.

See it in action

Built on a neuro-symbolic architecture — a Rust graph engine for deterministic reasoning paired with vector and lexical retrieval for semantic understanding — inspired by the CoALA (Cognitive Architectures for Language Agents) framework.

---

Why This Exists

AI agents forget everything between sessions. The current solutions:

• Platform-native memory (ChatGPT Memory, Claude MEMORY.md) — Proprietary, non-portable, no graph reasoning. Basically a notepad with a 200-line limit.
• Memory-as-a-service (Mem0, Zep) — Better retrieval, but treats memory as a database problem and locks you into their SDK or agent framework.
• Framework-specific (Letta/MemGPT) — Powerful, but requires you to adopt their entire agent architecture.

This project takes a different approach: pure MCP server, pluggable into any workflow, with cognitive features that go beyond storage into actual learning.

What makes it different

Feature	What it does	Why it matters
Schema Formation	Synthesizes higher-level principles from clusters of related insights via LLM	Your agent develops expertise — not just a bigger database
Prospective Memory	Dormant intentions that fire on context match: "When X comes up, remind me about Y"	Agents can defer decisions and act on them later, automatically
Contradiction Detection	Flags when new insights conflict with existing ones	No more stale knowledge silently misleading your agent
Metamemory	Tracks retrieval near-misses — the system knows what it doesn't know	Your agent gets intuition: "I think I've seen this before but can't find it"
Emotional Tagging	Valence tags (frustration, surprise, confusion, satisfaction) modulate salience	Painful debugging lessons stick harder; surprising discoveries surface more
Sleep Consolidation	Between-session replay: strengthens used memories, flags unfinished tasks (Zeigarnik effect)	Next session picks up where you left off, intelligently
Temporal Decay + Salience	Important memories resist decay; unused ones fade naturally	Self-maintaining memory — no manual cleanup needed
Encoding Specificity	Stores ambient context (active file, problem type) alongside insights	Better retrieval when you're in the same situation again

Architecture

┌──────────────────────────────────────────────────────┐
│                  MCP Server (main.py)                 │
│          24 tools: store, retrieve, schemas, etc.     │
├──────────────────────────────────────────────────────┤
│               Python Orchestrator Layer               │
│  memory_manager │ retrieval │ consolidation │ schema  │
│  validator      │ feedback  │ persistence            │
├──────────────────────────────────────────────────────┤
│                Rust Core (PyO3 bridge)                │
│  memory-graph: spread activation, decay, clustering   │
├──────────────────────────────────────────────────────┤
│                    Storage Layer                      │
│  ChromaDB (vectors) │ BM25 (lexical) │ JSON (state)  │
└──────────────────────────────────────────────────────┘

Why Rust + Python? Graph traversal, spread activation, and decay calculations are the hot path — called on every retrieval. Rust (via PyO3) keeps these operations fast (target: sub-200ms full retrieval including graph activation) without bottlenecking the host machine. Python handles the I/O-bound orchestration, scoring, and MCP interface.

Triple-threat retrieval: Vector similarity (ChromaDB) + lexical matching (BM25) + associative graph traversal (Rust spread-activation) — fused via Reciprocal Rank Fusion and weighted by recency, salience, feedback, schema boost, and encoding-context match. This allows the system to find relevant memories semantically, lexically, and associatively — not just one strategy.

Zero API keys required. Schema generation works through a two-step MCP flow: the engine finds candidate clusters and returns synthesis prompts, then the model you're already connected to (Claude, GPT, etc.) does the abstraction and commits the result. No external API calls needed. If you optionally set ANTHROPIC_API_KEY, schemas can also be generated automatically in the background during consolidation cycles.

---

Quick Start

Pre-built wheels (easiest — no Rust needed)

Download a pre-built wheel from the latest release, then:

pip install mcp_memory_engine-0.3.0-*.whl
pip install chromadb watchdog python-dotenv mcp pydantic psutil tree-sitter pathspec rank-bm25 httpx
python -c "from memory_manager import MemoryManager; print('OK')"

Pre-built wheels are available for Linux, macOS, and Windows — no Rust toolchain required.

From Source

git clone https://github.com/ForNeverAnd/mcp-memory-engine.git
cd mcp-memory-engine

# 1. Build the Rust extension (requires Rust + maturin)
pip install maturin
cd crates/memory-graph
maturin develop --release
cd ../..

# 2. Install Python dependencies
pip install -e .

# 3. Run the MCP server
python main.py

Docker

git clone https://github.com/ForNeverAnd/mcp-memory-engine.git
cd mcp-memory-engine
docker compose -f cloud/docker-compose.yml up -d

Server runs at http://localhost:8123. Verify:

curl http://localhost:8123/health

Connect to Claude Code / Cursor / Any MCP Client

Add to your MCP config:

{
  "mcpServers": {
    "memory": {
      "command": "python",
      "args": ["/path/to/mcp-memory-engine/main.py"]
    }
  }
}

Because this is a standard MCP server, it works with any MCP-compatible client — no SDK, no framework adoption, no lock-in.

---

How It Works in Practice

Store an insight:

store_insight(
    project_id="my-app",
    concepts=["auth", "jwt", "expiry"],
    insight="JWT tokens expire after 15 minutes; refresh tokens last 7 days.",
    salience=0.8,
    valence="satisfaction",
    encoding_context={"active_file": "src/auth/token.py", "problem_type": "architecture"}
)

Retrieve context:

retrieve_context(
    project_id="my-app",
    concepts=["authentication", "tokens"],
    current_context={"active_file": "src/auth/middleware.py"}
)

→ Returns ranked insights, triggered intentions, unfinished task reminders, and schema-level principles — all weighted by relevance, recency, salience, and past usefulness.

Set a prospective memory:

store_intention(
    project_id="my-app",
    trigger_concepts=["payments", "stripe"],
    intention_text="Verify Stripe webhook signatures before trusting payload.",
    expiry_hours=48
)

→ Fires automatically the next time "payments" or "stripe" appear in a retrieval query.

Generate schemas (learned principles):

generate_schemas(project_id="my-app")

→ Analyzes dense concept clusters and synthesizes abstract principles. E.g., after storing 5 insights about error handling, the system might form: "Boundary conditions in external API integrations require defensive validation at the transport layer, not the business logic layer."

---

All 24 MCP Tools

Tool	Purpose
store_insight	Store a decision, bug fix, or rule with concepts, salience, valence, and context
retrieve_context	Get ranked insights with schema boosting, intention triggers, and Zeigarnik reminders
index_workspace	Background file observation and code embedding
list_insights	List recent insights
delete_insight	Remove an insight
update_insight	Edit in-place (preserves history and graph connections)
export_memory	Export everything as human-readable markdown
get_memory_stats	Health and sizing metrics
health_check	Quick connectivity check
visualize_graph	Mermaid.js diagram of the memory graph
auto_summarize	Summarize the current session's warm memory
clear_warm_memory	Reset after summarization
get_contradictions	List unresolved contradictions
resolve_contradiction	Choose which version to keep
get_categories	Graph-derived topic clusters
force_consolidate	Run a consolidation cycle now
get_consolidation_log	Recent consolidation actions
mark_useful	Feedback: was this insight helpful?
generate_schemas	Find dense clusters and return synthesis prompts (Step 1)
commit_schema	Store a model-synthesized principle after validation (Step 2)
list_schemas	View learned principles
get_hierarchy	Memory hierarchy tree view
get_interference_hotspots	Ambiguous concept areas needing clarification
store_intention	Set a prospective memory (dormant until triggered)
list_intentions	View active intentions
clear_intention	Remove a fulfilled intention
get_knowledge_gaps	What the system doesn't know but has encountered

---

Configuration

All via environment variables with NEURO_ prefix:

Variable	Default	Description
NEURO_DECAY_RATE	0.05	Base decay rate for graph edges
NEURO_BM25_WEIGHT	0.3	BM25 weight in hybrid retrieval
NEURO_VECTOR_WEIGHT	0.7	Vector weight in hybrid retrieval
NEURO_RECENCY_WEIGHT	0.15	Recency weight in scoring
NEURO_RECENCY_DECAY_RATE	0.01	How fast recency score drops (~50% at 3 days)
NEURO_SALIENCE_WEIGHT	0.1	Salience weight in scoring
NEURO_USEFULNESS_WEIGHT	0.1	Feedback usefulness weight
NEURO_CONSOLIDATION_INTERVAL	300	Seconds between consolidation cycles
NEURO_SCHEMA_BOOST	1.3	Retrieval score multiplier for schemas
NEURO_CONTEXT_WEIGHT	0.1	Encoding-specificity context match weight

---

Cloud Deployment

A self-hosted REST API for remote access and multi-device sync:

docker compose -f cloud/docker-compose.yml up -d

Features encrypted file sync (AES-256-GCM), API key auth, and all MCP tools over HTTP. See cloud/README.md for details.

---

Development

cargo test                          # Rust tests
pytest tests/ -v                    # Python tests
python benchmarks/bench_retrieval.py # Benchmarks

See PLAN.md for the implementation roadmap and PLAN_COGNITIVE.md for the cognitive feature design documents.

---

The Cognitive Science Behind It

Each feature maps to established research in cognitive psychology and AI:

• Schema Formation → Expert chunking (de Groot, Chase & Simon)
• Temporal Decay + Salience → Memory consolidation theory (Ebbinghaus, McGaugh)
• Encoding Specificity → Tulving's encoding specificity principle
• Sleep Consolidation + Zeigarnik → Sleep-dependent memory consolidation, Zeigarnik effect
• Prospective Memory → Einstein & McDaniel's prospective memory framework
• Metamemory / Feeling of Knowing → Hart's feeling-of-knowing, metamemory research
• Emotional Tagging → Emotional enhancement of memory (Cahill & McGaugh)
• Contradiction Detection → Belief revision in epistemic logic
• Overall Architecture → CoALA: Cognitive Architectures for Language Agents (Sumers et al., 2023)

The design documents (PLAN_COGNITIVE.md) explain the mapping in detail.

---

License

MIT — see LICENSE.

Contributing

Open to contributions. If you're interested in cognitive architectures, neuro-symbolic AI, or MCP tooling, check the open issues or reach out.

Built with Rust, Python, stubbornness, and a lot of conversations with AI.