Skip to main content
Glama
Mnemograph
by tm42

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

./.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.

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

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

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:

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

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

# 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

~/.mnemograph/memory/    # or ~/.claude/memory, ~/.opencode/memory, etc.
├── mnemograph.db        # SQLite database (events + vectors)
├── state.json           # Cached materialized state (derived)
└── .git/                # Version history

Event 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 events

  • mnemograph 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 + main

  • Merge copies branch entities/relations into target branch

  • Delete cleans up after merge (or abandons exploratory work)

Branch Naming Conventions

Pattern

Use Case

feature/xyz

Feature-specific knowledge

explore/xyz

Exploratory/experimental work

project/xyz

Project-specific context

user/name

Personal workspace

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"

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 entities

  • topic/decisions — Architectural decisions

  • topic/patterns — Patterns and practices

  • topic/learnings — Key discoveries

  • topic/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 directly

Based On

Mnemograph builds on MCP server-memory — Anthropic's official memory server

License

MIT

Available Tools

31 tools
add_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

    A3.6/5.0

    Scored across 31 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      A 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.
      258
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An 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 npm
      737
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A 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.
      1
      MIT