From fd8d730e3b0acae9203f9ad4513dd9d724fbf3f4 Mon Sep 17 00:00:00 2001 From: Ralph Chang Date: Mon, 27 Apr 2026 12:38:11 +0800 Subject: [PATCH] docs: streamline README and document ongoing work --- README.md | 333 ++++++++++++++++++++++++------------------------------ 1 file changed, 150 insertions(+), 183 deletions(-) diff --git a/README.md b/README.md index c6e6f07..f96c931 100644 --- a/README.md +++ b/README.md @@ -3,29 +3,38 @@ [![npm version](https://img.shields.io/npm/v/opencode-working-memory.svg)](https://www.npmjs.com/package/opencode-working-memory) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) -**Automatic memory system that keeps your AI agent context-aware across compactions.** +Automatic memory for OpenCode agents. -Stop losing context when OpenCode compacts your conversation. This plugin automatically tracks what matters — decisions, active files, open errors — and preserves it across sessions. +This plugin helps your agent keep useful context across compactions and sessions: project decisions, preferences, important references, active files, and unresolved errors. -## What You Get +It works automatically, without manual memory tools or extra LLM/API calls. -**Three-layer memory, zero extra API calls:** +## Why This Exists -| Layer | Scope | What It Tracks | Persists? | -|-------|-------|----------------|-----------| -| **Workspace Memory** | Cross-session | Decisions, project info, references | ✅ Yes | -| **Hot Session State** | Per-session | Active files, open errors | ❌ Resets | -| **Native OpenCode** | Per-session | Todos | ✅ Built-in | +OpenCode compaction keeps conversations manageable, but important context can still get lost over time. -**Key benefits:** -- 🧠 **Remembers across sessions** — Workspace memory survives restarts -- 🔌 **No extra API calls** — Piggybacks on existing compaction -- 📡 **Zero configuration** — Works out of the box -- 🔧 **Zero tools** — No manual memory management needed +This plugin adds a workspace-aware memory layer so your agent can remember durable facts while keeping short-term session state fresh and lightweight. + +Use it when you want your agent to remember things like: + +- Project conventions +- User preferences +- Architecture decisions +- Important file paths or references +- Current active files and unresolved errors + +## Features + +- **Workspace memory** — durable project facts, preferences, decisions, and references across sessions. +- **Hot session state** — active files, open errors, and current working context for the current session. +- **Explicit memory triggers** — users can say “remember this”, “記住”, “覚えて”, or “기억해” to save durable facts. +- **Compaction-based extraction** — memory extraction piggybacks on OpenCode’s existing compaction flow. +- **No manual tools** — memory is injected automatically into the system prompt. +- **Quality guards** — filters noisy memories, temporary progress snapshots, stack traces, raw errors, and credentials. ## Installation -Add to your `~/.config/opencode/opencode.json`: +Add the plugin to your OpenCode config: ```json { @@ -33,206 +42,164 @@ Add to your `~/.config/opencode/opencode.json`: } ``` -Restart OpenCode. The plugin activates automatically — no manual setup needed. +Then restart OpenCode. The plugin activates automatically. ## How It Works -**Three layers, zero API calls, automatic persistence:** +OpenCode Working Memory adds durable memory without making extra LLM/API calls. -``` -┌──────────────────────────────────────────────────────────────────┐ -│ LAYER 1: WORKSPACE MEMORY │ -│ ┌────────────────────────────────────────────────────────────┐ │ -│ │ 📦 Persists across sessions (in same workspace) │ │ -│ │ 📦 Survives compaction & restart │ │ -│ │ │ │ -│ │ Stored in: ~/.local/share/.../workspace-memory.json │ │ -│ │ Contains: decisions • project info • references │ │ -│ │ Written: during compaction (no extra LLM call!) │ │ -│ └────────────────────────────────────────────────────────────┘ │ -└──────────────────────────────────────────────────────────────────┘ - ↑ extracted during compaction (piggyback, no API call) - │ -┌──────────────────────────────────────────────────────────────────┐ -│ LAYER 2: HOT SESSION STATE │ -│ ┌────────────────────────────────────────────────────────────┐ │ -│ │ 🔥 Per-session, auto-tracked, resets on new session │ │ -│ │ │ │ -│ │ Active files (what you're editing) │ │ -│ │ Open errors (typecheck, test, lint failures) │ │ -│ │ Recent decisions (candidates for Layer 1) │ │ -│ └────────────────────────────────────────────────────────────┘ │ -└──────────────────────────────────────────────────────────────────┘ - ↑ harvested during compaction → promoted to Layer 1 - │ -┌──────────────────────────────────────────────────────────────────┐ -│ LAYER 3: NATIVE OPENCODE STATE │ -│ ┌────────────────────────────────────────────────────────────┐ │ -│ │ ✅ Uses OpenCode's built-in todos │ │ -│ │ ✅ No plugin storage needed │ │ -│ │ ✅ Delegates to native features │ │ -│ └────────────────────────────────────────────────────────────┘ │ -└──────────────────────────────────────────────────────────────────┘ - -KEY INSIGHT: Layer 1 memories are extracted during OpenCode's - built-in compaction summary — NO additional LLM call! +```text +┌──────────────────────────────────────┐ +│ 🧭 Conversation Events │ +│ edits, commands, errors, remembers │ +└──────────────────┬───────────────────┘ + ▼ +┌──────────────────────────────────────┐ +│ 🔥 Hot Session State │ +│ active files, open errors, pending │ +│ │ +│ ~/.local/share/opencode-working- │ +│ memory/workspaces/{hash}/sessions/ │ +│ {sessionID}.json │ +└──────────────────┬───────────────────┘ + │ when OpenCode compacts + ▼ +┌──────────────────────────────────────┐ +│ 🧠 OpenCode Compaction │ +│ existing LLM/API call │ +│ + memory extraction instructions │ +│ │ +│ zero extra API calls │ +└──────────────────┬───────────────────┘ + │ filter, redact, dedupe + ▼ +┌──────────────────────────────────────┐ +│ 📦 Workspace Memory │ +│ decisions, preferences, refs │ +│ │ +│ ~/.local/share/opencode-working- │ +│ memory/workspaces/{hash}/ │ +│ workspace-memory.json │ +└──────────────────┬───────────────────┘ + ▼ +┌──────────────────────────────────────┐ +│ ⚡ Prompt Context │ +│ system[1]: frozen workspace memory │ +│ system[2+]: hot session state │ +└──────────────────────────────────────┘ ``` -### The Compaction Flow (No Extra API Call) +**Zero extra API calls:** the plugin does not call the model on its own. Memory extraction is folded into OpenCode's built-in compaction request. -``` -User Message ───────────────┐ - │ -Agent Response ─────────────┤ - │ normal conversation -... more turns ... ─────────┤ - │ - ▼ - ╔═══════════════════════════════════════════╗ - ║ COMPACTION (OpenCode built-in) ║ - ║ ║ - ║ OpenCode already calls LLM to summarize ║ - ║ ──────────────────────────────────────── ║ - ║ Plugin piggybacks on THIS call ║ - ║ to extract workspace memory candidates ║ - ║ ║ - ║ Output includes: ║ - ║ ║ - ║ - [decision] Use npm cache for plugins ║ - ║ - [project] React 18 with TypeScript ║ - ║ ║ - ╚═══════════════════════════════════════════╝ - │ - ▼ - ┌─────────────────────────────────┐ - │ Workspace Memory Updated │ - │ (persists across sessions) │ - └─────────────────────────────────┘ +**Cache-friendly layout:** durable workspace memory is rendered as a stable frozen snapshot for the session, while fast-changing hot session state is appended separately. Compaction starts a new cache epoch, refreshing the workspace snapshot after pending memories are promoted. + +The runtime context has three layers: + +| Layer | Purpose | Lifetime | +|---|---|---| +| Workspace Memory | Durable decisions, preferences, project facts, references | Cross-session | +| Hot Session State | Active files, open errors, recent context | Current session | +| Native OpenCode State | Todos and built-in state | OpenCode-managed | + +## Workspace Memory + +Workspace memory is for durable information that should help future sessions. + +Examples: + +```md +- [decision] Use npm cache for plugin loading, not npm link. +- [project] This repo uses TypeScript and Node.js test runner. +- [feedback] User prefers concise implementation summaries. +- [reference] Storage lives under ~/.local/share/opencode-working-memory/. ``` -### Workspace Memory (Long-term) +Memory types: -Persists across sessions within the same workspace. Automatically extracted during compaction when the agent marks something with "remember" or "note": +- `feedback` — user preferences or recurring feedback +- `project` — stable project-level facts +- `decision` — important implementation or architecture decisions +- `reference` — useful paths, commands, or configuration references -``` - -- [decision] Use npm cache for plugin loading, not npm link -- [project] This repo uses opencode-agenthub plugin system -- [reference] Storage: ~/.local/share/opencode-working-memory/... - +## Explicit Memory Triggers + +You can explicitly ask the agent to remember durable facts. + +Examples: + +```md +Remember this: we prefer Vitest for new frontend tests. +記住：這個 repo 發 release 前要先跑 npm test。 +覚えておいて: API clients should use the shared retry helper. +기억해줘: this project uses pnpm, not npm. ``` -**Memory types:** -- `feedback` - User preferences for this workspace -- `project` - Project-level information -- `decision` - Important decisions made -- `reference` - Key references (paths, patterns) +Supported trigger languages include: -**Sources:** -- `explicit` - User explicitly said "remember this" (confidence: 1.0) -- `compaction` - Extracted during compaction (confidence: 0.75) -- `manual` - Added programmatically (confidence: varies) +| Language | Examples | +|---|---| +| English | `remember this`, `save to memory`, `from now on`, `my preference` | +| Chinese | `記住`, `记住`, `記得`, `请帮我记住` | +| Japanese | `覚えて`, `覚えておいて`, `メモして` | +| Korean | `기억해`, `기억해줘`, `메모해줘` | -### Explicit Memory Triggers +Negative requests are respected too: -Workspace memory is automatic, but you can also explicitly ask the agent to remember durable facts for future sessions. - -Use memory triggers for preferences, decisions, project conventions, and stable references — not temporary progress updates or secrets. - -| Language | Example trigger phrases | -|----------|--------------------------| -| English | `remember this`, `save to memory`, `commit to memory`, `from now on`, `my preference` | -| Chinese | `记住`, `記住`, `记得`, `記得`, `请帮我记住`, `幫我記住` | -| Japanese | `覚えて`, `覚えておいて`, `忘れないで`, `メモして` | -| Korean | `기억해`, `기억해줘`, `잊지 마`, `메모해줘` | - -Negative requests are respected too, such as "don't remember this", `不要記住`, `覚えないで`, or `기억하지 마`. - -**Good examples:** -- "Remember this: we prefer Vitest for new unit tests." -- "覚えておいて: API clients should use the shared retry helper." -- "기억해줘: this project uses pnpm, not npm." - -**Avoid:** -- "Remember my password is hunter2." — credentials are redacted. -- "Remember Sprint 3 is 40% done." — temporary progress snapshots are filtered. -- "Remember the last command output." — session-specific details usually are not durable. - -### Hot Session State (Short-term) - -Automatically tracks current session context: - -- **Active Files**: What files you're working on (ranked by recency and action type) -- **Open Errors**: Errors that haven't been fixed yet (typecheck, test failures, etc.) -- **Recent Decisions**: Decisions made this session (candidates for long-term promotion) - -Injected into system prompt: -``` - -- [decision] Use npm cache for plugin loading, not npm link -- [project] This repo uses opencode-agenthub plugin system -- [reference] Storage: ~/.local/share/opencode-working-memory/workspaces/{hash}/ - - - -active_files: -- src/plugin.ts (edit, 18x) -- tests/plugin.test.ts (edit, 5x) -- src/extractors.ts (grep, 3x) -open_errors: -- [typecheck] TS2345: Argument of type 'string' is not assignable... - +```md +Don't remember this. +不要記住這個。 +覚えないで。 +기억하지 마. ``` -## Quality Guarantees +Avoid saving: -The plugin includes several quality guards: +- Secrets, passwords, tokens, or credentials +- Temporary progress updates +- Raw command output +- Short-lived session details -- **No false positive errors**: Bash commands like `git log` or `cat` with "error" in output are not misidentified -- **Negative memory filtering**: "Don't remember this" is correctly interpreted -- **Compaction quality gate**: Rejects git hashes, stack traces, path-heavy facts from becoming long-term memories -- **Canonical deduplication**: Memories are deduplicated with case/punctuation normalization +## Quality Guards -## No Tools Required +The plugin tries to keep memory useful and low-noise. -Unlike other memory plugins, **this plugin has no manual tools**. Everything is automatic: +It includes guards for: -- No `core_memory_update` — memory is extracted automatically -- No `core_memory_read` — memory is injected into system prompt -- No `working_memory_add` — active files are tracked automatically +- Credential redaction +- Duplicate memory cleanup +- Superseding older decisions with newer ones +- Filtering stack traces, git hashes, raw errors, and noisy path-heavy facts +- Rejecting temporary project progress snapshots -Just install and let it run. The plugin hooks into OpenCode's lifecycle events and does the right thing. +The goal is to remember durable facts, not every detail. ## Configuration -The plugin works out of the box with sensible defaults: +The plugin works out of the box. -- **Workspace Memory**: 5200 chars, 28 entries max -- **Hot State**: 1200 chars rendered, 8 active files, 3 errors shown -- **Storage**: `~/.local/share/opencode-working-memory/workspaces/{hash}/` +Default behavior: -See [Configuration Guide](docs/configuration.md) for customization options. +- Workspace memory budget: 5200 characters +- Workspace memory limit: 28 entries +- Hot session state budget: 1200 characters +- Active files shown: 8 +- Open errors shown: 3 -## For AI Agents +See [Configuration](docs/configuration.md) for customization options. -When using this plugin, the memory context appears in your system prompt. You can: +## Ongoing Work -1. **Tell users about memories**: "I remember you decided to use npm cache for plugins" -2. **Ask about preferences**: "Should I add this to my memory for this workspace?" -3. **Note important decisions**: These will be extracted during compaction +Current focus: -To add something to long-term memory explicitly: -``` -Remember this: [your note here] -``` - -The plugin captures this during compaction. +- Improve memory recording quality so only durable, useful facts are kept. +- Strengthen deduplication and supersession so stale memories do not pile up. +- Add better forgetting behavior for obsolete decisions, preferences, and project facts. ## Documentation -- [Architecture Overview](docs/architecture.md) - How the three layers work -- [Configuration](docs/configuration.md) - Customization options -- [Installation Guide](docs/installation.md) - Step-by-step setup +- [Architecture Overview](docs/architecture.md) +- [Configuration](docs/configuration.md) +- [Installation Guide](docs/installation.md) ## Development @@ -251,13 +218,13 @@ npm run typecheck ## License -MIT License - see [LICENSE](LICENSE) file for details. +MIT License. See [LICENSE](LICENSE) for details. ## Support -- 📖 [Documentation](docs/) -- 🐛 [Report Issues](https://github.com/sdwolf4103/opencode-working-memory/issues) +- [Documentation](docs/) +- [Report Issues](https://github.com/sdwolf4103/opencode-working-memory/issues) --- -**Made with ❤️ for the OpenCode community** \ No newline at end of file +Made with ❤️ for the OpenCode community.