Metadata-Version: 2.4
Name: mcp-memory-engine
Version: 0.3.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: chromadb
Requires-Dist: watchdog
Requires-Dist: python-dotenv
Requires-Dist: mcp
Requires-Dist: pydantic
Requires-Dist: psutil
Requires-Dist: tree-sitter>=0.22.0
Requires-Dist: tree-sitter-python
Requires-Dist: pathspec
Requires-Dist: rank-bm25
Requires-Dist: httpx
Requires-Dist: openai ; extra == 'all'
Requires-Dist: voyageai ; extra == 'all'
Requires-Dist: google-generativeai ; extra == 'all'
Requires-Dist: tree-sitter-rust ; extra == 'all'
Requires-Dist: tree-sitter-javascript ; extra == 'all'
Requires-Dist: tree-sitter-typescript ; extra == 'all'
Requires-Dist: tree-sitter-go ; extra == 'all'
Requires-Dist: tree-sitter-java ; extra == 'all'
Requires-Dist: tree-sitter-c-sharp ; extra == 'all'
Requires-Dist: tree-sitter-php ; extra == 'all'
Requires-Dist: tree-sitter-cpp ; extra == 'all'
Requires-Dist: tree-sitter-rust ; extra == 'all-langs'
Requires-Dist: tree-sitter-javascript ; extra == 'all-langs'
Requires-Dist: tree-sitter-typescript ; extra == 'all-langs'
Requires-Dist: tree-sitter-go ; extra == 'all-langs'
Requires-Dist: tree-sitter-java ; extra == 'all-langs'
Requires-Dist: tree-sitter-c-sharp ; extra == 'all-langs'
Requires-Dist: tree-sitter-php ; extra == 'all-langs'
Requires-Dist: tree-sitter-cpp ; extra == 'all-langs'
Requires-Dist: fastapi ; extra == 'cloud'
Requires-Dist: uvicorn[standard] ; extra == 'cloud'
Requires-Dist: cryptography ; extra == 'cloud'
Requires-Dist: httpx ; extra == 'cloud'
Requires-Dist: tree-sitter-cpp ; extra == 'cpp-lang'
Requires-Dist: tree-sitter-c-sharp ; extra == 'dotnet-lang'
Requires-Dist: google-generativeai ; extra == 'gemini'
Requires-Dist: tree-sitter-go ; extra == 'go-lang'
Requires-Dist: tree-sitter-javascript ; extra == 'js-lang'
Requires-Dist: tree-sitter-typescript ; extra == 'js-lang'
Requires-Dist: tree-sitter-java ; extra == 'jvm-lang'
Requires-Dist: openai ; extra == 'openai'
Requires-Dist: tree-sitter-php ; extra == 'php-lang'
Requires-Dist: tree-sitter-rust ; extra == 'rust-lang'
Requires-Dist: tree-sitter-rust ; extra == 'systems'
Requires-Dist: tree-sitter-cpp ; extra == 'systems'
Requires-Dist: tree-sitter-go ; extra == 'systems'
Requires-Dist: voyageai ; extra == 'voyage'
Requires-Dist: tree-sitter-javascript ; extra == 'web'
Requires-Dist: tree-sitter-typescript ; extra == 'web'
Provides-Extra: all
Provides-Extra: all-langs
Provides-Extra: cloud
Provides-Extra: cpp-lang
Provides-Extra: dotnet-lang
Provides-Extra: gemini
Provides-Extra: go-lang
Provides-Extra: js-lang
Provides-Extra: jvm-lang
Provides-Extra: openai
Provides-Extra: php-lang
Provides-Extra: rust-lang
Provides-Extra: systems
Provides-Extra: voyage
Provides-Extra: web
License-File: LICENSE
Summary: A general-purpose neuro-symbolic MCP memory engine for AI assistants.
Keywords: mcp,memory,ai,llm,rust,chromadb,treesitter,cursor,claude
Author-email: forneverand <forneverand@users.noreply.github.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Bug Tracker, https://github.com/ForNeverAnd/mcp-memory-engine/issues
Project-URL: Changelog, https://github.com/ForNeverAnd/mcp-memory-engine/blob/main/CHANGELOG.md
Project-URL: Homepage, https://github.com/ForNeverAnd/mcp-memory-engine
Project-URL: Repository, https://github.com/ForNeverAnd/mcp-memory-engine

# 🧠 MCP Memory Engine v2

**AI memory that learns — not just stores.**

An agent-agnostic cognitive memory layer, delivered as an [MCP](https://modelcontextprotocol.io/) 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

[![asciicast](https://asciinema.org/a/k68iBpY2l7rZSVGl.svg)](https://asciinema.org/a/k68iBpY2l7rZSVGl)

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](https://arxiv.org/abs/2309.02427) (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](https://github.com/ForNeverAnd/mcp-memory-engine/releases), then:
```bash
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
```bash
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
```bash
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:
```bash
curl http://localhost:8123/health
```

### Connect to Claude Code / Cursor / Any MCP Client

Add to your MCP config:
```json
{
  "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:

```bash
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](cloud/README.md) for details.

---

## Development

```bash
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](https://arxiv.org/abs/2309.02427) (Sumers et al., 2023)

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

---

## License

MIT — see [LICENSE](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.

