@rvboris/opencode-mempalace 0.4.0 → 0.5.0

package/README.md

@@ -14,7 +14,7 @@ Before every reply, the plugin searches your memory for relevant context. After
 
 ```
 You: "What build tool does this project use?"
-AI:  [searches memory] → "Bun. You decided that on April 10."
+AI:  [searches memory] → "Bun. This project uses Bun."
 ```
 
 ### The result
@@ -43,6 +43,57 @@ Add to `opencode.json`:
 
 That's it. Memory search, autosave, and both tools are active immediately.
 
+## How it works
+
+The plugin runs inside OpenCode as hooks + tools. A thin Python bridge calls the local `mempalace` package, which stores everything in ChromaDB with on-device `embeddinggemma-300m` embeddings. No cloud, no API keys.
+
+```mermaid
+flowchart TD
+    subgraph OC["OpenCode"]
+        U["User"]
+        M["AI Model"]
+    end
+
+    subgraph PL["TypeScript plugin (this repo)"]
+        H1["system.transform hook — injects: search memory first"]
+        H2["event hook — autosave on idle / compact / close"]
+        T["mempalace_memory (9 modes) + mempalace_status tools"]
+        HUD["TUI HUD — session stats badge"]
+    end
+
+    subgraph BR["Python bridge"]
+        A["mempalace_adapter.py — spawned per call"]
+    end
+
+    subgraph MP["mempalace package (local)"]
+        SRV["mcp_server / convo_miner"]
+        DB[("ChromaDB")]
+        EMB["embeddinggemma-300m ONNX"]
+    end
+
+    SF[("opencode_status.json")]
+
+    U -->|"message"| H1
+    H1 -->|"retrieval nudge"| M
+    M -->|"mempalace_memory search"| T
+    T --> A --> SRV --> EMB
+    SRV --> DB
+    A --> T --> M
+    M -->|"answers with context"| U
+    T -.->|"counters"| SF
+    HUD -.->|"reads"| SF
+    M -.->|"session idle"| H2
+    H2 -.->|"mine_messages"| A
+```
+
+**Retrieval** — before each reply, the `system.transform` hook nudges the model to search memory first. The model calls `mempalace_memory [search]`, the bridge forwards it to `mempalace`, and results (vector + BM25) come back as context for the answer.
+
+**Autosave** — on session idle, compaction, or close, the `event` hook mines the transcript for durable facts and saves them to the right memory area via `mine_messages`. Counters are written to `opencode_status.json`, which the TUI HUD reads.
+
+**Keyword save** — when the user says "remember this" / "note that", the plugin arms a save instruction so the model persists the fact immediately via `mempalace_memory [save]`.
+
+The plugin talks to `mempalace` through a local Python bridge (`bridge/mempalace_adapter.py`), spawned per call — it does **not** require the MemPalace MCP server.
+
 ## Features
 
 ### Hidden retrieval
@@ -51,18 +102,27 @@ Before each answer, the plugin injects a search instruction so the model checks
 
 ### Background autosave
 
-On session idle, compaction, or close, the plugin mines the conversation transcript for durable facts and saves them to the right memory area automatically.
+On session idle, compaction, or close, the plugin mines the conversation transcript for durable facts and saves them to the right memory area automatically. Low-signal fragments are filtered before mining, so prompt leftovers like `re.`, `ls>`, or mostly punctuation are skipped instead of becoming junk memory.
+
+### Reliable local bridge
+
+Write-like operations (`save`, autosave mining, diary writes, graph writes, checkpoints, deletes) are serialized through the adapter and retried on MemPalace palace-lock contention (`held by PID`). Search calls still run without that write queue.
 
 ### `mempalace_memory` — the one tool
 
-Four modes, one interface:
+Nine modes, one interface:
 
 | Mode | Purpose |
 |---|---|
 | `save` | Store a preference, fact, or decision |
-| `search` | Find relevant memory by query |
+| `search` | Find relevant memory by query (optional `source_file` filter) |
 | `kg_add` | Add a structured fact to the knowledge graph |
 | `diary_write` | Save a short work note |
+| `checkpoint` | Batch-save multiple items + optional diary in one call |
+| `delete` | Remove a memory by drawer ID |
+| `delete_by_source` | Bulk-remove memories by source file (dry-run by default) |
+| `kg_query` | Search the knowledge graph for an entity's relationships |
+| `diary_read` | Read recent diary entries |
 
 Examples:
 
@@ -78,6 +138,14 @@ mempalace_memory  mode: search  scope: project  room: decisions  query: build to
 mempalace_memory  mode: kg_add  subject: my-repo  predicate: uses  object: bun
 ```
 
+```text
+mempalace_memory  mode: checkpoint  items: [{"wing":"wing_user","room":"preferences","content":"likes dark mode"},{"wing":"wing_project","room":"decisions","content":"uses bun"}]
+```
+
+```text
+mempalace_memory  mode: delete_by_source  source_file: /data/import.jsonl  dry_run: true
+```
+
 ### `mempalace_status` — visible proof
 
 Check whether the plugin is actually helping:
@@ -93,10 +161,26 @@ Shows retrieval hit rate, last autosave outcome, memory previews, and cumulative
 A compact session stats line appears in the OpenCode prompt area:
 
 ```
-MEM hits 3 · saved 2 · failed 0 · writes 1
+MEM helps 3
+MEM cited 2
+MEM found 5
+MEM no hits
+MEM searched
+MEM quiet
+MEM helps 1 · fail 1
 ```
 
-Color-coded indicators for `SKIPPED` and `FAILED` states. Requires a `tui.json` entry (see below).
+- `MEM helps N` — memory improved or saved time (the most useful verdicts)
+- `MEM cited N` — memory was mentioned but did not change the answer
+- `MEM no help` — retrieval happened but had no effect
+- `MEM unknown` — model omitted the verdict tag
+- `MEM found N` — retrieval returned N memories and no judge verdict is recorded yet
+- `MEM no hits` — retrieval ran and returned no memories
+- `MEM searched` — retrieval ran, but result count is unavailable
+- `MEM quiet` — no retrieval activity yet
+- `· fail N` / `· skip N` — shown only when autosave has errors
+
+The HUD combines retrieval evidence with a **judge signal**. When the model reports `[memory: verdict]`, the plugin parses it after each turn and strips it before saving. If no verdict is available, retrieval results still show as `found`, `no hits`, or `searched`. Requires a `tui.json` entry (see below).
 
 ## Memory areas
 
@@ -154,7 +238,7 @@ To enable the prompt-area stats display, add a `tui.json` in your OpenCode confi
 {
   "$schema": "https://opencode.ai/tui.json",
   "plugin": [
-    "file:///path/to/mempalace-autosave/plugin/tui/index.tsx"
+    "file:///path/to/opencode-mempalace/plugin/tui/index.tsx"
   ]
 }
 ```
@@ -168,21 +252,6 @@ Or when installed from npm, use the package entry:
 }
 ```
 
-## How it works
-
-```
-User message
-  → system hook injects "search memory first" instruction
-  → model calls mempalace_memory [search]
-  → results inform the answer
-
-Session ends / idles
-  → event hook mines transcript
-  → Python adapter saves durable facts via MemPalace
-```
-
-The plugin uses a local Python bridge (`bridge/mempalace_adapter.py`) to communicate with MemPalace. It does **not** require the MemPalace MCP server.
-
 ## Compatibility
 
 | Requirement | Version |
@@ -194,14 +263,14 @@ The plugin uses a local Python bridge (`bridge/mempalace_adapter.py`) to communi
 
 ## Project docs
 
-- [Changelog](./CHANGELOG.md) — release history
+- [Changelog](./CHANGELOG.md) — release notes
 - [Contributing](./CONTRIBUTING.md) — changelog rules
 
 ## Local development
 
 ```bash
 git clone https://github.com/rvboris/opencode-mempalace.git
-cd opencode-mempalace/mempalace-autosave
+cd opencode-mempalace
 npm install
 npm run build
 ```
@@ -210,7 +279,7 @@ Load from source in `opencode.json`:
 
 ```jsonc
 {
-  "plugin": ["file:///ABSOLUTE/PATH/TO/mempalace-autosave/plugin/index.ts"]
+  "plugin": ["file:///ABSOLUTE/PATH/TO/opencode-mempalace/plugin/index.ts"]
 }
 ```
 

package/README.ru.md

@@ -14,7 +14,7 @@
 
 ```
 Ты: "Какую систему сборки мы используем?"
-ИИ:  [ищет в памяти] → "Bun. Это решение приняли 10 апреля."
+ИИ:  [ищет в памяти] → "Bun. Этот проект использует Bun."
 ```
 
 ### Результат
@@ -43,6 +43,57 @@ mempalace init ~/.mempalace/palace
 
 Готово. Поиск по памяти, автосохранение и оба инструмента активны сразу.
 
+## Как это работает
+
+Плагин работает внутри OpenCode как набор хуков и тулов. Тонкий Python-мост вызывает локальный пакет `mempalace`, который хранит всё в ChromaDB с локальными эмбеддингами `embeddinggemma-300m` на устройстве. Без облака, без API-ключей.
+
+```mermaid
+flowchart TD
+    subgraph OC["OpenCode"]
+        U["Пользователь"]
+        M["ИИ-модель"]
+    end
+
+    subgraph PL["TypeScript-плагин (этот репо)"]
+        H1["system.transform хук — подставляет: сначала ищи в памяти"]
+        H2["event хук — автосохранение при простое / компактизации / закрытии"]
+        T["тулы mempalace_memory (9 режимов) + mempalace_status"]
+        HUD["TUI HUD — бейдж статистики сессии"]
+    end
+
+    subgraph BR["Python-мост"]
+        A["mempalace_adapter.py — запускается на каждый вызов"]
+    end
+
+    subgraph MP["пакет mempalace (локально)"]
+        SRV["mcp_server / convo_miner"]
+        DB[("ChromaDB")]
+        EMB["embeddinggemma-300m ONNX"]
+    end
+
+    SF[("opencode_status.json")]
+
+    U -->|"сообщение"| H1
+    H1 -->|"подсказка поиска"| M
+    M -->|"mempalace_memory search"| T
+    T --> A --> SRV --> EMB
+    SRV --> DB
+    A --> T --> M
+    M -->|"ответ с контекстом"| U
+    T -.->|"счётчики"| SF
+    HUD -.->|"читает"| SF
+    M -.->|"простой сессии"| H2
+    H2 -.->|"mine_messages"| A
+```
+
+**Поиск (retrieval)** — перед каждым ответом хук `system.transform` подталкивает модель сначала проверить память. Модель вызывает `mempalace_memory [search]`, мост прокидывает вызов в `mempalace`, результаты (векторный + BM25-поиск) возвращаются как контекст для ответа.
+
+**Автосохранение** — при простое сессии, компактизации или закрытии хук `event` анализирует транскрипт, извлекает устойчивые факты и сохраняет их в нужную область памяти через `mine_messages`. Счётчики пишутся в `opencode_status.json`, который читает TUI HUD.
+
+**Сохранение по ключевому слову** — когда пользователь говорит «запомни это» / «отметь», плагин активирует инструкцию сохранения, чтобы модель сразу сохранила факт через `mempalace_memory [save]`.
+
+Плагин обращается к `mempalace` через локальный Python-мост (`bridge/mempalace_adapter.py`), запускаемый на каждый вызов, — MCP-сервер MemPalace ему **не нужен**.
+
 ## Возможности
 
 ### Скрытый поиск
@@ -51,18 +102,27 @@ mempalace init ~/.mempalace/palace
 
 ### Фоновое автосохранение
 
-При простое сессии, компактизации или завершении — плагин анализирует транскрипт, извлекает устойчивые факты и сохраняет их в нужную область памяти.
+При простое сессии, компактизации или завершении — плагин анализирует транскрипт, извлекает устойчивые факты и сохраняет их в нужную область памяти. Низкосигнальные фрагменты фильтруются до майнинга, поэтому остатки вроде `re.`, `ls>` или почти одна пунктуация не становятся мусорной памятью.
+
+### Надёжный локальный мост
+
+Операции записи (`save`, автосохранение, diary, граф, checkpoints, удаления) проходят через очередь адаптера и повторяются при конфликте palace-lock (`held by PID`). Поиск выполняется без этой очереди.
 
 ### `mempalace_memory` — единый инструмент
 
-Четыре режима, один интерфейс:
+Девять режимов, один интерфейс:
 
 | Режим | Назначение |
 |---|---|
 | `save` | Сохранить предпочтение, факт или решение |
-| `search` | Найти релевантную память по запросу |
+| `search` | Найти релевантную память по запросу (опциональный фильтр `source_file`) |
 | `kg_add` | Добавить структурированный факт в граф знаний |
 | `diary_write` | Записать короткую рабочую заметку |
+| `checkpoint` | Пакетное сохранение нескольких записей + опциональной diary за один вызов |
+| `delete` | Удалить память по ID записи |
+| `delete_by_source` | Массовое удаление памяти по файлу-источнику (dry-run по умолчанию) |
+| `kg_query` | Поиск по графу знаний — связи сущности |
+| `diary_read` | Чтение недавних записей diary |
 
 Примеры:
 
@@ -78,6 +138,14 @@ mempalace_memory  mode: search  scope: project  room: decisions  query: сист
 mempalace_memory  mode: kg_add  subject: my-repo  predicate: uses  object: bun
 ```
 
+```text
+mempalace_memory  mode: checkpoint  items: [{"wing":"wing_user","room":"preferences","content":"любит тёмную тему"},{"wing":"wing_project","room":"decisions","content":"использует bun"}]
+```
+
+```text
+mempalace_memory  mode: delete_by_source  source_file: /data/import.jsonl  dry_run: true
+```
+
 ### `mempalace_status` — видимое доказательство
 
 Проверь, реально ли плагин помогает:
@@ -93,10 +161,26 @@ mempalace_status
 Компактная строка статистики текущей сессии в области ввода OpenCode:
 
 ```
-MEM hits 3 · saved 2 · failed 0 · writes 1
+MEM helps 3
+MEM cited 2
+MEM found 5
+MEM no hits
+MEM searched
+MEM quiet
+MEM helps 1 · fail 1
 ```
 
-Цветовые индикаторы для `SKIPPED` и `FAILED`. Требует записи в `tui.json` (см. ниже).
+- `MEM helps N` — память улучшила ответ или сэкономила время (самые полезные вердикты)
+- `MEM cited N` — память была упомянута, но ответ не изменился
+- `MEM no help` — поиск был, но без эффекта
+- `MEM unknown` — модель не поставила тег с вердиктом
+- `MEM found N` — поиск вернул N записей, но judge-вердикт ещё не записан
+- `MEM no hits` — поиск был, но ничего не нашёл
+- `MEM searched` — поиск был, но количество результатов недоступно
+- `MEM quiet` — поиск по памяти ещё не выполнялся
+- `· fail N` / `· skip N` — показываются только при ошибках автосохранения
+
+HUD совмещает факт поиска и **judge-сигнал**. Когда модель сообщает `[memory: verdict]`, плагин парсит тег после хода и вырезает перед сохранением. Если вердикта нет, результаты поиска всё равно видны как `found`, `no hits` или `searched`. Требует записи в `tui.json` (см. ниже).
 
 ## Области памяти
 
@@ -154,7 +238,7 @@ MEM hits 3 · saved 2 · failed 0 · writes 1
 {
   "$schema": "https://opencode.ai/tui.json",
   "plugin": [
-    "file:///путь/до/mempalace-autosave/plugin/tui/index.tsx"
+    "file:///путь/до/opencode-mempalace/plugin/tui/index.tsx"
   ]
 }
 ```
@@ -168,21 +252,6 @@ MEM hits 3 · saved 2 · failed 0 · writes 1
 }
 ```
 
-## Как это работает
-
-```
-Сообщение пользователя
-  → системный хук подставляет «сначала проверь память»
-  → модель вызывает mempalace_memory [search]
-  → результаты влияют на ответ
-
-Сессия завершается / простаивает
-  → хук событий анализирует транскрипт
-  → Python-адаптер сохраняет устойчивые факты через MemPalace
-```
-
-Плагин использует локальную Python-прослойку (`bridge/mempalace_adapter.py`) для работы с MemPalace. Ему **не нужен** MCP-сервер MemPalace.
-
 ## Совместимость
 
 | Требование | Версия |
@@ -194,14 +263,14 @@ MEM hits 3 · saved 2 · failed 0 · writes 1
 
 ## Документация проекта
 
-- [Changelog](./CHANGELOG.md) — история изменений
+- [Changelog](./CHANGELOG.md) — заметки к релизам
 - [Contributing](./CONTRIBUTING.md) — правила ведения changelog
 
 ## Локальная разработка
 
 ```bash
 git clone https://github.com/rvboris/opencode-mempalace.git
-cd opencode-mempalace/mempalace-autosave
+cd opencode-mempalace
 npm install
 npm run build
 ```
@@ -210,7 +279,7 @@ npm run build
 
 ```jsonc
 {
-  "plugin": ["file:///ABSOLUTE/PATH/TO/mempalace-autosave/plugin/index.ts"]
+  "plugin": ["file:///ABSOLUTE/PATH/TO/opencode-mempalace/plugin/index.ts"]
 }
 ```
 

package/dist/bridge/mempalace_adapter.py

@@ -37,6 +37,7 @@ def main() -> int:
                 limit=payload.get("limit", 5),
                 wing=payload.get("wing"),
                 room=payload.get("room"),
+                source_file=payload.get("source_file"),
             )
         elif mode == "save":
             result = mcp_server.tool_add_drawer(
@@ -78,6 +79,31 @@ def main() -> int:
                 "mode": "mine_messages",
                 "wing": payload.get("wing"),
             }
+        elif mode == "delete":
+            result = mcp_server.tool_delete_drawer(drawer_id=payload["drawer_id"])
+        elif mode == "delete_by_source":
+            result = mcp_server.tool_delete_by_source(
+                source_file=payload["source_file"],
+                dry_run=payload.get("dry_run", True),
+            )
+        elif mode == "kg_query":
+            result = mcp_server.tool_kg_query(
+                entity=payload["entity"],
+                as_of=payload.get("as_of"),
+                direction=payload.get("direction", "both"),
+            )
+        elif mode == "diary_read":
+            result = mcp_server.tool_diary_read(
+                agent_name=payload.get("agent_name", "opencode"),
+                last_n=payload.get("last_n", 10),
+                wing=payload.get("wing", ""),
+            )
+        elif mode == "checkpoint":
+            result = mcp_server.tool_checkpoint(
+                items=payload["items"],
+                diary=payload.get("diary"),
+                dedup_threshold=payload.get("dedup_threshold", 0.9),
+            )
         else:
             result = {"success": False, "error": f"Unknown mode: {mode}"}
     except Exception as error:

package/dist/plugin/hooks/event.js

@@ -1,12 +1,12 @@
-import { AutosaveReason, AutosaveStatus, buildMessageSnapshot, getMessageSnapshot, getSessionState, markAutosaveComplete, markKeywordSavePending, markFailed, markRetrievalPending, setMessageSnapshot, shouldScheduleAutosave, } from "../lib/autosave";
+import { AutosaveReason, AutosaveStatus, buildAutosaveMiningTranscript, buildMessageSnapshot, getMessageSnapshot, getSessionState, markAutosaveComplete, markKeywordSavePending, markFailed, markRetrievalPending, setMessageSnapshot, shouldScheduleAutosave, } from "../lib/autosave";
 import { executeAdapter } from "../lib/adapter";
 import { loadConfig } from "../lib/config";
 import { COMPACTION_CONTEXT_MESSAGE, DEFAULT_AGENT_NAME, LOG_MESSAGES } from "../lib/constants";
-import { sanitizeText } from "../lib/derive";
+import { sanitizeText, stripJudgeTag, parseJudgeTag } from "../lib/derive";
 import { getProjectName, loadSessionMessages } from "../lib/opencode";
 import { redactSecrets } from "../lib/privacy";
 import { getProjectScope } from "../lib/scope";
-import { recordAutosave } from "../lib/status";
+import { recordAutosave, recordRetrievalJudge } from "../lib/status";
 import { writeLog } from "../lib/log";
 import { SESSION_EVENT_TYPES } from "../lib/types";
 const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -61,6 +61,16 @@ export const eventHooks = (ctx) => {
                 }
                 if (!isAutosaveTriggerEventType(event.type))
                     return;
+                // Parse judge tag from last assistant message before anything else.
+                // Only when a retrieval happened this turn (retrievalPending was set).
+                const state = getSessionState(sessionId);
+                if (state.retrievalPending) {
+                    const snapshot = getMessageSnapshot(sessionId);
+                    if (snapshot) {
+                        const verdict = (parseJudgeTag(snapshot.transcript) ?? "unknown");
+                        await recordRetrievalJudge({ sessionId, verdict });
+                    }
+                }
                 await writeLog("INFO", LOG_MESSAGES.autosaveTriggerReceived, {
                     eventType: event.type,
                     sessionId,
@@ -103,8 +113,9 @@ export const eventHooks = (ctx) => {
                     });
                     return;
                 }
-                const sanitizedTranscript = sanitizeText(redactSecrets(transcript));
-                if (!sanitizedTranscript.trim()) {
+                const sanitizedTranscript = sanitizeText(redactSecrets(stripJudgeTag(transcript)));
+                const miningTranscript = buildAutosaveMiningTranscript(sanitizedTranscript);
+                if (!miningTranscript) {
                     markAutosaveComplete(sessionId, userDigest, transcriptDigest, AutosaveStatus.Noop);
                     await recordAutosave({
                         sessionId,
@@ -118,7 +129,7 @@ export const eventHooks = (ctx) => {
                 const wing = getProjectScope(getProjectName(ctx.project), config.projectWingPrefix).wing;
                 const result = await executeAdapter(ctx.$, {
                     mode: "mine_messages",
-                    transcript: sanitizedTranscript,
+                    transcript: miningTranscript,
                     wing,
                     extract_mode: config.autoMineExtractMode,
                     agent: DEFAULT_AGENT_NAME,

package/dist/plugin/lib/adapter.d.ts

@@ -1,2 +1,23 @@
+import { spawn as nodeSpawn } from "node:child_process";
 import type { AdapterRequest, AdapterResponse } from "./types";
+/**
+ * Resolve the Python interpreter that owns the `mempalace` package.
+ *
+ * Resolution order:
+ *   1. `MEMPALACE_ADAPTER_PYTHON` env (explicit override).
+ *   2. The shebang of the `mempalace` CLI on $PATH — a console_script always
+ *      points at the interpreter that installed the package (pipx, uv-tool,
+ *      pip --user, or a venv), so this is the most reliable auto-detection.
+ *   3. `python3` then `python` on $PATH (best-effort; may still lack mempalace).
+ *
+ * Returns null if nothing usable was found.
+ */
+export declare const resolvePython: () => string | null;
+/** Test-only: clear the cached interpreter so env/PATH changes are re-read. */
+export declare const resetPythonResolver: () => void;
+declare let adapterDelay: (ms: number) => Promise<void>;
+export declare const setAdapterDelayForTests: (delay: typeof adapterDelay) => void;
+export declare const setAdapterSpawnForTests: (spawn: typeof nodeSpawn) => void;
+export declare const resetAdapterTestHooks: () => void;
 export declare const executeAdapter: (_shell: unknown, payload: AdapterRequest, retries?: number) => Promise<AdapterResponse>;
+export {};