{"id":44923393,"url":"https://github.com/sdwolf4103/opencode-working-memory","last_synced_at":"2026-05-15T05:15:31.762Z","repository":{"id":339102938,"uuid":"1160488919","full_name":"sdwolf4103/opencode-working-memory","owner":"sdwolf4103","description":"Automatic memory for OpenCode agents: persistent workspace memory, hot session context, and compaction-based memory extraction — with zero extra API calls.","archived":false,"fork":false,"pushed_at":"2026-05-08T05:05:55.000Z","size":521,"stargazers_count":115,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-08T06:54:01.042Z","etag":null,"topics":["ai-memory-system","opencode","opencode-plugin"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sdwolf4103.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-18T02:07:31.000Z","updated_at":"2026-05-08T05:08:03.000Z","dependencies_parsed_at":"2026-02-18T07:01:36.020Z","dependency_job_id":null,"html_url":"https://github.com/sdwolf4103/opencode-working-memory","commit_stats":null,"previous_names":["sdwolf4103/opencode-working-memory"],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/sdwolf4103/opencode-working-memory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdwolf4103%2Fopencode-working-memory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdwolf4103%2Fopencode-working-memory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdwolf4103%2Fopencode-working-memory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdwolf4103%2Fopencode-working-memory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sdwolf4103","download_url":"https://codeload.github.com/sdwolf4103/opencode-working-memory/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdwolf4103%2Fopencode-working-memory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33054633,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-15T02:00:06.351Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-memory-system","opencode","opencode-plugin"],"created_at":"2026-02-18T04:01:10.383Z","updated_at":"2026-05-15T05:15:31.741Z","avatar_url":"https://github.com/sdwolf4103.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenCode Working Memory\n\n[![npm version](https://img.shields.io/npm/v/opencode-working-memory.svg)](https://www.npmjs.com/package/opencode-working-memory)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nAutomatic memory for OpenCode agents.\n\nWorking memory is context that **remembers what matters, fades what changes, and stays out of the way.**\n\nOpenCode Working Memory preserves project decisions, preferences, and references across compactions and sessions, while keeping active files and unresolved errors fresh for the current session — with no manual tools or extra LLM/API calls.\n\n## Why This Exists\n\nOpenCode compaction keeps conversations manageable, but important context can still get lost over time.\n\nIt adds a workspace-aware memory layer so your agent can remember durable facts while keeping short-term session state fresh and lightweight.\n\nUse it when you want your agent to remember things like:\n\n- Project conventions\n- User preferences\n- Architecture decisions\n- Important file paths or references\n- Current active files and unresolved errors\n\n## Features\n\n- **Workspace memory** — durable project facts, preferences, decisions, and references across sessions.\n- **Hot session state** — active files, open errors, and current working context for the current session.\n- **Explicit memory triggers** — users can say “remember this”, “記住”, “覚えて”, or “기억해” to save durable facts.\n- **Compaction-based extraction** — memory extraction piggybacks on OpenCode’s existing compaction flow.\n- **Numbered memory refs** — compaction can `REINFORCE [M#]` useful memories or safely `REPLACE [M#]` obsolete compaction memories.\n- **No manual tools** — memory is injected automatically into the system prompt.\n- **Quality guards** — filters noisy memories, temporary progress snapshots, stack traces, raw errors, and credentials.\n- **Retention decay** — keeps the strongest memories in prompt context while older or weaker memories fade out naturally; important and reinforced memories decay more slowly.\n\n## Installation\n\nAdd OpenCode Working Memory to your OpenCode config:\n\n```json\n{\n  \"plugin\": [\"opencode-working-memory\"]\n}\n```\n\nThen restart OpenCode. It activates automatically.\n\n## How It Works\n\nOpenCode Working Memory adds durable memory without making extra LLM/API calls.\n\n```text\n┌──────────────────────────────────────┐\n│ 🧭 Conversation Events               │\n│ edits, commands, errors, remembers   │\n└──────────────────┬───────────────────┘\n                   ▼\n┌──────────────────────────────────────┐\n│ 🔥 Hot Session State                 │\n│ active files, open errors, pending   │\n│                                      │\n│ ~/.local/share/opencode-working-     │\n│ memory/workspaces/{hash}/sessions/   │\n│ {sessionID}.json                     │\n└──────────────────┬───────────────────┘\n                   │ when OpenCode compacts\n                   ▼\n┌──────────────────────────────────────┐\n│ 🧠 OpenCode Compaction               │\n│ existing LLM/API call                │\n│ + memory extraction instructions     │\n│                                      │\n│ zero extra API calls                 │\n└──────────────────┬───────────────────┘\n                   │ filter, redact, dedupe\n                   ▼\n┌──────────────────────────────────────┐\n│ 📦 Workspace Memory                  │\n│ decisions, preferences, refs         │\n│                                      │\n│ ~/.local/share/opencode-working-     │\n│ memory/workspaces/{hash}/            │\n│ workspace-memory.json                │\n└──────────────────┬───────────────────┘\n                   ▼\n┌──────────────────────────────────────┐\n│ ⚡ Prompt Context                     │\n│ system[1]*: frozen workspace memory  │\n│ system[2+]*: hot session state       │\n└──────────────────────────────────────┘\n```\n\n\\* Conceptually, workspace memory is pushed first when it is non-empty, and hot session state is pushed after workspace memory. If workspace memory is empty, hot state may be the first plugin-added system message. Actual `system[]` indices also depend on OpenCode and other plugins, so `system[1]` / `system[2+]` is a simplified model.\n\n**Zero extra API calls:** OpenCode Working Memory does not call the model on its own. Memory extraction is folded into OpenCode's built-in compaction request.\n\n**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.\n\nThe runtime context has three layers:\n\n| Layer | Purpose | Lifetime |\n|---|---|---|\n| Workspace Memory | Durable decisions, preferences, project facts, references | Cross-session |\n| Hot Session State | Active files, open errors, recent context | Current session |\n| Native OpenCode State | Todos and built-in state | OpenCode-managed |\n\n## Workspace Memory\n\nWorkspace memory is for durable information that should help future sessions.\n\nExamples:\n\n```md\n- [decision] Use npm cache for plugin loading, not npm link.\n- [project] This repo uses TypeScript and Node.js test runner.\n- [feedback] User prefers concise implementation summaries.\n- [reference] Storage lives under ~/.local/share/opencode-working-memory/.\n```\n\nMemory types:\n\n- `feedback` — user preferences or recurring feedback\n- `project` — stable project-level facts\n- `decision` — important implementation or architecture decisions\n- `reference` — useful paths, commands, or configuration references\n\n### Retention Decay\n\n\u003e **Memory should fade, so the agent can keep learning.**\n\u003e\n\u003e Important memories decay more slowly, but every memory must leave room for newer project reality.\n\nMemories decay over time. The strongest stay visible in the prompt; weaker ones fade from context without being deleted.\n\n```text\n  strength\n    │\n ██ │╲____   reinforced: slower decline\n    │     ╲______\n ▒▒ │            ╲__ ordinary memory\n    │               ╲\n    ├ ─ ─ ─ ─ ─ ─ ─ ─╲─ dynamic cap competition zone\n ░░ │                 ╲  easier for new memories to replace\n    │                  ↑ still stored, not deleted\n    └──────────────────────────────→ time / sessions\n```\n\n## Explicit Memory Triggers\n\nYou can explicitly ask the agent to remember durable facts.\n\nExamples:\n\n```md\nRemember this: we prefer Vitest for new frontend tests.\n記住：這個 repo 發 release 前要先跑 npm test。\n覚えておいて: API clients should use the shared retry helper.\n기억해줘: this project uses pnpm, not npm.\n```\n\nSupported trigger languages include:\n\n| Language | Examples |\n|---|---|\n| English | `remember this`, `save to memory`, `from now on`, `my preference` |\n| Chinese | `記住`, `记住`, `記得`, `请帮我记住` |\n| Japanese | `覚えて`, `覚えておいて`, `メモして` |\n| Korean | `기억해`, `기억해줘`, `메모해줘` |\n\nNegative requests are respected too:\n\n```md\nDon't remember this.\n不要記住這個。\n覚えないで。\n기억하지 마.\n```\n\nAvoid saving:\n\n- Secrets, passwords, tokens, or credentials\n- Temporary progress updates\n- Raw command output\n- Short-lived session details\n\n## Quality Guards\n\nOpenCode Working Memory tries to keep memory useful and low-noise.\n\nIt includes guards for:\n\n- Credential redaction\n- Duplicate memory cleanup\n- Accounting for promoted, absorbed, superseded, and rejected memories\n- Strength-based retention so useful memories stay visible without hard age pruning\n- Filtering stack traces, git hashes, raw errors, and noisy path-heavy facts\n- Rejecting temporary project progress snapshots\n\nThe goal is to remember durable facts, not every detail.\n\n**Good memory is selective memory.**\n\nHistorical cleanup is intentionally conservative: extraction-time filtering may reject more aggressively, but one-time migration cleanup only supersedes high-confidence garbage patterns. This protects existing durable memories written in declarative style, such as \"API endpoint is X\" or \"Product branding is Y\".\n\n### Numbered Memory Refs\n\nDuring compaction, existing workspace memories may be shown as numbered refs such as `[M1]` or `[M2]`. The model can use these refs to maintain memory without duplicating it:\n\n```md\nREINFORCE [M1]\nREPLACE [M2] project Updated durable project fact.\n```\n\n- `REINFORCE [M#]` strengthens an existing memory's retention signal without changing its text.\n- `REPLACE [M#] [type] text` supersedes a safe compaction-sourced memory and adds a replacement.\n- Manual, explicit, and already-reinforced memories are protected from automatic replacement.\n- Stale or mismatched numbered refs are rejected instead of mutating the wrong memory.\n\nUse `memory-diag commands` to inspect command outcomes and `memory-diag revert` to dry-run and apply manual recovery for successful numbered replacements.\n\n### Memory Diagnostics CLI\n\nUse the read-only diagnostics CLI when you want to understand what memory is doing for the current workspace.\n\n| Question | Command |\n|---|---|\n| Is memory healthy? | `npx --package opencode-working-memory memory-diag` or `npx --package opencode-working-memory memory-diag status` |\n| Why was something rejected? | `npx --package opencode-working-memory memory-diag rejected` |\n| Where did my memory go? | `npx --package opencode-working-memory memory-diag missing` |\n| Why is this memory shown or hidden? | `npx --package opencode-working-memory memory-diag explain \u003cmemory-id\u003e` |\n| How are numbered memory commands behaving? | `npx --package opencode-working-memory memory-diag commands` |\n| Revert a numbered replacement? | `npx --package opencode-working-memory memory-diag revert --memory \u003creplacement-memory-id\u003e` |\n\nGlobal options:\n\n- `--workspace \u003cpath\u003e` — inspect another workspace; defaults to the current directory.\n- `--verbose` — show detailed diagnostics.\n- `--json` — print machine-readable output where supported.\n\nExamples:\n\n```bash\nnpx --package opencode-working-memory memory-diag status\nnpx --package opencode-working-memory memory-diag rejected --verbose\nnpx --package opencode-working-memory memory-diag missing --workspace /path/to/project\nnpx --package opencode-working-memory memory-diag status --json\nnpx --package opencode-working-memory memory-diag commands --verbose\nnpx --package opencode-working-memory memory-diag revert --memory \u003creplacement-memory-id\u003e\n```\n\n`memory-diag revert` is dry-run by default. Add `--apply` only after reviewing the planned original/replacement status changes.\n\nThe npm package is opencode-working-memory; the installed bin is memory-diag, so package-qualified npx avoids resolving a different package named memory-diag.\n\nMaintainer-only diagnostics and cleanup commands are intentionally not documented here. Future work: move those internal commands to `docs/development.md`.\n\n## Configuration\n\nOpenCode Working Memory works out of the box.\n\nDefault behavior:\n\n- Workspace memory budget: 3600 characters (~900 tokens)\n- Workspace memory limit: 28 entries\n- Hot session state budget: 700 characters (~175 tokens)\n- Active files shown: 8\n- Open errors shown: 3\n\nSee [Configuration](docs/configuration.md) for customization options.\n\n## Roadmap\n\nCurrent focus:\n\n- Add explicit delete tombstones so removed memories do not get re-extracted.\n- Monitor numbered refs and protected replacements with `memory-diag commands` before tightening automatic replacement policy further.\n- Explore tiered hot/warm/cold storage after the retention model has more real-world data.\n\n## Documentation\n\n- [Architecture Overview](docs/architecture.md)\n- [Configuration](docs/configuration.md)\n- [Installation Guide](docs/installation.md)\n\n## Development\n\n```bash\ngit clone https://github.com/sdwolf4103/opencode-working-memory.git\ncd opencode-working-memory\nnpm install\nnpm test\nnpm run typecheck\n```\n\n## Requirements\n\n- OpenCode plugin API `\u003e=1.2.0 \u003c2.0.0`\n- Node.js \u003e= 22.6.0 (for `memory-diag` CLI, which runs TypeScript with `--experimental-strip-types`)\n\n## Limitations\n\n- Requires OpenCode plugin API `\u003e=1.2.0 \u003c2.0.0`; OpenCode hook changes may break compatibility.\n- Not a secret manager. Credential redaction is best-effort. Do not store secrets.\n- Working memory only. No semantic search, embeddings, or vector knowledge base.\n- Other prompt or compaction plugins may conflict depending on plugin order.\n- Multiple OpenCode processes on the same workspace may race on local files.\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n\n## Support\n\n- [Documentation](docs/)\n- [Report Issues](https://github.com/sdwolf4103/opencode-working-memory/issues)\n\n---\n\nMade with ❤️ for the OpenCode community.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsdwolf4103%2Fopencode-working-memory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsdwolf4103%2Fopencode-working-memory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsdwolf4103%2Fopencode-working-memory/lists"}