Skip to main content

Local context for AI agent workflows

note

The user-facing context guide now starts at Context. Use Context mode when you need to explain the maximum-assimilation contract, and Agent guide when handing a project to a coding agent.

Quick answer​

Local context is the operational knowledge an agent needs for a specific repository or workflow: conventions, constraints, current state, reusable notes, tool instructions, and run history. Agentplane keeps this context close to local workflows so agents do not depend on fragile chat history.

When should I use local context?​

Use local context when:

  • the agent repeatedly needs repo-specific conventions;
  • tasks span multiple steps or sessions;
  • workflows need reusable instructions;
  • you want context that is inspectable and versionable.

Do not use local context when:

  • a one-off prompt is enough;
  • the information contains secrets;
  • the context would become stale without review;
  • the agent needs live data that should be fetched by a tool instead.

What local context is​

Local context is Agentplane's repository-owned memory layer. It keeps reusable project knowledge in versioned files, then builds a local projection for fast search and retrieval.

Use it when an agent needs facts, wiki pages, graph edges, capability notes, or task-specific source sets that should survive outside one chat session.

Context management in v0.7​

Agentplane v0.7 keeps the v0.6 repo-owned context model and adds supervised semantic publication:

  • raw sources remain in the repository and are treated as evidence
  • wiki pages accumulate synthesis instead of forcing agents to re-derive it from scratch
  • fact and graph rows preserve structured claims and relationships
  • useful Markdown cross-links make related wiki pages discoverable without replacing graph edges
  • generated projections stay disposable and can be rebuilt
  • task history can become new context through explicit extraction tasks
  • verification checks keep sourced context from drifting into unsourced memory

This follows the LLM Wiki pattern described by Andrej Karpathy: keep raw sources separate, let an LLM maintain a persistent markdown wiki, and use a schema file such as AGENTS.md to make the agent a disciplined maintainer rather than a generic chatbot. Agentplane adapts that pattern for software repositories by adding task lifecycle, source refs, proposal-before-promotion, and verification gates.

Context engineering is broader than prompt writing. It is about selecting, compressing, isolating, and updating the information available to an agent at each step. Agentplane local context is a practical local implementation of that idea.

The LLM Wiki pattern is useful as a mental model for persistent, structured knowledge that an LLM can consult instead of relying on one huge prompt. Agentplane does not claim to implement Karpathy's gist verbatim; it adapts the useful part: local, structured, inspectable context that can be reviewed and versioned.

Source of truth​

Editable source artifacts live under context/**:

  • context/wiki/**: human-readable pages.
  • context/facts/**/*.jsonl: structured facts.
  • context/graph/**/*.jsonl: entities and edges.
  • context/capabilities/**/*.md: capability notes for agents.
  • context/raw/**: ingested raw material. context init leaves this as an empty user-owned source tree; create whatever nested structure fits the project.

Generated context artifacts live under .agentplane/context/derived/**. The fast local search projection is stored in the shared Agentplane cache database at .agentplane/cache.sqlite; context owns only its projection tables inside that file. Treat both the derived artifacts and the SQLite cache as disposable output.

The initial wiki profile creates only context/wiki/AGENTS.md and context/wiki/index.md. Ingestion tasks use the single public maximum-assimilation contract, so project-specific folders should appear from source-backed topology decisions rather than from an empty starter hierarchy. If a glossary is useful, keep it as a thin navigation index over canonical wiki pages and graph entities; aliases belong there, while factual claims and provenance stay on the backing wiki/fact/graph artifacts.

agentplane context init
agentplane context search "release checklist"
agentplane context show context/wiki/release.md#section=publish-gate
agentplane context check

context search defaults to curated context: wiki pages, derived facts, derived graph rows, and capability records. Use --scope tasks, --scope raw, or --scope all when you intentionally want task-history or raw-source recall mixed into results.

When agentplane context init runs in an empty standalone directory, it bootstraps the Agentplane project first and then creates the context workspace. In a non-empty directory that is not already an Agentplane project, run agentplane init explicitly before agentplane context init so the project gateway, workflow, backend, and conflict handling stay visible.

The default init profile is maximum-assimilation: a stricter context contract for preserving significant source meaning as durable project memory. Init does not pre-create internal wiki folders; first ingest creates structure only when there is source material to assimilate. Agents should generate the wiki hierarchy from evidence, but keep page frontmatter, source refs, modalities, claims, graph refs, conflicts, and visibility metadata stable enough for future publication proposals and context-pack synchronization.

context show resolves whole files, markdown sections, and line ranges. Markdown section refs use stable slugs such as #section=publish-gate; line refs use #lines=12-24 or #line=12.

Maximum-assimilation profile​

Use agentplane context init or agentplane context init --profile maximum-assimilation when the maintained wiki and derived artifacts should become the complete semantic memory, not just a navigable synthesis over raw files. In this mode, the next context ingestion tasks request the context.maximum_assimilation blueprint.

Older profile names are compatibility aliases for initialization. Context ingestion still creates context.maximum_assimilation tasks and applies the same verification gates.

The contract requires:

  • Preserve all significant source meaning in wiki, fact, graph, glossary, provenance, and coverage artifacts. If context/raw/** is deleted later, the maintained context should still be understandable and usable.
  • Choose the wiki structure from the first source analysis. Maximum-assimilation ingest does not create the default concepts/, entities/, decisions/, modules/, contradictions/, and reports/ starter scaffold unless the source analysis explicitly justifies that topology.
  • Record the wiki topology decision before creating page families: what folders/pages are canonical, why that granularity fits the sources, which terms are aliases, and which pages should stay as headings inside broader pages.
  • Treat the topology decision as a verification artifact, not just a planning note. It should classify the selected source shape, such as book/corpus, codebase, task history, product docs, research notes, or ops logs; name each canonical page family; cite source-backed evidence for every new family; explain page-vs-heading granularity; and keep ambiguous identities as aliases, possibly_same_as, conflicts, or open questions instead of normalizing them away.
  • Keep original source association through a source registry: source_id, original path, sha256: hash, content type, line count, ingest time, and availability state such as present|missing|private|redacted.
  • Use concrete line refs such as context/raw/source-name.md#lines=12-24 as provenance addresses, not as the retained content. When raw is missing, those refs become non-dereferenceable audit pointers while the wiki/fact/graph layer remains self-contained.
  • Extract canonical entities, aliases, relations, decisions, requirements, risks, workflows, conflicts, and open questions before writing narrative articles.
  • Maintain the canonical glossary as a separate root wiki file at context/wiki/glossary.md. Keep it as an alias/navigation layer over wiki pages and graph entities, use canonical terms from that glossary in synthesized prose when identity is clear, and preserve source-local wording as aliases or evidence details.
  • Use Obsidian-compatible wikilinks whose target case exactly matches a canonical page path, title, or alias. Prefer [[canonical-page|Display Label]] when the readable label differs from the file path. Keep standard Markdown links for source refs, external URLs, and file references so AgentPlane provenance checks stay readable.
  • Cite raw sources in prose with numeric notes such as [1], then keep raw-data Markdown links in a trailing ## Sources section.
  • Record a coverage report that separates assimilated spans, intentionally omitted boilerplate, duplicates, redacted private spans, unresolved identities, and conflicts.
  • Record an EVALUATOR quality review for source-shaped structure, granularity, useful wikilinks, line-addressed provenance, glossary alias safety, coverage gaps, raw-deletion resilience, and private leakage risk before finish.

Critical points:

  • Full assimilation does not override sensitivity boundaries. Secrets and non-publishable spans must not be copied into public wiki pages, task summaries, ACRs, or reports.
  • Source-shaped topology is a gate, not an aesthetic preference. Do not create a page family until the topology decision names the source evidence that justifies it; otherwise keep the material under stable headings inside an existing canonical page.
  • "100% significant content" means semantic coverage, not a line-for-line raw mirror. Boilerplate, duplicate text, generated noise, and private spans should be marked as omitted/redacted with reasons instead of being silently dropped.
  • Glossary normalization can corrupt meaning if aliases are guessed. Ambiguous identity should stay as possibly_same_as, conflict candidates, or open questions until reviewed.
  • The root glossary file is navigation and normalization, not a competing source of truth. Factual claims and provenance still belong on the backing wiki, fact, graph, source registry, and coverage artifacts.
  • Granularity can explode. Prefer reusable entity/concept/decision/risk/workflow pages plus stable headings for smaller objects, not one page per sentence.
  • Obsidian compatibility is a markdown/wiki contract, not editor-local configuration. Agentplane does not create .obsidian/** by default; vault settings remain user-owned.

Wiki pages and metadata​

agentplane context wiki new decisions/context-storage --modality decision --source .agentplane/tasks/<task-id>/README.md
agentplane context wiki lint context/wiki/decisions/context-storage.md
agentplane context wiki explain context/wiki/decisions/context-storage.md
agentplane context wiki link context/wiki/decisions/context-storage.md

Wiki pages are markdown context artifacts with YAML frontmatter. The frontmatter is a page manifest: it names the page's modality, epistemic status, source refs, related claims, graph refs, conflicts, and intended visibility. It is not a replacement for atomic claim/fact/graph rows; it links the human-readable page to those machine-readable artifacts.

Generated wiki pages also include Obsidian properties such as aliases, tags, and cssclasses so the same markdown reads cleanly in an Obsidian vault without .obsidian/** configuration.

Use separate pages when a concept, entity, decision, requirement, policy, risk, definition, workflow, or module is likely to be reused. Keep related claims on one topic page when that is more readable, but keep each important claim's modality and source visible. Decisions extracted from task history should become ADR/evolution records with provenance and supersession metadata rather than probabilistic facts.

Before writing wiki/fact/graph updates, agents should search existing context for matching entities and use canonical labels when the source mentions something already described. Source-local names can be recorded as aliases. If a source extends an existing entity, update the existing page or section and add sourced claims/provenance instead of creating a duplicate page. Smaller objects may live under stable headings inside a broader topic page and be referenced with section links from related pages.

Learn from files and changes​

agentplane context learn changes
agentplane context learn files ./notes.md

context learn is the human-facing task factory for reusable context. learn changes creates a context assimilation task from changed local context sources. learn files creates one from explicit files or directories. The generated task is then picked up by a CURATOR agent working in the repository through Codex, an IDE, or another human-assisted workflow.

Generated file/change tasks carry a portable context_assimilation prompt module and repeat the CURATOR contract in the task description so Codex, IDE agents, and humans get the same wiki/claims/cross-link/provenance instructions without a runner handoff.

When CURATOR writes wiki pages, links should appear inside the narrative text where they help the reader or a later agent resolve meaning. A page should not rely only on a trailing "Related Pages" list. If lookup shows that a source-local name probably matches an existing page or graph entity, CURATOR should use the canonical term in prose, link it to the canonical page or section, and record the source-local wording as an alias. For example, if a raw note says "MR Sync" and the graph already identifies it as Meridian Relay, the wiki sentence should use [[Meridian Relay]] or the local Markdown link to that page and preserve "MR Sync" as an alias/evidence detail.

In maximum-assimilation mode, prefer case-stable links such as [[meridian-relay|Meridian Relay]] and [[meridian-relay#Sync workflow|Meridian Relay sync]] for semantic wiki graph links. Use numeric source notes in prose, then list raw refs at the end: 1. [context/raw/...#lines=12-24](context/raw/...#lines=12-24).

After adding, moving, or materially renaming wiki pages, CURATOR should refresh relevant index.md navigation pages. agentplane context wiki index context/wiki updates generated index sections so new pages are discoverable without treating the index as a competing source of truth.

ap context ingest remains the lower-level pipeline command for agents and automation, including --all and --index-only.

Learn from completed tasks​

agentplane context learn tasks --tag release --limit 20 --dry-run
agentplane context learn tasks --tag branch_pr --limit 25
ap context harvest tasks --tag branch_pr --write-proposals
ap context harvest tasks --task 202605100837-PJZW2E --create-extraction-tasks

context learn tasks scans completed task history oldest-first and writes source-backed, unpublished knowledge proposal records. Supplying exactly one --task selects that proposal and creates one CURATOR semantic work order. A dry run only previews candidates.

The advanced ap context harvest tasks command exposes the full context pipeline and keeps its stages separate:

  • source indexing: task README, comments, and commit metadata become raw evidence under context/raw/tasks/**
  • proposal collection: CLI writes typed candidate records with exact source refs and mechanical duplicate/consolidation evidence under .agentplane/context/derived/proposals/task-knowledge/**
  • explicit selection: one --task creates one CURATOR work order and a selection receipt; broad collection never creates semantic work automatically
  • semantic decision: CURATOR reads the bounded source pack and returns one SGR describing durable, duplicate, transient, conflicting, or rejected knowledge
  • supervised publication: CLI validates and applies an accepted SGR, then owns indexes, checks, evaluator, ACR, finalization, and the apply receipt

Use --tag, --task, --since, --until, --after-task, and --limit to advance gradually from older completed work toward newer changes. --promote is rejected: task harvesting cannot publish semantic knowledge. Proposal and selection markers include the source digest, proposal path, source refs, work-order id, and publication state. Later broad runs skip unchanged source digests; an explicit --task can intentionally revisit a changed source. learn tasks and advanced write modes require an initialized context workspace from agentplane context init; dry-run mode can be used before initialization.

Each selected work order carries an extensions.agentplane.context source pack with the exact task README and ACR paths, source digest, proposal id, allowed outputs, provenance requirements, and a replaceable prompt module. CURATOR may write its task-local SGR result only. It must not write context/wiki/**, facts, graph rows, indexes, evaluator output, ACR, or finalization artifacts.

Verify task context​

ap context verify-task <task-id>

The verifier checks that task-facing context claims are source-backed:

  • task source-set entries point at existing files and include sha256: hashes
  • changed wiki pages carry source_refs, source_ref, no-source, or no_source
  • fact rows include provenance, confidence, and status
  • graph edges reference known entities and include source refs
  • capability notes include source refs
  • completed context tasks have an ACR context extension

The verifier does not require every known term to be linked. Agents should still prefer useful Markdown cross-links when an existing page or glossary anchor helps a future reader navigate related concepts, decisions, modules, risks, or entities.

Repository-local receipt bytes and their task reference are not an authentication channel. The standalone verifier and context finalize-task therefore remain fail-closed with compatibility_unverified when only a matching path and SHA-256 from the same writable repository are available. Use context supervise-task <task-id> --extraction <sgr-json> for the authenticated supervisor path: it supplies the in-memory observation, owns the mechanical checks, and records the durable phase receipts. For a manual recovery, run context wiki lint, context graph validate, and context doctor separately and record independent task verification with ap verify.

How this differs from RAG​

RAG retrieves source chunks at answer time. Local context still supports search, but the durable artifact is the maintained knowledge layer: markdown pages, facts, graph edges, capability notes, and task evidence that can be reviewed in Git.

Use raw search when you need to inspect source material. Use context management when a finding should compound into future agent work.

Privacy boundary​

context/raw/** is a user-owned source tree. AgentPlane reads the hierarchy and file contents but does not prescribe folders under it. Keep secrets out of public context artifacts and out of task summaries. The local context layer is repository-owned; it is not a secrets vault.

Common commands​

agentplane context init
agentplane context learn changes
agentplane context learn files <path>
agentplane context learn tasks --tag <tag> --limit 25
agentplane context learn tasks --task <task-id>
agentplane context doctor
agentplane context search "<query>"
agentplane context show <ref>
agentplane context check

context list is intentionally not a public command. Use search for discovery and the graph inspection commands when you need structured neighborhood views.

Further reading