@rvboris/opencode-mempalace 0.1.0 → 0.2.0

package/README.md

@@ -1,72 +1,21 @@
 # OpenCode MemPalace Plugin
 
-> Persistent memory for OpenCode with hidden retrieval, autosave, and a safe MemPalace wrapper tool.
+OpenCode memory layer with private retrieval and safe autosave.
 
 [Русская версия](./README.ru.md)
 
-OpenCode plugin for hidden retrieval and autosave with [MemPalace](https://github.com/milla-jovovich/mempalace) through a local Python adapter.
+## Why it matters
 
-- OpenCode: https://opencode.ai
-- MemPalace: https://github.com/milla-jovovich/mempalace
-
-## What it does
-
-- injects hidden retrieval hints before normal answers
-- marks autosave on session lifecycle events
-- exposes one safe memory tool: `mempalace_memory`
-- routes memory through enforced user/project scopes
-- applies privacy filtering before writes
-- logs to both OpenCode logs and a local file
-
-## Architecture
-
-```mermaid
-flowchart TD
-    U[User message] --> OC[OpenCode turn]
-    OC --> EV[Plugin hooks]
-    EV --> RET[Hidden retrieval instruction]
-    EV --> AS[Autosave pending on idle/compaction]
-    RET --> LLM[Model]
-    AS --> LLM
-    LLM --> TOOL[mempalace_memory]
-    TOOL --> ADAPTER[Python adapter]
-    ADAPTER --> MP[MemPalace backend]
-    MP --> ADAPTER
-    ADAPTER --> TOOL
-    TOOL --> LLM
-```
-
-## Installation
-
-Add to `opencode.json`:
-
-```json
-{
-  "plugin": ["@rvboris/opencode-mempalace"]
-}
-```
-
-OpenCode installs plugin dependencies automatically.
-
-## Local development
+Keep OpenCode context-aware without extra prompts.
 
-For source loading:
+- **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
 
-```jsonc
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": [
-    "file:///ABSOLUTE/PATH/TO/mempalace-autosave/plugin/index.ts"
-  ]
-}
-```
+## Quick start
 
-The plugin itself does not require the MemPalace MCP server. It uses the bundled Python adapter.
-
-## Prerequisites
-
-- Python 3.9+
-- MemPalace installed and initialized
+Install MemPalace:
 
 ```bash
 pip install mempalace
@@ -74,94 +23,41 @@ mempalace init <dir>
 mempalace mine <dir>
 ```
 
-## Build
-
-```bash
-npm run build
-```
-
-This builds TypeScript into `dist/` and copies the adapter to `dist/bridge/`.
+Add the plugin to `opencode.json`:
 
-## Configuration
-
-Environment variables:
-
-- `MEMPALACE_AUTOSAVE_ENABLED`
-- `MEMPALACE_RETRIEVAL_ENABLED`
-- `MEMPALACE_KEYWORD_SAVE_ENABLED`
-- `MEMPALACE_PRIVACY_REDACTION_ENABLED`
-- `MEMPALACE_MAX_INJECTED_ITEMS`
-- `MEMPALACE_RETRIEVAL_QUERY_LIMIT`
-- `MEMPALACE_AUTOSAVE_LOG_FILE`
-- `MEMPALACE_ADAPTER_PYTHON`
-- `MEMPALACE_USER_WING_PREFIX`
-- `MEMPALACE_PROJECT_WING_PREFIX`
-
-Optional config file: `~/.config/opencode/mempalace.jsonc`
-
-```jsonc
+```json
 {
-  "autosaveEnabled": true,
-  "retrievalEnabled": true,
-  "keywordSaveEnabled": true,
-  "maxInjectedItems": 6,
-  "retrievalQueryLimit": 5,
-  "keywordPatterns": ["remember", "save this", "don't forget", "note that"],
-  "privacyRedactionEnabled": true,
-  "userWingPrefix": "wing_user",
-  "projectWingPrefix": "wing_project"
+  "plugin": ["@rvboris/opencode-mempalace"]
 }
 ```
 
-## Runtime behavior
-
-### Retrieval
-
-On normal user turns the plugin can inject hidden retrieval guidance so the model searches existing memory before answering.
-
-### Autosave
+That is enough to enable memory search, autosave, and `mempalace_memory`.
 
-On `session.idle` and `session.compacted`, the plugin marks autosave as pending. The actual write happens on the next model turn through `mempalace_memory`.
+## What you get
 
-### Safe wrapper tool
+- 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
 
-The model should use only:
+The plugin does **not** require the MemPalace MCP server.
 
-- `mempalace_memory`
+## The one tool: `mempalace_memory`
 
-Direct mutation tools are blocked:
+This is the only tool the model needs.
 
-- `mempalace_add_drawer`
-- `mempalace_kg_add`
-- `mempalace_diary_write`
-- matching `mcp-router_*` variants
+### Modes
 
-## Scope policy
+- **`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
 
-### User scope
+### Examples
 
-- wing: `${MEMPALACE_USER_WING_PREFIX}_profile`
-- rooms: `preferences`, `workflow`, `communication`
-
-Use for:
-- response preferences
-- personal workflow habits
-- cross-project conventions
-
-### Project scope
-
-- wing: `${MEMPALACE_PROJECT_WING_PREFIX}_${slug(projectName)}`
-- rooms: `architecture`, `workflow`, `decisions`, `bugs`, `setup`
-
-Use for:
-- repo-specific setup
-- architecture decisions
-- build/test commands
-- bug/solution patterns
-
-## Examples
-
-### Save a user preference
+Save a user preference:
 
 ```text
 mempalace_memory
@@ -171,60 +67,120 @@ mempalace_memory
   content: Prefers concise responses and numbered steps.
 ```
 
-### Save a project decision
+Save a project decision:
 
 ```text
 mempalace_memory
   mode: save
   scope: project
   room: decisions
-  content: Use Bun for builds and tests; avoid npm.
+  content: Use Bun for builds and tests.
 ```
 
-### Add KG fact
+Search memory:
 
 ```text
 mempalace_memory
-  mode: kg_add
+  mode: search
   scope: project
+  room: workflow
+  query: build command
+  limit: 3
+```
+
+Add a graph fact:
+
+```text
+mempalace_memory
+  mode: kg_add
   subject: my-repo
   predicate: uses
   object: bun
 ```
 
-### Search memory
+## Memory areas
 
-```text
-mempalace_memory
-  mode: search
-  scope: user
-  room: preferences
-  query: user name
-  limit: 3
+**User memory**
+
+- `preferences`
+- `workflow`
+- `communication`
+
+Use it for stable cross-project habits and preferences.
+
+**Project memory**
+
+- `architecture`
+- `workflow`
+- `decisions`
+- `bugs`
+- `setup`
+
+Use it for repository-specific knowledge.
+
+## Configuration
+
+Optional config file: `~/.config/opencode/mempalace.jsonc`
+
+```jsonc
+{
+  "autosaveEnabled": true,
+  "retrievalEnabled": true,
+  "keywordSaveEnabled": true,
+  "maxInjectedItems": 6,
+  "retrievalQueryLimit": 5,
+  "privacyRedactionEnabled": true
+}
 ```
 
+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
 
-- supports `<private>...</private>` blocks
+- respects `<private>...</private>` blocks
 - redacts common secrets before writes
-- refuses to save fully private content
+- skips fully private content
 
-## Logging
+## Project docs
 
-Logs are written to:
+- Release history: [`CHANGELOG.md`](./CHANGELOG.md)
+- Changelog rules: [`CONTRIBUTING.md#changelog`](./CONTRIBUTING.md#changelog)
 
-- OpenCode built-in logger
-- file log: `~/.mempalace/opencode_autosave.log`
+## Local development
 
-For debugging:
+Load from source:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "file:///ABSOLUTE/PATH/TO/mempalace-autosave/plugin/index.ts"
+  ]
+}
+```
+
+Build:
+
+```bash
+npm run build
+```
+
+Debug logs:
 
 ```bash
 opencode --log-level DEBUG
 ```
 
-## Notes
+File log: `~/.mempalace/opencode_autosave.log`
 
-- no visible autosave chat messages
-- no OpenCode tool-to-tool calls
-- adapter uses stdin/stdout streaming
-- package is publishable as a standard OpenCode plugin
+## Links
+
+- OpenCode: https://opencode.ai
+- MemPalace: https://github.com/milla-jovovich/mempalace

package/README.ru.md

@@ -1,72 +1,21 @@
 # Плагин MemPalace для OpenCode
 
-> Постоянная память для OpenCode: скрытый retrieval, autosave и безопасный wrapper tool для MemPalace.
+Слой памяти для OpenCode: скрытый поиск по памяти и безопасное автосохранение.
 
 [English version](./README.md)
 
-Плагин для [OpenCode](https://opencode.ai) со скрытым retrieval и autosave в [MemPalace](https://github.com/milla-jovovich/mempalace) через локальный Python adapter.
+## Зачем он нужен
 
-- OpenCode: https://opencode.ai
-- MemPalace: https://github.com/milla-jovovich/mempalace
+Чтобы OpenCode отвечал с учётом прошлого контекста — без лишних подсказок и без шума в чате.
 
-## Что делает
-
-- добавляет скрытые подсказки для retrieval перед обычным ответом
-- помечает autosave на событиях жизненного цикла сессии
-- дает один безопасный tool: `mempalace_memory`
-- направляет память в user/project scope по явным правилам
-- применяет privacy-фильтрацию перед записью
-- пишет логи в OpenCode и в локальный файл
-
-## Схема работы
-
-```mermaid
-flowchart TD
-    U[Сообщение пользователя] --> OC[Ход OpenCode]
-    OC --> EV[Хуки плагина]
-    EV --> RET[Скрытая retrieval-инструкция]
-    EV --> AS[Autosave pending на idle/compaction]
-    RET --> LLM[Модель]
-    AS --> LLM
-    LLM --> TOOL[mempalace_memory]
-    TOOL --> ADAPTER[Python adapter]
-    ADAPTER --> MP[MemPalace backend]
-    MP --> ADAPTER
-    ADAPTER --> TOOL
-    TOOL --> LLM
-```
+- **Сам ищет нужную память** перед обычным ответом
+- **Тихо сохраняет важное** по ходу работы
+- **Пишет безопасно** через один контролируемый инструмент
+- **Учитывает приватность** перед сохранением
 
-## Установка
+## Быстрый старт
 
-Добавь в `opencode.json`:
-
-```json
-{
-  "plugin": ["@rvboris/opencode-mempalace"]
-}
-```
-
-OpenCode сам установит зависимости плагина при запуске.
-
-## Локальная разработка
-
-Для загрузки из исходников:
-
-```jsonc
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": [
-    "file:///ABSOLUTE/PATH/TO/mempalace-autosave/plugin/index.ts"
-  ]
-}
-```
-
-Самому плагину MemPalace MCP server не нужен — он использует встроенный Python adapter.
-
-## Требования
-
-- Python 3.9+
-- установлен и инициализирован MemPalace
+Установи MemPalace:
 
 ```bash
 pip install mempalace
@@ -74,94 +23,41 @@ mempalace init <dir>
 mempalace mine <dir>
 ```
 
-## Сборка
-
-```bash
-npm run build
-```
-
-Команда компилирует TypeScript в `dist/` и копирует adapter в `dist/bridge/`.
-
-## Конфигурация
+Добавь плагин в `opencode.json`:
 
-Переменные окружения:
-
-- `MEMPALACE_AUTOSAVE_ENABLED`
-- `MEMPALACE_RETRIEVAL_ENABLED`
-- `MEMPALACE_KEYWORD_SAVE_ENABLED`
-- `MEMPALACE_PRIVACY_REDACTION_ENABLED`
-- `MEMPALACE_MAX_INJECTED_ITEMS`
-- `MEMPALACE_RETRIEVAL_QUERY_LIMIT`
-- `MEMPALACE_AUTOSAVE_LOG_FILE`
-- `MEMPALACE_ADAPTER_PYTHON`
-- `MEMPALACE_USER_WING_PREFIX`
-- `MEMPALACE_PROJECT_WING_PREFIX`
-
-Дополнительно можно использовать файл `~/.config/opencode/mempalace.jsonc`:
-
-```jsonc
+```json
 {
-  "autosaveEnabled": true,
-  "retrievalEnabled": true,
-  "keywordSaveEnabled": true,
-  "maxInjectedItems": 6,
-  "retrievalQueryLimit": 5,
-  "keywordPatterns": ["remember", "save this", "don't forget", "note that"],
-  "privacyRedactionEnabled": true,
-  "userWingPrefix": "wing_user",
-  "projectWingPrefix": "wing_project"
+  "plugin": ["@rvboris/opencode-mempalace"]
 }
 ```
 
-## Как работает во время сессии
-
-### Retrieval
-
-На обычных пользовательских ходах плагин может подмешивать скрытую retrieval-инструкцию, чтобы модель сначала поискала релевантную память.
-
-### Autosave
+Этого достаточно, чтобы включить поиск по памяти, автосохранение и `mempalace_memory`.
 
-На `session.idle` и `session.compacted` плагин ставит autosave в состояние `pending`. Реальная запись делается на следующем ходе модели через `mempalace_memory`.
+## Что ты получаешь
 
-### Безопасный wrapper tool
+- скрытый поиск по памяти перед ответом
+- автосохранение на событиях сессии
+- раздельную память для пользователя и проекта
+- один безопасный инструмент для работы с памятью
+- локальную Python-прослойку для MemPalace
 
-Модель должна использовать только:
+Самому плагину **не нужен** сервер MCP от MemPalace.
 
-- `mempalace_memory`
+## Основной инструмент: `mempalace_memory`
 
-Прямые mutating tools блокируются:
+Это единственный инструмент, который нужен модели.
 
-- `mempalace_add_drawer`
-- `mempalace_kg_add`
-- `mempalace_diary_write`
-- соответствующие `mcp-router_*` варианты
+### Режимы
 
-## Политика scope
+- **`save`** — сохранить устойчивый факт, предпочтение или решение
+- **`search`** — найти релевантную память по запросу
+- **`kg_add`** — добавить структурированный факт в граф знаний
+- **`diary_write`** — записать короткую рабочую заметку
+- **`mine_messages`** — внутренний режим автосохранения, который использует сам плагин
 
-### User scope
+### Примеры
 
-- wing: `${MEMPALACE_USER_WING_PREFIX}_profile`
-- rooms: `preferences`, `workflow`, `communication`
-
-Используется для:
-- предпочтений по ответам
-- личных привычек работы
-- кросс-проектных соглашений
-
-### Project scope
-
-- wing: `${MEMPALACE_PROJECT_WING_PREFIX}_${slug(projectName)}`
-- rooms: `architecture`, `workflow`, `decisions`, `bugs`, `setup`
-
-Используется для:
-- repo-specific setup
-- архитектурных решений
-- build/test команд
-- паттернов баг/решение
-
-## Примеры
-
-### Сохранить user preference
+Сохранить пользовательское предпочтение:
 
 ```text
 mempalace_memory
@@ -171,60 +67,120 @@ mempalace_memory
   content: Prefers concise responses and numbered steps.
 ```
 
-### Сохранить project decision
+Сохранить проектное решение:
 
 ```text
 mempalace_memory
   mode: save
   scope: project
   room: decisions
-  content: Use Bun for builds and tests; avoid npm.
+  content: Use Bun for builds and tests.
 ```
 
-### Добавить KG факт
+Найти память:
 
 ```text
 mempalace_memory
-  mode: kg_add
+  mode: search
   scope: project
+  room: workflow
+  query: build command
+  limit: 3
+```
+
+Добавить факт в граф знаний:
+
+```text
+mempalace_memory
+  mode: kg_add
   subject: my-repo
   predicate: uses
   object: bun
 ```
 
-### Поиск в памяти
+## Области памяти
 
-```text
-mempalace_memory
-  mode: search
-  scope: user
-  room: preferences
-  query: user name
-  limit: 3
+**Память пользователя**
+
+- `preferences`
+- `workflow`
+- `communication`
+
+Подходит для стабильных привычек и предпочтений, которые полезны в любом проекте.
+
+**Память проекта**
+
+- `architecture`
+- `workflow`
+- `decisions`
+- `bugs`
+- `setup`
+
+Подходит для знаний, привязанных к конкретному репозиторию.
+
+## Настройка
+
+Необязательный файл конфигурации: `~/.config/opencode/mempalace.jsonc`
+
+```jsonc
+{
+  "autosaveEnabled": true,
+  "retrievalEnabled": true,
+  "keywordSaveEnabled": true,
+  "maxInjectedItems": 6,
+  "retrievalQueryLimit": 5,
+  "privacyRedactionEnabled": true
+}
 ```
 
-## Privacy
+Полезные переменные окружения:
+
+- `MEMPALACE_AUTOSAVE_ENABLED`
+- `MEMPALACE_RETRIEVAL_ENABLED`
+- `MEMPALACE_KEYWORD_SAVE_ENABLED`
+- `MEMPALACE_PRIVACY_REDACTION_ENABLED`
+- `MEMPALACE_AUTOSAVE_LOG_FILE`
+- `MEMPALACE_ADAPTER_PYTHON`
+
+## Приватность
 
 - поддерживаются блоки `<private>...</private>`
-- common secrets редактируются перед записью
-- полностью private content не сохраняется
+- типовые секреты скрываются перед записью
+- полностью приватное содержимое не сохраняется
+
+## Документация проекта
+
+- История изменений: [`CHANGELOG.md`](./CHANGELOG.md)
+- Правила ведения changelog: [`CONTRIBUTING.md#changelog`](./CONTRIBUTING.md#changelog)
+
+## Локальная разработка
+
+Загрузка из исходников:
 
-## Логи
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "file:///ABSOLUTE/PATH/TO/mempalace-autosave/plugin/index.ts"
+  ]
+}
+```
 
-Логи пишутся в:
+Сборка:
 
-- встроенный лог OpenCode
-- файл: `~/.mempalace/opencode_autosave.log`
+```bash
+npm run build
+```
 
-Для отладки:
+Журналы отладки:
 
 ```bash
 opencode --log-level DEBUG
 ```
 
-## Заметки
+Файл журнала: `~/.mempalace/opencode_autosave.log`
 
-- никаких видимых autosave-сообщений в чате
-- никаких OpenCode tool-to-tool вызовов
-- adapter использует stdin/stdout streaming
-- пакет подготовлен как полноценный publishable OpenCode plugin
+## Ссылки
+
+- OpenCode: https://opencode.ai
+- MemPalace: https://github.com/milla-jovovich/mempalace