- a pot-scoped context model for workspace isolation;
- a graph-backed memory layer for entities, claims, source refs, and timelines;
- a CLI-first agent surface exposed through
resolve,search,record, andstatus; - a lower-level graph workbench for explicit reads, proposals, commits, and quality workflows;
- backend adapters that let the same engine run locally or behind a managed service.
What The Context Engine Does
The Context Engine is not a generic knowledge graph. In this repository, Potpie consistently describes it as a system for grounding agents in real project context. That means it is responsible for:- scoping context to a pot, so reads and writes stay inside the right workspace;
- reading from code, repository structure, source history, and other linked systems;
- retrieving the smallest useful slice of context for a task instead of over-reading the repo;
- storing durable project memory such as decisions, observations, and validated graph facts;
- exposing both high-level agent tools and lower-level graph operations over the same underlying model.
Core Concepts
| Concept | What it means in Potpie |
|---|---|
| Pot | The workspace boundary for context. Sources, reads, claims, mutations, and status are all scoped to one pot. |
| Context graph | The graph-backed memory inside the Context Engine. It stores entities, relationships, claims, evidence, and timeline-style records. |
| Entity | A typed project object such as a service, feature, owner, issue, decision, runbook, or incident. |
| Claim | A canonical fact about an entity or relationship, with provenance and time metadata. |
| Source ref | Evidence that points back to a file, PR, ticket, document, or external system. |
| Semantic mutation | The agent-facing write contract for durable graph updates. Agents propose intent, not raw graph CRUD. |
| Workbench | The lower-level graph command surface for discovery, reads, proposals, commits, history, inbox, and quality checks. |
Runtime Shape
Potpie’s current architecture is CLI-first. Users and agents interact with the CLI, MCP server, or HTTP surface, and those surfaces route into the same host shell and service modules. In local usage, Potpie provisions local config, local storage, and an active default pot. In managed usage, the same graph-oriented services can run behind a backend API on hosted storage. The graph model stays the same; only the host and storage adapters change.Agent Surfaces
Most users do not work with the graph workbench directly. The normal entry point is the four-tool context surface:| Surface | Purpose |
|---|---|
status | Check readiness, active pot, and recommended next actions |
resolve | Retrieve bounded context for a task |
search | Run a narrower follow-up lookup |
record | Save durable project memory |
Why This Matters
The Context Engine exists to reduce two common failure modes in code agents:- reading too much of the repository and losing precision;
- answering from loose summaries instead of project-specific evidence.
- narrow debugging to the relevant execution surface;
- map the likely blast radius of a change before editing code;
- retrieve prior decisions and durable learnings instead of rediscovering them;
- move from broad task context to exact files only when deeper evidence is required.
How The Graph Fits In
The graph is an important implementation layer inside the Context Engine, but it is not the whole product. Use the graph-facing model when you need:- typed entities and relationships;
- source-backed claims with provenance;
- semantic mutation proposals and guarded commits;
- backend-level capabilities such as graph reads, inspection, analytics, and snapshots.