Mnemograph

Event-sourced knowledge graph memory for Claude Code with semantic search

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "mnemograph": {
      "command": "npx",
      "args": [
        "-y",
        "mnemograph"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

Mnemograph

A persistent, event-sourced knowledge graph for AI coding agents. 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.

Works with: Claude Code, opencode, codex CLI, Zed, Continue.dev, and any MCP-compatible agent.

Why Mnemograph?

AI coding 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

Memory Scope: Local vs Global

Before using mnemograph, decide where to store memory:

Scope	Path	Use When
Project-local	`./.claude/memory`	Knowledge specific to this repo (architecture, decisions, patterns)
Global	`~/.claude/memory`	Cross-project knowledge (personal learnings, universal patterns, preferences)
Custom	Any path via `MEMORY_PATH`	Shared team memory, org-wide knowledge bases

Important: Agents should ask the user which scope to use when first setting up mnemograph for a project. This affects where knowledge is stored and whether it's shared across projects.

bash

# Project-local (default)
MEMORY_PATH=".claude/memory"

# Global (cross-project)
MEMORY_PATH="$HOME/.claude/memory"

# CLI: use --global flag
mnemograph --global status
mnemograph --global graph

Quick Start

Option 1: Let Claude Code install it

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

Code

https://github.com/tm42/mnemograph

Or point Claude to the setup instructions directly:

Code

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: Other MCP Clients

Each MCP client has a different configuration format. See UNIVERSAL_MCP_COMPATIBILITY.md for copy-paste configs for:

opencode — ~/.config/opencode/opencode.json
Codex CLI — ~/.codex/config.yaml
Zed — ~/.config/zed/settings.json
Continue.dev — ~/.continue/config.json

The key environment variable is MEMORY_PATH — set it to where you want the knowledge graph stored.

Option 4: Install from source

bash

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

# Add to Claude Code (or adapt for your MCP client)
claude mcp add --scope user mnemograph \
  -e MEMORY_PATH="$HOME/.claude/memory" \
  -- uv run --directory /path/to/mnemograph mnemograph

Usage

MCP Tools (used by any agent)

Mnemograph exposes these tools via MCP:

Core Operations:

Tool	Description
`remember`	Primary storage: Store knowledge atomically (entity + observations + relations in one call)
`recall`	Primary retrieval: Get relevant context with auto token management. Use `focus=['Entity']` for full details. Default output is human-readable prose.
`create_entities`	Create entities (auto-blocks duplicates >80% match)
`create_relations`	Link entities with typed edges (implements, uses, decided_for, etc.)
`add_observations`	Add facts/notes to existing entities
`read_graph`	Get the full knowledge graph (warning: may be large)
`delete_entities`	Remove entities (cascades to relations)
`delete_relations`	Remove specific relations
`delete_observations`	Remove specific observations

Session Lifecycle:

Tool	Description
`session_start`	Signal session start, get initial context. Returns quick_start guide.
`session_end`	Signal session end, optionally save summary
`get_primer`	Get oriented with the knowledge graph (call at session start)

Branching (Parallel Workstreams):

Tool	Description
`create_branch`	Create a named branch for isolated work (e.g., "feature/auth-refactor")
`switch_branch`	Switch to a different branch
`list_branches`	List all branches
`merge_branch`	Merge a branch into main
`delete_branch`	Delete a branch
`get_current_branch`	Get the current branch name

Graph Maintenance:

Tool	Description
`find_similar`	Find entities with similar names (duplicate detection)
`find_orphans`	Find entities with no relations
`merge_entities`	Merge duplicate entities (consolidates observations, redirects relations)
`get_graph_health`	Assess graph quality: orphans, duplicates, overloaded entities
`suggest_relations`	Suggest potential relations based on semantic similarity
`create_entities_force`	Create entities bypassing duplicate check
`clear_graph`	Clear all entities/relations (event-sourced, can rewind)

Time Travel:

Tool	Description
`get_state_at`	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
`rewind`	Rewind graph to a previous state using git
`restore_state_at`	Restore graph to state at timestamp (audit-preserving)
`reload`	Reload graph state from disk (after git operations)

Edge Weights:

Tool	Description
`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)

Recall: Prose vs Graph Format

The recall tool returns context in prose format by default — human-readable text that agents can consume directly without parsing JSON:

python

# Default: prose format (human-readable)
recall(depth="medium", query="authentication")
# Returns:
# **MyApp** (project)
# A Python web service. Uses OAuth2 for user auth.
# Uses: PostgreSQL, Redis
#
# **Decisions:**
# • Decision: Use JWT — Stateless tokens for API authentication
#
# **Gotchas:**
# • Token expiry is 1 hour by default
# • Refresh tokens stored in Redis

# Optional: graph format (structured JSON)
recall(depth="medium", query="authentication", format="graph")

Depth levels:

shallow — Quick summary: entity counts, recent activity, gotchas
medium — Semantic search + 1-hop neighbors (~2000 tokens)
deep — Multi-hop traversal from focus entities (~5000 tokens)

Gotcha extraction: Observations prefixed with Gotcha:, Warning:, Note:, or Important: are automatically extracted into a dedicated section.

CLI Tools

mnemograph — Unified CLI for all memory operations:

server.ts

# Basic operations
mnemograph status                # Show entity/relation counts, recent events
mnemograph log                   # View event history
mnemograph log --session X       # Filter by session
mnemograph sessions              # List all sessions
mnemograph export                # Export graph as JSON

# VCS commands (git-based version control)
mnemograph vcs init              # Initialize memory as git repo
mnemograph vcs commit -m "msg"   # Commit current state
mnemograph vcs log               # View commit history
mnemograph vcs revert --event ID # Undo specific events (compensating events)
mnemograph vcs revert --session X # Undo entire session

# Graph visualization
mnemograph graph                 # Open interactive graph viewer
mnemograph graph --watch         # Live reload mode (refresh button)

# Time travel
mnemograph show --at "2 days ago"  # View state at a point in time
mnemograph diff "1 week ago"       # Show changes since then
mnemograph history "EntityName"    # Full changelog for an entity
mnemograph rewind -n 1             # Git-based rewind by N commits
mnemograph restore --to "yesterday" # Event-based restore (audit-preserving)

# Graph health and maintenance
mnemograph health                # Show graph health report (orphans, duplicates, etc.)
mnemograph health --fix          # Interactive cleanup mode
mnemograph similar "React"       # Find entities similar to "React" (duplicate check)
mnemograph orphans               # List entities with no relations
mnemograph suggest "FastAPI"     # Suggest relations for an entity
mnemograph clear                 # Clear all entities and relations (with confirmation)

# Global options (come *before* the subcommand)
mnemograph --global status       # Use global memory (~/.claude/memory)
mnemograph --memory-path /path graph  # Custom memory location

Running from anywhere (without activating the venv):

bash

# Using uv (recommended)
uv run --directory /path/to/mnemograph mnemograph graph

# Using uvx (if installed from PyPI)
uvx --from mnemograph mnemograph status

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

Read the full README →View source on GitHub →

Related MCP Servers

View all in Knowledge & Memory View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Mnemograph

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "mnemograph": { "command": "npx", "args": ["-y", "mnemograph"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/mnemograph?style=directory)](https://allmcps.com/mcp/mnemograph)

HTML Embed

<a href="https://allmcps.com/mcp/mnemograph"><img src="https://allmcps.com/api/badge/mnemograph?style=directory" alt="Mnemograph on AllMCPs" /></a>

Technical Specs & Signals

CategoryKnowledge & Memory

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

★ Featured

AllMCPs Server

The official MCP server for AllMCPs.com - submit and manage tools directly from your AI. The open directory for MCP servers. Connect Claude, Cursor, Windsurf, and AI agents to databases, tools, files, and APIs. Explore 10,000+ servers. AllMCPs is the premier, open directory for discovering, evaluating, and installing Model Context Protocol (MCP) servers to equip AI agents and LLMs with real-world superpowers.

Explore Server →

Own this project?

This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge and attach your website — proof is checked automatically, then reviewed by our team.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 🧠 Knowledge & Memory →Best MCP servers for Memory & Knowledge →Alternatives to Mnemograph →Install in Claude Desktop Install in Cursor Install in VS Code

Mnemograph

Event-sourced knowledge graph memory for Claude Code with semantic search

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "mnemograph": {
      "command": "npx",
      "args": [
        "-y",
        "mnemograph"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

Mnemograph

Works with: Claude Code, opencode, codex CLI, Zed, Continue.dev, and any MCP-compatible agent.

Why Mnemograph?

AI coding 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

Memory Scope: Local vs Global

Before using mnemograph, decide where to store memory:

Scope	Path	Use When
Project-local	`./.claude/memory`	Knowledge specific to this repo (architecture, decisions, patterns)
Global	`~/.claude/memory`	Cross-project knowledge (personal learnings, universal patterns, preferences)
Custom	Any path via `MEMORY_PATH`	Shared team memory, org-wide knowledge bases

Important: Agents should ask the user which scope to use when first setting up mnemograph for a project. This affects where knowledge is stored and whether it's shared across projects.

bash

# Project-local (default)
MEMORY_PATH=".claude/memory"

# Global (cross-project)
MEMORY_PATH="$HOME/.claude/memory"

# CLI: use --global flag
mnemograph --global status
mnemograph --global graph

Quick Start

Option 1: Let Claude Code install it

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

Code

https://github.com/tm42/mnemograph

Or point Claude to the setup instructions directly:

Code

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: Other MCP Clients

Each MCP client has a different configuration format. See UNIVERSAL_MCP_COMPATIBILITY.md for copy-paste configs for:

opencode — ~/.config/opencode/opencode.json
Codex CLI — ~/.codex/config.yaml
Zed — ~/.config/zed/settings.json
Continue.dev — ~/.continue/config.json

The key environment variable is MEMORY_PATH — set it to where you want the knowledge graph stored.

Option 4: Install from source

bash

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

# Add to Claude Code (or adapt for your MCP client)
claude mcp add --scope user mnemograph \
  -e MEMORY_PATH="$HOME/.claude/memory" \
  -- uv run --directory /path/to/mnemograph mnemograph

Usage

MCP Tools (used by any agent)

Mnemograph exposes these tools via MCP:

Core Operations:

Tool	Description
`remember`	Primary storage: Store knowledge atomically (entity + observations + relations in one call)
`recall`	Primary retrieval: Get relevant context with auto token management. Use `focus=['Entity']` for full details. Default output is human-readable prose.
`create_entities`	Create entities (auto-blocks duplicates >80% match)
`create_relations`	Link entities with typed edges (implements, uses, decided_for, etc.)
`add_observations`	Add facts/notes to existing entities
`read_graph`	Get the full knowledge graph (warning: may be large)
`delete_entities`	Remove entities (cascades to relations)
`delete_relations`	Remove specific relations
`delete_observations`	Remove specific observations

Session Lifecycle:

Tool	Description
`session_start`	Signal session start, get initial context. Returns quick_start guide.
`session_end`	Signal session end, optionally save summary
`get_primer`	Get oriented with the knowledge graph (call at session start)

Branching (Parallel Workstreams):

Tool	Description
`create_branch`	Create a named branch for isolated work (e.g., "feature/auth-refactor")
`switch_branch`	Switch to a different branch
`list_branches`	List all branches
`merge_branch`	Merge a branch into main
`delete_branch`	Delete a branch
`get_current_branch`	Get the current branch name

Graph Maintenance:

Tool	Description
`find_similar`	Find entities with similar names (duplicate detection)
`find_orphans`	Find entities with no relations
`merge_entities`	Merge duplicate entities (consolidates observations, redirects relations)
`get_graph_health`	Assess graph quality: orphans, duplicates, overloaded entities
`suggest_relations`	Suggest potential relations based on semantic similarity
`create_entities_force`	Create entities bypassing duplicate check
`clear_graph`	Clear all entities/relations (event-sourced, can rewind)

Time Travel:

Tool	Description
`get_state_at`	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
`rewind`	Rewind graph to a previous state using git
`restore_state_at`	Restore graph to state at timestamp (audit-preserving)
`reload`	Reload graph state from disk (after git operations)

Edge Weights:

Tool	Description
`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)

Recall: Prose vs Graph Format

The recall tool returns context in prose format by default — human-readable text that agents can consume directly without parsing JSON:

python

# Default: prose format (human-readable)
recall(depth="medium", query="authentication")
# Returns:
# **MyApp** (project)
# A Python web service. Uses OAuth2 for user auth.
# Uses: PostgreSQL, Redis
#
# **Decisions:**
# • Decision: Use JWT — Stateless tokens for API authentication
#
# **Gotchas:**
# • Token expiry is 1 hour by default
# • Refresh tokens stored in Redis

# Optional: graph format (structured JSON)
recall(depth="medium", query="authentication", format="graph")

Depth levels:

shallow — Quick summary: entity counts, recent activity, gotchas
medium — Semantic search + 1-hop neighbors (~2000 tokens)
deep — Multi-hop traversal from focus entities (~5000 tokens)

Gotcha extraction: Observations prefixed with Gotcha:, Warning:, Note:, or Important: are automatically extracted into a dedicated section.

CLI Tools

mnemograph — Unified CLI for all memory operations:

server.ts

# Basic operations
mnemograph status                # Show entity/relation counts, recent events
mnemograph log                   # View event history
mnemograph log --session X       # Filter by session
mnemograph sessions              # List all sessions
mnemograph export                # Export graph as JSON

# VCS commands (git-based version control)
mnemograph vcs init              # Initialize memory as git repo
mnemograph vcs commit -m "msg"   # Commit current state
mnemograph vcs log               # View commit history
mnemograph vcs revert --event ID # Undo specific events (compensating events)
mnemograph vcs revert --session X # Undo entire session

# Graph visualization
mnemograph graph                 # Open interactive graph viewer
mnemograph graph --watch         # Live reload mode (refresh button)

# Time travel
mnemograph show --at "2 days ago"  # View state at a point in time
mnemograph diff "1 week ago"       # Show changes since then
mnemograph history "EntityName"    # Full changelog for an entity
mnemograph rewind -n 1             # Git-based rewind by N commits
mnemograph restore --to "yesterday" # Event-based restore (audit-preserving)

# Graph health and maintenance
mnemograph health                # Show graph health report (orphans, duplicates, etc.)
mnemograph health --fix          # Interactive cleanup mode
mnemograph similar "React"       # Find entities similar to "React" (duplicate check)
mnemograph orphans               # List entities with no relations
mnemograph suggest "FastAPI"     # Suggest relations for an entity
mnemograph clear                 # Clear all entities and relations (with confirmation)

# Global options (come *before* the subcommand)
mnemograph --global status       # Use global memory (~/.claude/memory)
mnemograph --memory-path /path graph  # Custom memory location

Running from anywhere (without activating the venv):

bash

# Using uv (recommended)
uv run --directory /path/to/mnemograph mnemograph graph

# Using uvx (if installed from PyPI)
uvx --from mnemograph mnemograph status

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

Read the full README →View source on GitHub →

Related MCP Servers

View all in Knowledge & Memory View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Mnemograph

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "mnemograph": { "command": "npx", "args": ["-y", "mnemograph"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/mnemograph?style=directory)](https://allmcps.com/mcp/mnemograph)

HTML Embed

<a href="https://allmcps.com/mcp/mnemograph"><img src="https://allmcps.com/api/badge/mnemograph?style=directory" alt="Mnemograph on AllMCPs" /></a>

Technical Specs & Signals

CategoryKnowledge & Memory

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

★ Featured

AllMCPs Server

Explore Server →

Own this project?

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 🧠 Knowledge & Memory →Best MCP servers for Memory & Knowledge →Alternatives to Mnemograph →Install in Claude Desktop Install in Cursor Install in VS Code