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"]
  pots["Pot management"]
  graph_service["Graph service"]
  graph_backend["Graph backend"]
  skill_manager["Skill manager"]
  state_db[("State DB")]
  search_store[("Graph search store")]

  actor --> cli
  cli --> host
  host --> pots
  pots --> state_db
  host --> graph_service
  graph_service --> graph_backend
  graph_backend --> search_store
  host --> skill_manager
  pots --> graph_service

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_profile["Local profile"]
    local_daemon["Local daemon"]
    local_services["Service modules"]
    local_store[("Local stores")]
    local_daemon --> local_services
    local_services --> local_store
  end

  subgraph managed_profile["Managed backend"]
    managed_api["Managed backend API"]
    managed_services["Service modules"]
    managed_store[("Hosted stores")]
    managed_api --> managed_services
    managed_services --> managed_store
  end

  cli --> local_daemon
  cli -. "login + managed pot" .-> managed_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, tickets, ops events"]
  event_ledger["Event ledger"]
  context_graph["Context graph"]
  harness["Agent harness"]

  sources --> context_graph
  sources -. "webhooks / polling" .-> event_ledger
  event_ledger -. "pull / consume" .-> context_graph
  harness --> context_graph
  context_graph --> harness

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_index[("Semantic index")]
  inspection_views[("Inspection views")]
  analytics_rollups[("Analytics rollups")]

  claims --> semantic_index
  claims --> inspection_views
  claims --> analytics_rollups

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.