memory engine MCP Server

A living memory that decays, learns, and evolves with your AI.

Documentation

🧠 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.

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

✨ Features

Atomic memory model — knowledge stored as atoms (facts, decisions, events, preferences, logs, procedures, notes, session messages)
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
Session watcher — automatically ingests OpenClaw session messages as atoms with TTL (event-driven via inotify/watchdog)
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

🏗️ Architecture

┌─────────────────────────────────────────┐
│           Your AI Assistant              │
│         (via MCP Protocol)              │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│         MCP Server (FastMCP)            │
│     18 tools (recall, remember, ...)    │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│            Engine Layer                  │
│  ranking · decay · learning · merge     │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│     Session Watcher (watchdog/inotify)  │
│  monitors OpenClaw session JSONL files  │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│          SQLite (FTS5 + JSON1)          │
│     atoms · bonds · versions · Q&A      │
└─────────────────────────────────────────┘

Files

File	Purpose
`server.py`	MCP server — exposes 18 tools via FastMCP
`db.py`	SQLite layer — CRUD, FTS, bonds, versions
`engine.py`	Ranking, decay, similarity, gap detection
`learning.py`	Question generation (5 trigger types)
`importer.py`	Markdown → SQLite one-way importer
`session_watcher.py`	Watchdog-based session JSONL monitor
`schema.sql`	Database schema (atoms, bonds, FTS, versions)

~1,800 lines of Python. Dependencies: mcp SDK + watchdog.

🔧 MCP Tools (18)

Memory Operations

Tool	Description
`remember`	Create or update an atom
`recall`	Smart query (FTS × confidence × recency × weight)
`get_atom`	Get full atom details with all bonds
`list_atoms`	List atoms with filters (domain, type, status)
`merge_atoms`	Merge two atoms (secondary → primary)
`export_atom`	Export an atom as markdown

Knowledge Graph

Tool	Description
`link`	Create a typed bond between atoms
`unlink`	Remove a bond
`search_graph`	Traverse the knowledge graph from an atom

Session Management

Tool	Description
`recall_session`	Search messages within a specific session
`session_summary`	Get session overview (message count, time range)
`cleanup_sessions`	Delete expired session atoms (TTL cleanup)

System & Learning

Tool	Description
`stats`	Memory statistics (counts, domains, types)
`decay_run`	Execute decay cycle (reduce unused atom weights)
`learning_run`	Run learning engine (detect gaps, contradictions)
`ask_pending`	Get pending human questions
`answer_human`	Answer a pending question
`import_markdown`	Import markdown files (bulk or single)

📖 Usage Examples

Remember a decision

remember(
    title="Switched from npm to pnpm",
    body="Faster installs, better monorepo support. Migration completed 2026-06-15.",
    type="decision",
    domain="project:frontend",
    confidence=0.9,
    tags=["tooling", "npm", "pnpm"]
)

Recall relevant context

recall(query="frontend build tool choice", limit=5)
# Returns ranked results combining FTS match, confidence, recency, and weight

Link related concepts

link(
    from_id="switched_from_npm_to_pnpm",
    to_id="monorepo_setup",
    relation="depends_on",
    strength=0.8
)

Search within a session

recall_session(
    session_id="abc123-def456",
    query="database schema design",
    limit=10
)

Get a session summary

session_summary(session_id="abc123-def456")
# Returns: message count, user/assistant breakdown, time range, first topics

Import existing markdown notes

import_markdown()  # Bulk import all markdown files
import_markdown(filepath="/notes/project-decisions.md")  # Single file

Run the learning engine

learning_run()
# Detects: contradictions, weak atoms, merge candidates, decay-critical, gaps
# Generates human questions for findings

ask_pending(limit=5)
# Returns questions that need human input

🔍 Session Watcher

The session watcher monitors OpenClaw session JSONL files in real-time:

Event-driven — uses watchdog/inotify + polling fallback (every 30s) for reliability on Docker overlayfs
Persistent offsets — read positions stored in SQLite, survive container restarts
Deduplication — content_hash on every atom prevents duplicates on rescan or restart
Markdown digests — lightweight .md summary per session, survives JSONL deletion
Smart filtering — only captures user/assistant text; skips tool results, system messages, heartbeat noise, and system sessions (cron, MQTT, isolated)
Truncation detection — if a JSONL file shrinks (rotation/truncation), offset resets automatically
Auto-expiring — session atoms have a configurable TTL (default 30 days); a background thread cleans up expired atoms, digests, and stale offsets every 60 minutes
Automatic — starts on server boot, no manual intervention needed

Configuration

Mount the sessions directory and set the env vars:

volumes:
  - /path/to/openclaw/sessions:/sessions:ro
environment:
  - OPENCLAW_SESSIONS_DIR=/sessions
  - SESSION_TTL_DAYS=30
  - SESSION_DIGEST_DIR=/data/session_digests
  - SESSION_POLL_INTERVAL=30

Advanced filtering in config.json:

{
  "session_exclude_patterns": ["cron:", "mqtt", "heartbeat", "isolated"],
  "session_max_content_chars": 2000,
  "session_cleanup_interval_minutes": 60
}

🚀 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
      # Optional: OpenClaw sessions for session watcher
      - /path/to/openclaw/sessions:/sessions:ro
    environment:
      - MEMORY_DB_PATH=/data/memory.db
      - MARKDOWN_SOURCE=/workspace/memory
      - MEMORY_HOST=0.0.0.0
      - MEMORY_PORT=8085
      # Optional: session watcher
      - OPENCLAW_SESSIONS_DIR=/sessions
      - SESSION_TTL_DAYS=30

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, Cline, etc.):

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

See mcp.json for a ready-to-use example.

📊 Use Cases

Developer tools memory — persistent context for coding assistants (Claude Code, Cursor, Cline, Windsurf): remember project decisions, architecture choices, and coding preferences across sessions
Personal AI assistant memory — remember preferences, decisions, project context across sessions
Session continuity — automatically capture conversation context, never lose where you left off
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:

Section	What it controls
`decay`	Interval, decay factor, critical threshold, archive timeout
`ranking`	Weight of FTS score, confidence, recency, and atom weight
`learning`	Thresholds for contradiction, merge similarity, gap detection
`sessions_dir`	Path to OpenClaw sessions directory
`session_ttl_days`	TTL for session message atoms (default 30)
`session_poll_interval`	Polling fallback interval in seconds (default 30)
`session_digest_dir`	Directory for markdown session digests
`session_exclude_patterns`	Session ID patterns to skip (cron, mqtt, etc.)
`session_max_content_chars`	Max chars per session atom before truncation
`session_cleanup_interval_minutes`	TTL cleanup loop interval (default 60)

🧬 How It Differs

Feature	memory-graph	sqlite-memory	Memory Engine
Storage	SQLite	SQLite	SQLite
FTS search	❌	✅ (BM25)	✅ (multi-factor)
Decay	❌	❌	✅
Learning/Q&A	❌	❌	✅
Session watcher	❌	❌	✅
Markdown import	❌	❌	✅
Auto-bonding	❌	❌	✅
Graph traversal	Basic	❌	✅ (depth + relation)
Merge atoms	❌	❌	✅
TTL	❌	❌	✅
Versioning	❌	❌	✅

📝 License

MIT — see LICENSE.

🤝 Contributing

Contributions welcome! Open an issue or PR.

Made with 🧠 by SimoneB79