mnemograph 0.1.1

Event-sourced knowledge graph memory system for Claude Code

Mnemograph

A persistent, event-sourced knowledge graph for Claude Code. Unlike simple key-value memory, Mnemograph captures entities, relations, and observations — enabling semantic search, tiered context retrieval, and git-based version control of your AI's memory.

Why Mnemograph?

Claude Code sessions are ephemeral. Mnemograph gives your AI partner persistent memory that:

• Survives across sessions — decisions, patterns, learnings persist
• Supports semantic search — find relevant context by meaning, not just keywords
• Provides tiered retrieval — shallow summaries to deep subgraphs based on need
• Versions like code — branch, commit, diff, revert your knowledge graph
• Enables collaboration — share memory repos across users or projects

Quick Start

Option 1: Let Claude Code install it

Give Claude Code this repo URL and ask it to set up mnemograph:

https://github.com/tm42/mnemograph

Or point Claude to the setup instructions directly:

Read https://raw.githubusercontent.com/tm42/mnemograph/main/SETUP_CLAUDE_CODE.md and follow them

Option 2: Manual installation

# Install from PyPI
pip install mnemograph

# Add to Claude Code (global, available in all projects)
claude mcp add --scope user mnemograph \
  -e MEMORY_PATH="$HOME/.claude/memory" \
  -- uvx mnemograph

# Initialize memory directory
mkdir -p ~/.claude/memory

Option 3: Install from source

git clone https://github.com/tm42/mnemograph.git
cd mnemograph
uv sync

# Add to Claude Code
claude mcp add --scope user mnemograph \
  -e MEMORY_PATH="$HOME/.claude/memory" \
  -- uv run --directory /path/to/mnemograph mnemograph

Usage

MCP Tools (used by Claude)

Mnemograph exposes these tools to Claude Code:

Tool	Description
create_entities	Create nodes: concepts, decisions, patterns, projects, questions, learnings
create_relations	Link entities with typed edges (implements, uses, decided_for, etc.)
add_observations	Add facts/notes to existing entities
delete_entities	Remove entities (cascades to relations)
delete_relations	Remove specific relations
delete_observations	Remove specific observations
read_graph	Get the full knowledge graph
search_nodes	Text search across names and observations
open_nodes	Get specific entities with their relations
search_semantic	Vector similarity search (meaning-based)
memory_context	Tiered retrieval: shallow (summary), medium (search+neighbors), deep (subgraph)

CLI Tools

mnemograph-cli — Event-level operations:

mnemograph-cli status              # Show entity/relation counts, recent events
mnemograph-cli log                 # View event history
mnemograph-cli log --session X     # Filter by session
mnemograph-cli revert --event ID   # Undo specific events
mnemograph-cli revert --session X  # Undo entire session
mnemograph-cli export              # Export graph as JSON

claude-mem — Git-based version control:

claude-mem init                  # Initialize memory as git repo
claude-mem status                # Show uncommitted changes
claude-mem commit -m "message"   # Commit current state
claude-mem log                   # View commit history

Architecture

~/.claude/memory/
├── events.jsonl    # Append-only event log (source of truth)
├── state.json      # Cached materialized state (derived)
├── vectors.db      # Semantic search index (derived)
└── .git/           # Version history

Event sourcing means all changes are recorded as immutable events. The current state is computed by replaying events. This enables:

• Full history of all changes
• Revert any operation
• Branch/merge knowledge graphs
• Audit trail of what Claude learned and when

Two-layer versioning:

• mnemograph-cli revert — fine-grained, undo specific events via compensating events
• claude-mem commit/revert — coarse-grained, git-level checkpoints

Entity Types

Type	Purpose	Example
concept	Ideas, patterns, approaches	"Repository pattern", "Event sourcing"
decision	Choices with rationale	"Chose SQLite over Postgres for simplicity"
project	Codebases, systems	"auth-service", "mnemograph"
pattern	Recurring code patterns	"Error handling with Result type"
question	Open unknowns	"Should we add real-time sync?"
learning	Discoveries	"pytest fixtures simplify test setup"
entity	Generic (people, files, etc.)	"Alice", "config.yaml"

Development

git clone https://github.com/tm42/mnemograph.git
cd mnemograph
uv sync                    # Install dependencies
uv run pytest              # Run tests
uv run ruff check .        # Lint
uv run mnemograph          # Run MCP server directly

Based On

Mnemograph builds on ideas from:

• MCP server-memory — Anthropic's official memory server (baseline)
• Mem0 — extraction/consolidation patterns
• Graphiti — bi-temporal modeling inspiration
• Event sourcing principles — append-only logs, state materialization

License

MIT