DOCSEARCHbyAlgolia
Submit Docs

Potpie Documentation

repository·main·Indexed 26 days ago

https://github.com/potpie-ai/potpie

Potpie turns codebases and software development lifecycles into a living context graph for AI agents. It indexes code, history, and team knowledge to enable agents to perform complex tasks with project-specific context. The system includes a CLI for managing pots, a swappable GraphBackend (defaulting to falkordb_lite), and a Skill Manager for integrating with agent harnesses like Claude Code, Cursor, and Codex.

Tokens
66.6K
Snippets
91
Records
410
Agent score
88%

What's inside Potpie

  1. Understand the Nudge Trigger Model

    main

    Nudges allow durable graph memory to be injected into an in-session agent without consuming extra tokens for querying. A mechanical hook reads the graph at specific lifecycle moments and injects relevant data or instructions. The process is deterministic and uses a local embedder for similarity, avoiding external model calls on this path.

    There are three layers to the model:

    1. Policy (domain/nudge.py): Defines how specific events map to actions.
    2. Executor (application/services/nudge_service.py): Handles the reading of graph views and deduplication.
    3. Dedup Ledger (adapters/outbound/session/injection_ledger.py): Ensures the same information isn't injected multiple times within a session.

  2. Understand the Context Graph data model

    main

    The Context Graph is a durable, shared project memory for AI agents. It stores compact claims plus source references, rather than full payloads (like PR diffs or chat logs).

    Core Concepts

    • Pot: The unit of isolation and tenancy. Every operation is scoped to a pot_id (stored as group_id). The first local setup creates a default pot.
    • Entity: A stable project object (e.g., Service, Feature, Decision, Activity). There are 24 catalog types.
    • Claim: A canonical, sourced, time-stamped fact about an entity or relationship. This is the single source of truth.
    • Source ref: A pointer to the evidence (e.g., file path, PR, ticket URL).
    • Inbox item: Pending graph work captured when an agent is not yet ready to commit an ontology update. It is not a fact until processed.

  3. Understand the Potpie Read Side Principles

    main
    Potpie follows a strict principle for all read operations: Potpie returns ranked evidence, never a synthesized answer. The system provides the raw, sourced evidence (claims, entities, relationships), and the agent or human user is responsible for reasoning over that evidence to form a summary or answer. There is no server-side answer synthesis in the read trunk.

  4. Potpie Integrations and Coding Harnesses

    main

    Potpie supports various integrations to index project context and coding harnesses to provide that context to AI agents.

    Supported Integrations

    • GitHub: Index repositories, pull requests, issues, reviews, and source history.
    • Linear: Index teams, issues, projects, and documents.
    • Jira: Index projects, issues, status, and changelog context.
    • Confluence: Index spaces, pages, runbooks, and decisions.

    Supported Coding Harnesses

    • Claude Code
    • OpenAI Codex
    • Cursor
    • OpenCode

  5. Understand the Context Graph Architecture

    main

    The Context Graph uses a hexagonal (ports-and-adapters) architecture. The core logic resides in a pure domain layer (ontology, contracts, and identity) and an application layer (services and use cases). I/O is handled by adapters (inbound like HTTP/CLI and outbound like graph backends/connectors).

    Key architectural components:

    • Domain Layer: Contains the ontology, DTOs, and coherence invariants. It has no I/O.
    • Application Layer: Orchestrates domain logic via services (e.g., graph_service, nudge_service) and readers.
    • Adapters Layer: Concrete implementations for I/O, including the Postgres event store, local embedders, and various graph backends.
    • Host/Daemon: The HostShell facade and the potpie/daemon/lifecycle.py manage the lifecycle and IPC.

  6. Distinguish between Internal Event Store and External Event Ledger

    main

    Potpie uses two distinct ledger concepts. Do not conflate them:

    1. Internal Event Store (Real/Live): A Postgres-based system where inbound episodes, events, and records land. It manages the lifecycle of events using the states queued, processing, done, or error. It is used by the HTTP ingestion server.
    2. External Event Ledger (Seam/Stub): A managed or self-hosted service that owns provider credentials, webhooks, and normalized source history. It uses a cursor concept (per pot, source) to advance through events. Note: As of current development, the external ledger clients are mostly TODO stubs and are non-functional against real providers.

  7. Understand the potpie-integrations architecture

    main

    The potpie-integrations package follows a hexagonal architecture layout to support external integrations such as OAuth providers, project_sources, Linear sync, and HTTP routers.

    Key directory roles:

    • integrations/domain/: Contains the registry, provider definitions, and shared schemas.
    • integrations/application/: Contains services and provider bootstrap logic.
    • integrations/adapters/outbound/: Contains persistence models, OAuth clients, Linear GraphQL, and crypto implementations.
    • integrations/adapters/inbound/http/: Contains FastAPI routers that are mounted by the main application.

    Note: The installable Python package root is integrations. This is designed to prevent collisions with the context-engine editable install.

  8. Understand the Sandbox Core Model

    main

    The Potpie sandbox is composed of three distinct layers to ensure isolation and persistence:

    1. RepoCache: A durable git mirror (local or remote) used to avoid re-cloning. It is shared infrastructure and does not hold uncommitted edits.
    2. Workspace: A durable checkout or git worktree created from a RepoCache. It provides a stable filesystem root for an agent session and preserves uncommitted edits, dependency installs, and branch state.
    3. SandboxRuntime: The compute environment (e.g., Docker, Daytona, E2B, or local subprocess) that executes commands against a Workspace.

    Key Principle: Destroying a SandboxRuntime does not delete the Workspace unless explicitly requested. Persistent agent work belongs to the Workspace, not the runtime.

  9. Understand the Potpie Ontology and Graph Contract

    main
    Potpie uses a declarative, spec-driven ontology and graph contract (V1.5) to define the structure of its data plane. This contract is built from three primary catalogs: ENTITY_TYPES, EDGE_TYPES, and RECORD_TYPES. All other components, such as the identity registry, singleton registry, and classifier tables, are derived views over these catalogs. The contract ensures coherence between the data plane and the workbench commands (potpie graph catalog, describe, status).

  10. Understand the Potpie Context Graph write path

    main

    Writing facts into the Context Graph follows a tiered stack. Agents and harnesses emit semantic operations via a flat DSL, which are then validated, lowered into structural mutations, and finally applied through one of two 'spines'.

    The Write Spines

    • Spine A (Canonical): Uses the graph propose $\rightarrow$ graph commit --verify workflow. This is the recommended path for most users.
    • Spine B (Immediate): Uses mutate(). This is a legacy/internal path reached only via the record or context_record bridges.

    The Tiered Stack

    1. Semantic DSL: Parses flat JSON operations into DTOs.
    2. Validation + Risk: Performs pure-domain checks and assigns a MutationRisk (low/medium/high).
    3. Lowering: Converts accepted operations into a MutationBatch with provenance.
    4. Pre-apply Gate: Performs final validation, canonicalization, and potential soft-fail downgrades.
    5. Write Door: The single entry point (apply_mutation_batch) that executes the idempotent writes to the canonical store.

  11. Configure Workspace Flows

    main

    Potpie uses three distinct workspace flows depending on the intended use case:

    1. Analysis Flow (Read-only):

      • Used for code search and exploration.
      • Uses a clean worktree for a specific branch/commit.
      • Attaches a read-only runtime.
      • Executes whitelisted read-only commands.

    2. Edit Flow (Read/Write):

      • Used for feature work, bug fixes, and PR creation.
      • Keyed by conversation_id.
      • Creates a new branch (e.g., agent/edits-{conversation_id}).
      • Attaches a write-capable runtime with writable mounts.
      • The workspace is the source of truth for files (replaces Redis-based change tracking).

    3. Task Flow (Isolated/Multi-agent):

      • Used for background work or multiple independent implementation attempts.
      • Keyed by task_id.
      • Creates isolated branches (e.g., agent/task-{task_id}).
      • Results can be merged/diffed back into the main conversation edit workspace.