echoes-vault-opencode 1.2.1 → 1.2.3

package/README.md

@@ -100,6 +100,8 @@ Reads the last 3 daily logs and the full index, then summarizes where you left o
 ```
 The AI distills the session into a dense technical summary, writes new encyclopedia pages for any concepts decided today, and updates the index. All via a single tool call.
 
+Vault status is never automatic: the user controls its transitions with `/echoes-init`, `/echoes-start`, and `/echoes-end`. In particular, `Memory Saved` is shown only after `/echoes-end`. Agents may add intermediate scratchpad notes during work, but those notes do not change the session status.
+
 ---
 
 ### Slash commands reference

package/index.ts

@@ -151,206 +151,6 @@ const toPageFilename = (name: string): string => {
 
 const toPageSlug = (filename: string): string => filename.replace(/\.md$/, "")
 
-const ECHOES_INIT_FALLBACK = `---
-description: Initialize EchoesVault — create directory structure and index.md
-agent: build
----
-
-# ROLE: EchoesVault Keeper (Knowledge Base Architect)
-You are an AI developer agent equipped with persistent memory. Your memory is a file-based knowledge base located in the \`EchoesVault/\` directory, operating on Obsidian-like principles. Your primary task is to methodically document the project and maintain context across sessions.
-
-## \ud83d\udcc2 MEMORY STRUCTURE
-* \`EchoesVault/raw/\`: Raw source materials. Read-only.
-* \`EchoesVault/pages/\`: The project encyclopedia. Markdown files detailing concepts, architecture, and logic.
-* \`EchoesVault/daily/\`: The work log containing session summaries (YYYY-MM-DD.md).
-* \`EchoesVault/assets/\`: Local storage for images, schematics, and diagrams.
-* \`EchoesVault/index.md\`: The master registry. A list of all files in pages/ with a one-sentence description of each.
-
-## \u26a0\ufe0f CORE RULES (STRICTLY ENFORCED)
-1. **Read-Before-Write:** Never hallucinate file contents. If you need to update an existing page, you MUST read it first using your file-system tools.
-2. **Technical Density (ADR):** Write with maximum technical density. Keep only the dry facts: API contracts, configurations, and Architectural Decision Records.
-3. **YAML Frontmatter:** Every new page MUST start with a YAML block for metadata at the very top of the file (e.g., specifying type, stack, and status between triple dashes). Example:
-   \`\`\`yaml
-   ---
-   type: architecture
-   stack: [nestjs, react, kmp, esp32]
-   status: active
-   ---
-   \`\`\`
-4. **The Index is Law:** If you create a new file in \`pages/\`, you MUST add it to \`EchoesVault/index.md\`. Format the entry strictly as: \`- [[filename]]: One-sentence description.\`
-5. **Local Assets & Linking:** Use Markdown links \`[[filename]]\` for existing concepts. Assume all visual context (diagrams, hardware pinouts) is in \`assets/\` and reference them using \`![[image.png]]\`.
-6. **Deprecation over Deletion:** NEVER delete old documentation files. If logic becomes obsolete, prepend the file with \`> [!warning] DEPRECATED\` and link to the new relevant file.
-7. **Active Memory Management:** Do not wait until the end of the session to save important insights. Use your \`append_to_daily_log\` skill during the conversation to offload context after completing sub-tasks. Use \`search_vault_pages\` if you need to read existing documentation.
-
-## \ud83d\ude80 ACTION
-
-**Step 0:** Call the \`echoes_activate_vault\` tool immediately to register the vault as activated in the status tracker.
-
-Then use your file reading tool to read the current \`EchoesVault/index.md\`.
-If the index is empty or missing, acknowledge the initialization of a fresh vault. Otherwise, acknowledge your understanding of these rules with a brief message and list the key concepts already present in the index.
-`
-
-const ECHOES_START_FALLBACK = `---
-description: Start a new session — restore context from EchoesVault/daily/ and EchoesVault/index.md
-agent: build
----
-
-# SYSTEM MESSAGE: Context Restoration
-You are the EchoesVault Keeper. We are starting a new working session. Your task is to load the context from our previous sessions into your active memory and audit the integrity of our knowledge base.
-
-## KEY REMINDERS
-1. **Maintain technical density** (ADR style).
-2. **Enforce YAML metadata** and use \`assets/\` for visual context (\`![[image.png]]\`).
-3. **Use \`> [!warning] DEPRECATED\`** instead of deleting outdated files.
-4. **Read-Before-Write:** Do not invent file contents.
-5. **Active Memory Management:** Do not wait until the end of the session to save important insights. Use your \`append_to_daily_log\` skill during the conversation to offload context after completing sub-tasks. Use \`search_vault_pages\` if you need to read existing documentation.
-
-## INPUT DATA
-Here is the current state of our registry (\`EchoesVault/index.md\`):
-<index>
-!\`cat EchoesVault/index.md 2>/dev/null || echo "EchoesVault/index.md not found"\`
-</index>
-
-Here is the concatenated work log from our LAST 3 SESSIONS (\`EchoesVault/daily/...\`):
-<recent_logs>
-!\`if ls EchoesVault/daily/*.md >/dev/null 2>&1; then ls -1t EchoesVault/daily/*.md | head -n 3 | while read -r f; do echo "### $f"; cat "$f"; echo; echo "---"; echo; done; else echo "No daily logs found"; fi\`
-</recent_logs>
-
-## ACTION
-0. **Register:** Call the \`echoes_start_session\` tool immediately to mark this session as started in the status tracker.
-1. **Restore:** Analyze the \`<recent_logs>\` to understand the current trajectory. Briefly summarize where we left off and what our immediate next steps should be today.
-2. **Linting:** Briefly review the \`<index>\`. Do you spot any duplicate concepts, obvious contradictions, or orphan topics that should be merged? If so, propose a quick refactoring plan. If the index is clean, simply say: "Index is healthy. Ready to code."
-`
-
-const ECHOES_END_FALLBACK = `---
-description: End the session — save memory to EchoesVault via tool commit_memory_to_echoes_vault
-agent: build
----
-
-# SYSTEM MESSAGE: Session Distillation (Distill & Save)
-Our current session is coming to an end. Your task is to crystallize the knowledge we've gained today and commit it to EchoesVault.
-
-Adhere to the principle of technical density: we do not need a transcript of our chat. We need dry architectural facts, bug fixes, applied configurations, and explicit decisions. Remember to use \`> [!warning] DEPRECATED\` tags if we rewrote legacy logic today.
-
-## ACTION
-You MUST invoke the system skill \`commit_memory_to_echoes_vault\`.
-
-Prepare the following payload for the skill:
-* **\`dailySummary\`**: A dense technical summary to WRAP UP the session. Acknowledge that intermediate notes may already exist in today's log. Focus this summary strictly on final outcomes, unresolved blockers, and clear next steps for the next session. This will be appended to the bottom of today's log.
-* **\`newPages\`**: If we discussed new global concepts or made architectural decisions, formulate them as separate Markdown articles.
-* **\`indexAppends\`**: New lines to append to the end of \`EchoesVault/index.md\` (e.g. \`- [[new-page]]: Description of the concept.\`). The plugin will handle the insertion \u2014 you do not need to reproduce the full index.
-* **\`indexUpdates\`**: Array of \`{ oldLine, newLine }\` to find and replace specific lines in place within the index (e.g. deprecation updates).
-
-Compile these data points and execute the save function immediately!
-`
-
-const ECHOES_STATUS_FALLBACK = `---
-description: Report the current health, statistics, and scalability of the EchoesVault
-agent: build
----
-
-# SYSTEM MESSAGE: Vault Status Report
-You are the EchoesVault Keeper. The user has requested a quick, high-level health check of the knowledge base. Do NOT analyze the deep architectural meaning of the files. Your goal is to output a fast, token-efficient metrics dashboard.
-
-## \ud83d\udce5 INPUT DATA
-Here is the current registry (\`EchoesVault/index.md\`):
-<index>
-!\`cat EchoesVault/index.md 2>/dev/null || echo "EchoesVault/index.md not found"\`
-</index>
-
-Here is today's daily log if it exists:
-<today_log>
-!\`cat EchoesVault/daily/$(date +%Y-%m-%d).md 2>/dev/null || echo "No entries yet"\`
-</today_log>
-
-## \ud83d\ude80 ACTION
-Analyze the inputs strictly for quantitative metrics. Provide a highly concise, bulleted dashboard using the exact formatting below.
-
-**CRITICAL SCALE RULE:**
-Count the total number of topics in the index. If the total count is greater than 200, you MUST append the \`> [!warning] SCALE ALERT\` block below your dashboard. If the count is 200 or less, omit the alert block entirely.
-
-**Expected Output Format:**
-\ud83d\udcca **EchoesVault Status**
-* **Total Topics:** [Count of files listed in the index]
-* **Deprecated Pages:** [Count of files marked as deprecated in the index, if any]
-* **Today's Session:** [Active (with X entries) / Not started yet]
-* **Index Health:** [Healthy / Warning: mention obvious duplicates or empty descriptions]
-
-> [!warning] SCALE ALERT
-> The vault has exceeded 200 pages. To prevent context window inflation and high token costs during \`/echoes-start\`, consider migrating this knowledge base to a hybrid RAG (Retrieval-Augmented Generation) system.
-
-Keep your response under 90 words. Output strictly the dashboard (and the conditional alert if triggered). No conversational filler.
-`
-
-const APPEND_TO_DAILY_LOG_FALLBACK = `---
-name: echoes_append_to_daily_log
-description: Append an intermediate technical note or decision to today's daily log immediately after completing a sub-task.
----
-
-# TOOL USAGE: echoes_append_to_daily_log
-You are equipped with a scratchpad tool to manage your cognitive load. You MUST use this tool to offload important context into \`EchoesVault/daily/YYYY-MM-DD.md\`.
-
-## \ud83c\udfaf EXACT TRIGGER CONDITIONS (WHEN TO CALL THIS TOOL)
-Do NOT use this tool randomly. You MUST invoke this tool IMMEDIATELY in the current response if ANY of the following specific events occur:
-1. **Task Completion:** We successfully finish a logical unit of work (e.g., a script works, a bug is verified as fixed, tests pass) BEFORE starting the next user request.
-2. **Context Switch:** The user asks to change focus (e.g., "Now let's work on the frontend" after we just worked on the backend).
-3. **Architectural Agreement:** We just agreed on a core rule, library choice, database schema, or API contract.
-4. **Explicit User Command:** The user explicitly tells you to "take a note", "remember this", "save our progress", or "log this".
-
-## \u26a0\ufe0f RULES
-1. **Be Concise:** Write ONLY dry facts and bullet points (e.g., "Refactored AuthGuard to use JWT refresh tokens"). No conversational filler.
-2. **Do Not Interrupt Flow:** Make the tool call silently or add a brief confirmation in your response like: *"Logged the AuthGuard update to the daily vault. Ready for the frontend."*
-3. **No File Overwrites:** This tool ONLY appends to the end of today's file.
-
-## \ud83d\udce5 PAYLOAD PARAMETERS
-- \`logEntry\`: (String) The markdown-formatted bullet points to append.
-`
-
-const SEARCH_VAULT_PAGES_FALLBACK = `---
-name: echoes_search_vault_pages
-description: Search the EchoesVault for specific concepts, keywords, or implementation details.
----
-
-# TOOL USAGE: echoes_search_vault_pages
-You are the EchoesVault Keeper. If you encounter a concept, API, or architectural pattern in our conversation that you suspect is documented but you lack the full context, use this tool BEFORE generating code.
-
-## \ud83c\udfaf WHEN TO USE
-- The user asks to modify an existing component, but its structure is not in your current context window.
-- You need to verify if an Architectural Decision Record (ADR) exists for a specific technology.
-- You want to fulfill the "Read-Before-Write" core rule.
-
-## \u26a0\ufe0f RULES
-1. **Targeted Queries:** Use specific technical keywords (e.g., "AuthGuard", "esp32 pinout", "database schema") rather than natural language questions.
-2. **Handle Deprecations:** If the search returns a file marked with \`> [!warning] DEPRECATED\`, look for the link to the new relevant file and read that instead.
-
-## \ud83d\udce5 PAYLOAD PARAMETERS
-- \`query\`: (String) The specific keyword or short phrase to search for across the \`pages/\` directory.
-`
-
-const CREATE_OR_UPDATE_PAGE_FALLBACK = `---
-name: echoes_create_or_update_page
-description: Atomically create a new markdown page or update an existing one in EchoesVault/pages/, automatically updating the index.
----
-
-# TOOL USAGE: echoes_create_or_update_page
-Use this tool when a new global concept has been defined or an existing component's architecture has fundamentally changed during our session. This allows you to update the encyclopedia immediately.
-
-## \ud83c\udfaf WHEN TO USE
-- We finalized a new database schema or API contract.
-- A major refactoring occurred, rendering previous documentation inaccurate.
-- You need to document a newly integrated library or hardware component.
-
-## \u26a0\ufe0f RULES
-1. **Strict YAML Frontmatter:** Every page MUST include a YAML metadata block at the top (type, stack, status).
-2. **Index Sync:** When you create a new file, you must provide a one-sentence description for the index. The system will automatically append it to \`index.md\`.
-3. **Deprecate, Don't Delete:** If you are rewriting an existing page completely because the logic changed, consider if you should instead create a new page (e.g., \`api-v2.md\`) and update the old one with a \`> [!warning] DEPRECATED\` callout via this tool.
-
-## \ud83d\udce5 PAYLOAD PARAMETERS
-- \`filename\`: (String) The exact filename without paths (e.g., \`auth-architecture.md\`).
-- \`content\`: (String) The full markdown content of the page, starting with the YAML frontmatter.
-- \`indexDescription\`: (String) A one-sentence description of the file. Required if this is a newly created file. Format: "- [[filename]]: description".
-`
-
 const ensureCommands = async (directory: string, commands: Record<string, string>): Promise<void> => {
   const cmdDir = path.join(directory, ".opencode", "commands")
   await fs.mkdir(cmdDir, { recursive: true })
@@ -388,25 +188,29 @@ const parseCommandFrontmatter = (cmd: string): { template: string; description?:
   return { template: match[2], description: frontmatter.description, agent: frontmatter.agent }
 }
 
+const statusActions = {
+  "echoes-init": "init",
+  "echoes-start": "start",
+  "echoes-end": "end",
+} as const
+
+type StatusAction = (typeof statusActions)[keyof typeof statusActions]
+
 const OpenCodeEchoes: Plugin = async ({ directory }) => {
   const pluginDir = path.dirname(new URL(import.meta.url).pathname)
 
-  const readPromptFile = async (relativePath: string, fallback: string): Promise<string> => {
-    try {
-      return await fs.readFile(path.join(pluginDir, "prompts", relativePath), "utf-8")
-    } catch {
-      return fallback
-    }
+  const readPromptFile = async (relativePath: string): Promise<string> => {
+    return await fs.readFile(path.join(pluginDir, "prompts", relativePath), "utf-8")
   }
 
-  const ECHOES_INIT = await readPromptFile("commands/echoes-init.md", ECHOES_INIT_FALLBACK)
-  const ECHOES_START = await readPromptFile("commands/echoes-start.md", ECHOES_START_FALLBACK)
-  const ECHOES_END = await readPromptFile("commands/echoes-end.md", ECHOES_END_FALLBACK)
-  const ECHOES_STATUS = await readPromptFile("commands/echoes-status.md", ECHOES_STATUS_FALLBACK)
+  const ECHOES_INIT = await readPromptFile("commands/echoes-init.md")
+  const ECHOES_START = await readPromptFile("commands/echoes-start.md")
+  const ECHOES_END = await readPromptFile("commands/echoes-end.md")
+  const ECHOES_STATUS = await readPromptFile("commands/echoes-status.md")
 
-  const APPEND_TO_DAILY_LOG = await readPromptFile("skills/echoes-append-to-daily-log.md", APPEND_TO_DAILY_LOG_FALLBACK)
-  const SEARCH_VAULT_PAGES = await readPromptFile("skills/echoes-search-vault-pages.md", SEARCH_VAULT_PAGES_FALLBACK)
-  const CREATE_OR_UPDATE_PAGE = await readPromptFile("skills/echoes-create-or-update-page.md", CREATE_OR_UPDATE_PAGE_FALLBACK)
+  const APPEND_TO_DAILY_LOG = await readPromptFile("skills/echoes-append-to-daily-log.md")
+  const SEARCH_VAULT_PAGES = await readPromptFile("skills/echoes-search-vault-pages.md")
+  const CREATE_OR_UPDATE_PAGE = await readPromptFile("skills/echoes-create-or-update-page.md")
 
   const commands: Record<string, string> = {
     "echoes-init.md": ECHOES_INIT,
@@ -433,10 +237,11 @@ const OpenCodeEchoes: Plugin = async ({ directory }) => {
   await ensureCommands(directory, commands)
   await ensureSkills(directory, skills)
 
+  // Sidebar status can change only through the matching user-invoked command.
+  const authorizedStatusActions = new Map<string, StatusAction>()
+
   const state = await readState(directory)
   state.pluginVersion = await getPluginVersion()
-  state.session.started = false
-  state.session.saved = false
   state.stats = await collectStats(paths)
   await writeState(directory, state)
 
@@ -448,10 +253,17 @@ const OpenCodeEchoes: Plugin = async ({ directory }) => {
         input.command[name.replace(".md", "")] = { template, description, agent }
       }
     },
+    "command.execute.before": async (input) => {
+      const command = input.command.replace(/^\//, "") as keyof typeof statusActions
+      const action = statusActions[command]
+      if (action) {
+        authorizedStatusActions.set(input.sessionID, action)
+      }
+    },
     tool: {
       commit_memory_to_echoes_vault: tool({
         description:
-          "Save session memory to EchoesVault. Writes a daily summary, creates new knowledge base pages, and updates the Vault index. Call this at session end to persist all context.",
+          "Save final session memory to EchoesVault. This succeeds only after the user explicitly runs /echoes-end; never call it merely because a task is complete.",
         args: {
           dailySummary: tool.schema
             .string()
@@ -489,7 +301,14 @@ const OpenCodeEchoes: Plugin = async ({ directory }) => {
             .optional()
             .describe("Lines to find and replace in place within EchoesVault/index.md"),
         },
-        async execute(args, _ctx) {
+        async execute(args, ctx) {
+          if (authorizedStatusActions.get(ctx.sessionID) !== "end") {
+            return [
+              "Final memory was not saved.",
+              "Only an explicit user /echoes-end command can save final memory and set the status to Memory Saved.",
+            ].join("\n")
+          }
+
           const today = getDateStr()
 
           await ensureVaultDirs(paths)
@@ -538,6 +357,7 @@ const OpenCodeEchoes: Plugin = async ({ directory }) => {
           st.session.lastSave = new Date().toISOString()
           st.stats = await collectStats(paths)
           await writeState(directory, st)
+          authorizedStatusActions.delete(ctx.sessionID)
 
           return [
             `✅ Memory committed to EchoesVault.`,
@@ -658,26 +478,36 @@ const OpenCodeEchoes: Plugin = async ({ directory }) => {
       }),
       echoes_activate_vault: tool({
         description:
-          "Mark the EchoesVault as activated. Called automatically during /echoes-init to register the vault in the status tracker.",
+          "Mark the EchoesVault as activated. This succeeds only after the user explicitly runs /echoes-init.",
         args: {},
-        async execute(_args, _ctx) {
+        async execute(_args, ctx) {
+          if (authorizedStatusActions.get(ctx.sessionID) !== "init") {
+            return "Vault status was not changed. Only an explicit user /echoes-init command can activate EchoesVault."
+          }
+
           const st = await readState(directory)
           st.initialized = true
           st.stats = await collectStats(paths)
           await writeState(directory, st)
+          authorizedStatusActions.delete(ctx.sessionID)
           return "EchoesVault activated."
         },
       }),
       echoes_start_session: tool({
         description:
-          "Mark the current EchoesVault session as started. Called automatically during /echoes-start to update the status tracker.",
+          "Mark the current EchoesVault session as started. This succeeds only after the user explicitly runs /echoes-start.",
         args: {},
-        async execute(_args, _ctx) {
+        async execute(_args, ctx) {
+          if (authorizedStatusActions.get(ctx.sessionID) !== "start") {
+            return "Vault status was not changed. Only an explicit user /echoes-start command can start an EchoesVault session."
+          }
+
           const st = await readState(directory)
           st.session.started = true
           st.session.saved = false
           st.session.lastStart = new Date().toISOString()
           await writeState(directory, st)
+          authorizedStatusActions.delete(ctx.sessionID)
           return "EchoesVault session started."
         },
       }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "echoes-vault-opencode",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "EchoesVault — persistent memory plugin for OpenCode. Obsidian-style knowledge base with daily logs, encyclopedia pages, and session resumption.",
   "type": "module",
   "main": "index.ts",

package/prompts/commands/echoes-end.md

@@ -6,6 +6,8 @@ agent: build
 # SYSTEM MESSAGE: Session Distillation (Distill & Save)
 Our current session is coming to an end. Your task is to crystallize the knowledge we've gained today and commit it to EchoesVault.
 
+This command is the user's explicit approval to finalize the session. Never invoke the final-memory tool outside this command, including after an ordinary task completion.
+
 Adhere to the principle of technical density: we do not need a transcript of our chat. We need dry architectural facts, bug fixes, applied configurations, and explicit decisions. Remember to use `> [!warning] DEPRECATED` tags if we rewrote legacy logic today.
 
 ## ACTION

package/tui.tsx

@@ -74,7 +74,7 @@ const tui: TuiPlugin = async (api) => {
         const statusDesc = () => {
           const s = state()
           if (!s || !s.initialized) return null
-          if (s.session.saved) return "Vault memorized session data"
+          if (s.session.saved) return "Final memory saved by /echoes-end"
           if (s.session.started) return null
           return null
         }