Skip to content

EchoesVault v0.2.0 — Team-Safe Storage

Choose a tag to compare

View all tags
@psinetron psinetron released this 31 Aug 10:38
· 11 commits to main since this release
0.2.0
744fd3e

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.

Assets 2
Loading