psinetron/echoes-vault-codex/echoes-vault

EchoesVault memory operations

Keep durable project knowledge in <workspace>/EchoesVault/. Resolve <workspace> as the Git root when one exists, otherwise the current working directory. Resolve <plugin-root> as the parent of the skills/ directory that contains this SKILL.md. Use <plugin-root>/scripts/echoes_vault.py as <launcher>. It delegates execution to a compatible project runtime, recovers a missing runtime for an initialized vault, refuses an outdated runtime until explicit upgrade, and never downgrades a newer one.

Run the deterministic storage CLI with:

python3 <launcher> --workspace <workspace> \
  --agent codex --adapter-version 1.1.1 <command>

Pass write payloads as JSON through stdin (--payload -) or a temporary JSON file. Do not interpolate untrusted Markdown into a shell command.

Core rules

1. Read before writing. Search the vault and read an existing page before updating it.
2. Store dry technical facts, decisions, contracts, configurations, verified fixes, blockers, and next steps—not chat transcripts.
3. Start every page with YAML frontmatter containing type, stack, and status.
4. Include summary: a non-empty single line of at most 160 characters describing the page.
5. Never edit index.md; the CLI generates it deterministically from page filenames, summary,

and status without loading page bodies into model context.

1. Use [[wikilinks]] for page references and ![[asset.png]] for files in EchoesVault/assets/.
2. Deprecate instead of deleting. Set status: deprecated, prepend > [!warning] DEPRECATED,

and link to the replacement.

1. Never report final memory as saved after normal task completion. Only $echoes-end may finalize a session.

Choose an operation

Recall before work

Use targeted search when an existing component, decision, API, schema, or configuration might already be documented:

python3 <launcher> --workspace <workspace> \
  --agent codex --adapter-version 1.1.1 search "specific keyword"

Read the returned page around each relevant line. Follow replacement links from deprecated pages.

Append an intermediate note

After a verified logical unit, an architectural agreement, a context switch, or an explicit “remember/log this” request, submit:

{
  "entry": "- Implemented X.\n- Verified with Y.\n- Remaining blocker: Z.",
  "agent": "codex"
}

to append --payload -. Keep the entry concise. This is a scratchpad write and does not end the session.

If no vault exists and the user has asked to remember something, run init first. Otherwise, do not initialize a vault implicitly.

Create or update a knowledge page

Use a page for a durable global concept such as an architecture, API contract, schema, library integration, hardware mapping, or ADR.

For a new page, submit to upsert --payload -:

{
  "filename": "auth-architecture.md",
  "content": "---\ntype: architecture\nstack: [python]\nstatus: active\nsummary: Authentication boundaries and token flow.\n---\n\n# Authentication architecture\n"
}

For an existing page:

1. Read the full page.
2. Run hash <filename> and copy its sha256.
3. Submit the full replacement content plus expectedSha256 to upsert.

Retain or deliberately update the page's summary when replacing its full content. The optimistic hash prevents overwriting a concurrent edit in the current checkout. If it fails, reread the page and reconcile changes. A project-level runtime lock serializes simultaneous EchoesVault writers.

Successful completion

Confirm the exact session-entry or page path written. Mention whether the generated index changed. Keep working unless the user requested a final save.