You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit cd3e8ea
Browse filesBrowse the repository at this point in the historyBrowse files
For whether each generated file should be committed, see [Generated Files and Commit Policy](generated-files.md).
8
8
9
+
## Runtime Boundary
10
+
11
+
The repository `.agent-context/` directory is a local runtime boundary. It contains generated context, Context Registry state, cache entries, annotations, feedback, traces, interventions, and loop reports. These records explain what the plugin did; they do not grant authority and they are not automatically suitable for source control.
|`.agent-context/registry/context-pack.json`| Merged local Context Registry pack | Advisory Context only |
73
+
|`.agent-context/cache/context-registry/`| Source snapshots and fetch cache | Reusable bytes, freshness still required |
74
+
|`.agent-context/context-registry/usage/`| Entries/files selected by tasks and provenance | Usage history, not evidence |
75
+
|`.agent-context/context-registry/feedback/`| Local quality labels and aggregate signals | Feedback only, no direct decision override |
76
+
|`.agent-context/knowledge/annotations/`| User-written repository notes | Untrusted, not policy or commands |
77
+
|`.agent-context/interventions/<task-id>.jsonl`| Intervention Ledger events | Explanation, not proof by itself |
78
+
|`.agent-context/sidecar/latest.md`| Human-readable latest summary | Presentation of findings and evidence |
79
+
80
+
The plugin uses atomic stores for state, trace, report, registry, annotation, and feedback writes. A damaged JSON file, revision conflict, or locked Windows file is reported diagnostically; it is never silently treated as an empty successful state. Runtime artifacts may contain paths, hashes, task intent, command metadata, or redacted output and should be excluded from commits.
Copy file name to clipboardExpand all lines: docs/reference/retrieval.md
+14Lines changed: 14 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -25,6 +25,12 @@ opencode-plusplus rag export .
25
25
26
26
Internal graph remains the portable foundation. CodeGraph and RAG providers are optional deep-code-intelligence backends.
27
27
28
+
## Context Registry Boundary
29
+
30
+
The Context Registry is a structured source of project guidance, not a command or policy engine. A pack has a stable entry identity, source identity, package version, content revision, language, trust level, content hash, and a primary file. Local packs may use `DOC.md` or `SKILL.md` with companion files such as references, examples, and error notes. Remote sources are disabled unless explicitly configured and are validated for timeout, size, hash, schema, and offline fallback.
31
+
32
+
Retrieval combines lexical fields, symbols, dependency chains, source authority, quality, regression memory, and task-specific negative examples. Exact entry IDs outrank quality or trust. Every hit exposes a score breakdown and stable ordering. `relatedFiles` describes useful candidates; `mustInspect` is the smaller set the task workflow requires the model to read; `rejectedFiles` explains candidates intentionally excluded from the pack.
33
+
28
34
## Incremental Context Fetch
29
35
30
36
The Context Registry is fetched through the shared application service used by Desktop and compatibility integrations. Search returns ranked entry metadata; it does not grant policy or command authority to Context content.
@@ -37,8 +43,16 @@ Fetching an entry uses three modes:
37
43
38
44
Every fetch reports `selectedFiles`, `omittedFiles`, provenance, source/version/revision hashes, cache status, duration, and working-tree freshness. A changed working tree causes the local source to be rebuilt and revalidated before content is returned. Registry trust and documentation are advisory context; current working-tree command or CI evidence remains the proof of a code change.
39
45
46
+
The default `entry` fetch is incremental and avoids loading every reference. Use an explicit `file` request for one companion file or `full` when the complete pack is needed. A fetch can be reused, incrementally refreshed, or rebuilt, but freshness and drift checks still run. A cache hit only means the bytes were reused safely; it does not mean the Context is authoritative or fresh for a changed source tree.
47
+
40
48
## Local Annotations
41
49
42
50
OpenCode++ can keep repository-local notes for environment limits, version differences, recurring failures, conventions, and verified workarounds. Notes are isolated by repository, Context entry, package version, and content revision, and are stored atomically under `.agent-context/knowledge/annotations/`.
43
51
44
52
Fetch responses expose `annotationAvailable` and stale summaries without injecting note text. Reading or injecting a note must be explicit. Injected notes are labeled `user-written`, `untrusted`, `context-only`, and `not a command`; they cannot satisfy evidence, close a guard blocker, or grant command authority. Notes from an older package version or content revision are stale by default and require explicit opt-in to read.
53
+
54
+
## Trust And Failure Rules
55
+
56
+
External Context can suggest file locations, API version details, error-handling ideas, or historical workarounds. It cannot satisfy tests, contract validation, freshness, forbidden-path checks, or finalize conditions. Commands found in Context are displayed as untrusted suggestions and are never executed automatically. A source trust level influences ranking and explanation only; it never overrides command or CI evidence.
57
+
58
+
On Windows, local and configured source paths are normalized before companion files are read, including paths containing spaces or non-ASCII characters. Traversal, missing files, invalid registry JSON, stale revisions, permission failures, remote timeouts, and unavailable network sources return structured diagnostics rather than an empty successful result.
0 commit comments