Skip to content
Back to search

echoes-vault-codex

Persistent memory plugin for Codex. Obsidian-style knowledge base that survives across sessions

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/psinetron--echoes-vault-codex/badge.svg)](/listings/psinetron--echoes-vault-codex)

HTML

<a href="/listings/psinetron--echoes-vault-codex"><img src="/api/listings/psinetron--echoes-vault-codex/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install the plugin once:

codex plugin marketplace add psinetron/echoes-vault-codex
codex plugin add echoes-vault-codex@echoes-vault

Start a new Codex task in the repository that should own the memory and ask in any language:

Initialize EchoesVault for this project.
Инициализируй EchoesVault для этого проекта.

Then use natural language rather than memorizing commands:

Restore project memory.
Show EchoesVault status.
Remember this architectural decision.
Save and finish this EchoesVault session.

Initialization is project-local. The globally installed Codex plugin stays silent in every other repository until EchoesVault is initialized there. Commit the generated protocol, portable runtime, and adapters so Codex, OpenCode, Claude, and teammates all follow the same rules.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 593 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <h1>EchoesVault</h1>
  3. <p>Agent-neutral, repository-local Markdown memory bootstrapped from Codex.</p>
  4. <a href="https://learn.chatgpt.com/docs/plugins"><img src="https://img.shields.io/badge/Codex-Plugin-111827?logo=openai&amp;logoColor=white" alt="Codex Plugin" /></a>
  5. <img src="https://img.shields.io/badge/Release-1.1.1-2563EB" alt="Release 1.1.1" />
  6. <a href="EchoesProtocol.md"><img src="https://img.shields.io/badge/Protocol-1.0.0-7C3AED" alt="Protocol 1.0.0" /></a>
  7. <a href="#using-different-agents"><img src="https://img.shields.io/badge/Agents-Codex%20%7C%20OpenCode%20%7C%20Claude-059669" alt="Codex, OpenCode, and Claude" /></a>
  8. <a href="https://github.com/psinetron/echoes-vault-codex/actions/workflows/tests.yml"><img src="https://github.com/psinetron/echoes-vault-codex/actions/workflows/tests.yml/badge.svg" alt="Tests" /></a>
  9. <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&amp;logoColor=white" alt="Python 3.9+" /></a>
  10. <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
  11. <a href="https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf"><img src="https://img.shields.io/badge/OKF-aligned-4285F4" alt="OKF aligned" /></a>
  12. <a href="https://buymeacoffee.com/psinetron"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Support-FFDD00?logo=buymeacoffee&amp;logoColor=000000" alt="Support EchoesVault on Buy Me a Coffee" /></a>
  13. <a href="https://github.com/psinetron/echoes-vault-codex/commits/main"><img src="https://img.shields.io/github/last-commit/psinetron/echoes-vault-codex" alt="Last commit" /></a>
  14. </div>
  15. EchoesVault is a persistent memory plugin for Codex and a portable project-memory protocol for
  16. Codex, OpenCode, Claude, and other coding agents. Codex bootstraps a shared runtime and agent
  17. instructions into the repository; after that, every supported agent uses the same validation,
  18. locking, logs, and deterministic index. Knowledge stays in plain Markdown, remains readable without
  19. any agent, works naturally with Git, and opens as an Obsidian-compatible vault.
  20. **Managed adapters:** `1.1.1` · **Engine:** `1.1.1` · **Protocol:** `1.0.0` · **Marker schema:** `3`
  21. ## Quick start
  22. Install the plugin once:
  23. ```sh
  24. codex plugin marketplace add psinetron/echoes-vault-codex
  25. codex plugin add echoes-vault-codex@echoes-vault
  26. ```
  27. Start a new Codex task in the repository that should own the memory and ask in any language:
  28. ```text
  29. Initialize EchoesVault for this project.
  30. Инициализируй EchoesVault для этого проекта.
  31. ```
  32. Then use natural language rather than memorizing commands:
  33. ```text
  34. Restore project memory.
  35. Show EchoesVault status.
  36. Remember this architectural decision.
  37. Save and finish this EchoesVault session.
  38. ```
  39. Initialization is project-local. The globally installed Codex plugin stays silent in every other
  40. repository until EchoesVault is initialized there. Commit the generated protocol, portable runtime,
  41. and adapters so Codex, OpenCode, Claude, and teammates all follow the same rules.
  42. ## Contents
  43. - [Installation](#installation)
  44. - [What it provides](#what-it-provides)
  45. - [Protocol 1.0.0 specification](EchoesProtocol.md)
  46. - [Agent-neutral protocol](#agent-neutral-protocol)
  47. - [Open Knowledge Format alignment](#open-knowledge-format-alignment)
  48. - [Status card and quick actions](#status-card-and-quick-actions)
  49. - [Team development without CI/CD](#team-development-without-cicd)
  50. - [Upgrade to 1.1.1](#upgrade-to-111)
  51. - [Local development](#local-development)
  52. - [Security and privacy](#security-and-privacy)
  53. - [Support](#support)
  54. ## Installation
  55. ### Requirements
  56. - Codex in the ChatGPT desktop app or Codex CLI. Plugins are not currently supported by the Codex IDE extension.
  57. - Python 3.9 or newer available as `python3`.
  58. - Git, when installing from GitHub.
  59. - No Python packages, API keys, accounts, background services, or network access at runtime.
  60. Review the bundled [`SessionStart` hook](hooks/session_start.py) before enabling the plugin if your
  61. environment requires auditing third-party commands.
  62. ### Install from GitHub — CLI
  63. This repository contains a Codex marketplace manifest. Add it as a marketplace source:
  64. ```sh
  65. codex plugin marketplace add psinetron/echoes-vault-codex
  66. ```
  67. Then choose either installation method.
  68. **Interactive plugin browser:**
  69. ```text
  70. codex
  71. /plugins
  72. ```
  73. Open the **EchoesVault** marketplace, select **EchoesVault for Codex**, install it, and make sure it
  74. is enabled. Start a new Codex session after installation.
  75. **Direct CLI installation:**
  76. ```sh
  77. codex plugin add echoes-vault-codex@echoes-vault
  78. ```
  79. Verify the result:
  80. ```sh
  81. codex plugin list
  82. ```
  83. The expected entry is `echoes-vault-codex@echoes-vault` with status `installed, enabled`.
  84. ### Install from GitHub — desktop app
  85. 1. Run `codex plugin marketplace add psinetron/echoes-vault-codex` once in a terminal.
  86. 2. Restart the ChatGPT desktop app.
  87. 3. Open **Plugins**.
  88. 4. Select the **EchoesVault** marketplace.
  89. 5. Open **EchoesVault for Codex** and select the plus button to install it.
  90. 6. Confirm that it appears in the **Installed** row and is enabled.
  91. 7. Start a new Codex task; already-open tasks do not acquire newly installed skills and hooks.
  92. ### Local development installation
  93. Clone the repository:
  94. ```sh
  95. git clone https://github.com/psinetron/echoes-vault-codex.git
  96. cd echoes-vault-codex
  97. ```
  98. Run the tests before installing:
  99. ```sh
  100. python3 -m unittest discover -s tests -v
  101. ```
  102. Ask Codex to connect the existing folder to your personal marketplace:
  103. ```text
  104. Use $plugin-creator to add the existing plugin in the current directory to my personal
  105. marketplace, install it, and use the cachebuster update flow for future local changes.
  106. ```
  107. The standard personal marketplace lives at `~/.agents/plugins/marketplace.json`. Do not replace
  108. that file if it already contains other plugins; let `$plugin-creator` merge the entry safely.
  109. After each local code change:
  110. 1. Run the tests.
  111. 2. Ask `$plugin-creator` to update the cachebuster and reinstall `echoes-vault-codex`.
  112. 3. Start a new Codex task to load the updated bundle.
  113. ### First project setup
  114. The plugin is installed once for Codex but remains silent in projects that do not have an
  115. EchoesVault. Open the target project in a new task and ask in any language, for example:
  116. ```text
  117. Initialize EchoesVault for this project.
  118. Инициализируй EchoesVault для этого проекта.
  119. Подключи локальную память проекта.
  120. ```
  121. Exact skill names are optional. You can also invoke `$echoes-init` explicitly. Initialization
  122. creates only repository-local files:
  123. ```text
  124. EchoesVault/
  125. ├── .echoes-vault.json
  126. ├── .gitignore
  127. ├── AGENT_PROTOCOL.md # shared contract for every agent
  128. ├── index.md # generated locally; ignored by Git
  129. ├── pages/
  130. ├── daily/YYYY-MM-DD/ # UTC date; one unique file per write
  131. ├── assets/
  132. └── raw/
  133. .echoes-vault/
  134. ├── .gitignore
  135. ├── echoes_vault.py # portable runtime; committed to Git
  136. ├── state.json # local runtime state; ignored by Git
  137. └── lock # short-lived local lock; ignored by Git
  138. AGENTS.md # managed block for Codex/OpenCode
  139. CLAUDE.md # managed block for Claude
  140. .claude/skills/echoes-vault/SKILL.md
  141. .opencode/skills/echoes-vault/SKILL.md
  142. .opencode/commands/echoes-init.md
  143. .opencode/commands/echoes-start.md
  144. .opencode/commands/echoes-status.md
  145. .opencode/commands/echoes-end.md
  146. ```
  147. On later tasks, the first response includes a status card for initialized projects. Other projects
  148. remain unaffected and show no card.
  149. ### Bootstrap for OpenCode, Claude, or another agent
  150. Codex is convenient for installing and initializing EchoesVault, but it is not required after the
  151. portable files have been created. To bootstrap a project without Codex, clone or download this
  152. repository once and run its bundled engine against the target project:
  153. ```sh
  154. git clone https://github.com/psinetron/echoes-vault-codex.git
  155. python3 echoes-vault-codex/scripts/echoes_vault.py \
  156. --workspace /path/to/your/project --agent codex --adapter-version 1.1.1 init
  157. ```
  158. Commit the generated protocol, portable runtime, and adapters in the target project. Teammates and
  159. other agents then use `.echoes-vault/echoes_vault.py` from that project and do not need a global
  160. EchoesVault installation.
  161. ### Update
  162. Refresh all configured marketplaces:
  163. ```sh
  164. codex plugin marketplace upgrade
  165. ```
  166. Or refresh only EchoesVault:
  167. ```sh
  168. codex plugin marketplace upgrade echoes-vault
  169. ```
  170. Open `/plugins` in Codex CLI or the Plugins page in the desktop app, reinstall/update the plugin,
  171. and start a new task. If Codex still loads an older local development build, use
  172. `$plugin-creator` to apply a new cachebuster before reinstalling.
  173. ### Disable or uninstall
  174. In Codex CLI, open `codex`, enter `/plugins`, select the installed plugin, and either disable it or
  175. uninstall it. In the desktop app, open the plugin under **Installed** and select **Uninstall
  176. plugin**.
  177. Remove the marketplace source only when you no longer need it:
  178. ```sh
  179. codex plugin marketplace remove echoes-vault
  180. ```
  181. Uninstalling the Codex plugin does **not** delete project knowledge or its portable runtime.
  182. Initialized repositories continue to contain `EchoesVault/`, `.echoes-vault/echoes_vault.py`, and
  183. the agent adapters. They can be used by another supported agent or read as plain Markdown.
  184. ### Troubleshooting installation
  185. | Symptom | Check |
  186. |---|---|
  187. | Marketplace does not appear | Run `codex plugin marketplace list`, then restart the desktop app. |
  188. | Plugin is installed but skills are missing | Start a new Codex task or CLI session. |
  189. | Status card does not appear | Confirm that the project contains `EchoesVault/.echoes-vault.json`; legacy vaults may still be detected by `index.md`. |
  190. | Hook reports a Python error | Run `python3 --version`; version 3.9+ must be on `PATH`. |
  191. | Local edits are ignored | Update the manifest cachebuster, reinstall, and start a new task. |
  192. | You do not want memory in a project | Do not initialize it; the globally installed plugin remains silent there. |
  193. | Protocol mismatch is reported | Stop writes, update the adapter or plugin, then run initialization again. Never force an older writer against a newer vault. |
  194. | Portable runtime or agent adapters are missing | For adapters, run project `configure-agents`. If the runtime is missing or damaged, run `upgrade` from the installed plugin's bundled launcher. |
  195. | An OpenCode command was not replaced | EchoesVault preserves unrecognized user-owned files. Compare it with the generated command and reconcile it manually. |
  196. For Codex's general plugin installation and marketplace model, see the [official plugin documentation](https://learn.chatgpt.com/docs/plugins) and [plugin packaging guide](https://developers.openai.com/plugins/build/plugins).
  197. ## What it provides
  198. - `$echoes-init` — idempotently create or activate the vault.
  199. - `$echoes-start` — rebuild and restore the full index plus the three latest session entries.
  200. - `$echoes-vault` — search pages, append scratchpad notes, and safely maintain knowledge pages.
  201. - `$echoes-end` — explicitly distill and save final session memory.
  202. - `$echoes-status` — show a compact dashboard with size, metrics, filesystem checks, metadata validity, index integrity, and scale warnings.
  203. - **Agent Protocol 1.0.0** — a tracked contract that every coding agent reads before using memory.
  204. - **Portable engine 1.1.1** — the same dependency-free Python storage engine is committed into each initialized repository and is always the execution source after bootstrap.
  205. - **Claude and OpenCode adapters** — project skills and root instruction blocks are installed without replacing unrelated user instructions.
  206. - **OKF-aligned knowledge storage** — pages follow the core [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) model of plain Markdown, YAML frontmatter, typed concepts, portable directories, and progressive-disclosure indexes.
  207. - A lightweight `SessionStart` hook that asks Codex to show the current status card once in its first response after startup, resume, or clear, but only in initialized projects. Uninitialized projects remain silent. Compaction refreshes hidden context without repeating the card.
  208. - Natural-language starter actions for initialization, restore, status, and explicit final save, so normal use does not require memorizing skill names.
  209. - A dependency-free Python CLI with atomic replacement writes, a project-local lock, strict page metadata, conflict-marker detection, path sanitization, and optimistic concurrency checks.
  210. The managed project structure is intentionally Git-friendly:
  211. ```text
  212. EchoesVault/
  213. ├── .echoes-vault.json # tracked initialization marker
  214. ├── .gitignore # ignores only generated index.md
  215. ├── AGENT_PROTOCOL.md # generated cross-agent contract
  216. ├── index.md # generated from page metadata
  217. ├── pages/
  218. ├── daily/YYYY-MM-DD/ # UTC date; unique scratchpad/session files
  219. ├── assets/
  220. └── raw/
  221. ```
  222. The tracked portable engine lives at `.echoes-vault/echoes_vault.py`. Runtime state and the shared
  223. local lock live at `.echoes-vault/state.json` and `.echoes-vault/lock`; they contain no durable
  224. knowledge and are ignored locally.
  225. ## Agent-neutral protocol
  226. The complete public implementer specification is available in
  227. **[EchoesProtocol.md](EchoesProtocol.md)**. It defines the repository layout, marker and page
  228. schemas, deterministic index algorithm, unique daily-log format, portable CLI contract, locking,
  229. optimistic concurrency, Git behavior, migration rules, security boundaries, and a compatibility
  230. checklist for third-party agents and tools. The specification is MIT-licensed and can be reused by
  231. Codex, OpenCode, Claude, editor extensions, custom agents, and independent integrations.
  232. Initialization writes `EchoesVault/AGENT_PROTOCOL.md` and adds a delimited EchoesVault block to
  233. the repository's `AGENTS.md` and `CLAUDE.md`. Existing content outside that block is preserved.
  234. Project skills are also written for Claude and OpenCode:
  235. ```text
  236. .claude/skills/echoes-vault/SKILL.md
  237. .opencode/skills/echoes-vault/SKILL.md
  238. .opencode/commands/echoes-init.md
  239. .opencode/commands/echoes-start.md
  240. .opencode/commands/echoes-status.md
  241. .opencode/commands/echoes-end.md
  242. ```
  243. All agents are instructed to use the repository runtime:
  244. ```sh
  245. python3 .echoes-vault/echoes_vault.py --workspace . \
  246. --agent <agent-name> --adapter-version <adapter-version> <command>
  247. ```
  248. The Codex plugin package, portable engine, protocol, marker schema, and each agent adapter have
  249. separate versions. Only `protocolVersion` defines storage compatibility. An OpenCode plugin version
  250. is never compared with the Python engine version. The bundled Codex engine is used only for first
  251. initialization, explicit upgrade, or recovery of a missing project runtime; it delegates to a
  252. compatible project runtime and never downgrades a newer one.
  253. The runtime marker declares `protocolVersion: "1.0.0"`. An adapter that encounters a different
  254. protocol version must stop before writing instead of guessing compatibility. Optional `agent`
  255. values in append and end payloads add provenance to unique log filenames and bodies:
  256. ```json
  257. {
  258. "entry": "- Confirmed the shared authentication contract.",
  259. "agent": "claude"
  260. }
  261. ```
  262. Legacy OpenCode tools that directly edit `index.md` or append to `daily/YYYY-MM-DD.md` must not be
  263. used with a protocol 1.0 vault. OpenCode should use the generated project skill and portable
  264. runtime instead. The standalone [EchoesVault for OpenCode](https://github.com/psinetron/echoes-vault-opencode)
  265. requires a corresponding protocol-aware release before its legacy tools can be mixed safely.
  266. Recognized legacy EchoesVault command files and known direct-tool skills are replaced by project-
  267. runtime redirects; unrelated user-owned files with the same names are preserved and reported by
  268. the health check for manual reconciliation.
  269. ### Using different agents
  270. - **Codex:** use the plugin actions, `$echoes-*` skills, or natural-language requests.
  271. - **OpenCode:** use the generated `/echoes-init`, `/echoes-start`, `/echoes-status`, and
  272. `/echoes-end` project commands. They call the portable runtime rather than legacy mutation tools.
  273. - **Claude Code:** `CLAUDE.md` advertises the protocol and the generated project skill handles
  274. natural-language initialization, restoration, status, recall, logging, and explicit final save.
  275. - **Other agents:** read `AGENTS.md` and `EchoesVault/AGENT_PROTOCOL.md`, then invoke the portable
  276. CLI directly.
  277. The portable command surface is:
  278. | Command | Purpose |
  279. |---|---|
  280. | `init` | Initialize or migrate the vault and install every adapter |
  281. | `migrate` | Explicitly migrate a recognized legacy vault |
  282. | `upgrade` | Explicitly upgrade the project runtime and tracked adapters |
  283. | `protocol` | Report supported and repository protocol versions |
  284. | `configure-agents` | Repair protocol documentation, guides, skills, and OpenCode commands |
  285. | `inspect` / `status --format card` | Inspect quantitative health without changing any file |
  286. | `hydrate` | Refresh only ignored `index.md` and local `state.json` |
  287. | `start --recent 3` | Restore the index and latest session entries |
  288. | `search <query>` | Search page bodies literally |
  289. | `append --payload -` | Write one unique scratchpad file |
  290. | `hash <filename>` | Obtain the optimistic concurrency hash for an existing page |
  291. | `upsert --payload -` | Create or safely replace a complete page |
  292. | `end --confirm-explicit-user-end --payload -` | Perform an explicitly authorized final save |
  293. | `rebuild-index` | Validate metadata and reconstruct the generated local index |
  294. ## Open Knowledge Format alignment
  295. EchoesVault follows the core ideas of Google's [Open Knowledge Format v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md): knowledge is stored as UTF-8 Markdown, concept pages begin with YAML frontmatter, every page has a `type`, and `index.md` enables progressive discovery without loading the complete vault.
  296. EchoesVault deliberately extends the strict OKF shape with Obsidian `[[wikilinks]]`, required `stack`
  297. and `status` fields, `daily/` session logs, and lifecycle values used by the original OpenCode plugin.
  298. For that reason this project describes itself as **OKF-aligned**, rather than claiming strict OKF
  299. v0.2 conformance. The files remain human-readable, Git-friendly, and straightforward for agents
  300. and generic Markdown tooling to consume.
  301. Every knowledge page uses frontmatter like:
  302. ```yaml
  303. ---
  304. type: architecture
  305. stack: [python, codex]
  306. status: active
  307. summary: Authentication boundaries and token flow.
  308. ---
  309. ```
  310. `summary` is required, must fit on one line, and is limited to 160 characters. The Python runtime
  311. builds `index.md` from filenames and these summaries in a fixed Unicode-aware order. Page bodies are
  312. not used, so rebuilding the index consumes no model context and the same pages always produce the
  313. same bytes. Existing pre-1.0 vaults are migrated automatically when their old index contains a
  314. description for every page missing `summary`.
  315. ## Status card and quick actions
  316. After the plugin is installed, start a new Codex task. On the first response, EchoesVault adds a
  317. compact card similar to:
  318. ```text
  319. ### EchoesVault · ✓ Healthy
  320. | Storage | Knowledge | Session |
  321. |---|---|---|
  322. | 186.4 KB · 48 files | 42 pages · 6 logs | active |
  323. Protocol: 1.0.0 · engine: 1.1.1 · adapters ready.
  324. Integrity: index, structure, metadata, and local paths are consistent.
  325. ```
  326. The card is generated from live filesystem data. `inspect` and `status` are strictly read-only: they
  327. do not initialize, migrate, repair adapters, regenerate the index, write state, or create a lock.
  328. Projects without the initialization marker (or a legacy `EchoesVault/index.md`) show no card and
  329. receive no hook context. A legacy vault gets an actionable migration card. Use the
  330. plugin starter actions, invoke `$echoes-status`, or ask naturally in any language: “show vault
  331. status”, “покажи состояние памяти”, “restore project memory”, or “сохрани эту сессию”. Exact skill
  332. names are optional. Codex plugins cannot pin a permanent custom sidebar, so the card appears in the
  333. conversation instead.
  334. For scripts and diagnostics, request the same card directly:
  335. ```sh
  336. python3 .echoes-vault/echoes_vault.py --workspace . inspect --format card
  337. ```
  338. From a clone of this repository, you can also inspect another workspace with the bundled engine:
  339. ```sh
  340. python3 scripts/echoes_vault.py --workspace /path/to/project inspect --format card
  341. ```
  342. ## Why Codex is the bootstrapper
  343. The original OpenCode plugin exposes runtime tools, command templates, and a custom TUI sidebar
  344. through OpenCode-specific APIs. A Codex plugin natively packages skills, scripts, hooks, and optional
  345. MCP servers. EchoesVault uses Codex as the installer and bootstrapper, then places an agent-neutral
  346. runtime and instructions inside the repository:
  347. | Choice | Benefit | Trade-off |
  348. |---|---|---|
  349. | Skills instead of custom slash-command registration | Native discovery and explicit `$echoes-*` workflows | Invocation uses `$echoes-start`, not `/echoes-start` |
  350. | Local CLI instead of an MCP server | No daemon, network, package install, or protocol dependency | Codex executes a local command rather than calling named MCP tools |
  351. | Repository-portable runtime and protocol | Codex, OpenCode, and Claude share one writer and one set of invariants | The generated runtime and adapters are committed to each project |
  352. | One-time SessionStart card instead of a sidebar | Live health is visible at the start of a task and after resume | There is no always-visible custom status panel |
  353. | Explicit start/end | Predictable token cost and no accidental final save | The user must request restoration and finalization |
  354. | Frontmatter-generated local index | Stable output, no model-token rebuild cost, and no index merge conflicts | Every page needs a concise `summary` |
  355. | Unique daily files plus a project-local lock | Concurrent local writes and cross-branch logs do not overwrite one shared file | Same-page semantic conflicts still need human resolution |
  356. | Optimistic hashes for existing pages | Prevents silent lost updates | Existing-page updates need one extra hash step |
  357. Compared with the original, the port deliberately strengthens frontmatter validation, rejects path traversal, detects missing structure, symbolic links, unreadable files, invalid page metadata, Git conflict markers, and duplicate/orphan/missing index entries, uses UTC for sortable log paths, and avoids copying OpenCode/TUI dependencies. It keeps local-offset timestamps inside logs, deprecation-over-deletion, read-before-write, daily scratchpads, index synchronization, and the 200-page scale warning.
  358. ## Team development without CI/CD
  359. Commit durable knowledge and the small initialization files:
  360. ```text
  361. EchoesVault/.echoes-vault.json
  362. EchoesVault/.gitignore
  363. EchoesVault/AGENT_PROTOCOL.md
  364. EchoesVault/pages/**
  365. EchoesVault/daily/**
  366. EchoesVault/assets/**
  367. EchoesVault/raw/**
  368. .echoes-vault/.gitignore
  369. .echoes-vault/echoes_vault.py
  370. AGENTS.md
  371. CLAUDE.md
  372. .claude/skills/echoes-vault/SKILL.md
  373. .opencode/skills/echoes-vault/SKILL.md
  374. .opencode/commands/echoes-init.md
  375. .opencode/commands/echoes-start.md
  376. .opencode/commands/echoes-status.md
  377. .opencode/commands/echoes-end.md
  378. ```
  379. Do not commit generated or machine-local files:
  380. ```text
  381. EchoesVault/index.md
  382. .echoes-vault/state.json
  383. .echoes-vault/lock
  384. .opencode/echoes-state.json
  385. .codex/echoes-vault-state.json
  386. ```
  387. `echoes-init` adds those ignore rules automatically. If `EchoesVault/index.md` was already tracked
  388. before upgrading, remove only that file from Git's index once while keeping the local copy:
  389. ```sh
  390. git rm --cached EchoesVault/index.md
  391. git add EchoesVault .echoes-vault/.gitignore .echoes-vault/echoes_vault.py AGENTS.md CLAUDE.md
  392. git add .claude/skills/echoes-vault/SKILL.md .opencode/skills/echoes-vault/SKILL.md
  393. git add .opencode/commands/echoes-init.md .opencode/commands/echoes-start.md
  394. git add .opencode/commands/echoes-status.md .opencode/commands/echoes-end.md
  395. git commit -m "Make EchoesVault index generated locally"
  396. ```
  397. After pulling, switching branches, or merging, explicitly refresh the ignored generated index and
  398. local state without touching tracked adapters:
  399. ```sh
  400. python3 .echoes-vault/echoes_vault.py --workspace . hydrate
  401. ```
  402. `start` also hydrates before returning context. A focused index recovery command is available:
  403. ```sh
  404. python3 .echoes-vault/echoes_vault.py --workspace . rebuild-index
  405. ```
  406. Different pages and unique daily-log files normally merge cleanly. If two branches edit the same
  407. knowledge page, Git still reports the ordinary Markdown conflict; resolve its meaning manually,
  408. remove every conflict marker, keep valid frontmatter including `summary`, run `hydrate`, and request
  409. EchoesVault status. The read-only health card reports unresolved `<<<<<<<`, `=======`, or
  410. `>>>>>>>` markers. Its Git-readiness section also reports durable files that are untracked or
  411. ignored and local `state.json`/`lock` files that were accidentally tracked, with exact suggested
  412. commands; it never runs `git add` or `git rm` itself. No CI job,
  413. Git hook, daemon, or background watcher is required.
  414. ### Upgrade to 1.1.1
  415. After installing the Codex plugin 1.1.1, run initialization once in every existing vault. It keeps
  416. Protocol 1.0.0, installs engine 1.1.1, preserves local state schema 4, and refreshes the managed
  417. agent adapters. This patch also exposes the neutral `managedAdapterVersion` diagnostics field;
  418. `codexAdapterVersion` remains as a deprecated compatibility alias for existing integrations:
  419. ```text
  420. Update this project's EchoesVault to protocol 1.0.0.
  421. Обнови EchoesVault этого проекта до протокола 1.0.0.
  422. ```
  423. Or run the bundled engine directly:
  424. ```sh
  425. python3 /path/to/echoes-vault-codex/scripts/echoes_vault.py --workspace . \
  426. --agent codex --adapter-version 1.1.1 upgrade
  427. ```
  428. State is read in this priority: `.echoes-vault/state.json`, `.opencode/echoes-state.json`, then
  429. `.codex/echoes-vault-state.json`. Session flags and timestamps are preserved and schema 4 state is
  430. written to `.echoes-vault/state.json`. Known legacy OpenCode skills are converted to shared-runtime
  431. redirects; unknown files remain untouched and appear as adapter conflicts. Do not enable an older
  432. OpenCode writer that still edits the index or shared daily files directly.
  433. ## Local development
  434. Validate all skills and the plugin:
  435. ```sh
  436. for skill in skills/*; do
  437. python3 /path/to/skill-creator/scripts/quick_validate.py "$skill"
  438. done
  439. python3 /path/to/plugin-creator/scripts/validate_plugin.py .
  440. ```
  441. Run the test suite:
  442. ```sh
  443. python3 -m unittest discover -s tests -v
  444. ```
  445. The runtime requires Python 3.9 or newer and only the standard library.
  446. ## Security and privacy
  447. EchoesVault makes no network requests and has no authentication. Vault data operations are confined
  448. to `EchoesVault/`, `.echoes-vault/`, the managed blocks in `AGENTS.md` and `CLAUDE.md`, and the
  449. generated Claude/OpenCode project skills inside the resolved workspace; symbolic-link escapes are
  450. rejected. Existing unrelated root instructions are preserved. Treat the vault like source code: do
  451. not store secrets unless the repository's access policy permits them.
  452. ## Support
  453. If EchoesVault saves you time or helps your agents work more consistently, you can support its
  454. continued development on [Buy Me a Coffee](https://buymeacoffee.com/psinetron). Support is entirely
  455. optional—the plugin remains open source under the MIT License.
  456. ## License
  457. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.