{
  "markdown": "# Mnemograph\n\n<!-- mcp-name: io.github.tm42/mnemograph -->\n\nA 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.\n\n**Works with**: Claude Code, opencode, codex CLI, Zed, Continue.dev, and any MCP-compatible agent.\n\n## Why Mnemograph?\n\nAI coding sessions are ephemeral. Mnemograph gives your AI partner persistent memory that:\n\n- **Survives across sessions** — decisions, patterns, learnings persist\n- **Supports semantic search** — find relevant context by meaning, not just keywords\n- **Provides tiered retrieval** — shallow summaries to deep subgraphs based on need\n- **Versions like code** — branch, commit, diff, revert your knowledge graph\n- **Enables collaboration** — share memory repos across users or projects\n\n## Memory Scope: Local vs Global\n\n**Before using mnemograph, decide where to store memory:**\n\n| Scope | Path | Use When |\n|-------|------|----------|\n| **Project-local** | `./.claude/memory` | Knowledge specific to this repo (architecture, decisions, patterns) |\n| **Global** | `~/.claude/memory` | Cross-project knowledge (personal learnings, universal patterns, preferences) |\n| **Custom** | Any path via `MEMORY_PATH` | Shared team memory, org-wide knowledge bases |\n\n**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.\n\n```bash\n# Project-local (default)\nMEMORY_PATH=\".claude/memory\"\n\n# Global (cross-project)\nMEMORY_PATH=\"$HOME/.claude/memory\"\n\n# CLI: use --global flag\nmnemograph --global status\nmnemograph --global graph\n```\n\n## Quick Start\n\n### Option 1: Let Claude Code install it\n\nGive Claude Code this repo URL and ask it to set up mnemograph:\n\n```\nhttps://github.com/tm42/mnemograph\n```\n\nOr point Claude to the setup instructions directly:\n\n```\nRead https://raw.githubusercontent.com/tm42/mnemograph/main/SETUP_CLAUDE_CODE.md and follow them\n```\n\n### Option 2: Manual installation\n\n```bash\n# Install from PyPI\npip install mnemograph\n\n# Add to Claude Code (global, available in all projects)\nclaude mcp add --scope user mnemograph \\\n  -e MEMORY_PATH=\"$HOME/.claude/memory\" \\\n  -- uvx mnemograph\n\n# Initialize memory directory\nmkdir -p ~/.claude/memory\n```\n\n### Option 3: Other MCP Clients\n\nEach MCP client has a different configuration format. See [UNIVERSAL_MCP_COMPATIBILITY.md](UNIVERSAL_MCP_COMPATIBILITY.md) for copy-paste configs for:\n\n- **opencode** — `~/.config/opencode/opencode.json`\n- **Codex CLI** — `~/.codex/config.yaml`\n- **Zed** — `~/.config/zed/settings.json`\n- **Continue.dev** — `~/.continue/config.json`\n\nThe key environment variable is `MEMORY_PATH` — set it to where you want the knowledge graph stored.\n\n### Option 4: Install from source\n\n```bash\ngit clone https://github.com/tm42/mnemograph.git\ncd mnemograph\nuv sync\n\n# Add to Claude Code (or adapt for your MCP client)\nclaude mcp add --scope user mnemograph \\\n  -e MEMORY_PATH=\"$HOME/.claude/memory\" \\\n  -- uv run --directory /path/to/mnemograph mnemograph\n```\n\n## Usage\n\n### MCP Tools (used by any agent)\n\nMnemograph exposes these tools via MCP:\n\n**Core Operations:**\n\n| Tool | Description |\n|------|-------------|\n| `remember` | **Primary storage**: Store knowledge atomically (entity + observations + relations in one call) |\n| `recall` | **Primary retrieval**: Get relevant context with auto token management. Use `focus=['Entity']` for full details. Default output is human-readable prose. |\n| `create_entities` | Create entities (auto-blocks duplicates >80% match) |\n| `create_relations` | Link entities with typed edges (implements, uses, decided_for, etc.) |\n| `add_observations` | Add facts/notes to existing entities |\n| `read_graph` | Get the full knowledge graph (warning: may be large) |\n| `delete_entities` | Remove entities (cascades to relations) |\n| `delete_relations` | Remove specific relations |\n| `delete_observations` | Remove specific observations |\n\n**Session Lifecycle:**\n\n| Tool | Description |\n|------|-------------|\n| `session_start` | Signal session start, get initial context. Returns quick_start guide. |\n| `session_end` | Signal session end, optionally save summary |\n| `get_primer` | Get oriented with the knowledge graph (call at session start) |\n\n**Branching (Parallel Workstreams):**\n\n| Tool | Description |\n|------|-------------|\n| `create_branch` | Create a named branch for isolated work (e.g., \"feature/auth-refactor\") |\n| `switch_branch` | Switch to a different branch |\n| `list_branches` | List all branches |\n| `merge_branch` | Merge a branch into main |\n| `delete_branch` | Delete a branch |\n| `get_current_branch` | Get the current branch name |\n\n**Graph Maintenance:**\n\n| Tool | Description |\n|------|-------------|\n| `find_similar` | Find entities with similar names (duplicate detection) |\n| `find_orphans` | Find entities with no relations |\n| `merge_entities` | Merge duplicate entities (consolidates observations, redirects relations) |\n| `get_graph_health` | Assess graph quality: orphans, duplicates, overloaded entities |\n| `suggest_relations` | Suggest potential relations based on semantic similarity |\n| `create_entities_force` | Create entities bypassing duplicate check |\n| `clear_graph` | Clear all entities/relations (event-sourced, can rewind) |\n\n**Time Travel:**\n\n| Tool | Description |\n|------|-------------|\n| `get_state_at` | View graph state at any point in history |\n| `diff_timerange` | Show what changed between two points in time |\n| `get_entity_history` | Full changelog for a specific entity |\n| `rewind` | Rewind graph to a previous state using git |\n| `restore_state_at` | Restore graph to state at timestamp (audit-preserving) |\n| `reload` | Reload graph state from disk (after git operations) |\n\n**Edge Weights:**\n\n| Tool | Description |\n|------|-------------|\n| `get_relation_weight` | Get weight breakdown (recency, co-access, explicit) |\n| `set_relation_importance` | Set explicit importance weight (0.0-1.0) |\n| `get_strongest_connections` | Find entity's most important connections |\n| `get_weak_relations` | Find pruning candidates (low-weight relations) |\n\n### Recall: Prose vs Graph Format\n\nThe `recall` tool returns context in **prose format by default** — human-readable text that agents can consume directly without parsing JSON:\n\n```python\n# Default: prose format (human-readable)\nrecall(depth=\"medium\", query=\"authentication\")\n# Returns:\n# **MyApp** (project)\n# A Python web service. Uses OAuth2 for user auth.\n# Uses: PostgreSQL, Redis\n#\n# **Decisions:**\n# • Decision: Use JWT — Stateless tokens for API authentication\n#\n# **Gotchas:**\n# • Token expiry is 1 hour by default\n# • Refresh tokens stored in Redis\n\n# Optional: graph format (structured JSON)\nrecall(depth=\"medium\", query=\"authentication\", format=\"graph\")\n```\n\n**Depth levels:**\n- `shallow` — Quick summary: entity counts, recent activity, gotchas\n- `medium` — Semantic search + 1-hop neighbors (~2000 tokens)\n- `deep` — Multi-hop traversal from focus entities (~5000 tokens)\n\n**Gotcha extraction:** Observations prefixed with `Gotcha:`, `Warning:`, `Note:`, or `Important:` are automatically extracted into a dedicated section.\n\n### CLI Tools\n\n**`mnemograph`** — Unified CLI for all memory operations:\n\n```bash\n# Basic operations\nmnemograph status                # Show entity/relation counts, recent events\nmnemograph log                   # View event history\nmnemograph log --session X       # Filter by session\nmnemograph sessions              # List all sessions\nmnemograph export                # Export graph as JSON\n\n# VCS commands (git-based version control)\nmnemograph vcs init              # Initialize memory as git repo\nmnemograph vcs commit -m \"msg\"   # Commit current state\nmnemograph vcs log               # View commit history\nmnemograph vcs revert --event ID # Undo specific events (compensating events)\nmnemograph vcs revert --session X # Undo entire session\n\n# Graph visualization\nmnemograph graph                 # Open interactive graph viewer\nmnemograph graph --watch         # Live reload mode (refresh button)\n\n# Time travel\nmnemograph show --at \"2 days ago\"  # View state at a point in time\nmnemograph diff \"1 week ago\"       # Show changes since then\nmnemograph history \"EntityName\"    # Full changelog for an entity\nmnemograph rewind -n 1             # Git-based rewind by N commits\nmnemograph restore --to \"yesterday\" # Event-based restore (audit-preserving)\n\n# Graph health and maintenance\nmnemograph health                # Show graph health report (orphans, duplicates, etc.)\nmnemograph health --fix          # Interactive cleanup mode\nmnemograph similar \"React\"       # Find entities similar to \"React\" (duplicate check)\nmnemograph orphans               # List entities with no relations\nmnemograph suggest \"FastAPI\"     # Suggest relations for an entity\nmnemograph clear                 # Clear all entities and relations (with confirmation)\n\n# Global options (come *before* the subcommand)\nmnemograph --global status       # Use global memory (~/.claude/memory)\nmnemograph --memory-path /path graph  # Custom memory location\n```\n\n**Running from anywhere** (without activating the venv):\n\n```bash\n# Using uv (recommended)\nuv run --directory /path/to/mnemograph mnemograph graph\n\n# Using uvx (if installed from PyPI)\nuvx --from mnemograph mnemograph status\n```\n\n**Graph Visualization** — Interactive D3.js viewer:\n\n- **Layout algorithms**: Force-directed, Radial (hubs at center), Clustered (by component)\n- **Color modes**: By entity type, connected component, or degree centrality\n- **Edge weight slider**: Filter connections by strength\n- **Live refresh**: `--watch` mode with Refresh button for real-time updates\n\n## Architecture\n\n```\n~/.mnemograph/memory/    # or ~/.claude/memory, ~/.opencode/memory, etc.\n├── mnemograph.db        # SQLite database (events + vectors)\n├── state.json           # Cached materialized state (derived)\n└── .git/                # Version history\n```\n\n**Event sourcing** means all changes are recorded as immutable events in SQLite. The current state is computed by replaying events. This enables:\n\n- Full history of all changes\n- Revert any operation\n- Branch/merge knowledge graphs\n- Audit trail of what Claude learned and when\n\n**Two-layer versioning:**\n- `mnemograph vcs revert` — fine-grained, undo specific events via compensating events\n- `mnemograph rewind` / `mnemograph restore` — coarse-grained, git-level or timestamp-based restore\n\n## Branching\n\nBranches let you work on isolated knowledge without affecting the main graph. Perfect for:\n\n- **Exploratory work** — try approaches without polluting shared knowledge\n- **Feature-specific context** — \"feature/auth-refactor\" keeps auth decisions separate\n- **Multiple projects** — switch context between different codebases\n\n### Creating and Using Branches\n\n```python\n# Create a branch for your feature\ncreate_branch(name=\"feature/auth-refactor\")\n\n# Work normally — all operations happen on this branch\nremember(name=\"OAuth2\", entity_type=\"concept\",\n         observations=[\"Implementing OAuth2 flow\"])\n\n# Switch back to main to see clean state\nswitch_branch(name=\"main\")\n\n# Merge when ready\nmerge_branch(source=\"feature/auth-refactor\", target=\"main\")\n```\n\n### How Branching Works\n\n- **Main branch** always exists, contains shared knowledge\n- **Feature branches** inherit from main but additions stay isolated\n- **Automatic filtering** — `recall`, `search`, etc. only see current branch + main\n- **Merge** copies branch entities/relations into target branch\n- **Delete** cleans up after merge (or abandons exploratory work)\n\n### Branch Naming Conventions\n\n| Pattern | Use Case |\n|---------|----------|\n| `feature/xyz` | Feature-specific knowledge |\n| `explore/xyz` | Exploratory/experimental work |\n| `project/xyz` | Project-specific context |\n| `user/name` | Personal workspace |\n\n## Entity Types\n\n| Type | Purpose | Example |\n|------|---------|---------|\n| `concept` | Ideas, patterns, approaches | \"Repository pattern\", \"Event sourcing\" |\n| `decision` | Choices with rationale | \"Chose SQLite over Postgres for simplicity\" |\n| `project` | Codebases, systems | \"auth-service\", \"mnemograph\" |\n| `pattern` | Recurring code patterns | \"Error handling with Result type\" |\n| `question` | Open unknowns | \"Should we add real-time sync?\" |\n| `learning` | Discoveries | \"pytest fixtures simplify test setup\" |\n| `entity` | Generic (people, files, etc.) | \"Alice\", \"config.yaml\" |\n\n## Topic Convention\n\nUse **topic entities** as entry points for browsing related knowledge:\n\n```python\n# Create topic entry points\ncreate_entities([\n    {\"name\": \"topic/projects\", \"entityType\": \"entity\"},\n    {\"name\": \"topic/decisions\", \"entityType\": \"entity\"},\n    {\"name\": \"topic/patterns\", \"entityType\": \"entity\"},\n])\n\n# Link entities to their topics\ncreate_relations([\n    {\"from\": \"auth-service\", \"to\": \"topic/projects\", \"relationType\": \"part_of\"},\n    {\"from\": \"Decision: Use Redis\", \"to\": \"topic/decisions\", \"relationType\": \"part_of\"},\n])\n```\n\n**Standard topics:**\n- `topic/projects` — Project entities\n- `topic/decisions` — Architectural decisions\n- `topic/patterns` — Patterns and practices\n- `topic/learnings` — Key discoveries\n- `topic/questions` — Open questions\n\nThis makes it easy to query \"what decisions have we made?\" by exploring `topic/decisions`.\n\n## Development\n\n```bash\ngit clone https://github.com/tm42/mnemograph.git\ncd mnemograph\nuv sync                    # Install dependencies\nuv run pytest --cov        # Run tests with coverage (enforces 75% minimum)\nuv run ruff check .        # Lint\nuv run mnemograph          # Run MCP server directly\n```\n## Based On\n\nMnemograph builds on [MCP server-memory](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) — Anthropic's official memory server\n\n## License\n\nMIT\n",
  "bytes": 13961,
  "sha": "f937ba2ff99f89b8c4e2c64ce000a8e3f99b41b06bdaee65418a809f675fbb72",
  "repo_slug": "tm42/mnemograph",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_tm42_mnemograph_98396b4e/readme"
}