Context Graph · Use Case

AI Agent Development, Remembered

Coding agents are brilliant and forgetful. Each session rebuilds what already exists, loses the why behind last week's choices, and drifts from the team's methodology. Context Graph gives an agentic project a shared, decision-aware memory — and a methodology that doesn't just live in a README, it runs.

The full use case · from onboarding to governed execution · built on LightRAG · part of Context Graph · supported by Sellence
query-before-build record the why governed actions ontology · rules · actions · RBAC · lifecycle one surface: MCP field-validated
The gap

What an agent forgets between sessions

An AI coding agent has near-perfect recall inside a session and near-total amnesia between them. That amnesia has a shape, and it's expensive.

rebuilds

It writes a second persistence module because it never knew the first one existed. Duplicate seams, drift, wasted runs.

forgets the why

Last week it chose threading.Lock over asyncio.Lock for a reason. This week that reasoning is gone — so it "fixes" the deliberate choice.

drifts from process

The methodology lives in a README nobody re-reads. Reviews get skipped, states get jumped, no audit trail survives.

Commit messages and doc prose don't fix this: they record what changed, rarely why, and they aren't queryable as decisions. Context Graph closes the loop by making the project's decision lineage a first-class, queryable memory — every edge can carry who decided it, why, via which channel, under which policy, and whether it still holds — and by turning the team's methodology into data the graph enforces rather than a document it ignores.

The pitch in one line: query before you build, record the why, and let the methodology run itself.
The habit

The development loop

Working with Context Graph is three habits around one shared memory. They compound: every recorded decision makes the next "does this exist / why is it like this" query sharper.

1 · Query before you build query_auto · query_cgr3 “does this already exist? why?” 2 · Act via governed actions invoke_action · get_manifest validated · authorized · audited 3 · Record the why RecordDecision · CR / ADR who · why · channel · policy Context Graph shared, decision-aware project memory — one workspace per project modules · APIs · tasks · change requests · ADRs · commits · skills · (h, r, t, rc) grounds the next query
Three habits, one memory. Every action and decision flows back into the graph, so the next query-before-build is grounded in the project's real, current reasoning — not last-known-good guesswork.
◆ The filter for what to record
If you can't say who decided it and why, it's telemetry, not memory. The graph stores decisions, not keystrokes — a design choice, a tech pick, an API contract, a rejected option. That discipline is what keeps the decision log valuable instead of noisy.
The data model

The project as a graph

Onboarding installs a dev-shaped ontology: the object types an agentic project actually has, and the typed relationships between them. This is the structure query-before-build searches and the shape governed actions write into.

Developer / Agent Module API Task Change Request Decision / ADR Commit owns exposes_api implements changed_by touched_by justified_by decided
Methodology, expressed as types. Modules expose APIs and depend on each other; tasks and change requests move a feature forward; every change request is justified_by an ADR. The ontology is per-workspace data — see the Ontology guide.

Because relations are open-world, a keyword the ontology hasn't seen is a warning, not an error — the graph keeps growing while the ontology stays a guide rather than a straitjacket.

The stack

Five governance layers

The methodology isn't prose — it's five composable, per-workspace layers. Each is optional; each mirrors the same shape (schema · store · service); together they turn "please follow the process" into something the graph checks.

Ontology

What can exist

Object types, their properties, and the legal relationships between them. The vocabulary every other layer speaks. Guide →

Rules — the methodology gate

What to check

A concept-matching DSL (sim() over embeddings) that flags a decision for review, passes it, or rejects it. Advisory by default. Guide →

Actions

What you can do

Typed operations bound to object types — ProposeModule, RecordDecision, AdvanceTask — each validated, gated, and audited. Guide →

RBAC

Who may do it

Opt-in, deny-by-default within a policy, fully permissive when none is set — so a single-agent project needs zero config, and a multi-agent team gets real boundaries.

Lifecycle

What order it happens in

Declarative state machines per object type. A completed task can't jump back to pending; an illegal transition is refused with 409. The guardrail that keeps state honest.

Manifest

What an agent is told

GET /workspace/manifest?role= assembles ontology + actions (RBAC-filtered to the role) + rules + lifecycle + skills into one self-describing bundle.

◆ Start with nothing, add what you need
A brand-new single-agent project can run with just an ontology and open actions — no rules, no RBAC, no lifecycle. Each layer is switched on the moment the project earns the complexity, and never before.
Execution

One action, five guards

Every governed action runs the same ordered pipeline. The ordering is the point: authorization and legality are checked before anything is written or done, and the whole thing lands as an audit record on the graph.

1 · RBACmay this role? 2 · Lifecyclelegal transition? 3 · Rules gatePASS · FLAG · REJECT 4 · Side effecthandler runs 5 · Audit edgeon the graph provenance = action:… 403 deny 409 illegal 422 reject FLAG still writes — advisory, not a block
Deny early, audit always. RBAC and lifecycle can stop an action before it starts; the rules gate can reject it; a FLAG is advice, not a wall. Whatever passes is recorded as its own edge with an action: provenance — see the Action Layer.
# discover what you can do, then do it — both over MCP
get_manifest()                                           # role-filtered actions, object types, lifecycle
invoke_action(action="ProposeModule", object_ref="state.sqlite_store",
              args={"name": "state.sqlite_store"})        # → PASS | FLAG (reuse-check)
invoke_action(action="AdvanceTask", object_ref="task-42",
              args={"to": "completed"})                    # → 409 if the jump is illegal
Getting started

Onboarding & backfill

Two paths in, depending on whether the project is new or already has history.

new project  POST /onboard

Describe the project in natural language. NL authors tailor the ontology and the methodology rules to what you said, install the layers, and hand back the manifests. Minutes, not a config sprint.

existing repo  backfill_git.py

For a project that predates the flow: a deterministic import of its reality — modules from source dirs, the author, recent commits (and the modules they touched), the docs, and with --code the source itself — so the graph knows the codebase from day one.

The agent pulls its own playbook

No files to hand-copy into a repo. The server serves everything an agent needs to bootstrap itself, generated live from the workspace's installed config — so the guide lists the real object types, the real actions with their params, and the real guardrails, never a stale template. The whole greenfield flow is read one URL:

  1. Read the bootstrap bundle — GET /workspace/bootstrap returns the .mcp.json to write, the backfill command, links to the playbook and manifest, and the ordered next steps (JSON, for machine init).
  2. Wire MCP — write the returned mcp_config to .mcp.json and connect. One surface, done.
  3. Backfill if the repo isn't empty — curl $SERVER/workspace/backfill-script | python - --repo . --workspace <ws> --code. The server serves the script; the agent runs it against its own checkout (the server can't reach your filesystem).
  4. Read the playbook — GET /workspace/playbook returns a Markdown operating guide (the three habits, your actions, the signals) rendered from this workspace's live manifest.
  5. Start the loop.

Onboarding a new workspace first? POST /onboard tailors the config and returns the same bootstrap bundle — the wizard hands the agent its entry points in one call.

What backfill imports

  1. Structural facts (no LLM): source directories → Module nodes, git author → Developer, recent commits → Commit nodes linked to the modules they changed.
  2. Semantic layer: README + docs/ ingested through the extraction pipeline so the architecture and the prose "why" become query-able with provenance.
  3. Code layer (--code): source files ingested full-content, so file- and symbol-level questions ("where is clear_on_start handled?") resolve from the code, not guesswork.
◆ Read-your-writes for your own decisions
A decision an agent records is query-able immediately: /query (and query_auto) blend the decision store into every answer — semantically and by exact name — so asking "explain adr-m2-concurrency" returns the recorded ADR with its full rationale, in the same session it was written.
The interface

One surface: MCP

An agent shouldn't juggle a dozen REST calls. Everything — querying, recording decisions, discovering what it can do, and invoking governed actions — is a single MCP tool surface, wired once via .mcp.json. (The same operations exist as REST endpoints if you ever want to curl them.)

HabitMCP toolsWhat it gives the agent
queryquery_auto · query_cgr3 · search_precedents · get_entity_context Grounding: what exists, why it's like this, and precedents for the call it's about to make.
recordrecord_decision · ingest_decision_summary Durable, structured why — the ADR a future session would otherwise lose.
actget_manifest · invoke_action Discover the role's governed actions, then run one — validated, authorized, audited.
inspectlist_decisions · get_edge_context The audit trail: what was decided, by whom, under which rule.

→ Deeper walkthrough of the agent-side setup and one feature end to end: The Project Graph — Onboarding, Flow & Data.

Evidence

Field-validated on a real project

We onboarded a separate, single-agent project (an OSINT investigator) onto Context Graph and had its dev agent ship three real features entirely through the loop — grumbling freely into a feedback file the whole time. The honest read:

1 build
stopped before it started — query-before-build surfaced an existing state repo, so the agent extended the seam instead of duplicating it
3 ADRs
durable, structured why — incl. the threading.Lock-over-asyncio.Lock rationale a later session would have "fixed"
0 bad jumps
the CR lifecycle open → in progress → closed held as a real, enforced audit trail

The exercise also drove real fixes back into the product — an MCP request-body bug, a mis-firing query route, and the read-your-writes gap on recorded decisions (a decision is now query-able the instant it's recorded). That feedback-to-fix loop is the methodology working on itself.

◆ Honest about the ceiling
Value climbs further with two upgrades the field run pinpointed: a file-level module graph with dependency and API edges (so the reuse check names the overlap, not just flags the concept), and a type flag separating recorded ADRs from decision-shaped sentences extracted out of docs. Both are on the roadmap — see Closing the Gaps.
Positioning

Generic by design

None of this is hard-wired. Context Graph is a generic, decision-aware knowledge graph; AI-agent development is a use case, expressed entirely as data — an agentic-dev preset of ontology, rules, actions, seed, RBAC, and lifecycle files. The core ships none of those verbs.

Swap the preset and the same engine governs a sales desk, a claims pipeline, or a research team. The methodology-as-data contract is the product; agentic dev is the first thing we pointed it at.

This distinguishes it from code-indexing tools: those map the codebase; Context Graph remembers the decisions made across it and enforces how the next one gets made. The graph is a control plane, not an index.

Go deeper

Where it sits · try it

This page is the map. The deeper documents:

◆ The one-sentence version
Point an AI coding agent at Context Graph and it stops rebuilding what exists, stops losing the why, and starts following a methodology the graph actually enforces — with an audit trail to prove it.
↑ Top