EchoesVault for OpenCode memory report

Type: agentic-system-analyses/types/agentic-system-memory-report.md

Boundary and evidence

This report covers the whole shipped memory loop within the supplied boundary: portable CLI, OpenCode tools and command hooks, generated agent instructions, durable Markdown, derived index, migration, restoration, search, and health/display metadata. It excludes host model internals, host context compaction, arbitrary future compatible project runtimes, and unsupplied deployed vaults. Those exclusions prevent conclusions about actual model consumption, complete trace provenance, deployed code identity or memory benefit. They do not prevent tracing the frozen implementation's admission and delivery mechanisms.

Evidence is SRC-1, implementation and doctrine/design only. Direct reads covered index.ts, runtime.ts, tui.tsx, README.md, prompts/commands/echoes-end.md, and the generated instructions, path/state definitions, metadata/index/migration functions, health aggregation, writer/reader handlers, parser, delegation and dispatch in scripts/echoes_vault.py. Other runtime guarantees below explicitly rely on supplied records, rather than claiming fresh inspection of every implementation detail. HEAD was rechecked against the full frozen revision. No target code or tests were executed.

Entry point or operation	Source paths	Coverage and conclusion limits
Plugin command configuration, lifecycle event hook, all nine registered tools	index.ts, runtime.ts	Direct reads; supplied RT-RTE-context-restore, RT-RTE-page-upsert, RT-RTE-daily-append, RT-RTE-session-save. No autonomous conversation-capture hook appears in this inspected registration.
CLI init/migrate/upgrade/configure-agents; generated commands, skills and root guides	scripts/echoes_vault.py	Direct template/dispatch/delegation reads plus supplied RT-RTE-runtime-install; MEM-RTE-summary-migration. Actual cross-host loading unobserved.
Append, upsert, end; legacy indexDescription payload	scripts/echoes_vault.py, prompts/commands/echoes-end.md	Direct handlers; annotations below. Semantic admission remains caller/model judgment.
Start and search; host-directed complete-page reads	scripts/echoes_vault.py, index.ts	Direct code and generated reading guidance; RT-RTE-context-restore. Complete-file reads are afforded by host tools, not performed by search.
Hash, hydrate, rebuild-index	scripts/echoes_vault.py	Direct handlers; MEM-OBJ-index, MEM-OBJ-page-metadata. Hash is replacement metadata, not semantic verification.
Inspect/status/protocol; TUI polling	scripts/echoes_vault.py, tui.tsx	Direct health aggregation, dispatch and TUI; MEM-RTE-health-report, MEM-OBJ-local-state. No retained semantic evaluation judgment established.
Raw sources, assets, legacy daily files, existing pages	README.md, scripts/echoes_vault.py	MEM-OBJ-source-material, MEM-OBJ-daily, MEM-OBJ-page-body. Initial authorship/import control is unresolved for preexisting files; no dedicated raw-ingestion consumer found in inspected dispatch.
Lock, atomic replacement, runtime trust; tests	scripts/echoes_vault.py, tests/runtime.test.ts	Supplied runtime integrity account and boundary coverage only for lock internals/tests. Tests not independently read or run here; neither passing tests nor transactional saves is inferred.

Core ideas

The system separates authored knowledge from its discovery view. Page bodies hold potentially explanatory project knowledge; their short authored summaries become an automatically regenerated index. The engine does not summarize bodies to create those summaries. It checks representation and concurrency, not whether a claim is verified. Daily entries are caller-written intermediate notes or session distillations, not automatically captured raw conversations (MEM-OBJ-page-body, MEM-OBJ-page-metadata, MEM-OBJ-daily).

Restoration is a requested reload, not an unsolicited push: a user starts the workflow, code returns the entire index and a filename-selected recent subset of daily files, and the foreground agent can search for details. Three files is a count budget, not a token budget. Search is literal line retrieval, not semantic ranking. These distinctions qualify the README's small-context framing without disputing its omission of full page bodies (RT-RTE-context-restore; SRC-1, README.md, scripts/echoes_vault.py).

Source trust has two distinct consumers. The host receives project text as data; the interpreter executes the installed Python runtime with process authority. Static generated guides instruct future agents but are not experience-derived memory. A compatible runtime version is a delegation condition, not cryptographic identity. These paths should not be merged into one authority classification (RT-BAP-project-context, RT-BAP-agent-guidance, RT-BAP-project-runtime).

Shared records

Components

none declared in this member

Operative objects

MEM-OBJ-page-body

Label: Page body

Source-native identity: body of EchoesVault/pages/*.md, natural-language Markdown on the local filesystem. This is the content part of a complete knowledge page, distinct from the summary and status fields below. Closest supplied record is the write route RT-RTE-page-upsert, not an object counterpart. Whole-page replacement addresses the body; sections, reasons and claims are not separately managed by the writer. Bodies may contain decisions and explanations, but neither their accuracy nor retention of reasons is mechanically required. Initial content can predate initialization; later upsert/end proposals come from a caller, ordinarily the host agent following distillation guidance. Caller identity alone does not resolve human authorship or approval.

Consumers are literal search (text matching), then host-directed full-page reads (interpretation). Index generation validates the whole page but does not expose the body. Authority at the host is project knowledge, not executable policy; changed reliance is unobserved. SRC-1, scripts/echoes_vault.py, prompts/commands/echoes-end.md.

Prepare only durable knowledge pages that add or materially revise reusable project knowledge. --- prompts/commands/echoes-end.md

MEM-OBJ-page-metadata

Label: Page frontmatter

Source-native identity: type, stack, status, summary frontmatter in the same page files. Storage is local Markdown. Operative form is mixed: required-key presence and deprecated-status equality are symbolic parser inputs; summary is authored natural language subsequently interpreted by agents. This object is distinct from page body and from the generated index; no supplied object counterpart exists. Closest supplied admission route is RT-RTE-page-upsert.

Lineage: caller supplies fields; prepare_page can inject a supplied legacy indexDescription if summary is missing, or reject disagreement when both exist. Migration can copy a preexisting index description. Normalize_summary collapses whitespace and enforces one line and 160 characters; it does not derive meaning from the body. Parser requires stack presence but does not assign retrieval priority from stack/type. Existing-content SHA-256 is an ephemeral concurrency token returned by hash and consumed by replacement checks, not a quality score or authenticated author identity. SRC-1, scripts/echoes_vault.py.

if legacy_summary != metadata["summary"]: raise EchoesError( f"indexDescription conflicts with frontmatter summary for {filename}." ) --- scripts/echoes_vault.py

MEM-OBJ-index

Label: Generated index

Source-native identity: ignored EchoesVault/index.md, filesystem Markdown derived from current validated immediate page files. Its links are symbolic display identifiers; its descriptions are natural-language summaries. Unlike MEM-OBJ-page-metadata, it is a disposable view, not the authored source. Closest supplied record is RT-RTE-context-restore, a consumer route rather than this object.

Lineage: stable page ordering, normalized slugs and copied summary text, with a deprecated prefix when needed. It includes all valid pages, not task-selected bodies, rationale, evaluation histories or semantic embeddings. Start delivers it to the host as discovery context. Hydrate/rebuild/start and successful page writes regenerate it; invalid pages can prevent regeneration. A page can carry important reasons absent from its summary, so index delivery alone does not deliver those reasons. SRC-1, scripts/echoes_vault.py.

if metadata["status"] == "deprecated" and not summary.casefold().startswith("deprecated"): summary = f"DEPRECATED — {summary}" rows.append((stable_path_key(page), f"- [[{slug}]]: {summary}")) --- scripts/echoes_vault.py

MEM-OBJ-daily

Label: Daily entries

Source-native identity: Markdown files under EchoesVault/daily/**/*.md, including legacy flat files and newly generated unique UTC-path entries. Natural-language content is stored on the filesystem with symbolic filename/header and optional agent-label metadata. Closest supplied records RT-RTE-daily-append and RT-RTE-session-save are producers, not duplicate objects.

Append preserves the submitted entry after trimming, adding a Scratchpad header; end similarly wraps dailySummary in a Session header. They are opaque caller-authored payloads to the engine, though directly readable, not opaque binary checkpoints. The requested lineage is session experience → agent distillation → retained note, but no automatic extraction from the host transcript verifies that lineage. Legacy origin remains unresolved. Later start consumes complete selected files, irrespective of scratchpad versus final kind. Older files remain reachable on disk when they fall outside selection. Actual behavioral authority comes through later host interpretation, not through headers or agent labels. SRC-1, scripts/echoes_vault.py; distillation guidance is quoted in RT-CMP-host-model.

name = ( f"{moment.strftime('%Y%m%dT%H%M%S%f')}Z-{kind}{agent_part}-" f"{secrets.token_hex(4)}.md" ) --- scripts/echoes_vault.py

MEM-OBJ-local-state

Label: Local session state

Source-native identity: ignored .echoes-vault/state.json, symbolic JSON on the filesystem. It contains session started/saved flags and times, current counters, versions and last-writer metadata, not retained knowledge bodies or model state. Read_state falls back to old OpenCode/Codex state files, normalizes selected fields and defaults otherwise. Write_state refreshes counters from health. Closest supplied records are RT-RTE-context-restore and RT-RTE-session-save, which mutate it, not object counterparts.

Later maintenance calls read it, and TUI polls it and the marker every three seconds. Its authority is status presentation and command suggestion; the marker and runtime checks, not the displayed saved flag, govern initialized/compatible operation. A saved label is not a retained verification result about factual quality. It may describe the last save even after subsequent knowledge writes. SRC-1, scripts/echoes_vault.py, tui.tsx.

if (state()?.session.saved) return "Memory Saved" if (state()?.session.started) return "Active" --- tui.tsx

MEM-OBJ-source-material

Label: Raw sources and assets

Source-native identities: EchoesVault/raw/ and EchoesVault/assets/, local filesystem containers prescribed for source material and referenced assets. Their payload encodings and initial producers are unresolved; Markdown links and image syntax are natural-language-document references interpreted by host tools. These are distinct from pages, daily entries and RT-OBJ-agent-protocol. The latter prescribes their role but is not their content.

Known consumer boundary: inspected start/search/index handlers read pages and daily files, not raw/asset bodies. Health checks inventory structure and files; generated protocol affords asset references. There is no dedicated admission/import/read-back operation for these contents in inspected dispatch. This limits conclusions about raw-to-derived provenance, validation and consumer authority; it does not establish that agents cannot independently read or write them. SRC-1, README.md, scripts/echoes_vault.py.

Use [[page-slug]] for knowledge links and ![[asset.png]] for files in EchoesVault/assets/. --- scripts/echoes_vault.py

Routes

MEM-RTE-summary-migration

Label: Legacy summary migration Part of: RT-RTE-runtime-install

This is the content-migration subroute of installation, not a second declaration of all executable/adapter installation. Init/migrate/upgrade dispatch to cmd_init, whose refresh_index permits migration. Engine owns transformation/admission: existing page lacking summary + unique legacy index description → validated injected frontmatter → rebuilt index → later start. Existing summaries remain unchanged. No new model call or answer oracle selects wording; caller initiates maintenance, but per-description human approval is not wired. Mode is caller-directed maintenance. Proposed change is copying existing text, not knowledge synthesis. Errors reject missing/invalid descriptions, invalid page format and colliding page names before the migration write loop. Atomic per-page replacement is not batch rollback; recovery requires valid source correction and retry. SRC-1, scripts/echoes_vault.py.

• Immediate return: migrated page names in indexRefresh, or metadata error.
• Later read-back: injected summary persists in pages, subsequently enters generated index and later start output.
• Delegated visibility: shared durable pages expose copied text to authorized agents/clones; generated index remains local.
• Selection predicate: immediate pages without summary, matched by exact stem to an unambiguous legacy index entry; all existing summary-bearing pages bypass copying.
• Invalidation or expiry: later page replacement can revise summary; no expiry or automatic backup.
• Activation or effect: changes retained metadata and discovery text, not evidence of changed host reasoning.
• Evidence limits: initial legacy-description authorship/truth unresolved; actual migrations unobserved; no semantic evaluation.
• implementation conclusion status: wired
• operation conclusion status: uninspected

summary = normalize_summary(description, page.stem) migrations.append((page, inject_summary(normalized, summary))) --- scripts/echoes_vault.py

MEM-RTE-health-report

Label: Health reporting and display

This route is distinct from supplied mutation/restoration routes: inspect/status derive structural health; TUI independently polls retained metadata. Engine owns mechanical diagnosis; operator/host chooses any subsequent repair. Checks include frontmatter validity, conflicts, missing/stale index entries, structure, adapters, runtime, Git readiness and scale. Guidance comes from protocol/format rules, not reference answers for saved claims. Mode is requested inspection plus periodic display, not candidate experimentation. Neither diagnosis nor the display admits revised knowledge. SRC-1, scripts/echoes_vault.py, tui.tsx.

• Immediate return: JSON/card health for inspect/status; TUI presents session labels, page/daily counts and suggested lifecycle command.
• Later read-back: TUI later polls persisted marker/state; inspection reads current files and state, but its diagnostic result is not itself saved as a semantic judgment.
• Delegated visibility: host receives card/JSON; UI user receives metadata display; no automatic transfer of a private transcript.
• Selection predicate: requested workspace paths for checks; TUI selects marker/state fields every three seconds, not task-relevant knowledge.
• Invalidation or expiry: next inspection recomputes health; TUI next poll replaces snapshot. Stored flags/counters persist until later writer refresh.
• Activation or effect: display/diagnostic output, not automatic page rejection, cleanup or semantic repair.
• Evidence limits: structural healthy/saved labels do not establish truth, useful retrieval, durability across a partial save, or actual operator response.
• implementation conclusion status: wired
• operation conclusion status: uninspected

"integrity": "healthy" if issue_count == 0 and state_health["valid"] else "attention", --- scripts/echoes_vault.py

Claims

none declared in this member

Evidenced absences

none declared in this member

Behavioral-authority paths

none declared in this member

Annotations

On RT-RTE-context-restore

Memory-specific selection: start emits all generated summary/link rows plus entire selected daily files. It does not filter out deprecated pages or prefer final entries over scratchpads. Recent is reverse lexical relative-path order, not parsed timestamps. Legacy flat paths can therefore coexist with UTC directory paths without a universal chronological guarantee. Search scans immediate page lines, including metadata, in stable file/line order. Default limit is 100, clamp 1–500, each match display at most 300 characters; matched full lines determine inclusion before display truncation. It does not search raw/assets/daily or automatically open a relevant complete page. SRC-1, scripts/echoes_vault.py.

"text": line.strip()[:300], --- scripts/echoes_vault.py

The user/agent requests restoration/search; automatic selection happens inside that request. There is no independent memory push established by this registration. Index is unbounded in total length, selected daily files have no size cap, and scaleAlert adds advice rather than truncation. This keeps page bodies out initially and affords later reload; it does not remove old conversation turns or isolate a sub-agent frame. Returned content enters context by value, not an automatically dereferenced pointer. Host context/window construction and compaction remain uninspected. SRC-1, index.ts, scripts/echoes_vault.py; the supplied route quotes its project-data authority boundary.

On RT-RTE-page-upsert

Write agency is caller proposal followed by deterministic software admission. The caller can create/replace at any time through the registered tool without lifecycle grant. Physical writing by Python does not establish human selection or semantic endorsement. Summary normalization and legacy indexDescription injection are known transformations, while initial page provenance may be unknown. Code does not demand evidence citations or retain a predecessor/reason-for-change record. Reasons survive only if included in submitted text. Later full-body readers can see them; index-only consumers cannot. SRC-1, index.ts, scripts/echoes_vault.py; MEM-OBJ-page-body, MEM-OBJ-page-metadata.

On RT-RTE-daily-append

An append is an explicitly supplied note, not engine trace capture. The stored header/agent attribution and trimmed note preserve the supplied payload, not the original host conversation or independent evidence. It can later occupy one recent-entry slot regardless of finalization status. No semantic curation is performed after submission. SRC-1, scripts/echoes_vault.py; MEM-OBJ-daily.

On RT-RTE-session-save

The prompt requests a trace-fed transformation: current session → model-authored dense final summary and reusable page revisions → daily/page persistence → future start/search/file reads. The engine receives only proposed products, not the underlying conversation, and cannot establish that the requested verification or distillation occurred. The user starts finalization, not per-claim approval. There is no supplied operation evidence of improved future capacity. The stored product can carry reasons or criticism in prose, but retained rationale and subsequent reliance are content-dependent, not guaranteed by the page/log format. SRC-1, prompts/commands/echoes-end.md, scripts/echoes_vault.py; the supplied route distinguishes CLI confirmation from host-gated initiation.

On RT-OBJ-agent-protocol

Static guidance prescribes deprecation instead of deletion, body warning/replacement link, durable knowledge instead of transcripts, and reread/reconcile/hash/retry. These instructions shape proposals but are not themselves derived from accumulated session traces. Symbolic status handling only adds the index prefix and health count: it does not verify a replacement link, suppress the old page from search, or force a reader to follow the link. SRC-1, scripts/echoes_vault.py.

Deprecate instead of deleting. Use status: deprecated, a warning in the body, and a link to the replacement. --- scripts/echoes_vault.py

Write side

Admission differs by surface. Page creation/replacement and end page batches use safe names, frontmatter/summary checks, conflict checks, prospective complete-index validation and existing-file hashes. Append and final dailySummary require nonempty strings but do not mechanically verify facts. Neither ungated upsert/append nor CLI-supplied confirmation requires human content approval. Generated instruction/runtime installation has separate ownership/version checks; it is not learned semantic content. Raw/assets initialization and later human-versus-agent control are unresolved, while subsequent page normalization, summary copying and index derivation are inspectable (RT-RTE-page-upsert, RT-RTE-daily-append, RT-RTE-session-save, RT-RTE-runtime-install, MEM-RTE-summary-migration).

Maintenance rebuilds the disposable index/state rather than learning from health outcomes. Status evaluates structure without retaining a new judgment or automatically editing knowledge. Deprecation is admitted as ordinary page replacement: obsolete content remains physically present and searchable, with an index warning. Rejection returns an error, not a durable rejected-candidate archive. Partial file writes can survive a later failure; reread/reconcile/retry and hydrate/rebuild are recovery affordances, not predecessor rollback. SRC-1, scripts/echoes_vault.py; supplied integrity account in RT-RTE-page-upsert; MEM-RTE-health-report.

Within the inspected CLI dispatch/tool surface there is no dedicated prune/delete/automatic archive or conversation-checkpoint operation. This is a bounded surface finding, not a claim that host filesystem edits are impossible. Daily notes can remain indefinitely while falling outside recent selection. Host compaction or alternative provider checkpoints are outside the frozen implementation evidence. The qualifying session-to-memory chain is requested foreground-agent distillation, not an implemented background trace-learning model. Persistence and editable text are established; improved capacity, content-directed criticism and actual later behavioral adoption are not inferred from those facts.

Read-back

The principal later consumer is the enclosing host agent. On start, Python automatically selects the full generated index and requested count of recent daily files and delivers text through stdout/tool output or generated command substitution. On search, the agent supplies a query and code returns literal line matches; generated guidance affords full-page reading and following replacement links. Search result paths are targeting aids, not proof of those reads. Pages can therefore reach later consumers either as summaries or selected body snippets/full text, with different retained reasons at each channel. SRC-1, scripts/echoes_vault.py, index.ts; RT-RTE-context-restore.

A second later consumer is the TUI/status operator reading access/session metadata, not project knowledge; a third is the interpreter executing installed code. Neither is evidence that a model adopted saved content. Static generated guides remain procedural authority through host loading, separate from accumulated-use read-back. Raw/assets retain only a documented reference affordance within this inspected loop, not a wired targeted consumer route (MEM-RTE-health-report, RT-BAP-project-runtime, RT-BAP-agent-guidance, MEM-OBJ-source-material).

Integration issues

• No correction to supplied runtime facts is required. Its filename-order, byte-budget, semantic-admission, path-local authorization and runtime-trust limits survive direct countercase inspection. The generated local start template does not repeat the bundled prompt's explicit project-data warning, so do not generalize that wording to all adapters; authority remains host-mediated, not enforced by Python. SRC-1, scripts/echoes_vault.py; RT-BAP-project-context, RT-RTE-context-restore.
• MEM-RTE-summary-migration explicitly declares a part of installation, not a duplicate of RT-RTE-runtime-install. New object records describe artifacts rather than supplied producer/consumer routes. MEM-RTE-health-report separates diagnosis/display from those mutation routes. No other possible duplicate found after comparison with supplied runtime declarations.
• Initial page/daily/raw/asset provenance, human approval per invocation and correctness of legacy descriptions remain unresolved. This prevents complete trace-origin or semantic-control classification; known later transformations must not be erased by that uncertainty (MEM-OBJ-page-body, MEM-OBJ-daily, MEM-OBJ-source-material, MEM-RTE-summary-migration).
• Actual full-page reads, retained rationale, successful deprecation following and changed future decisions remain unobserved. Content delivery and a request to distill verified decisions cannot establish those outcomes (RT-RTE-context-restore, RT-RTE-session-save, RT-OBJ-agent-protocol).

Limitations and checks

The frozen Git HEAD matched 875c45aa45559529b87a7481b0c21e6dfd8c5eb0; source identity and report identity match the supplied boundary/invocation. Source-native dispatch and all registered tools were checked against the supplied runtime routes, including summary compatibility input, legacy migration, health/display, raw/assets and direct/generated CLI alternatives. No other repository, run evidence or external service was introduced. Method scope was rechecked against the supplied member type, worker rules and shared records contract. No target executions, dependency installations or tests were performed.

The evidence supports implementation wiring and procedural affordances, not deployed activation, reliable instruction following, saved-claim truth or improved memory performance. Initial retained content and external host/provider state remain local unknowns. Deterministic validation: the invocation's validate-output command passed (exit 0): “Member content check passes; invocation residue not checked. This is not job acceptance or claim support.” This establishes neither semantic acceptance nor operational success.