Memory Graph

Portable repo-local memory kit for Claude, Codex, macOS/Linux, and Windows.

The kit stores durable project memory in .agent/memory.db (SQLite + FTS5 + sqlite-vec) and exposes it through the memgraph/ wrapper. The wrapper supports startup context, hybrid recall, document/archive ingestion (ingest-docs), index verification (verify-doc-index), and typed write helpers for decisions, claims, workflow tasks, runs, policies, review gates, entities, and relations.

Contents

• project-memory-structure-instruction.md — canonical doctrine for project memory, strategic documents, AGENTS.md, CLAUDE.md, git, and startup flow.
• memgraph/ — portable skill/CLI kit with wrappers, schema, scripts, queries, references, and install instructions.
• graphify-vs-memgraph-memory-analysis.md — comparison of this repo-local memory model with Graphify-style inferred code graphs.

Quick Start

The intended use is agent-led initialization. Give this repository to your Claude/Codex agent and ask it to install the memory kit into the target project.

Suggested prompt:

Initialize repo-local memory in this project using
https://github.com/Mavline/Memory-graph.

Follow project-memory-structure-instruction.md. Copy the memgraph/ kit into the
project root, set up AGENTS.md and CLAUDE.md, create the EMPTY .agent/memory.db
(bootstrap touches no documents and writes no test records), configure startup
context for Claude and Codex, verify session-context, and commit only the
intended portable files. Keep .env, memgraph/venv/, memgraph/vendor/, archives,
backups, and generated scratch files out of git. Make it work on macOS/Linux
and Windows.

Quick Start stands up the empty memory infrastructure only: no documents are required to exist, nothing is indexed, and an empty memory is a healthy state. What happens next depends on the project:

• New project — documents are indexed as they appear. After every commit that creates, updates, moves, or deletes a managed document (docs/**/*.md, AGENTS.md, .agent/tasks/**/spec.md), run memgraph/memgraph ingest-docs and memgraph/memgraph verify-doc-index, then commit the updated .agent/memory.db. The bootstrap commit itself is the first such event — it adds AGENTS.md, a managed document — so run the lifecycle chain right after it; until then the state is infrastructure-complete but not yet document-synced. Typed memory (decisions, claims, tasks) is written only when real events happen; no smoke records are ever written.
• Existing repository — run a one-time backfill: inventory the committed document corpus, run ingest-docs once, prove full coverage with verify-doc-index, spot-check semantic recall against a known document, and re-run ingest-docs to prove idempotency (a no-op). From then on the project follows the per-commit document lifecycle above.

Manual reference: place memgraph/ at the root of the target project.

macOS/Linux:

cd memgraph
python3 -m venv venv
./venv/bin/python -m pip install --upgrade pip
./venv/bin/python -m pip install -r requirements.txt
mkdir -p vendor
case "$(uname -s)" in
  Darwin) cp "$(./venv/bin/python -c 'import sqlite_vec; print(sqlite_vec.loadable_path())')" vendor/vec0.dylib ;;
  Linux) cp "$(./venv/bin/python -c 'import sqlite_vec; print(sqlite_vec.loadable_path())')" vendor/vec0.so ;;
  *) echo "Unsupported Unix platform"; exit 1 ;;
esac
./venv/bin/python scripts/bootstrap.py --target ..
cd ..
memgraph/memgraph session-context

Windows PowerShell:

cd memgraph
python -m venv venv
venv\Scripts\python.exe -m pip install --upgrade pip
venv\Scripts\python.exe -m pip install -r requirements.txt
New-Item -ItemType Directory -Force vendor | Out-Null
$base = & venv\Scripts\python.exe -c "import sqlite_vec; print(sqlite_vec.loadable_path())"
$src = if (Test-Path "$base") { "$base" } elseif (Test-Path "$base.dll") { "$base.dll" } else { throw "vec0 not found near $base" }
Copy-Item $src vendor\vec0.dll
venv\Scripts\python.exe scripts\bootstrap.py --target ..
cd ..
powershell.exe -NoProfile -ExecutionPolicy Bypass -File memgraph/memgraph.ps1 session-context

For full setup details, including Claude SessionStart and Codex AGENTS.md startup rules, read memgraph/install/README.md.