v1.1.1

EchoesVault v1.1.1

• Renamed CODEX_ADAPTER_VERSION to the agent-neutral MANAGED_ADAPTER_VERSION.
• Preserved codexAdapterVersion as a deprecated compatibility alias.
• Updated the engine and managed adapters to 1.1.1.

EchoesVault v1.1.0 — Cross-Agent Runtime Compatibility

EchoesVault v1.1.0

This release improves compatibility between Codex, OpenCode, Claude Code, and other agents sharing the same project memory.

Highlights

• Added safe delegation to the project-local runtime without downgrading newer engines.
• Made status, inspect, and the SessionStart hook strictly read-only.
• Added explicit hydrate, migrate, and upgrade commands.
• Added migration from legacy OpenCode and Codex state files.
• Replaced recognized legacy OpenCode skills with shared-runtime redirects.
• Added Git readiness checks with suggested commands.
• Switched new daily-log paths to UTC for reliable cross-time-zone ordering.
• Separated adapter, engine, protocol, marker schema, and state schema versions.

Upgrade

After installing v1.1.0, ask Codex to upgrade EchoesVault in each initialized project, or run:

python3 scripts/echoes_vault.py --workspace /path/to/project \
  --agent codex --adapter-version 1.1.0 upgrade

Protocol compatibility remains at 1.0.0. Legacy OpenCode writers that directly modify index.md or shared daily files should remain disabled until they receive a protocol-aware update.

v1.0.0 — Agent-Neutral Project Memory

EchoesVault v1.0.0 — Agent-Neutral Project Memory

EchoesVault 1.0 introduces a shared, repository-portable memory protocol for Codex, OpenCode,
Claude Code, and other coding agents.

The vault is no longer coupled to one agent's plugin implementation. Every supported agent reads
the same protocol and uses the same local storage engine, validation rules, lock, deterministic
index, and merge-safe daily-log layout.

Highlights

• Agent Protocol 1.0.0
• Repository-portable Python runtime
• Codex, OpenCode, and Claude project adapters
• Managed AGENTS.md and CLAUDE.md integration
• Protocol compatibility checks that fail safely before writes
• Shared cross-agent write lock
• Optional agent provenance in daily and session logs
• Automatic migration from EchoesVault 0.2.x
• Safe migration of recognized legacy OpenCode commands

One protocol for every agent

Initialization now creates:

EchoesVault/AGENT_PROTOCOL.md
EchoesVault/.echoes-vault.json
.echoes-vault/echoes_vault.py
AGENTS.md
CLAUDE.md
.claude/skills/echoes-vault/SKILL.md
.opencode/skills/echoes-vault/SKILL.md
.opencode/commands/echoes-init.md
.opencode/commands/echoes-start.md
.opencode/commands/echoes-status.md
.opencode/commands/echoes-end.md

AGENTS.md and CLAUDE.md receive a delimited EchoesVault block. Existing instructions outside
the managed block are preserved.

The initialization marker now declares:

{
  "schemaVersion": 3,
  "protocolVersion": "1.0.0",
  "generatedIndex": true,
  "dailyLayout": "unique-files-v1",
  "runtime": ".echoes-vault/echoes_vault.py",
  "requiredFrontmatter": ["type", "stack", "status", "summary"]
}

An incompatible runtime stops before writing and asks for an adapter upgrade instead of guessing
how to mutate the vault.

Portable storage engine

The same dependency-free Python runtime is committed into every initialized repository:

python3 .echoes-vault/echoes_vault.py --workspace . <command>

Available commands include:

• init
• protocol
• configure-agents
• start
• status
• search
• append
• hash
• upsert
• end
• rebuild-index

This gives agents without a dedicated EchoesVault plugin access to the same safe storage contract.

OpenCode compatibility

Protocol-aware project commands are generated for OpenCode. Recognized commands created by older
EchoesVault releases are migrated to use the portable runtime.

Legacy tools that directly edit EchoesVault/index.md or append to a shared
daily/YYYY-MM-DD.md file must not be used with protocol 1.0 vaults.

Claude Code compatibility

Claude receives:

• a managed protocol notice in CLAUDE.md;
• a project-local .claude/skills/echoes-vault/SKILL.md adapter;
• access to the same portable runtime used by Codex and OpenCode.

Cross-agent log provenance

append and end payloads accept an optional agent field:

{
  "entry": "- Confirmed the shared authentication contract.",
  "agent": "claude"
}

The normalized agent name is recorded in both the unique filename and the Markdown entry.

Agent-neutral runtime state

Machine-local state and locking moved from .codex/ to .echoes-vault/:

.echoes-vault/state.json
.echoes-vault/lock

Both files are ignored by Git. All agents operating in the same working tree now share one lock.

The legacy .codex/echoes-vault-state.json file is read automatically during migration.

Upgrade from 0.2.x

After installing 1.0.0, initialize each existing vault once:

python3 /path/to/echoes-vault-codex/scripts/echoes_vault.py --workspace . init

This operation:

• upgrades the marker to protocol 1.0.0;
• migrates local session state;
• installs the portable runtime and protocol document;
• adds or updates managed agent instructions;
• installs Claude and OpenCode project adapters;
• replaces recognized legacy OpenCode EchoesVault commands;
• preserves knowledge pages, logs, assets, raw files, and unrelated agent instructions.

If EchoesVault/index.md is still tracked by Git, remove it from the Git index while preserving the
local generated file:

git rm --cached EchoesVault/index.md

Git contract

Commit the portable runtime, protocol, adapters, pages, unique daily files, assets, and raw sources.

Do not commit:

EchoesVault/index.md
.echoes-vault/state.json
.echoes-vault/lock

Validation

Version 1.0.0 includes automated coverage for:

• portable runtime execution;
• agent-guide preservation and idempotency;
• recognized legacy OpenCode command migration;
• unsupported-protocol rejection;
• legacy Codex state migration;
• Codex, OpenCode, and Claude log provenance;
• deterministic index generation;
• concurrent writes;
• real multi-branch Git merges;
• conflict-marker and metadata diagnostics.

No CI/CD integration, daemon, network service, API key, or background watcher is required at
runtime.

EchoesVault v0.2.0 — Team-Safe Storage

EchoesVault v0.2.0 — Team-Safe Storage

This release makes EchoesVault significantly safer and more convenient for teams working across multiple Git branches—without requiring CI/CD, background services, or Git hooks.

Highlights

• Deterministic, automatically generated index.md
• Merge-safe daily and session logs
• Safe parallel writes through a project-local lock
• Automatic migration of existing vaults
• Git conflict-marker detection
• Improved status card and integrity diagnostics
• Zero model-token cost for index regeneration

Deterministic generated index

EchoesVault/index.md is now generated automatically from page filenames and frontmatter metadata:

---
type: architecture
stack: [python, codex]
status: active
summary: Authentication boundaries and token flow.
---

The new summary field:

• is required for every knowledge page;
• must be a single line;
• is limited to 160 characters;
• becomes the page description in index.md.

Pages are sorted using deterministic Unicode-aware ordering, so the same set of pages always produces the same index.

Page bodies are not loaded into the model when rebuilding the index. Index generation is performed entirely by the local Python runtime and does not consume model context.

Git-friendly index behavior

EchoesVault/index.md remains available locally for Codex, Obsidian, and manual browsing, but it is now ignored by Git.

Each developer gets an identical locally generated index without introducing index conflicts during branch merges.

The index is automatically validated and regenerated when EchoesVault:

• initializes a vault;
• starts or restores a session;
• displays vault status;
• searches or updates knowledge;
• writes a session entry;
• finalizes a session;
• runs through the SessionStart status hook.

A manual recovery command is also available:

python3 scripts/echoes_vault.py \
  --workspace /path/to/project \
  rebuild-index

Merge-safe daily logs

Daily and session entries no longer share one date-level Markdown file.

Every write now creates a unique file:

EchoesVault/daily/YYYY-MM-DD/
├── 20260831T102301123456-scratchpad-a1b2c3d4.md
├── 20260831T102744654321-session-e5f6a7b8.md
└── 20260831T110012987654-session-c9d0e1f2.md

Filenames contain:

• the date and time with microsecond precision;
• the entry type;
• a random identifier.

This allows developers working in different branches to create session logs independently and merge them without modifying the same file.

Parallel-write protection

EchoesVault now uses a project-local lock for storage operations.

This serializes simultaneous EchoesVault writers in the same working tree and prevents concurrent operations from producing incomplete page or index updates.

The lock is short-lived and stored locally at:

.codex/echoes-vault.lock

It is automatically ignored by Git.

Improved integrity checks

The status dashboard now detects and reports:

• missing or invalid page metadata;
• unresolved Git conflict markers;
• deterministic index build errors;
• duplicate or filesystem-colliding page names;
• orphan pages;
• missing indexed pages;
• symbolic links and unsafe paths;
• unreadable files;
• invalid runtime state;
• vault size and scale warnings.

The SessionStart hook can also regenerate a missing local index before displaying the status card.

Automatic migration

Existing vaults are migrated automatically when possible.

For pages without summary, EchoesVault extracts the existing description from the legacy index.md entry and writes it into the page frontmatter.

Existing indexDescription write payloads remain supported for backward compatibility, but new integrations should place summary directly in page frontmatter.

Migration stops safely if a page has no usable legacy description, allowing the missing metadata to be fixed without overwriting the existing index.

Repository layout

Durable files that should be committed:

EchoesVault/.echoes-vault.json
EchoesVault/.gitignore
EchoesVault/pages/**
EchoesVault/daily/**
EchoesVault/assets/**
EchoesVault/raw/**
.codex/.gitignore

Generated or machine-local files that should not be committed:

EchoesVault/index.md
.codex/echoes-vault-state.json
.codex/echoes-vault.lock

Upgrading an existing repository

If EchoesVault/index.md is already tracked by Git, remove it from the Git index once while preserving the local file:

git rm --cached EchoesVault/index.md
git add EchoesVault/.gitignore EchoesVault/.echoes-vault.json .codex/.gitignore
git commit -m "Make EchoesVault index generated locally"

After upgrading the plugin, start a new Codex task and request EchoesVault status. The vault structure, metadata, ignore rules, and generated index will be initialized or migrated automatically.

Validation

This release includes 20 automated unit and integration tests covering:

• deterministic index generation;
• legacy vault migration;
• parallel page writes;
• unique daily-log creation;
• Git conflict-marker detection;
• Unicode filename collisions;
• SessionStart restoration;
• real branch merges with independent pages and daily logs.

A real two-branch Git merge is verified to complete without generated-index or daily-log conflicts.

Notes

Conflicts are still possible when two branches intentionally edit the same knowledge page. These are semantic Markdown conflicts and should be resolved manually.

No CI/CD pipeline, daemon, background watcher, or external service is required.

v0.1.1

EchoesVault for Codex v0.1.1

The first public release of EchoesVault for Codex — a project-scoped, local Markdown knowledge store designed for Codex.

Highlights

• Store project knowledge locally in readable Markdown files
• Initialize a separate EchoesVault for each project
• Interact with the vault using natural language
• Use initialization requests in different languages
• Automatically display a vault status card
• Monitor vault size, health, and integrity
• Keep project knowledge isolated between repositories
• Validate vault structure and detect potential inconsistencies
• Install through a Codex-compatible GitHub marketplace
• Run automated tests with GitHub Actions
• Fully open source under the MIT License

Installation

Add the EchoesVault GitHub repository as a Codex marketplace:

codex plugin marketplace add psinetron/echoes-vault-codex