memory engine

✨ 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

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

🔧 MCP Tools (18)

Memory Operations

Knowledge Graph

Session Management

System & Learning

🔍 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
}

📊 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

🧬 How It Differs

📝 License

MIT — see LICENSE.

🤝 Contributing

Contributions welcome! Open an issue or PR.

📖 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

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

⚙️ Configuration

Edit config.json to tune: