@rvboris/opencode-mempalace 0.2.0 → 0.3.0

package/README.md

@@ -1,29 +1,39 @@
-# OpenCode MemPalace Plugin
+# @rvboris/opencode-mempalace
 
-OpenCode memory layer with private retrieval and safe autosave.
+**Persistent memory for OpenCode — zero config, visible results.**
+
+Your AI coding assistant forgets everything between sessions. This plugin fixes that. It silently saves what matters and finds it when needed — no extra prompts, no manual effort.
 
 [Русская версия](./README.ru.md)
 
-## Why it matters
+---
+
+## What it does
+
+Before every reply, the plugin searches your memory for relevant context. After every session, it quietly saves durable knowledge. You never have to say "remember this" — but when you do, it listens.
+
+```
+You: "What build tool does this project use?"
+AI:  [searches memory] → "Bun. You decided that on April 10."
+```
 
-Keep OpenCode context-aware without extra prompts.
+### The result
 
-- **Finds relevant memory automatically** before normal replies
-- **Saves durable knowledge quietly** in the background
-- **Keeps writes safe** through one controlled tool
-- **Protects sensitive data** before anything is stored
+- Answers informed by your past decisions, preferences, and project history
+- No repeated explanations across sessions
+- Privacy-first: secrets and private blocks are never stored
+- Works entirely locally — no cloud, no API keys, no MCP server
 
 ## Quick start
 
-Install MemPalace:
+**Prerequisites:** [OpenCode](https://opencode.ai) and Python 3.10+ with pip.
 
 ```bash
 pip install mempalace
-mempalace init <dir>
-mempalace mine <dir>
+mempalace init ~/.mempalace/palace
 ```
 
-Add the plugin to `opencode.json`:
+Add to `opencode.json`:
 
 ```json
 {
@@ -31,96 +41,88 @@ Add the plugin to `opencode.json`:
 }
 ```
 
-That is enough to enable memory search, autosave, and `mempalace_memory`.
+That's it. Memory search, autosave, and both tools are active immediately.
 
-## What you get
+## Features
 
-- hidden memory lookup before answers
-- autosave on session lifecycle events
-- separate user and project memory
-- one safe memory tool for the model
-- local Python bridge to MemPalace
+### Hidden retrieval
 
-The plugin does **not** require the MemPalace MCP server.
+Before each answer, the plugin injects a search instruction so the model checks your memory first. No tool call noise in the chat — the context just appears.
 
-## The one tool: `mempalace_memory`
+### Background autosave
 
-This is the only tool the model needs.
+On session idle, compaction, or close, the plugin mines the conversation transcript for durable facts and saves them to the right memory area automatically.
 
-### Modes
+### `mempalace_memory` — the one tool
 
-- **`save`** — store a durable preference, fact, or decision
-- **`search`** — find relevant memory by query
-- **`kg_add`** — add a structured fact to the knowledge graph
-- **`diary_write`** — save a short work note or daily log
-- **`mine_messages`** — internal autosave mode used by the plugin
+Four modes, one interface:
 
-### Examples
+| Mode | Purpose |
+|---|---|
+| `save` | Store a preference, fact, or decision |
+| `search` | Find relevant memory by query |
+| `kg_add` | Add a structured fact to the knowledge graph |
+| `diary_write` | Save a short work note |
 
-Save a user preference:
+Examples:
 
 ```text
-mempalace_memory
-  mode: save
-  scope: user
-  room: preferences
-  content: Prefers concise responses and numbered steps.
+mempalace_memory  mode: save  scope: user  room: preferences  content: Prefers concise responses.
 ```
 
-Save a project decision:
+```text
+mempalace_memory  mode: search  scope: project  room: decisions  query: build tool
+```
 
 ```text
-mempalace_memory
-  mode: save
-  scope: project
-  room: decisions
-  content: Use Bun for builds and tests.
+mempalace_memory  mode: kg_add  subject: my-repo  predicate: uses  object: bun
 ```
 
-Search memory:
+### `mempalace_status` — visible proof
+
+Check whether the plugin is actually helping:
 
 ```text
-mempalace_memory
-  mode: search
-  scope: project
-  room: workflow
-  query: build command
-  limit: 3
+mempalace_status
 ```
 
-Add a graph fact:
+Shows retrieval hit rate, last autosave outcome, memory previews, and cumulative counters. Use `verbose: true` for full detail.
+
+### TUI HUD — memory stats in your prompt
+
+A compact session stats line appears in the OpenCode prompt area:
 
-```text
-mempalace_memory
-  mode: kg_add
-  subject: my-repo
-  predicate: uses
-  object: bun
 ```
+MEM hits 3 · saved 2 · failed 0 · writes 1
+```
+
+Color-coded indicators for `SKIPPED` and `FAILED` states. Requires a `tui.json` entry (see below).
 
 ## Memory areas
 
-**User memory**
+**User memory** — cross-project preferences and habits:
 
-- `preferences`
-- `workflow`
-- `communication`
+- `preferences` — coding style, communication preferences
+- `workflow` — working patterns, tool choices
+- `communication` — language, response format
 
-Use it for stable cross-project habits and preferences.
+**Project memory** — repository-specific knowledge:
 
-**Project memory**
+- `architecture` — design decisions, patterns
+- `workflow` — build commands, CI config
+- `decisions` — ADRs, trade-offs
+- `bugs` — known issues, workarounds
+- `setup` — environment setup, dependencies
 
-- `architecture`
-- `workflow`
-- `decisions`
-- `bugs`
-- `setup`
+## Privacy
 
-Use it for repository-specific knowledge.
+- `<private>...</private>` blocks are respected and never stored
+- Common secrets (API keys, tokens, passwords) are redacted before writes
+- Fully private content is skipped entirely
 
 ## Configuration
 
-Optional config file: `~/.config/opencode/mempalace.jsonc`
+Optional config file at `~/.config/opencode/mempalace.jsonc`:
 
 ```jsonc
 {
@@ -133,54 +135,93 @@ Optional config file: `~/.config/opencode/mempalace.jsonc`
 }
 ```
 
-Useful environment variables:
-
-- `MEMPALACE_AUTOSAVE_ENABLED`
-- `MEMPALACE_RETRIEVAL_ENABLED`
-- `MEMPALACE_KEYWORD_SAVE_ENABLED`
-- `MEMPALACE_PRIVACY_REDACTION_ENABLED`
-- `MEMPALACE_AUTOSAVE_LOG_FILE`
-- `MEMPALACE_ADAPTER_PYTHON`
-
-## Privacy
-
-- respects `<private>...</private>` blocks
-- redacts common secrets before writes
-- skips fully private content
-
-## Project docs
+Environment variables:
 
-- Release history: [`CHANGELOG.md`](./CHANGELOG.md)
-- Changelog rules: [`CONTRIBUTING.md#changelog`](./CONTRIBUTING.md#changelog)
+| Variable | Purpose |
+|---|---|
+| `MEMPALACE_AUTOSAVE_ENABLED` | Toggle background autosave |
+| `MEMPALACE_RETRIEVAL_ENABLED` | Toggle hidden retrieval |
+| `MEMPALACE_KEYWORD_SAVE_ENABLED` | Toggle keyword-triggered saves |
+| `MEMPALACE_PRIVACY_REDACTION_ENABLED` | Toggle secret redaction |
+| `MEMPALACE_ADAPTER_PYTHON` | Path to Python binary |
+| `MEMPALACE_ADAPTER_TIMEOUT_MS` | Adapter timeout (default 15000) |
 
-## Local development
+## TUI HUD setup
 
-Load from source:
+To enable the prompt-area stats display, add a `tui.json` in your OpenCode config directory:
 
-```jsonc
+```json
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/tui.json",
   "plugin": [
-    "file:///ABSOLUTE/PATH/TO/mempalace-autosave/plugin/index.ts"
+    "file:///path/to/mempalace-autosave/plugin/tui/index.tsx"
   ]
 }
 ```
 
-Build:
+Or when installed from npm, use the package entry:
+
+```json
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": ["@rvboris/opencode-mempalace/tui"]
+}
+```
+
+## 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 |
+|---|---|
+| OpenCode | latest |
+| Python | 3.10+ |
+| MemPalace | 3.3+ |
+| OS | macOS, Linux, Windows |
+
+## Project docs
+
+- [Changelog](./CHANGELOG.md) — release history
+- [Contributing](./CONTRIBUTING.md) — changelog rules
+
+## Local development
 
 ```bash
+git clone https://github.com/rvboris/opencode-mempalace.git
+cd opencode-mempalace/mempalace-autosave
+npm install
 npm run build
 ```
 
-Debug logs:
+Load from source in `opencode.json`:
 
-```bash
-opencode --log-level DEBUG
+```jsonc
+{
+  "plugin": ["file:///ABSOLUTE/PATH/TO/mempalace-autosave/plugin/index.ts"]
+}
 ```
 
-File log: `~/.mempalace/opencode_autosave.log`
+Debug: `opencode --log-level DEBUG` or check `~/.mempalace/opencode_autosave.log`.
 
 ## Links
 
 - OpenCode: https://opencode.ai
 - MemPalace: https://github.com/milla-jovovich/mempalace
+- npm: https://www.npmjs.com/package/@rvboris/opencode-mempalace
+
+## License
+
+MIT

package/README.ru.md

@@ -1,29 +1,39 @@
-# Плагин MemPalace для OpenCode
+# @rvboris/opencode-mempalace
 
-Слой памяти для OpenCode: скрытый поиск по памяти и безопасное автосохранение.
+**Персистентная память для OpenCode — нулевая конфигурация, видимый результат.**
+
+Твой ИИ-ассистент забывает всё между сессиями. Этот плагин это исправляет. Он незаметно сохраняет важное и находит его, когда нужно — без лишних подсказок и ручной работы.
 
 [English version](./README.md)
 
-## Зачем он нужен
+---
+
+## Что он делает
+
+Перед каждым ответом плагин ищет в памяти релевантный контекст. После каждой сессии — тихо сохраняет устойчивые знания. Тебе не нужно говорить «запомни это» — но если скажешь, плагин услышит.
+
+```
+Ты: "Какую систему сборки мы используем?"
+ИИ:  [ищет в памяти] → "Bun. Это решение приняли 10 апреля."
+```
 
-Чтобы OpenCode отвечал с учётом прошлого контекста — без лишних подсказок и без шума в чате.
+### Результат
 
-- **Сам ищет нужную память** перед обычным ответом
-- **Тихо сохраняет важное** по ходу работы
-- **Пишет безопасно** через один контролируемый инструмент
-- **Учитывает приватность** перед сохранением
+- Ответы, опирающиеся на прошлые решения, предпочтения и историю проекта
+- Не нужно повторять объяснения от сессии к сессии
+- Приватность: секреты и приватные блоки никогда не сохраняются
+- Работает полностью локально — без облака, API-ключей и MCP-сервера
 
 ## Быстрый старт
 
-Установи MemPalace:
+**Требования:** [OpenCode](https://opencode.ai) и Python 3.10+ с pip.
 
 ```bash
 pip install mempalace
-mempalace init <dir>
-mempalace mine <dir>
+mempalace init ~/.mempalace/palace
 ```
 
-Добавь плагин в `opencode.json`:
+Добавь в `opencode.json`:
 
 ```json
 {
@@ -31,92 +41,84 @@ mempalace mine <dir>
 }
 ```
 
-Этого достаточно, чтобы включить поиск по памяти, автосохранение и `mempalace_memory`.
+Готово. Поиск по памяти, автосохранение и оба инструмента активны сразу.
 
-## Что ты получаешь
+## Возможности
 
-- скрытый поиск по памяти перед ответом
-- автосохранение на событиях сессии
-- раздельную память для пользователя и проекта
-- один безопасный инструмент для работы с памятью
-- локальную Python-прослойку для MemPalace
+### Скрытый поиск
 
-Самому плагину **не нужен** сервер MCP от MemPalace.
+Перед каждым ответом плагин подставляет инструкцию «сначала проверь память». Модель видит релевантный контекст без лишнего шума в чате.
 
-## Основной инструмент: `mempalace_memory`
+### Фоновое автосохранение
 
-Это единственный инструмент, который нужен модели.
+При простое сессии, компактизации или завершении — плагин анализирует транскрипт, извлекает устойчивые факты и сохраняет их в нужную область памяти.
 
-### Режимы
+### `mempalace_memory` — единый инструмент
 
-- **`save`** — сохранить устойчивый факт, предпочтение или решение
-- **`search`** — найти релевантную память по запросу
-- **`kg_add`** — добавить структурированный факт в граф знаний
-- **`diary_write`** — записать короткую рабочую заметку
-- **`mine_messages`** — внутренний режим автосохранения, который использует сам плагин
+Четыре режима, один интерфейс:
 
-### Примеры
+| Режим | Назначение |
+|---|---|
+| `save` | Сохранить предпочтение, факт или решение |
+| `search` | Найти релевантную память по запросу |
+| `kg_add` | Добавить структурированный факт в граф знаний |
+| `diary_write` | Записать короткую рабочую заметку |
 
-Сохранить пользовательское предпочтение:
+Примеры:
 
 ```text
-mempalace_memory
-  mode: save
-  scope: user
-  room: preferences
-  content: Prefers concise responses and numbered steps.
+mempalace_memory  mode: save  scope: user  room: preferences  content: Предпочитает краткие ответы.
 ```
 
-Сохранить проектное решение:
+```text
+mempalace_memory  mode: search  scope: project  room: decisions  query: система сборки
+```
 
 ```text
-mempalace_memory
-  mode: save
-  scope: project
-  room: decisions
-  content: Use Bun for builds and tests.
+mempalace_memory  mode: kg_add  subject: my-repo  predicate: uses  object: bun
 ```
 
-Найти память:
+### `mempalace_status` — видимое доказательство
+
+Проверь, реально ли плагин помогает:
 
 ```text
-mempalace_memory
-  mode: search
-  scope: project
-  room: workflow
-  query: build command
-  limit: 3
+mempalace_status
 ```
 
-Добавить факт в граф знаний:
+Показывает процент попаданий при поиске, последний результат автосохранения, превью памяти и накопительные счётчики. Для полного отчёта — `verbose: true`.
+
+### TUI HUD — статистика памяти в строке промпта
+
+Компактная строка статистики текущей сессии в области ввода OpenCode:
 
-```text
-mempalace_memory
-  mode: kg_add
-  subject: my-repo
-  predicate: uses
-  object: bun
 ```
+MEM hits 3 · saved 2 · failed 0 · writes 1
+```
+
+Цветовые индикаторы для `SKIPPED` и `FAILED`. Требует записи в `tui.json` (см. ниже).
 
 ## Области памяти
 
-**Память пользователя**
+**Память пользователя** — кросс-проектные предпочтения и привычки:
 
-- `preferences`
-- `workflow`
-- `communication`
+- `preferences` — стиль кода, предпочтения общения
+- `workflow` — рабочие паттерны, выбор инструментов
+- `communication` — язык, формат ответов
 
-Подходит для стабильных привычек и предпочтений, которые полезны в любом проекте.
+**Память проекта** — знания, привязанные к репозиторию:
 
-**Память проекта**
+- `architecture` — архитектурные решения, паттерны
+- `workflow` — команды сборки, CI-конфиг
+- `decisions` — ADR, компромиссы
+- `bugs` — известные баги, обходные пути
+- `setup` — настройка окружения, зависимости
 
-- `architecture`
-- `workflow`
-- `decisions`
-- `bugs`
-- `setup`
+## Приватность
 
-Подходит для знаний, привязанных к конкретному репозиторию.
+- Блоки `<private>...</private>` уважаются и никогда не сохраняются
+- Типовые секреты (API-ключи, токены, пароли) скрываются перед записью
+- Полностью приватное содержимое пропускается целиком
 
 ## Настройка
 
@@ -133,54 +135,93 @@ mempalace_memory
 }
 ```
 
-Полезные переменные окружения:
-
-- `MEMPALACE_AUTOSAVE_ENABLED`
-- `MEMPALACE_RETRIEVAL_ENABLED`
-- `MEMPALACE_KEYWORD_SAVE_ENABLED`
-- `MEMPALACE_PRIVACY_REDACTION_ENABLED`
-- `MEMPALACE_AUTOSAVE_LOG_FILE`
-- `MEMPALACE_ADAPTER_PYTHON`
-
-## Приватность
-
-- поддерживаются блоки `<private>...</private>`
-- типовые секреты скрываются перед записью
-- полностью приватное содержимое не сохраняется
-
-## Документация проекта
+Переменные окружения:
 
-- История изменений: [`CHANGELOG.md`](./CHANGELOG.md)
-- Правила ведения changelog: [`CONTRIBUTING.md#changelog`](./CONTRIBUTING.md#changelog)
+| Переменная | Назначение |
+|---|---|
+| `MEMPALACE_AUTOSAVE_ENABLED` | Включить/выключить фоновое автосохранение |
+| `MEMPALACE_RETRIEVAL_ENABLED` | Включить/выключить скрытый поиск |
+| `MEMPALACE_KEYWORD_SAVE_ENABLED` | Включить/выключить сохранение по ключевым словам |
+| `MEMPALACE_PRIVACY_REDACTION_ENABLED` | Включить/выключить скрытие секретов |
+| `MEMPALACE_ADAPTER_PYTHON` | Путь к бинарнику Python |
+| `MEMPALACE_ADAPTER_TIMEOUT_MS` | Таймаут адаптера (по умолчанию 15000) |
 
-## Локальная разработка
+## Настройка TUI HUD
 
-Загрузка из исходников:
+Чтобы включить отображение статистики в строке промпта, добавь `tui.json` в каталог конфигурации OpenCode:
 
-```jsonc
+```json
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://opencode.ai/tui.json",
   "plugin": [
-    "file:///ABSOLUTE/PATH/TO/mempalace-autosave/plugin/index.ts"
+    "file:///путь/до/mempalace-autosave/plugin/tui/index.tsx"
   ]
 }
 ```
 
-Сборка:
+Или при установке из npm — используй пакетный вход:
+
+```json
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": ["@rvboris/opencode-mempalace/tui"]
+}
+```
+
+## Как это работает
+
+```
+Сообщение пользователя
+  → системный хук подставляет «сначала проверь память»
+  → модель вызывает mempalace_memory [search]
+  → результаты влияют на ответ
+
+Сессия завершается / простаивает
+  → хук событий анализирует транскрипт
+  → Python-адаптер сохраняет устойчивые факты через MemPalace
+```
+
+Плагин использует локальную Python-прослойку (`bridge/mempalace_adapter.py`) для работы с MemPalace. Ему **не нужен** MCP-сервер MemPalace.
+
+## Совместимость
+
+| Требование | Версия |
+|---|---|
+| OpenCode | latest |
+| Python | 3.10+ |
+| MemPalace | 3.3+ |
+| ОС | macOS, Linux, Windows |
+
+## Документация проекта
+
+- [Changelog](./CHANGELOG.md) — история изменений
+- [Contributing](./CONTRIBUTING.md) — правила ведения changelog
+
+## Локальная разработка
 
 ```bash
+git clone https://github.com/rvboris/opencode-mempalace.git
+cd opencode-mempalace/mempalace-autosave
+npm install
 npm run build
 ```
 
-Журналы отладки:
+Загрузка из исходников в `opencode.json`:
 
-```bash
-opencode --log-level DEBUG
+```jsonc
+{
+  "plugin": ["file:///ABSOLUTE/PATH/TO/mempalace-autosave/plugin/index.ts"]
+}
 ```
 
-Файл журнала: `~/.mempalace/opencode_autosave.log`
+Отладка: `opencode --log-level DEBUG` или файл `~/.mempalace/opencode_autosave.log`.
 
 ## Ссылки
 
 - OpenCode: https://opencode.ai
 - MemPalace: https://github.com/milla-jovovich/mempalace
+- npm: https://www.npmjs.com/package/@rvboris/opencode-mempalace
+
+## Лицензия
+
+MIT