MemoGraph: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What is MemoGraph

MemoGraph is a graph-based memory system for LLMs. It stores memories as markdown files in a "vault" directory, builds a knowledge graph from wikilinks ([[title]]) and YAML frontmatter, and exposes retrieval via a Python API, CLI, MCP server, and web UI.

Commands

Python environment

pip install -e ".[dev]"          # Install with all dev dependencies
pip install -e ".[all]"          # Install with all optional features
pip install -e ".[embeddings]"   # Add sentence-transformers / numpy
pip install -e ".[web]"          # Add FastAPI / uvicorn
pip install -e ".[integrations]" # Add Obsidian / Notion watchers

Testing

pytest                                    # Run all tests
pytest tests/test_graph.py                # Run a single test file
pytest tests/test_graph.py::test_foo      # Run a single test function
pytest -m "not slow and not integration"  # Skip slow / integration tests
pytest -m unit                            # Only unit tests
pytest --no-cov                           # Skip coverage (faster)

Test layout: top-level tests/ holds unit tests for each module; subfolders tests/ai/, tests/swarm/, tests/integrations/, tests/integration_suite/, and tests/stress/ group their respective slower or feature-gated suites. pytest.ini_options auto-injects --cov, so use --no-cov for fast iteration. Available markers: unit, slow, integration, stress, benchmark, load.

Linting and formatting

ruff check .           # Lint
ruff check . --fix     # Lint and auto-fix
ruff format .          # Format (line length 100)
mypy memograph/        # Type-check

Running the MCP server

python -m memograph.mcp.run_server --vault ~/my-vault
python -m memograph.mcp.run_server --vault ~/my-vault --provider claude --model claude-sonnet-4-6
# Or via env vars:
MEMOGRAPH_VAULT=~/my-vault python -m memograph.mcp.run_server