Context Graph¶

The context graph is Potpie's project-memory layer for AI agents. It stores compact, sourced facts about your project so agents don't rebuild context from raw code, PRs, tickets, docs, and chat every time.

The problem it solves¶

Project context is scattered:

Decisions live in PRs, ADRs, Slack threads, and tickets
Ownership and topology live in repo files, dashboards, and tribal memory
Prior bugs and fixes are hard to retrieve by symptom
Agents start each task with no durable memory of what previous agents learned

Potpie holds that context once, keeps it fresh, and exposes it through a small, stable surface.

Core model¶

The context graph is built on a compact set of concepts:

Concept	Meaning
Pot	Unit of isolation and context — a workspace boundary. Every query, source, and graph operation is scoped to one pot.
Entity	Stable project object: a service, feature, decision, issue, owner, runbook, or incident.
Claim	Canonical fact about an entity or relationship, with provenance and time fields.
Source ref	Pointer back to evidence: file path, PR, ticket, doc URL, alert, or deploy event.
Semantic mutation	Agent-facing structured write proposal that lowers into validated graph mutations.
Inbox item	Pending graph work captured when the agent or user is not ready to choose an ontology update.

Info

The graph stores compact facts and references — not full PR diffs, document bodies, chat transcripts, or telemetry streams.

How agents interact with the graph¶

Read surface¶

Agents can query the context graph through the CLI or MCP tools:

Surface	What it does
`potpie resolve` / `context_resolve`	Query compact context using intent, include, scope, and mode parameters
`potpie search` / `context_search`	Narrow follow-up lookup for specific entities, decisions, or patterns
`potpie status` / `context_status`	Discover readiness, active pot, source/skill/backend status

Write surface¶

Surface	What it does
`potpie record` / `context_record`	Capture durable project learnings through validated semantic mutations
`potpie graph propose`	Create an inspectable semantic mutation plan (no graph write)
`potpie graph commit`	Apply a validated plan and write audit/history
`potpie graph inbox add`	Capture pending graph work for later processing

Architecture¶

The context graph operates in two deployment modes with the same service modules:

flowchart TB
  actor["user or agent"]
  cli["potpie CLI"]
  host["host shell"]
  pot["Pot Management"]
  graph["Graph Service"]
  backend["GraphBackend"]
  skills["Skill Manager"]
  state[(state DB)]
  store[(graph/search store)]

  actor --> cli --> host
  host --> pot --> state
  host --> graph --> backend --> store
  host --> skills
  pot --> graph

Component	Responsibility
CLI	User/agent surface, command UX, setup flags, JSON rendering, active-pot selection
Host shell	Local daemon or managed backend API — owns lifecycle, auth, health, migrations
Pot Management	Active pot, pot CRUD, source registry, lifecycle, status aggregation
Graph Service	Data plane — reads, semantic mutations, validation, inbox, history
GraphBackend	Swappable store: mutation, claim query, semantic search, inspection, analytics
Skill Manager	Skill catalog and install/update into agent harnesses

Local vs. managed¶

Aspect	Local (default)	Managed (opt-in)
Entry point	`potpie setup`	`potpie login`
Storage	Local state DB, embedded graph store	Hosted operational DB, hosted graph/search
Graph state	Stays on your machine	Hosted with collaboration controls
Transition	Explicit `potpie cloud push/pull`	Same CLI surface

flowchart LR
  cli["potpie CLI"]

  subgraph local["Local profile"]
    direction TB
    daemon["local daemon"]
    lservices["service modules"]
    lstore[(local stores)]
    daemon --> lservices --> lstore
  end

  subgraph managed["Managed backend"]
    direction TB
    api["managed backend API"]
    mservices["service modules"]
    mstore[(hosted stores)]
    api --> mservices --> mstore
  end

  cli --> daemon
  cli -.->|login + managed pot| api

Both profiles use the same CLI surface — --local and --managed flags disambiguate when needed.

Source ingestion¶

The context graph can consume data from multiple sources:

flowchart LR
  sources["code, docs, PRs,<br/>tickets, ops events"]
  ledger["Event Ledger"]
  graph["Context Graph"]
  agent["agent harness"]

  sources --> graph
  sources -.->|webhooks / polling| ledger
  ledger -.->|pull / consume| graph
  agent --> graph
  graph --> agent

The Event Ledger (managed or self-hosted) handles webhook receivers, event history, and replay tokens. Local or managed graphs pull events from it explicitly.

Warning

Using a managed ledger does not imply cloud graph storage. It only gives the selected graph a source-event feed. Graph state location is always determined by the active pot.

Storage principle¶

The graph model is the invariant. Physical storage is an adapter.

flowchart LR
  claims[(canonical claims)]
  semantic[(semantic index)]
  inspection[(inspection views)]
  analytics[(analytics rollups)]

  claims --> semantic
  claims --> inspection
  claims --> analytics

The canonical claim store is the source of truth. Semantic indexes, traversal views, and analytics are rebuildable projections.

Relationship to the Knowledge Graph¶

The Knowledge Graph is the code-structural layer — AST-parsed nodes and edges representing functions, classes, and their dependencies, enriched with LLM-generated descriptions and semantic embeddings.

The Context Graph is the broader project-memory layer that encompasses the knowledge graph and adds:

Project decisions and conventions
Source history from PRs, tickets, and docs
Team ownership and topology
Prior bugs, fixes, and incident learnings
Integration data from GitHub, Linear, Jira, and Confluence

Together, they give agents both structural code awareness and durable project context.