RepoCodex synthesis
Type: agentic-system-analyses/types/agentic-system-synthesis.md
Bounded synthesis
RepoCodex is a repository-native memory system for coding agents, not an enclosing agent runtime. It retains explanations of code decisions beside source code, supplies them before later edits, and checks whether their declared anchors and literals remain attached to current text. This account covers the complete shipped loop at Git revision 96978e292fcb3b100f53ac024b353e1b8b2c8af4, with cutoff 2026-11-08: skills, installer, CLI/MCP commands, persistence, retrieval, maintenance and enforcement callers. SRC-1 supplies implementation and doctrine/design only. No execution trace, test result or causal experiment was supplied or produced. External hosts, models, dependencies and consuming deployments are outside the frozen source boundary; their responsibilities are not RepoCodex guarantees (boundary, Source register).
Before the edit: select explanations, not a whole memory dump
Installation copies skills, rule pointers, hook and Action configuration into a consuming repository. The foreground coding agent remains responsible for next-step selection, code edits, tool use and communication with its user. RepoCodex provides deterministic commands and natural-language procedures. Installation enables later client loading; it does not demonstrate loading or compliance (RT-RTE-install-wiring, RT-CMP-coding-agent).
The representative workflow is explicitly connected by the packaged coding skill: request context for intended edit paths, inspect plausible callers, edit code, validate the diff, repair or author memory, revalidate, and commit code with memory and indexes. The caller inspection has a default 12-file cap. It is work requested of the foreground agent, not a RepoCodex-created subagent frame (RT-RTE-coding-loop, workflow account).
Retained concepts are Markdown files in discovered .context shards. Their prose bodies explain why to a model; parsed frontmatter supplies paths, statuses, literals and other fixed-rule inputs. Body links also have symbolic consumers for discovery and impact. The same file therefore supports interpretation and mechanical selection without making its explanation mechanically true (RT-OBJ-concept-body, RT-OBJ-concept-frontmatter, memory annotations).
A path-context request reconstructs reverse mappings from current concepts, selects eligible pinned bodies, sorts them, and returns full bodies plus related/catalog titles. Persisted reverse-index files are separately checked for synchronization; retrieval does not depend on loading those committed copies. Default selected-body retrieval omits drafts and deprecated concepts. Sources, verified stamps, stable status and Git churn affect order, not authenticated warrant. All eligible matching bodies are returned: the character-based token estimate is not a hard budget. This is requested read-back, not unsolicited injection, host compaction or eviction of previous turns (RT-RTE-context-read, MEM-OBJ-reverse-index, MEM-CLM-context-selection).
Related bodies require another agent decision to open them. The direct MCP identity tool is a distinct route: it returns complete frontmatter and body without lifecycle filtering, including deprecated content still on disk. Ordinary path context omits rationale, supersession and anchor details; their stored presence is not evidence that the agent received those reasons. Deprecation consequently withdraws default body selection, not all access (MEM-RTE-concept-read, memory read-back).
After the edit: attachment checks and scoped admission
Validation derives classifications and maintenance findings from current source text, parsed metadata, links and the diff. A live anchor does not guarantee that every term or frozen literal survives: the separate claim evaluator can report CLAIM_BROKEN while an N-of-M anchor remains LIVE. Relocation checking also has unequal predicates: a Git rename target can qualify with a nonempty matched region, whereas the search alternative requires all terms. These are source deductions, not observed failures. They bound what pin checking establishes: local text attachment under implemented predicates, not software behavior, causal explanation or semantic continuity (EPI-RTE-claim-check, EPI-RTE-relocation-check).
The foreground agent interprets the verdict and skipped_memory, rather than treating LIVE alone as completion. Uncovered substantive edits require pinning memory under the skill; accepted unanchored narrative does not discharge that obligation. The write command admits caller-supplied Markdown through revision/type checks and, when anchors exist, the anchor gate. It inserts no per-content human approval. Its acceptance is for storage and mechanical suitability, not a decision that the explanation is true (RT-RTE-memory-write, workflow recovery account).
There is no universal all-writes gate. Anchorless input skips anchor evaluation. CLI JSON reanchor patches mutate paths and optional terms directly; MCP reconcile instead uses the ordinary write route. Bootstrap and identity relocation have their own admission mechanisms. Recovery is not transactional: a superseding proposal can deprecate its predecessor before failing later checks, and relocation unlinks before writing the new identity. Restoring state and retrying remain caller responsibilities (RT-RTE-memory-write, RT-RTE-anchor-patch, RT-RTE-relocate-identity).
Reaching delivery: conditional denial, advisory semantic review
Configured hook/check invocations can translate blocking into a nonzero exit and deny a commit or check. Plain CLI validation returns zero despite a blocking payload; MCP returns data for its caller to act on. Installation defaults to shadow posture, which blocks skipped-memory rather than every other diagnostic. An exemption with accepted acknowledgment evidence clears blocking reasons. The Action checks non-author approving review/token evidence, but the validator itself does not authenticate reviewer identity. Staged path selection also uses working-tree source reads, so it is not a complete attestation of the exact staged snapshot. Deployment and branch protection remain unobserved (RT-RTE-validate-change, RT-BAP-check-enforcement).
The requested delivery unit is code plus maintained .context files and generated indexes. A configured check accepting that unit is narrower than semantic approval or merge. A separate review skill asks an external agent to compare new explanations with the originating diff. Its findings are advisory and cannot themselves fail the required deterministic check. The advisory Action invokes deterministic output without providing agent judgments; audit imports findings as returned proposals, not automatic semantic edits. Thus semantic checking is requested, but neither an actual judgment nor an accepted criticism-and-revision sequence is evidenced (workflow delivery account, EPI-RTE-semantic-review, RT-RTE-review-audit).
Explicit repair invokes the first available Cursor, Claude or Codex harness with a static prompt and repository working directory. Computed lost/candidate data remains in the caller's result rather than entering the child prompt. The process boundary does not establish model-window isolation. There is no verdict guard, retry loop or post-child validation in this driver; zero process exit is not proof of repaired memory (RT-RTE-agent-repair).
Across invocations: retained updates without demonstrated improvement
The strongest supported trace-fed contribution is deterministic bootstrap: selected repository history subjects become gated, persisted draft explanations that later draft-enabled context or direct identity reads can deliver. This is a wired automatic trace-to-artifact-to-later-consumer path. Its original input is recorded repository change events. The comment/document branch instead imports static text; a latest file-touch commit pointer neither makes that text a trace nor authenticates its original explanation. Copying with a wrapper is acquisition, not production of an accepted new explanatory claim (RT-RTE-bootstrap-drafts, EPI-RTE-bootstrap-import).
The coding protocol separately affords retained revision from validation feedback, at weaker evidence strength than deterministic bootstrap. These support the artifact-update sense of trace learning, not demonstrated improved capacity for future action. Neither route has an observed beneficial comparison. Initial content provenance, actual repair transformations and additional semantic effects of arbitrary prose remain unresolved. The profile verification preserves partial coverage rather than upgrading those alternatives from one positive witness (RT-RTE-coding-loop, profile verification).
Other maintenance has narrower effects. GC automatically deprecates concepts lacking inbound links and any anchor hit, or expired drafts; it does not refute their content. Catalogs retain navigation summaries, write logs retain operation labels, and metrics feed a later diagnostic ratio rather than a semantic update policy. A replace-path event labels itself false drift without independently checking that diagnosis (EPI-RTE-audit-gc, MEM-OBJ-context-catalog, MEM-OBJ-context-log, MEM-RTE-metric-readback).
Independent higher-level properties remain unestablished, not collectively disproved. For theory-builder condition 1, the records identify a capacity to store localized explanations, but supply no actual formulated-theory instance. Condition 2 requires content-dependent decisions, not delivery alone; those decisions are unobserved. Condition 3 requires stated content-directed criticism and changed reliance or revision; a requested advisory review does not establish it. Condition 4 requires the criticism's result to shape another round; retained revision metadata alone does not show that sequence. There is likewise no evidence that criticism of a consumed theory improved future capacity. Reflection's two causal directions through a self-representation are not established, and external host role assignments do not establish autonomous performance of every internal theory-building operation. These conclusions follow the separate evidential limits in the epistemic bounded conclusion, not an inference from opaque model processing.
For self-improvement, the relevant potential boundary is the shipped memory loop across later coding invocations, with preservation of existing behavior as the declared objective. Retained explanations can enter its behavior-shaping organization; they are not excluded merely because they are outputs. Nevertheless, no exercised pathway links objective-bearing evidence to a determined update, that update to later live reliance, and subsequent operation causally dependent on it. Installation changes instructions but is not an evidence-responsive improvement demonstration; repair process success closes none of those missing links. Successful self-improvement and improved capacity therefore remain unestablished independently of wired trace-fed retention (EPI-CLM-loop-protection, RT-BAP-memory-consumption, RT-RTE-agent-repair, epistemic bounded conclusion).
For the scenario of making a code change while preserving recorded reasons, the implemented contribution is inspectable path-selected explanation delivery plus conditional mechanical maintenance pressure. The evidence does not support a general guarantee that agents read those reasons, preserve behavior or keep prose true. A trace connecting retrieved content, the resulting edit, semantic review, retained correction and later reliance would change the operation assessment. A controlled regression comparison would be needed for protective benefit. Universal admission or repaired-state guarantees would instead require changed enforcement coverage and post-repair checking, not merely more observations of the ordinary branch (EPI-CLM-pin-match, EPI-CLM-loop-protection, report verification).
Limitations
| Limitation | Affected SRC IDs and record citations | Inspected boundary | Conclusion prevented | Evidence that would resolve it |
|---|---|---|---|---|
| Cross-shard identity collision can yield different consumer resolutions; no collision instance is supplied. This is the report verifier's retained limit. | SRC-1; RT-OBJ-concept-frontmatter, RT-RTE-context-read, RT-RTE-memory-write, MEM-RTE-concept-read; verification limit | Shard-relative identity derivation, last-loaded retrieval dictionary and first-match direct reads/writes | Global identity uniqueness or consistent cross-shard resolution | A common qualified-identity/uniqueness contract enforced across these consumers; collision evidence to establish actual incidence |
| Implementation and instructions are not evidence of exercised compliance or benefit. | SRC-1; RT-RTE-coding-loop, RT-BAP-memory-consumption, EPI-CLM-loop-protection | Frozen shipped loop; no observed-run or causal layer | Successful delivery, changed coding decisions, anti-regression benefit or improved future capacity | Linked consuming-repository traces and outcome comparisons with an appropriate contrast |
| Mechanical attachment and admission do not validate explanation semantics. | SRC-1; RT-RTE-memory-write, EPI-RTE-claim-check, EPI-RTE-relocation-check, EPI-RTE-semantic-review | Gate, liveness, relocation and advisory review consumers | Pin success as proof of true why, accepted ampliative knowledge or semantic continuity | Candidate-level evidence, semantic evaluation and an evidence-consuming acceptance decision for a named use and scope |
| Enforcement depends on route, posture, exemption and external invocation; staged validation reads working-tree source. | SRC-1; RT-RTE-validate-change, RT-BAP-check-enforcement | CLI/MCP, packaged hook and Action configuration | Universal denial, exact staged-snapshot attestation or deployed merge protection | Source-snapshot-consistent checking, complete route coverage and deployment evidence for the asserted policy |
| Initial provenance, actual child repair and host/provider behavior remain unresolved. | SRC-1; EPI-RTE-bootstrap-import, RT-RTE-agent-repair, RT-CMP-coding-agent | Known local import/write routes and subprocess interface; external internals excluded | Complete authorship, admission, transformation or model-parameter learning inventory; certified repair | Provenance-linked content and child traces, post-child validation, and separately scoped host/provider evidence |
| No actual theory-use/criticism/iteration or exercised self-improvement chain is supplied. | SRC-1; RT-OBJ-concept-body, RT-BAP-memory-consumption, EPI-RTE-semantic-review, RT-RTE-agent-repair | Shipped authoring, consumption, review and repair mechanisms | Established theory-builder conditions, reflection, autonomous theory building, criticism-induced capacity improvement or exercised self-improvement | Localized theory instances and decision/criticism/next-round records; self-representation causal paths; role evidence; causally linked later operation and separate outcome evidence |
No additional frozen-source reads were needed for this synthesis. The supplied reconciliation reports no unresolved cross-report conflict; profile verification declares no additional limit. Neither statement removes the bounded uncertainties above.