Mnemograph
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Mnemograph remember that we decided to use FastAPI for the backend"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: MegaMemory
Memory Scope: Local vs Global
Before using mnemograph, decide where to store memory:
Scope | Path | Use When |
Project-local |
| Knowledge specific to this repo (architecture, decisions, patterns) |
Global |
| Cross-project knowledge (personal learnings, universal patterns, preferences) |
Custom | Any path via | 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.
# Project-local (default)
MEMORY_PATH=".claude/memory"
# Global (cross-project)
MEMORY_PATH="$HOME/.claude/memory"
# CLI: use --global flag
mnemograph --global status
mnemograph --global graphQuick 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/mnemographOr point Claude to the setup instructions directly:
Read https://raw.githubusercontent.com/tm42/mnemograph/main/SETUP_CLAUDE_CODE.md and follow themOption 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/memoryOption 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.jsonCodex CLI —
~/.codex/config.yamlZed —
~/.config/zed/settings.jsonContinue.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
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 mnemographUsage
MCP Tools (used by any agent)
Mnemograph exposes these tools via MCP:
Core Operations:
Tool | Description |
| Primary storage: Store knowledge atomically (entity + observations + relations in one call) |
| Primary retrieval: Get relevant context with auto token management. Use |
| Create entities (auto-blocks duplicates >80% match) |
| Link entities with typed edges (implements, uses, decided_for, etc.) |
| Add facts/notes to existing entities |
| Get the full knowledge graph (warning: may be large) |
| Remove entities (cascades to relations) |
| Remove specific relations |
| Remove specific observations |
Session Lifecycle:
Tool | Description |
| Signal session start, get initial context. Returns quick_start guide. |
| Signal session end, optionally save summary |
| Get oriented with the knowledge graph (call at session start) |
Branching (Parallel Workstreams):
Tool | Description |
| Create a named branch for isolated work (e.g., "feature/auth-refactor") |
| Switch to a different branch |
| List all branches |
| Merge a branch into main |
| Delete a branch |
| Get the current branch name |
Graph Maintenance:
Tool | Description |
| Find entities with similar names (duplicate detection) |
| Find entities with no relations |
| Merge duplicate entities (consolidates observations, redirects relations) |
| Assess graph quality: orphans, duplicates, overloaded entities |
| Suggest potential relations based on semantic similarity |
| Create entities bypassing duplicate check |
| Clear all entities/relations (event-sourced, can rewind) |
Time Travel:
Tool | Description |
| View graph state at any point in history |
| Show what changed between two points in time |
| Full changelog for a specific entity |
| Rewind graph to a previous state using git |
| Restore graph to state at timestamp (audit-preserving) |
| Reload graph state from disk (after git operations) |
Edge Weights:
Tool | Description |
| Get weight breakdown (recency, co-access, explicit) |
| Set explicit importance weight (0.0-1.0) |
| Find entity's most important connections |
| 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:
# 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, gotchasmedium— 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:
# 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 locationRunning from anywhere (without activating the venv):
# Using uv (recommended)
uv run --directory /path/to/mnemograph mnemograph graph
# Using uvx (if installed from PyPI)
uvx --from mnemograph mnemograph statusGraph 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:
--watchmode with Refresh button for real-time updates
Architecture
~/.mnemograph/memory/ # or ~/.claude/memory, ~/.opencode/memory, etc.
├── mnemograph.db # SQLite database (events + vectors)
├── state.json # Cached materialized state (derived)
└── .git/ # Version historyEvent sourcing means all changes are recorded as immutable events in SQLite. 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 vcs revert— fine-grained, undo specific events via compensating eventsmnemograph rewind/mnemograph restore— coarse-grained, git-level or timestamp-based restore
Branching
Branches let you work on isolated knowledge without affecting the main graph. Perfect for:
Exploratory work — try approaches without polluting shared knowledge
Feature-specific context — "feature/auth-refactor" keeps auth decisions separate
Multiple projects — switch context between different codebases
Creating and Using Branches
# Create a branch for your feature
create_branch(name="feature/auth-refactor")
# Work normally — all operations happen on this branch
remember(name="OAuth2", entity_type="concept",
observations=["Implementing OAuth2 flow"])
# Switch back to main to see clean state
switch_branch(name="main")
# Merge when ready
merge_branch(source="feature/auth-refactor", target="main")How Branching Works
Main branch always exists, contains shared knowledge
Feature branches inherit from main but additions stay isolated
Automatic filtering —
recall,search, etc. only see current branch + mainMerge copies branch entities/relations into target branch
Delete cleans up after merge (or abandons exploratory work)
Branch Naming Conventions
Pattern | Use Case |
| Feature-specific knowledge |
| Exploratory/experimental work |
| Project-specific context |
| Personal workspace |
Entity Types
Type | Purpose | Example |
| Ideas, patterns, approaches | "Repository pattern", "Event sourcing" |
| Choices with rationale | "Chose SQLite over Postgres for simplicity" |
| Codebases, systems | "auth-service", "mnemograph" |
| Recurring code patterns | "Error handling with Result type" |
| Open unknowns | "Should we add real-time sync?" |
| Discoveries | "pytest fixtures simplify test setup" |
| Generic (people, files, etc.) | "Alice", "config.yaml" |
Topic Convention
Use topic entities as entry points for browsing related knowledge:
# Create topic entry points
create_entities([
{"name": "topic/projects", "entityType": "entity"},
{"name": "topic/decisions", "entityType": "entity"},
{"name": "topic/patterns", "entityType": "entity"},
])
# Link entities to their topics
create_relations([
{"from": "auth-service", "to": "topic/projects", "relationType": "part_of"},
{"from": "Decision: Use Redis", "to": "topic/decisions", "relationType": "part_of"},
])Standard topics:
topic/projects— Project entitiestopic/decisions— Architectural decisionstopic/patterns— Patterns and practicestopic/learnings— Key discoveriestopic/questions— Open questions
This makes it easy to query "what decisions have we made?" by exploring topic/decisions.
Development
git clone https://github.com/tm42/mnemograph.git
cd mnemograph
uv sync # Install dependencies
uv run pytest --cov # Run tests with coverage (enforces 75% minimum)
uv run ruff check . # Lint
uv run mnemograph # Run MCP server directlyBased On
Mnemograph builds on MCP server-memory — Anthropic's official memory server
License
MIT
Available Tools
31 toolsadd_observationsA
Add atomic facts to existing entities. One fact per observation — don't dump paragraphs. Use prefixes: 'Gotcha: ...', 'Warning: ...', 'Status: ...', 'Source: ...'. For relations, use create_relations instead of 'X is related to Y' observations.
Inputs: observations (required).
branch_addA
Add entities to the current branch. Only works on non-main branches. Optionally includes relations between added entities.
Inputs: entity_names (required), include_relations.
branch_checkoutA
Switch to a different branch. Changes what entities/relations are visible in queries. Use 'main' to see everything.
Inputs: name (required).
branch_createB
Create a new branch with seed entities. Uses BFS to expand from seeds to N-hop neighbors. Branch names follow format: / where type is project|feature|domain|spike|archive.
Inputs: name (required), depth, checkout, description, +1 more.
branch_currentA
Get the name and details of the currently active branch.
Inputs: no named parameters.
branch_diffA
Show differences between two branches. Returns entities and relations that are only in one branch vs the other, plus what's common to both.
Inputs: branch_b (required), branch_a.
branch_listA
List all memory branches. Branches are filtered views of the knowledge graph. Main branch sees everything; other branches see filtered subsets.
Inputs: include_archived.
clear_graphA
Clear ALL entities and relations from the graph. Use sparingly! For graphs with >10 entities: requires reason AND confirm_token. Event-sourced: can rewind to before clear with get_state_at(timestamp).
Inputs: reason, confirm_token.
create_relationsA
Create relations (edges) between entities. Every entity should have at least one relation. Use specific types: uses, implements, part_of, depends_on, alternative_to, decided_by, affects. Avoid generic 'related_to' when a specific type fits.
Inputs: relations (required).
delete_entitiesA
Delete entities by name (cascades to relations)
Inputs: entityNames (required).
delete_observationsC
Delete specific observations from entities
Inputs: deletions (required).
delete_relationsC
Delete specific relations
Inputs: relations (required).
diff_timerangeC
Show what changed between two points in time
Inputs: start (required), end.
find_orphansA
Find entities with no relations (likely incomplete). Orphans should be connected, merged into another entity, or deleted.
Inputs: no named parameters.
find_similarA
Find entities with similar names (potential duplicates). Use before creating to check for existing entities. Returns similarity scores — consider merging if >0.85.
Inputs: name (required), threshold.
get_entity_historyB
Get the history of all changes to an entity
Inputs: entity_name (required).
get_graph_healthA
Assess knowledge graph quality. Returns: orphan count, potential duplicates, overloaded entities, weak relations. Run periodically to maintain graph hygiene. Use full=true for deep duplicate detection (slower).
Inputs: full.
get_primerA
Get oriented with this knowledge graph. Call at session start.
Inputs: no named parameters.
get_state_atA
Get graph state at a specific point in time (event rewind)
Inputs: timestamp (required).
get_strongest_connectionsB
Get an entity's strongest connections by edge weight
Inputs: entity_name (required), limit.
get_weak_relationsA
Get relations below a weight threshold (pruning candidates)
Inputs: limit, max_weight.
merge_entitiesA
Merge source entity into target. Source's observations and relations move to target, then source is deleted. Use to consolidate duplicates (e.g., merge 'ReactJS' into 'React').
Inputs: source (required), target (required), delete_source.
recallA
PRIMARY RETRIEVAL TOOL. Get relevant context with automatic token management. Use focus=['EntityName'] to get full details on specific entities. shallow=quick summary, medium=semantic search+neighbors, deep=full exploration.
Inputs: depth (required), focus, query, format, +1 more.
reloadA
Reload graph state from mnemograph.db on disk. Use after: git operations (checkout, restore), external edits to mnemograph.db, or any time MCP server seems out of sync.
Inputs: no named parameters.
rememberA
Store knowledge atomically — entity + observations + relations in ONE call. PRIMARY TOOL for storing new knowledge. Prevents orphan entities. AUTO-BLOCKS if similar entity exists (>80% match). Use force=True to override.
Inputs: name (required), entity_type (required), force, relations, +1 more.
restore_state_atA
Restore graph to state at a specific timestamp. Emits clear + recreate events — full audit trail preserved. Use get_state_at() first to preview what will be restored.
Inputs: timestamp (required), reason.
rewindA
Rewind graph to a previous state using git. Fast undo, audit trail in git only. For audit-preserving restore, use restore_state_at() instead.
Inputs: steps, to_commit.
session_endB
Signal session end, optionally save summary
Inputs: summary.
session_startB
Signal session start and get initial context. Returns quick_start guide with tool usage. IMPORTANT: If memory is empty, ask user whether to use project-local or global memory scope.
Inputs: project_hint.
set_relation_importanceB
Set explicit importance weight for a relation
Inputs: importance (required), relation_id (required).
suggest_relationsA
Suggest potential relations for an entity based on semantic similarity and co-occurrence. Useful for connecting newly created entities or discovering missing links.
Inputs: entity (required), limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 31 tools
Each tool has a distinct purpose, but the high number (31) may cause some confusion for agents, especially with multiple state-manipulation tools (e.g., rewind, restore_state_at, clear_graph). However, descriptions are clear enough to differentiate them.
All tool names follow a consistent verb_noun pattern in lowercase with underscores (e.g., add_observations, branch_create, get_state_at). No mixing of styles or vague verbs.
31 tools is above the typical well-scoped range (3-15). While the knowledge graph domain is complex, the count feels slightly heavy, potentially overwhelming for agents.
The tool set covers the full lifecycle: entity CRUD, relations, branching, time-travel, maintenance (orphans, duplicates, health), sessions, and retrieval. No obvious gaps for the stated purpose.
Maintenance
Related MCP Connectors
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Persistent, portable memory for AI assistants — your private memory graph, from any MCP client.
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Shared long-term memory for AI agents: save and recall context as a searchable knowledge graph.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceA graph-based MCP server that provides AI coding agents with persistent memory to store patterns, track complex relationships, and retrieve knowledge across sessions. It leverages graph structures to handle temporal queries and relational paths that traditional vector stores often miss.258MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that lets coding agents build and query a persistent knowledge graph of concepts, architecture, and decisions, enabling them to remember across sessions.175 npm737MIT
- AlicenseAqualityCmaintenanceA local knowledge graph MCP server that provides AI agents with permanent, structured memory about codebases, enabling semantic search, blast radius analysis, and convention enforcement.83MIT
- AlicenseNot gradedqualityCmaintenanceA universal MCP server providing persistent, structured memory through a knowledge graph with graph storage, semantic vector search, and multi-hop traversal for AI agents and IDEs.1MIT