Mnemograph

io.github.tm42Published by GitHub account tm42v0.5.1Updated Oct 24, 2026

Event-sourced knowledge graph memory for AI coding agents with semantic search

VerifiedSTDIODesktop onlyKnowledge & MemoryDeveloper Tools

Overview

AI-generated overview

Gives coding agents a persistent, event-sourced knowledge graph memory with semantic search, branching, and git-style history.

What you can do
Mnemograph stores entities, relations, and observations in a local knowledge graph so an assistant can remember decisions, patterns, and learnings across sessions. Tools include remember and recall for storage and retrieval, session lifecycle helpers, branch and merge operations, graph maintenance such as duplicate detection and merging, and time-travel tools for viewing, diffing, rewinding, and restoring past states. Recall returns human-readable prose by default, with shallow, medium, and deep retrieval depths.
When to use it
Use it when an assistant should carry project knowledge between coding sessions, for example architecture decisions, recurring patterns, and gotchas. It suits multi-project or team setups where memory is shared through a repository, and workflows that need isolated branches or an audit trail of what was learned.
Requirements
Runs locally over stdio as a PyPI package, typically launched with uvx, so Python tooling is needed. Set MEMORY_PATH to the memory directory; project-local, global, and custom paths are supported. No authentication is declared. Git is used for version history.
Before you install
The server writes, merges, and deletes knowledge graph data, and clear_graph or delete tools can remove entities and relations, though event sourcing allows rewinding. Memory may be stored in a shared repository, so anything recorded there is visible to others with access. Choose the memory scope deliberately, since a global path mixes knowledge across projects.

Installation

In SourceWeft

  1. Open Mnemograph in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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:

ScopePathUse When
Project-local./.claude/memoryKnowledge specific to this repo (architecture, decisions, patterns)
Global~/.claude/memoryCross-project knowledge (personal learnings, universal patterns, preferences)
CustomAny path via MEMORY_PATHShared 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 flagmnemograph --global statusmnemograph --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

bash
# Install from PyPIpip 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 directorymkdir -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.gitcd mnemographuv 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:

ToolDescription
rememberPrimary storage: Store knowledge atomically (entity + observations + relations in one call)
recallPrimary retrieval: Get relevant context with auto token management. Use focus=['Entity'] for full details. Default output is human-readable prose.
create_entitiesCreate entities (auto-blocks duplicates >80% match)
create_relationsLink entities with typed edges (implements, uses, decided_for, etc.)
add_observationsAdd facts/notes to existing entities
read_graphGet the full knowledge graph (warning: may be large)
delete_entitiesRemove entities (cascades to relations)
delete_relationsRemove specific relations
delete_observationsRemove specific observations

Session Lifecycle:

ToolDescription
session_startSignal session start, get initial context. Returns quick_start guide.
session_endSignal session end, optionally save summary
get_primerGet oriented with the knowledge graph (call at session start)

Branching (Parallel Workstreams):

ToolDescription
create_branchCreate a named branch for isolated work (e.g., "feature/auth-refactor")
switch_branchSwitch to a different branch
list_branchesList all branches
merge_branchMerge a branch into main
delete_branchDelete a branch
get_current_branchGet the current branch name

Graph Maintenance:

ToolDescription
find_similarFind entities with similar names (duplicate detection)
find_orphansFind entities with no relations
merge_entitiesMerge duplicate entities (consolidates observations, redirects relations)
get_graph_healthAssess graph quality: orphans, duplicates, overloaded entities
suggest_relationsSuggest potential relations based on semantic similarity
create_entities_forceCreate entities bypassing duplicate check
clear_graphClear all entities/relations (event-sourced, can rewind)

Time Travel:

ToolDescription
get_state_atView graph state at any point in history
diff_timerangeShow what changed between two points in time
get_entity_historyFull changelog for a specific entity
rewindRewind graph to a previous state using git
restore_state_atRestore graph to state at timestamp (audit-preserving)
reloadReload graph state from disk (after git operations)

Edge Weights:

ToolDescription
get_relation_weightGet weight breakdown (recency, co-access, explicit)
set_relation_importanceSet explicit importance weight (0.0-1.0)
get_strongest_connectionsFind entity's most important connections
get_weak_relationsFind 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:

bash
# Basic operationsmnemograph status                # Show entity/relation counts, recent eventsmnemograph log                   # View event historymnemograph log --session X       # Filter by sessionmnemograph sessions              # List all sessionsmnemograph export                # Export graph as JSON
# VCS commands (git-based version control)mnemograph vcs init              # Initialize memory as git repomnemograph vcs commit -m "msg"   # Commit current statemnemograph vcs log               # View commit historymnemograph vcs revert --event ID # Undo specific events (compensating events)mnemograph vcs revert --session X # Undo entire session
# Graph visualizationmnemograph graph                 # Open interactive graph viewermnemograph graph --watch         # Live reload mode (refresh button)
# Time travelmnemograph show --at "2 days ago"  # View state at a point in timemnemograph diff "1 week ago"       # Show changes since thenmnemograph history "EntityName"    # Full changelog for an entitymnemograph rewind -n 1             # Git-based rewind by N commitsmnemograph restore --to "yesterday" # Event-based restore (audit-preserving)
# Graph health and maintenancemnemograph health                # Show graph health report (orphans, duplicates, etc.)mnemograph health --fix          # Interactive cleanup modemnemograph similar "React"       # Find entities similar to "React" (duplicate check)mnemograph orphans               # List entities with no relationsmnemograph suggest "FastAPI"     # Suggest relations for an entitymnemograph 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

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

python
# Create a branch for your featurecreate_branch(name="feature/auth-refactor")
# Work normally — all operations happen on this branchremember(name="OAuth2", entity_type="concept",         observations=["Implementing OAuth2 flow"])
# Switch back to main to see clean stateswitch_branch(name="main")
# Merge when readymerge_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

PatternUse Case
feature/xyzFeature-specific knowledge
explore/xyzExploratory/experimental work
project/xyzProject-specific context
user/namePersonal workspace

Entity Types

TypePurposeExample
conceptIdeas, patterns, approaches"Repository pattern", "Event sourcing"
decisionChoices with rationale"Chose SQLite over Postgres for simplicity"
projectCodebases, systems"auth-service", "mnemograph"
patternRecurring code patterns"Error handling with Result type"
questionOpen unknowns"Should we add real-time sync?"
learningDiscoveries"pytest fixtures simplify test setup"
entityGeneric (people, files, etc.)"Alice", "config.yaml"

Topic Convention

Use topic entities as entry points for browsing related knowledge:

python
# Create topic entry pointscreate_entities([    {"name": "topic/projects", "entityType": "entity"},    {"name": "topic/decisions", "entityType": "entity"},    {"name": "topic/patterns", "entityType": "entity"},])
# Link entities to their topicscreate_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

bash
git clone https://github.com/tm42/mnemograph.gitcd mnemographuv sync                    # Install dependenciesuv run pytest --cov        # Run tests with coverage (enforces 75% minimum)uv run ruff check .        # Lintuv run mnemograph          # Run MCP server directly

Based On

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

License

MIT

Source: README.md at commit 4136ad7

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.5.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts