pi-graphiti

🕸️ Persistent knowledge-graph extension for Pi, backed by a Graphiti MCP server.

What it gives you

This extension wraps Graphiti MCP server. The MCP server provides add_memory, search_nodes, etc. as raw tools.

• graph tool — single pi-native tool with three actions (add / search / episodes) so you don't need pi-mcp-adapter to use graphiti.
• Automatic episode writes — pushes a snapshot every N user turns, before context compaction, and on session shutdown. No need for the model to remember to write.
• LLM curation pass (on by default) — the turn-based nudge spawns a short-lived child pi -p (loading only this extension, so it just has the graph tool) that reviews the recent conversation and decides what is worth persisting and at which scope (project vs global), then calls graph add itself — or says "Nothing to save." Set reviewEnabled: false to fall back to raw snapshot pushes (all project scope) that rely purely on graphiti's server-side extraction.
• Proactive in-turn saving — the system-prompt policy tells the agent when to persist proactively (corrections, preferences, durable facts/decisions, conventions, end of significant work), so it saves during normal turns instead of only on the background nudge.
• Correction detector (on by default) — a user correcting the agent fires an immediate curation review, capturing the highest-signal "you should have remembered that" moment right away. Set correctionDetection: false to disable.
• System-prompt policy block — every session starts knowing the graph exists and when to use it.
• Optional ambient recall — opt-in injection of relevant entities/facts at session start, keyed on the latest user message.
• Project/global scoping (on by default) — split of graph memory into a per-project group and a shared global group, so project-specific facts and cross-project knowledge stay separated. Set projectScoping: false to collapse to a single bucket.
• /graph slash command — status, search, ingest, dump, load, clear directly from the prompt.

Requirements

A running Graphiti MCP server (FalkorDB or Neo4j backend). Stand one up by following Graphiti's docs, or run /graph setup after installing to provision and start a local Docker stack for you.

Default URL the extension expects: http://localhost:8000/mcp/ (Graphiti's default HTTP endpoint).

Install

# from npm (once published)
pi install npm:pi-graphiti

# or pinned from git
pi install git:github.com/p2c2e/pi-graphiti@v0.4.0

Configure

Configuration is optional — defaults work against a local graphiti server. You can run /graph setup to configure to your liking.

Config file: ~/.pi/agent/pi-graphiti-config.json

{
  "enabled": true,
  "url": "http://localhost:8000/mcp/",
  "groupId": "",
  "injectContext": false,
  "projectScoping": true,
  "nudgeInterval": 10,
  "flushOnCompact": true,
  "flushOnShutdown": true,
  "flushMinTurns": 6
}

Environment overrides (take precedence over the JSON file):

Variable	Default	Notes
PI_GRAPHITI_ENABLED	true	Set to false to disable without uninstalling.
PI_GRAPHITI_URL	http://localhost:8000/mcp/	MCP endpoint.
PI_GRAPHITI_GROUP_ID	pigraphiti<user><host>	Sanitized to [A-Za-z0-9_]+ — hyphens corrupt RediSearch queries.
PI_GRAPHITI_INJECT_CONTEXT	false	Inject recall block at session start.
PI_GRAPHITI_PROJECT_SCOPING	true	Split memory into per-project (<groupId>_proj_<project>) + global groups. Set false for a single bucket.
PI_GRAPHITI_NUDGE_INTERVAL	10	User turns between background pushes.
PI_GRAPHITI_REVIEW_ENABLED	true	Nudge runs an LLM curation pass (child pi -p) that picks facts + scope. false = raw snapshot push.
PI_GRAPHITI_CORRECTION_DETECTION	true	Detect user corrections in real time and fire an immediate curation review (rate-limited, reachability-gated).
PI_GRAPHITI_REVIEW_RECENT	0	Recent messages fed to the curation review. 0 = all.
PI_GRAPHITI_LLM_MODEL	(default model)	Model override for the review subprocess (e.g. a cheap/fast model).
PI_GRAPHITI_LLM_THINKING	(off when model set)	Thinking level for the review subprocess.
PI_GRAPHITI_FLUSH_ON_COMPACT	true	Push snapshot before compaction.
PI_GRAPHITI_FLUSH_ON_SHUTDOWN	true	Push snapshot on shutdown.
PI_GRAPHITI_FLUSH_MIN_TURNS	6	Minimum user turns before flush triggers.
PI_GRAPHITI_TIMEOUT_MS	60000	Per-call timeout for real work (writes, searches, episode reads).
PI_GRAPHITI_STATUS_TIMEOUT_MS	3000	Budget for cheap reachability probes (get_status). Bounds how long a hung server can delay a turn. See outage resilience.
PI_GRAPHITI_SPOOL	true	Spool episodes to disk when the server is down and replay them automatically. Set false to drop failed writes instead.
PI_GRAPHITI_SPOOL_MAX_ENTRIES	200	Max spooled episodes (newest win).
PI_GRAPHITI_SPOOL_MAX_BYTES	8388608	Max total spool size (8MB).
PI_GRAPHITI_SPOOL_MAX_AGE_DAYS	14	Spooled episodes older than this are discarded on drain.
PI_GRAPHITI_SPOOL_DRAIN_BATCH	25	Max episodes replayed per drain cycle (/graph spool drain replays all).

Usage

The graph tool is exposed to the LLM automatically. From the user side:

/graph                       Status + recent episodes + active group
/graph setup                 Interactive wizard: set group id + project scoping, and configure/start the backend (local Docker stack or external MCP server)
/graph search QUERY          search_nodes + search_memory_facts
/graph dump [path]           Export ALL episodes (every group) to markdown; use before reverting to flat files
/graph load <path>           Re-import episodes from a dump file back into their original group ids
/graph ingest <path> [global] Memorize a text file: chunk it and push the chunks as episodes into the current project's graph memory (or the global group with "global")
/graph clear                 clear_graph for the active group (destructive)
/graph spool                 Show the offline write queue (episodes captured while the server was down); `drain` replays now, `clear` discards
/graph uninstall             Tear down the local Docker stack, but ONLY if /graph setup started it; run before `pi remove`

Uninstalling: run /graph uninstall (alias /graph teardown) before pi remove. It stops the local Docker stack only when the setup wizard started it (config startedBySetup); a pre-existing or external stack is left running with a message. pi remove itself only edits settings and cannot run teardown. A best-effort preuninstall npm script does the same cleanup for plain npm uninstall.

When the MCP server is down

Graphiti is an optional accelerator, never a blocker: every path catches failures and the agent keeps working. Cost of an outage:

• Server stopped / port closed (the common case): connections are refused in ~1ms. No measurable impact.
• Server hung / black-holed (paused container, VPN drop, wedged FalkorDB): reachability probes are capped at PI_GRAPHITI_STATUS_TIMEOUT_MS (3s) rather than the 60s work timeout, getStatus() enforces that deadline internally so no call site can forget it, and concurrent callers share one probe.
• Sustained outage: failed probes back off 5s -> 15s -> 60s -> 300s (cap), so a dead server costs ~12 probes/hour instead of 120. A success resets the breaker immediately, and every /graph subcommand force-probes so you never wait out a backoff window.
• No memory is lost. Episodes that cannot be written (turn nudge, pre-compact and shutdown flushes, and the agent's own graph add) are appended to a disk spool at ~/.pi/agent/pi-graphiti-spool/pending.jsonl and replayed automatically on the next healthy cycle. /graph shows the pending depth; /graph spool drain forces a replay and /graph spool clear discards. Bounded by entry count, total bytes, and age; anything the spool does drop is recorded in dead-letter.jsonl rather than deleted silently. (One gap: the correction detector still skips rather than spools during an outage.)
• Shutdown does no network I/O at all - it spools synchronously, so a slow server cannot make the episode race process exit. The pre-compact flush, which the host awaits, has its own 5s write budget and spools on expiry.

Full analysis, per-path blocking table, and the remaining tracked work (outage notification, compact-flush budget) are in docs/design/outage-resilience.md.

Scope (when projectScoping is enabled)

The graph tool accepts a scope argument:

• add / episodes: "project" (default) or "global".
• search: "both" (default, unions project + global), "project", or "global".

The per-project group id is derived as <groupId>_proj_<sanitizedProjectName>, where the project name is the current working directory's basename. With scoping disabled (projectScoping: false), every operation uses the single groupId bucket and scope is ignored.

Ingesting a document from the CLI

To load an arbitrary text file (notes, docs, transcripts) into graphiti episode memory outside of a pi session, use the ingest script:

npm run ingest -- <file> [options]
# or: npx tsx scripts/ingest-file.ts <file> [options]

Options:

• --group <id> target group_id (sanitized to [A-Za-z0-9_]).
• --name <base> episode base name (default: file basename).
• --source <kind> text | message | json (default: text).
• --chunk-chars <n> per-episode safety cap (default: 8000; 0 = whole file as one episode). Chunking is paragraph-driven: each paragraph is its own episode, and a paragraph larger than the cap is split into sentences packed up to the cap (hard-cut only if a single sentence still exceeds it).
• --dry-run show the chunk plan without writing.

Group precedence: --group > PI_GRAPHITI_GROUP_ID > default. The document is written to that one explicit group (project scoping does not remap it), so you can drop a file into a specific bucket:

PI_GRAPHITI_GROUP_ID=myscratch npx tsx scripts/ingest-file.ts notes.md --chunk-chars 6000

Episodes extract asynchronously; allow ~30-90s before the entities/facts are searchable.

Coexistence with other memory extensions

This extension is self-contained and stores everything in its own graphiti group IDs, so it can run alongside other memory extensions without conflict.

• It registers its own graph tool, so the LLM picks it based on tool descriptions.
• Its before_agent_start hook appends its own block to the system prompt — Pi composes multiple such blocks safely.
• It uses its own group IDs / storage, so there are no double-writes.
• To share a graph across machines/installs, set PI_GRAPHITI_GROUP_ID to the same value.

Design notes

• Direct HTTP MCP client (no pi mcp dependency). Lets us own timeouts, retries, and silent degradation.
• Group IDs are sanitized to [A-Za-z0-9_]+ because FalkorDB/RediSearch treats - as a NOT operator and silently corrupts queries.
• Async extraction — add_memory queues entity/fact extraction server-side. A just-added episode may not be searchable for tens of seconds.
• Fail-quiet — if the graphiti server is unreachable, all writes/reads degrade silently. The extension is an accelerator, never a blocker.

License

MIT