RemaGraph

Every agent leaves a trace. RemaGraph is a lightweight MCP tool that captures what an AI coding agent leaves behind while it works, so whoever picks up next can follow the trail.

RemaGraph is a lightweight MCP (Model Context Protocol) tool built for AI coding agents that work across many tasks and hand-offs without a human in the loop for every step. Its job is simple: capture what an agent learned, decided, or ran into along the way, and make that trail retrievable later — by the same agent, or by a completely different one picking up the work. It complements CodeGraph: CodeGraph tracks what's structurally wrong with the code; RemaGraph tracks what happened while someone (or something) was working on it.

Installation

RemaGraph is published on PyPI. Recommended install:

uv tool install remagraph

or with plain pip:

pip install remagraph

Prefer a specific tag, or want the bleeding edge from main? Install straight from the git repo:

# Pinned to a specific release tag
uv tool install git+https://github.com/aiken884/RemaGraph.git@v0.7.1-beta

# Whatever is currently on main
uv tool install git+https://github.com/aiken884/RemaGraph.git

Or install from source for local development:

git clone https://github.com/aiken884/RemaGraph.git
cd RemaGraph
uv pip install -e .

Dependencies: Python ≥3.11, model2vec, mcp (FastMCP), pydantic.

Quick Start (5 minutes, no coding required)

1. Install (see "Installation" above).
2. Initialize:

   remagraph init --project myproject
   source ~/.local/state/remagraph-myproject/env.sh
   

3. Run a task in one shot — reads memory, executes, writes memory back:

    remagraph auto --task-id fix-login-001 --agent-id my-ai -- echo "swap this for your actual command"
   

   or use the wrapper script:

   curl -O https://raw.githubusercontent.com/aiken884/RemaGraph/main/examples/simple/remagraph-task.sh
   chmod +x remagraph-task.sh
   TASK_ID=fix-login-001 AGENT_ID=my-ai ./remagraph-task.sh python my_agent.py
   

If you just want to check memory first, with no execution and no writes:

remagraph auto --recall-only --task-id fix-login-001 --agent-id my-ai

No code required. Full plain-language walkthrough: docs/task-memory-convention.md.

New users may also find docs/internal/alpha-test-playbook.md useful as an onboarding guide — it includes scenarios and a feedback template.

Note: this repository is public and the package is published on PyPI, but it's still a pre-1.0 beta (see BOUNDARIES.md — no frozen public API yet).

MCP Quick Start

1. MCP client configuration

Point any MCP client at RemaGraph. Example configs for common clients follow.

Note (since the BUG 1 fix): remagraph serve now must be bound to a single project at startup — via either the --project <id> argument or the REMAGRAPH_PROJECT environment variable. If neither is set, it fails fast and never enters the MCP stdio loop, which prevents a process from silently reading and writing across projects if it happens to inherit another project's environment variables. Each project maps to its own dedicated remagraph serve process; a single running process cannot switch between projects dynamically.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "remagraph": {
      "command": "remagraph",
      "args": ["serve", "--project", "myproject"],
      "env": {
        "REMAGRAPH_STATE_DIR": "/home/user/.local/state/remagraph-myproject"
      }
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "remagraph": {
      "command": "remagraph",
      "args": ["serve"],
      "env": {
        "REMAGRAPH_PROJECT": "myproject"
      }
    }
  }
}

OpenCode / Claude Code — any client that supports stdio MCP works the same way as above.

2. Environment variables

Directories are created automatically when missing (mode 0700); DB files are created at mode 0600. Paths are checked against a security denylist that rejects system directories.

3. CLI basics

# Start the stdio MCP server (must be bound to a single project via --project or REMAGRAPH_PROJECT)
remagraph serve --project myproject

# Initialize / run a task in one shot
remagraph init --project myproject
remagraph auto --task-id T001 --agent-id my-agent -- make test

# Query (task-id alone is fine)
remagraph search --task-id T001
remagraph search --query "FastMCP lifecycle" --top-k 5
remagraph status --limit 10

MCP Tools

RemaGraph exposes five tools over MCP (stdio transport), compatible with Claude Desktop, Cursor, and other mainstream MCP clients: remagraph_store, remagraph_search, remagraph_status, remagraph_maintain, and remagraph_migrate_project.

remagraph_store — write memory

An agent writes a memory record; it must pass five arbitration rules before landing in SQLite + the FTS5 index.

Behavior of the four kind values (PPLX Priority B):

• task_handoff — a task hand-off record, carries handoff_note
• status_update — a status update; automatically supersedes the prior record for the same task_id
• discovered_constraint — a newly discovered constraint; can invalidates existing, now-wrong memories
• fleet_member — owned by the dispatching coordinator, records/recycles fleet members (task_id=fleet auto-supersedes)

remagraph_search — query memory

FTS5 BM25 full-text search (trigram tokenizer, CJK-aware) plus tag/kind/agent_id/task_id filtering.

Short queries (≤2 characters) return an empty result set instead of raising an error. Beyond results/has_more, every response always carries cross_project_fanout_capped (bool; only meaningful when cross_project_label is used — ordinary queries always get false). When cross_project_label is used, each result also carries source_project_id marking which project it came from. Every result includes the full field set (id/project_id/summary/agent_id/kind/task_id/timestamp/score/learnings/handoff_note/tags/status/created_at/updated_at — everything except embedding).

remagraph_status — query a project's latest state

Returns all active status_update memories, deduplicated by task_id (only the newest record per task survives). Also includes version-compatibility handshake info, so callers don't have to wait for a remagraph_store write to fail before learning about a version mismatch.

Beyond the existing latest array, the response always includes these compatibility handshake fields:

remagraph_maintain — run DB maintenance

Runs automatic database maintenance (WAL checkpoint, prune superseded/invalidated memories, FTS5 optimize, VACUUM, integrity check), gated by the same safety valve (maintenance.safety_validate_project) used by the CLI maintain subcommand.

Note: unlike the CLI maintain subcommand, this MCP tool has no dry_run option — every call executes for real.

Response (success): {"status": "ok", "stats": {...}}. Response (failure): {"status": "error", "reason": "..."}.

stats is produced by maintenance.run_maintenance(); most fields only appear when the corresponding step actually ran:

remagraph_migrate_project — one-time cross-project migration

One-time migration of memories from a source project to a target project's independent DB (e.g. default → project-a), marking the originals invalidated in the source. Performs a real migration — this tool and the CLI's migrate-project subcommand (cli.cmd_migrate_project) both call the same shared core implementation (store.migrate_project_memories), so they always produce the same end state for the same inputs.

How it works:

1. The target project is validated through the same safety_validate_project(to_project, require_env_match=False) safety valve used elsewhere (project-id naming-convention rules, project.json metadata consistency, etc).
2. The source project's state_dir is resolved via the shared project registry (db.get_registered_state_dir(from_project)) — not a hardcoded path. If from_project has never been registered (no prior remagraph command has resolved a state_dir for it), the call fails with a clear error rather than silently treating it as zero migratable records. from_project == "default" is the one exception: it resolves via the ambient REMAGRAPH_STATE_DIR/REMAGRAPH_HOME the same way any other "default"-project usage does, since "default" is deliberately never registered in the normal course of things.
3. Records that heuristically look like they belong to to_project (a LIKE match against task_id/tags/agent_id/summary) are copied into the target project's own DB with project_id forced to to_project, and the originals are marked status='invalidated' in the source with a migrated-to:<to_project> breadcrumb appended to learnings.
4. If either the source or target database is currently in the read-only degraded schema-compatibility tier (see "Version Compatibility" below), the migration is rejected with a clear error instead of failing silently or partially.

Response (success): {"status": "ok" | "dry-run", "from": "...", "to": "...", "dry_run": true|false, "migrated_count": N, "skipped_ids": [...]}. Response (failure): {"status": "error", "reason": "..."}.

Governance & Security

• Rate limiting — per-agent token bucket (60 calls / 60 seconds) to prevent abuse
• Input validation — task_id / agent_id are checked against format rules via Pydantic validators
• Path safety — REMAGRAPH_STATE_DIR rejects system directory paths
• Audit rotation — audit-YYYYMM.jsonl, split automatically by month
• DB size cap — SQLite max_page_count set to a 100MB soft limit
• Migration — built-in schema version tracking and a migration chain
• Version-compatibility degradation — when a database's schema version is newer than the running code, the database's own min_reader_version/min_writer_version decide one of three outcomes: fully compatible (normal reads and writes), read-only degraded (writes rejected, reads unaffected), or refused outright. Callers can learn this ahead of time via remagraph_status's compatibility handshake fields, without waiting for a write to fail. See the "Version Compatibility" section of DESIGN.md
• Cross-project registry — project_registry automatically records known projects and their state_dir, backing remagraph_search's cross_project_label read-only cross-project lookups. See the "Cross-Project Collaboration" section of DESIGN.md
• Stale-record cleanup — cleanup_superseded() can purge non-active records older than 90 days

CLI Subcommands (for headless agents)

Besides MCP mode, remagraph supports the following CLI subcommands (all with JSON output):

# One-shot, most recommended: read memory → run the command → write memory
remagraph auto --task-id task-001 --agent-id my-agent -- make test

# Initialize
remagraph init --project myproject

# Write memory
remagraph store \
  --task-id task-001 --agent-id my-agent --kind status_update \
  --summary "Task complete, all tests passing, no regressions found" \
  --learnings '["Watch out for FastMCP lifecycle handling"]' \
  --tags '["python","mcp"]'

# Query (task-id alone is fine, query is not required)
remagraph search --task-id task-001
remagraph search --query "FastMCP lifecycle" --top-k 5

# Query latest status
remagraph status --limit 10

Plain-language convention: docs/task-memory-convention.md. Full spec: DESIGN.md; audit contract: docs/audit.md.

Development & Verification

# uv is recommended
uv sync --all-extras
uv run ruff check src tests
uv run mypy src/
uv run pytest -m 'not slow'
REMAGRAPH_STATE_DIR=$(mktemp -d) uv run pytest tests/smoke

• CI pipeline: smoke → adversarial → lint (ruff + mypy) → test (coverage ≥80%); plus gitleaks, pip-audit, and mutmut (non-blocking).
• Never let tests default to writing production state — smoke tests must use REMAGRAPH_STATE_DIR or pytest's tmp_path.

Resources

• DESIGN.md — the design source of truth: schema, arbitration rules, cross-project collaboration, version compatibility
• CHANGELOG.md — version history
• CONTRIBUTING.md — how to contribute
• SECURITY.md — how to report a vulnerability
• docs/architecture.md — system architecture
• docs/task-memory-convention.md — plain-language guide to the task-memory convention
• docs/audit.md — the audit log contract
• docs/governance/checklist.md — the governance checklist

License

Apache-2.0. RemaGraph is an independent project — its source code is entirely self-authored and does not contain or derive from any other project's code.

Support

If RemaGraph is quietly keeping your agents' memory straight, you can support its development on Ko-fi (card or PayPal) or directly via PayPal. Entirely optional — RemaGraph is, and stays, free.