@rvboris/opencode-mempalace 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rvboris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,230 @@
+# OpenCode MemPalace Plugin
+
+> Persistent memory for OpenCode with hidden retrieval, autosave, and a safe MemPalace wrapper tool.
+
+[Русская версия](./README.ru.md)
+
+OpenCode plugin for hidden retrieval and autosave with [MemPalace](https://github.com/milla-jovovich/mempalace) through a local Python adapter.
+
+- 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
+
+For source loading:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "file:///ABSOLUTE/PATH/TO/mempalace-autosave/plugin/index.ts"
+  ]
+}
+```
+
+The plugin itself does not require the MemPalace MCP server. It uses the bundled Python adapter.
+
+## Prerequisites
+
+- Python 3.9+
+- MemPalace installed and initialized
+
+```bash
+pip install mempalace
+mempalace init <dir>
+mempalace mine <dir>
+```
+
+## Build
+
+```bash
+npm run build
+```
+
+This builds TypeScript into `dist/` and copies the adapter to `dist/bridge/`.
+
+## 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
+{
+  "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"
+}
+```
+
+## Runtime behavior
+
+### Retrieval
+
+On normal user turns the plugin can inject hidden retrieval guidance so the model searches existing memory before answering.
+
+### Autosave
+
+On `session.idle` and `session.compacted`, the plugin marks autosave as pending. The actual write happens on the next model turn through `mempalace_memory`.
+
+### Safe wrapper tool
+
+The model should use only:
+
+- `mempalace_memory`
+
+Direct mutation tools are blocked:
+
+- `mempalace_add_drawer`
+- `mempalace_kg_add`
+- `mempalace_diary_write`
+- matching `mcp-router_*` variants
+
+## Scope policy
+
+### User scope
+
+- 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
+
+```text
+mempalace_memory
+  mode: save
+  scope: user
+  room: preferences
+  content: Prefers concise responses and numbered steps.
+```
+
+### Save a project decision
+
+```text
+mempalace_memory
+  mode: save
+  scope: project
+  room: decisions
+  content: Use Bun for builds and tests; avoid npm.
+```
+
+### Add KG fact
+
+```text
+mempalace_memory
+  mode: kg_add
+  scope: project
+  subject: my-repo
+  predicate: uses
+  object: bun
+```
+
+### Search memory
+
+```text
+mempalace_memory
+  mode: search
+  scope: user
+  room: preferences
+  query: user name
+  limit: 3
+```
+
+## Privacy
+
+- supports `<private>...</private>` blocks
+- redacts common secrets before writes
+- refuses to save fully private content
+
+## Logging
+
+Logs are written to:
+
+- OpenCode built-in logger
+- file log: `~/.mempalace/opencode_autosave.log`
+
+For debugging:
+
+```bash
+opencode --log-level DEBUG
+```
+
+## Notes
+
+- no visible autosave chat messages
+- no OpenCode tool-to-tool calls
+- adapter uses stdin/stdout streaming
+- package is publishable as a standard OpenCode plugin

package/README.ru.md

@@ -0,0 +1,230 @@
+# Плагин MemPalace для OpenCode
+
+> Постоянная память для OpenCode: скрытый retrieval, autosave и безопасный wrapper tool для MemPalace.
+
+[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
+
+## Что делает
+
+- добавляет скрытые подсказки для 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
+
+```bash
+pip install mempalace
+mempalace init <dir>
+mempalace mine <dir>
+```
+
+## Сборка
+
+```bash
+npm run build
+```
+
+Команда компилирует TypeScript в `dist/` и копирует adapter в `dist/bridge/`.
+
+## Конфигурация
+
+Переменные окружения:
+
+- `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
+{
+  "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"
+}
+```
+
+## Как работает во время сессии
+
+### Retrieval
+
+На обычных пользовательских ходах плагин может подмешивать скрытую retrieval-инструкцию, чтобы модель сначала поискала релевантную память.
+
+### Autosave
+
+На `session.idle` и `session.compacted` плагин ставит autosave в состояние `pending`. Реальная запись делается на следующем ходе модели через `mempalace_memory`.
+
+### Безопасный wrapper tool
+
+Модель должна использовать только:
+
+- `mempalace_memory`
+
+Прямые mutating tools блокируются:
+
+- `mempalace_add_drawer`
+- `mempalace_kg_add`
+- `mempalace_diary_write`
+- соответствующие `mcp-router_*` варианты
+
+## Политика scope
+
+### 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
+  mode: save
+  scope: user
+  room: preferences
+  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.
+```
+
+### Добавить KG факт
+
+```text
+mempalace_memory
+  mode: kg_add
+  scope: project
+  subject: my-repo
+  predicate: uses
+  object: bun
+```
+
+### Поиск в памяти
+
+```text
+mempalace_memory
+  mode: search
+  scope: user
+  room: preferences
+  query: user name
+  limit: 3
+```
+
+## Privacy
+
+- поддерживаются блоки `<private>...</private>`
+- common secrets редактируются перед записью
+- полностью private content не сохраняется
+
+## Логи
+
+Логи пишутся в:
+
+- встроенный лог OpenCode
+- файл: `~/.mempalace/opencode_autosave.log`
+
+Для отладки:
+
+```bash
+opencode --log-level DEBUG
+```
+
+## Заметки
+
+- никаких видимых autosave-сообщений в чате
+- никаких OpenCode tool-to-tool вызовов
+- adapter использует stdin/stdout streaming
+- пакет подготовлен как полноценный publishable OpenCode plugin

package/dist/bridge/mempalace_adapter.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+import json
+import sys
+
+from mempalace.mcp_server import (
+    tool_add_drawer,
+    tool_diary_write,
+    tool_kg_add,
+    tool_search,
+)
+
+
+def main() -> int:
+    payload = json.load(sys.stdin)
+
+    mode = payload["mode"]
+    if mode == "search":
+        result = tool_search(
+            query=payload["query"],
+            limit=payload.get("limit", 5),
+            wing=payload.get("wing"),
+            room=payload.get("room"),
+        )
+    elif mode == "save":
+        result = tool_add_drawer(
+            wing=payload["wing"],
+            room=payload["room"],
+            content=payload["content"],
+            added_by=payload.get("added_by", "opencode"),
+        )
+    elif mode == "kg_add":
+        result = tool_kg_add(
+            subject=payload["subject"],
+            predicate=payload["predicate"],
+            object=payload["object"],
+            valid_from=payload.get("valid_from", ""),
+            source_closet=payload.get("source_closet", ""),
+        )
+    elif mode == "diary_write":
+        result = tool_diary_write(
+            agent_name=payload["agent_name"],
+            entry=payload["entry"],
+            topic=payload.get("topic", "autosave"),
+        )
+    else:
+        result = {"success": False, "error": f"Unknown mode: {mode}"}
+
+    output = json.dumps(result, ensure_ascii=False)
+    sys.stdout.buffer.write(output.encode("utf-8", errors="replace"))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/plugin/hooks/chat-params.d.ts

@@ -0,0 +1,5 @@
+export declare const chatParamHooks: () => {
+    "chat.params": (input: {
+        sessionID: string;
+    }) => Promise<void>;
+};

package/dist/plugin/hooks/chat-params.js

@@ -0,0 +1,8 @@
+import { setCurrentTurnSessionId } from "../lib/autosave";
+export const chatParamHooks = () => {
+    return {
+        "chat.params": async (input) => {
+            setCurrentTurnSessionId(input.sessionID);
+        },
+    };
+};

package/dist/plugin/hooks/event.d.ts

@@ -0,0 +1,19 @@
+type PluginContext = {
+    client: any;
+    project: any;
+    directory: string;
+    worktree: string;
+    $: any;
+};
+export declare const eventHooks: (ctx: PluginContext) => {
+    event: ({ event }: {
+        event: any;
+    }) => Promise<void>;
+    "experimental.session.compacting": (input: {
+        sessionID?: string;
+    }, output: {
+        context: string[];
+        prompt?: string;
+    }) => Promise<void>;
+};
+export {};

package/dist/plugin/hooks/event.js

@@ -0,0 +1,110 @@
+import { AutosaveReason, AutosaveStatus, buildTranscriptDigest, buildUserDigest, extractLastUserMessage, finalizeAutosave, getSessionState, markKeywordSavePending, markFailed, markPending, markRetrievalPending, shouldScheduleAutosave, } from "../lib/autosave";
+import { loadConfig } from "../lib/config";
+import { writeLog } from "../lib/log";
+const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const toReason = (eventType) => {
+    if (eventType === "session.compacted")
+        return AutosaveReason.Compacted;
+    if (eventType === "session.error")
+        return AutosaveReason.Error;
+    return AutosaveReason.Idle;
+};
+const loadMessages = async (ctx, sessionId) => {
+    const response = await ctx.client.session.messages({ path: { id: sessionId } });
+    return response?.data ?? response ?? [];
+};
+export const eventHooks = (ctx) => {
+    return {
+        event: async ({ event }) => {
+            try {
+                if (!["session.idle", "session.compacted", "session.error", "session.updated", "message.updated"].includes(event?.type))
+                    return;
+                const sessionId = event?.properties?.sessionID;
+                if (!sessionId) {
+                    await writeLog("WARN", "autosave event missing sessionID", { eventType: event?.type });
+                    return;
+                }
+                const config = await loadConfig();
+                if (event?.type === "session.updated" || event?.type === "message.updated") {
+                    const messages = await loadMessages(ctx, sessionId);
+                    const userDigest = buildUserDigest(messages);
+                    if (config.retrievalEnabled) {
+                        markRetrievalPending(sessionId, userDigest);
+                    }
+                    const lastUserMessage = extractLastUserMessage(messages);
+                    if (lastUserMessage && config.keywordSaveEnabled && config.keywordPatterns.length) {
+                        const keywordPattern = new RegExp(`\\b(${config.keywordPatterns.map(escapeRegex).join("|")})\\b`, "i");
+                        if (config.keywordSaveEnabled && keywordPattern.test(lastUserMessage)) {
+                            markKeywordSavePending(sessionId);
+                            await writeLog("INFO", "keyword-triggered autosave hint detected", { sessionId });
+                        }
+                    }
+                }
+                if (!["session.idle", "session.compacted", "session.error"].includes(event?.type))
+                    return;
+                await writeLog("INFO", "autosave trigger received", {
+                    eventType: event?.type,
+                    sessionId,
+                });
+                const state = getSessionState(sessionId);
+                if (state.status === AutosaveStatus.Running && event?.type === "session.idle") {
+                    const finalized = finalizeAutosave(sessionId);
+                    await writeLog("INFO", "finalized autosave turn", {
+                        sessionId,
+                        status: finalized.status,
+                        toolCalls: finalized.successfulToolCalls.length,
+                    });
+                }
+                if (event?.type === "session.error") {
+                    const failed = markFailed(sessionId);
+                    await writeLog("ERROR", "autosave failed on session error", {
+                        sessionId,
+                        retryCount: failed.retryCount,
+                    });
+                    return;
+                }
+                if (!config.autosaveEnabled)
+                    return;
+                const messages = await loadMessages(ctx, sessionId);
+                const userDigest = buildUserDigest(messages);
+                const transcriptDigest = buildTranscriptDigest(messages);
+                if (!shouldScheduleAutosave(sessionId, userDigest, transcriptDigest)) {
+                    await writeLog("INFO", "skipping autosave state", {
+                        sessionId,
+                        reason: toReason(event?.type),
+                        userDigest,
+                        transcriptDigest,
+                        status: getSessionState(sessionId).status,
+                    });
+                    return;
+                }
+                markPending(sessionId, toReason(event?.type), userDigest, transcriptDigest);
+                await writeLog("INFO", "marked autosave pending", {
+                    sessionId,
+                    reason: toReason(event?.type),
+                    userDigest,
+                    transcriptDigest,
+                });
+            }
+            catch (error) {
+                await writeLog("ERROR", "event hook failed", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        },
+        "experimental.session.compacting": async (input, output) => {
+            if (!input.sessionID) {
+                await writeLog("WARN", "compaction hook missing sessionID", {});
+                return;
+            }
+            const state = getSessionState(input.sessionID);
+            if (state.status !== AutosaveStatus.Pending)
+                return;
+            output.context.push("MemPalace autosave is pending. Before answering after compaction, persist durable facts, decisions, preferences, outcomes, and diary notes using MemPalace MCP tools. Do not dump the full transcript.");
+            await writeLog("INFO", "injected compaction autosave context", {
+                sessionId: input.sessionID,
+                reason: state.pendingReason,
+            });
+        },
+    };
+};

package/dist/plugin/hooks/system.d.ts

@@ -0,0 +1,10 @@
+type PluginContext = {
+    client: any;
+    project: any;
+};
+export declare const systemHooks: (ctx: PluginContext) => {
+    "experimental.chat.system.transform": (_input: {}, output: {
+        system: string[];
+    }) => Promise<void>;
+};
+export {};