🧠 Memory Engine

A living memory system for AI assistants — built on SQLite + MCP (Model Context Protocol).

Not just a key-value store. Not just a knowledge graph. A living memory that decays, learns, and evolves with your AI.

✨ Features

• _atomic memory model — knowledge stored as atoms (facts, decisions, events, preferences, logs, procedures, notes)

• multi-factor ranking — recall combines FTS relevance × confidence × recency × weight (not just BM25)

• organic decay — atoms lose weight over time if not accessed; critical ones get flagged for review

• learning engine — generates questions for the human when it detects contradictions, gaps, weak atoms, or merge candidates

• auto-bonding — creates relationship links between atoms automatically during import

• graph traversal — navigate the knowledge graph with depth control and relation filtering

• markdown import — one-way sync from your existing markdown notes (coexistence, not replacement)

• merge & deduplicate — consolidate similar atoms intelligently

• TTL support — atoms that expire automatically

• versioning — automatic atom history tracking

Related MCP server: sostenuto

🏗️ Architecture

┌─────────────────────────────────────────┐
│           Your AI Assistant              │
│         (via MCP Protocol)              │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│         MCP Server (FastMCP)            │
│     15 tools (recall, remember, ...)    │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│            Engine Layer                  │
│  ranking · decay · learning · merge     │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│          SQLite (FTS5 + JSON1)          │
│     atoms · bonds · versions · Q&A      │
└─────────────────────────────────────────┘

Files

Total: ~1,600 lines of Python. No external dependencies beyond mcp SDK.

🔧 MCP Tools

🚀 Quick Start

Docker (recommended)

# docker-compose.yml
services:
  memory-engine:
    build: .
    restart: unless-stopped
    expose:
      - "8085"
    volumes:
      - memory-data:/data
      - ./your-markdown-notes:/workspace/memory:ro
    environment:
      - MEMORY_DB_PATH=/data/memory.db
      - MARKDOWN_SOURCE=/workspace/memory
      - MEMORY_HOST=0.0.0.0
      - MEMORY_PORT=8085

volumes:
  memory-data:

docker compose up -d

Local (Python ≥3.11)

pip install -r requirements.txt
python server.py

Connect to your MCP client

Add to your MCP client config (e.g., Claude Desktop, OpenClaw, etc.):

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

📊 Use Cases

• Personal AI assistant memory — remember preferences, decisions, project context across sessions

• Team knowledge base — shared memory accessible to AI agents

• Project documentation — import existing markdown docs, query them naturally

• Learning journal — track decisions and their rationale over time

⚙️ Configuration

Edit config.json to tune:

🧬 How It Differs

📝 License

MIT — see LICENSE.

🤝 Contributing

Contributions welcome! Open an issue or PR.