Mnemex¶

Memory persistence for AI assistants with temporal decay

What is Mnemex?¶

Mnemex is a Model Context Protocol (MCP) server that gives AI assistants like Claude a memory system with:

Short-term memory (STM) with temporal decay (like human working memory)
Long-term memory (LTM) for permanent storage in Obsidian-compatible Markdown
Knowledge graph with entities, relations, and context tracking
Smart consolidation to merge related memories
11 MCP tools and 7 CLI commands

Why Mnemex?¶

🔒 Privacy First: All data stored locally on your machine - no cloud, no tracking, no data sharing

📁 Human-Readable: - Short-term memory in JSONL format (one JSON object per line) - Long-term memory in Markdown with YAML frontmatter - Both formats are easy to inspect, edit, and version control

🎯 Full Control: Your memories, your files, your rules

Quick Start¶

Installation¶

# Recommended: UV tool install
uv tool install git+https://github.com/simplemindedbot/mnemex.git

Configuration¶

Create ~/.config/mnemex/.env:

# Storage
MNEMEX_STORAGE_PATH=~/.config/mnemex/jsonl

# Decay model (power_law | exponential | two_component)
MNEMEX_DECAY_MODEL=power_law
MNEMEX_PL_HALFLIFE_DAYS=3.0

# Long-term memory
LTM_VAULT_PATH=~/Documents/Obsidian/Vault

Claude Desktop Setup¶

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mnemex": {
      "command": "mnemex"
    }
  }
}

Restart Claude Desktop and you're ready!

Features¶

🧠 Temporal Decay¶

Memories fade over time unless reinforced through repeated access:

Power-law decay (default): Realistic forgetting curve matching human memory
Exponential decay: Traditional time-based forgetting
Two-component decay: Fast + slow decay for short/long term

🔗 Knowledge Graph¶

Build a graph of connected concepts:

Entities: People, projects, concepts
Relations: Explicit links between memories
Context tracking: Understand relationships over time

🤝 Smart Consolidation¶

Automatically detect and merge similar memories:

Duplicate detection: Near-duplicates → keep longest
Content merging: Related but distinct → combine with separation
Metadata preservation: Tags, entities, timestamps all preserved
Audit trail: Track consolidation history

📊 Unified Search¶

Search across both STM and LTM:

Temporal ranking: Recent memories weighted higher
Semantic similarity: Optional embedding-based search
Entity matching: Find related concepts
Tag filtering: Narrow results by category

Documentation¶

Architecture - System design and components
API Reference - All 11 MCP tools documented
Knowledge Graph - Entity and relation system
Scoring Algorithm - How temporal decay works
Deployment Guide - Production setup

Contributing¶

Contributions welcome! See CONTRIBUTING.md for guidelines.

License¶

MIT License - see LICENSE for details.

Status¶

✅ v1.0.0 Released (2025-10-09)

See ROADMAP.md for upcoming features.