# Mnemograph

<!-- mcp-name: io.github.tm42/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

```bash
# 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

```bash
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) |
| `get_state_at` | Time travel: view graph state at any point in history |
| `diff_timerange` | Show what changed between two points in time |
| `get_entity_history` | Full changelog for a specific entity |
| `get_relation_weight` | Get weight breakdown (recency, co-access, explicit) |
| `set_relation_importance` | Set explicit importance weight (0.0-1.0) |
| `get_strongest_connections` | Find entity's most important connections |
| `get_weak_relations` | Find pruning candidates (low-weight relations) |

### CLI Tools

**`mnemograph-cli`** — Event-level operations:

```bash
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:

```bash
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
claude-mem graph                 # Open interactive graph viewer
claude-mem graph --watch         # Live reload mode (refresh button)
claude-mem --global graph        # Use global memory (~/.claude/memory)
```

**Graph Visualization** — Interactive D3.js viewer:

- **Layout algorithms**: Force-directed, Radial (hubs at center), Clustered (by component)
- **Color modes**: By entity type, connected component, or degree centrality
- **Edge weight slider**: Filter connections by strength
- **Live refresh**: `--watch` mode with Refresh button for real-time updates

## 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

```bash
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](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) — Anthropic's official memory server (baseline)
- [Mem0](https://github.com/mem0ai/mem0) — extraction/consolidation patterns
- [Graphiti](https://github.com/getzep/graphiti) — bi-temporal modeling inspiration
- Event sourcing principles — append-only logs, state materialization

## License

MIT
