kgai synthesis
Type: agentic-system-analyses/types/agentic-system-synthesis.md
Bounded synthesis
kgai is a decision-memory system for AI-assisted development. It records acted-on structural choices, their reasons and changes to a domain graph, then exposes those records before later work. This account covers the shipped engine, model-facing instructions, lifecycle hooks, optional side-model capture, synchronization clients and editor reader at commit 0ac7f1fae4528805c1d5f504c1bfd6cc34ac953b, with an analysis cutoff of 2026-10-14. Evidence is SRC-1 implementation, doctrine/design and attributed operation in the frozen repository. No target execution, observed run or causal experiment establishes successful capture or benefit. External coding hosts, model providers, native database internals and remote services are not part of the inspected implementation (boundary, Source register).
From a coding task to a retained decision
The host agent owns the coding task, tools, context window and next model step. kgai supplies a skill that asks it to recall prior decisions before nontrivial changes and respect or deliberately supersede them. The foreground model is the semantic layer: it chooses vocabulary for lexical recall and decides which structural choices merit capture. Routine skill/review capture requests no confirmation; the explicit decision command instead asks the user to confirm a proposal. These are model-facing policies, not engine-side semantic or consent guarantees (RT-OBJ-knowledge-graph, RT-RTE-foreground-capture).
Session hooks install/check the engine, attempt synchronization, inject approved capture conventions and track edits or recording. A Stop hook can nudge an eligible agent to record, but its markers do not prove a durable write: the classic classifier can treat a requested ingest, including a dry run or failed command, as recording. Project configuration has a separate gate. Allowed-setting fingerprints enable approved project values; equivalent configurations inherit approval. The registry does not authenticate human consent. Convention text reaches model context, while a store setting selects the read/write destination (RT-RTE-config-admission, RT-OBJ-trusted, MEM-OBJ-prompt). Upstream byte truncation and downstream shell slicing mean even raw convention reload need not reproduce the authored file (report-verification limits).
The engine accepts titled decisions and typed mutations, resolves references, computes authority and supersession, locks managed writes, appends events to an installation-specific log and applies them to the graph. It rejects covered schema/identity errors, but permits empty rationale and warns rather than rejects when no element is attached. These checks establish operational admissibility, not truth or structural importance. Append precedes projection; a later failure can leave a retained prefix requiring rebuild, not an all-or-nothing batch (RT-RTE-foreground-capture, MEM-OBJ-event).
Natural-language titles and rationales inform later models or humans. Symbolic mutations and authority fields determine graph state and current decision heads independently of reason quality. A new authority-bearing decision supersedes heads; a bare upsert of an existing element can attach provenance without taking authority. Link retirement changes live structure but preserves history. Correction therefore need not erase an old reason, and supersession is not confidentiality withdrawal (MEM-OBJ-decision, MEM-OBJ-graph, EPI-OBJ-decision-mutations).
The optional capture workflow has its own completion boundary
The representative multi-step workflow is the optional mod's end-of-turn capture path. After a foreground answer with counted successful edits and no recording mark, code calls a side model with structural selection criteria. Shell-only edits do not enter this mod's edit counter. The external host supplies the copied context; the exact payload and no-tools isolation are not locally established. The side answer is not appended to the foreground transcript. UI hiding of successful tool rows is a separate display operation, not demonstrated model-context trimming (RT-RTE-fork-capture, workflow account).
The side model returns NONE or proposed JSON. Parsing and engine dry-run can reject invalid proposals, not false reasons. Auto mode proceeds to real ingest. Confirm mode offers Record/Skip only on terminal/desktop surfaces; elsewhere it falls back to automatic admission. Dry-run and real ingest are separate calls, so validation does not reserve an unchanged store or guarantee the write. Drawn sessions schedule capture after foreground completion; headless sessions await the check. Pending confirmation is not persistence, and a success announcement can report an already-present decision rather than a fresh event. Failures produce diagnostics, not an automatic retry or rebuild. The coding answer, proposal and durable capture are three distinct outcomes (RT-RTE-fork-capture, workflow annotations).
Later recall selects less than the retained history
The log is authoritative retained memory; Kuzu is a rebuildable graph projection, while the editor builds a separate in-memory projection. Context recall defaults to 15 elements and delivers at most four current head reasons per element. Search defaults to 20 hits. Context/search rationales are shortened above 160 bytes; full history or editor decision detail can return the whole rationale. Historical and provenance-only text may influence element ranking without appearing in delivered head reasons. Recency can cross the context inclusion threshold without topic/path overlap. Neither a filtered result nor retained full text guarantees complete relevant explanation at the model consumer (MEM-RTE-context-recall, MEM-RTE-search-history, RT-RTE-editor-read).
The inspected abbreviation can omit a scope condition. That is a source-derived countercase, not a measured retrieval failure. Full-history access is a separate recovery call, not automatic restoration. Decision recall is requested delivery; SessionStart automatically supplies conventions, not task-sensitive decision history. As-of reads reconstruct old recorded structure without rationale. Count and text limits are not a total model-token budget (EPI-RTE-recall-shaping, MEM-RTE-asof-recall, MEM-OBJ-prompt).
Synchronization imports decisions without per-reason human approval and can create competing heads. Engine replay and object synchronization apply integrity checks, but the editor lacks the engine's event-hash and decision-ID gate; AsOf checks event hashes only. Hash consistency does not authenticate an author's evidence or make a rationale true. Conflict detection lists multiple authoritative unsuperseded heads on one element, not contradictions in meaning: compatible concurrent properties can be flagged, while contradictory reasons on different elements can escape. Resolution is a model/user choice followed by a new authority-bearing decision (RT-RTE-team-sync, EPI-RTE-branch-check).
What the loop supports, and what would change the assessment
For retaining and revisiting recorded engineering choices, kgai has connected producer, persistence, revision and later-consumer paths. For recovering every relevant qualification before a change, its ordinary recall is insufficient as a guarantee: capture completeness, lexical selection, head eligibility and abbreviation each constrain delivery. For evaluating explanations or detecting semantic contradictions, its schema, hash and head-count checks assess different targets. The README's full-story, semantic-conflict and avoided-dead-end claims therefore exceed what these routes establish (EPI-CLM-full-story, EPI-CLM-semantic-conflicts, EPI-CLM-dead-ends). No evidence-consuming truth acceptance followed by knowledge lifecycle integration was established in the inspected capture, conflict, recall and diagnostic paths; unassessed evaluators prevent a system-complete negative.
The strongest supported learning-related contribution is an automatic experience-to-decision path in the optional auto/headless fork, with durable reasons and wired later readers. This is trace learning in the write-route sense, not demonstrated improved capacity. Exact original trace inputs remain indeterminate. Foreground capture offers a weaker, instructed experience-retention path. Live mutation and supersession revise current memory, but do not by themselves establish improvement. The partial curation inventory also omits a separate wired classification of recall consolidation; that limits transformation comparisons, not the existence of clipped recall (RT-RTE-fork-capture, MEM-OBJ-event, profile verification, profile-verification limits).
A theory builder formulates explanations, makes decisions depend on their content, criticizes that content and retains criticism's result for another round. The foreground route's separate assessments are: condition 1, localized explanation, afforded; condition 2, content-dependent consumption, claimed; condition 3, content-directed criticism, afforded; condition 4, criticism-shaped iteration, afforded. Rationale and successor decisions provide expressive capacity; they do not establish exercised criticism. Improved future capacity from criticism of a consumed theory remains uninspected. Reflection is afforded at the consuming project's structural self-description, not demonstrated criticism of kgai's capture method. Reflective and autonomous theory building remain uninspected; automatic capture does not establish every internal theory operation (RT-RTE-foreground-capture).
Exercised self-improvement of kgai's own operation is likewise unestablished at this boundary. Retained reasons can reach later behavior, but the records do not close a causal chain from objective-relevant criticism to a change in kgai's own behavior-determining organization and subsequent dependent operation. Installation replaces executable capability, not a demonstrated improvement selected from decision experience (RT-BAP-decision-recall, RT-RTE-engine-install). This leaves the positive memory pathway intact without attributing successful learning, reflection or autonomy to it.
Grounded traces linking task inputs, capture, stored decisions, delivered reasons and subsequent actions would establish exercised paths and resolve trace origin. A controlled comparison independently varying recall or capture would be needed to attribute benefit to that component. Evidence-consuming evaluation of named engineering claims would change the truth-acceptance assessment; a semantic comparison predicate would change the conflict assessment. Full-reason delivery with tested selection coverage would change recall completeness. The existing smoke harness checks one-versus-zero decision counts for structural versus trivial tasks, not rationale truth, downstream action or component effect; no results are supplied (EPI-RTE-capture-evaluation).
Limitations
| Limitation | Affected SRC IDs and record citations | Inspected boundary | Conclusion prevented | Evidence that would resolve it |
|---|---|---|---|---|
| Implementation is not observed operation or benefit | SRC-1; RT-RTE-foreground-capture, RT-RTE-fork-capture, EPI-RTE-capture-evaluation | Frozen source, instructions and evaluator design; no target run | Successful capture, model compliance, later behavioral dependence, improved capacity and causal component benefit | Grounded end-to-end traces and objective-relative comparisons with independent component variation |
| Host/provider state and copied fork inputs are opaque | SRC-1; RT-CMP-host-model, RT-RTE-fork-capture | Shipped host API call and prompt, not host/provider implementation | Exact trace-source classification, complete memory inventory, model fixity/learning and deployed fork isolation | Pinned host/provider contracts and inspectable copied inputs, retention/update routes and execution evidence |
| Upstream convention truncation is omitted from the recorded transformation inventory | SRC-1; MEM-OBJ-prompt, RT-RTE-config-admission; report limit | Settings-layer UTF-8-boundary byte truncation before effective selection, followed by shell injection cap | Complete raw authored-text reload, shell-only cap, exact 8000-byte total ceiling or token budget | Corrected transformation records covering layer truncation, appended marker, raw return and injection |
| Replay equality and coherent concurrent snapshots are not demonstrated | SRC-1; MEM-OBJ-graph, MEM-RTE-asof-recall, RT-RTE-editor-read; report limit | Engine, bulk/shared replay dependency, historical filtering and reader reload | Universal equality of projection fields across all inputs/consumers, uniform integrity admission or coherent concurrent-file snapshots | Executed equivalence and concurrency tests covering fields, malformed/tampered inputs and distinct consumer gates |
| Transport, platform and evaluator inventories are bounded | SRC-1; RT-RTE-team-sync, RT-RTE-engine-install, EPI-RTE-capture-evaluation; report limit | Object/Git safeguards and selected installer/evaluator paths; full cloud/S3, platform branches and other tests not traced | Transport-wide security/availability, installation compatibility and system-complete evaluator or truth-acceptance negatives | Full material branch inspection plus relevant execution evidence and external-service contracts |
| Recall consolidation is omitted as a distinct wired curation unit | SRC-1; EPI-RTE-recall-shaping, MEM-RTE-context-recall, MEM-RTE-search-history; profile limit | Implemented head selection and rationale reduction; curation axis is partial | Complete transformation inventory or consolidation-wiring comparisons; faithfulness is separately not guaranteed | Revised unit classification retaining wired reduction and qualifier-loss uncertainty; union values need not change |
| Semantic warrant and recall completeness remain local, not universal | SRC-1; MEM-OBJ-decision, EPI-RTE-recall-shaping, EPI-RTE-branch-check | Caller reasons, typed admission, head-count conflicts and shortened demand recall | Truth of reasons, semantic-conflict equivalence, complete explanatory delivery and guaranteed avoidance of failed approaches | Provenance-grounded claims, scoped evidence-consuming acceptance, semantic evaluation and delivery/behavior traces |
| Consent and installed capability are not established by local approval/readiness alone | SRC-1; RT-RTE-config-admission, RT-RTE-engine-install | Fingerprint approval, CLI trust, mutable release endpoint and optional checksum/readiness checks | Authenticated human approval, prompt-injection immunity, exact deployed pin or host-wide isolation | Authenticated admission records, verified installed bytes and deployed permission/enforcement evidence |
| Revision capacity does not establish exercised theory building or self-improvement | SRC-1; RT-RTE-foreground-capture, RT-BAP-decision-recall | Retained reasons, supersession and later consumers; no objective-relative criticism/update/use trace | Criticism-improved future capacity, exercised reflection, autonomous theory building or exercised self-improvement of kgai | Records linking challenged explanation, evidence, blame, revision and next-round dependence; for self-improvement, objective-relevant update to kgai's own organization and causally dependent subsequent operation |