{"id":47861447,"url":"https://github.com/kuitos/opencode-claude-memory","last_synced_at":"2026-04-13T12:02:20.284Z","repository":{"id":348268435,"uuid":"1197196805","full_name":"kuitos/opencode-claude-memory","owner":"kuitos","description":"🔄 Claude Code-compatible memory for OpenCode — zero config, local-first, no migration.","archived":false,"fork":false,"pushed_at":"2026-04-06T16:58:44.000Z","size":85,"stargazers_count":9,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-07T02:03:11.088Z","etag":null,"topics":["claude-code","memory","opencode","plugin"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/opencode-claude-memory","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/kuitos.png","metadata":{"files":{"readme":"README.md","changelog":null,"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-03-31T11:59:04.000Z","updated_at":"2026-04-06T11:51:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kuitos/opencode-claude-memory","commit_stats":null,"previous_names":["kuitos/opencode-memory-plugin"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/kuitos/opencode-claude-memory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuitos%2Fopencode-claude-memory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuitos%2Fopencode-claude-memory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuitos%2Fopencode-claude-memory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuitos%2Fopencode-claude-memory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kuitos","download_url":"https://codeload.github.com/kuitos/opencode-claude-memory/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuitos%2Fopencode-claude-memory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31751707,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T09:16:15.125Z","status":"ssl_error","status_checked_at":"2026-04-13T09:16:05.023Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["claude-code","memory","opencode","plugin"],"created_at":"2026-04-03T23:43:28.395Z","updated_at":"2026-04-13T12:02:20.274Z","avatar_url":"https://github.com/kuitos.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🧠 Claude Code-compatible memory for OpenCode\n\n**Make OpenCode and Claude Code share the same memory — zero config, local-first, and no migration required.**\n\nClaude Code writes memory → OpenCode reads it. OpenCode writes memory → Claude Code reads it.\n\n[![npm version](https://img.shields.io/npm/v/opencode-claude-memory.svg?style=flat-square)](https://www.npmjs.com/package/opencode-claude-memory)\n[![npm downloads](https://img.shields.io/npm/dm/opencode-claude-memory.svg?style=flat-square)](https://www.npmjs.com/package/opencode-claude-memory)\n[![License](https://img.shields.io/npm/l/opencode-claude-memory.svg?style=flat-square)](https://github.com/kuitos/opencode-claude-memory/blob/main/LICENSE)\n\n[Quick Start](#-quick-start) • [Why this exists](#-why-this-exists) • [What makes this different](#-what-makes-this-different) • [How it works](#-how-it-works) • [Who this is for](#-who-this-is-for) • [FAQ](#-faq)\n\n\u003c/div\u003e\n\n---\n\n## ✨ At a glance\n\n- **Claude Code-compatible memory**\n  Uses Claude Code’s existing memory paths, file format, and taxonomy.\n- **Zero config**\n  Install + enable plugin, then keep using `opencode` as usual.\n- **Local-first, no migration**\n  Memory stays as local Markdown files in the same directory Claude Code already uses.\n- **Auto-dream consolidation**\n  Periodically runs a background memory consolidation pass (Claude-style auto-dream gating).\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- `opencode`\n- `python3` available in `PATH`\n\n`python3` is a runtime dependency for the wrapper's scoped session detection and fork cleanup logic.\nIf it is missing or not executable, post-session maintenance becomes less reliable: session targeting can fall back to less precise heuristics, and fork cleanup is skipped for safety.\n\nCommon install commands:\n\n```bash\n# macOS (Homebrew)\nbrew install python\n\n# Ubuntu / Debian\nsudo apt-get update \u0026\u0026 sudo apt-get install -y python3\n\n# Fedora\nsudo dnf install -y python3\n\n# Arch Linux\nsudo pacman -S python\n```\n\n### 1. Install\n\n```bash\nnpm install -g opencode-claude-memory\nopencode-memory install   # one-time: installs shell hook\n```\n\nThis installs:\n- The **plugin** — memory tools + system prompt injection\n- The `opencode-memory` **CLI** — wraps opencode with automatic memory extraction + auto-dream consolidation\n- A **shell hook** — defines an `opencode()` function in your `.zshrc`/`.bashrc` that delegates to `opencode-memory`\n\nIf `python3` is not installed yet, install it first using the commands above before enabling the shell hook.\n\n### 2. Configure\n\n```jsonc\n// opencode.json\n{\n  \"plugin\": [\"opencode-claude-memory\"]\n}\n```\n\n### 3. Use\n\n```bash\nopencode\n```\n\nThat’s it. Memory extraction runs in the background after each session, and auto-dream consolidation is checked with time/session gates.\n\nTo uninstall:\n\n```bash\nopencode-memory uninstall   # removes shell hook from .zshrc/.bashrc\nnpm uninstall -g opencode-claude-memory\n```\n\nTo print the wrapper package version:\n\n```bash\nopencode-memory self -v\n```\n\nThis removes the shell hook, the CLI, and the plugin. Your saved memories in `~/.claude/projects/` are **not** deleted.\n\n## 💡 Why this exists\n\nIf you use both Claude Code and OpenCode on the same repository, memory often ends up in separate silos.\n\nThis project solves that by making OpenCode read and write memory in Claude Code’s existing structure, so your context carries over naturally between both tools.\n\n## 🧩 What makes this different\n\nMost memory plugins introduce a new storage model or migration step.\n\nThis one is a **compatibility layer**, not a new memory system:\n\n- same memory directory conventions as Claude Code\n- same Markdown + frontmatter format\n- same memory taxonomy (`user`, `feedback`, `project`, `reference`)\n- same project/worktree resolution behavior\n\nThe outcome: **shared context across Claude Code and OpenCode without maintaining two memory systems.**\n\n## ⚙️ How it works\n\n```mermaid\ngraph LR\n    A[You run opencode] --\u003e B[Shell hook calls opencode-memory]\n    B --\u003e C[opencode-memory finds real binary]\n    C --\u003e D[Runs opencode normally]\n    D --\u003e E[You exit]\n    E --\u003e F[Extract memories if needed]\n    F --\u003e G[Evaluate auto-dream gate]\n    G --\u003e H[Consolidate memories if gate passes]\n    H --\u003e I[Memories saved to ~/.claude/projects/]\n```\n\nThe shell hook defines an `opencode()` function that delegates to `opencode-memory`:\n\n1. Shell function intercepts `opencode` command (higher priority than PATH)\n2. `opencode-memory` finds the real `opencode` binary in PATH\n3. Runs it with all your arguments\n4. After you exit, it checks whether the session already wrote memory files\n5. If needed, it forks the session with a memory extraction prompt\n6. It evaluates the auto-dream gate (default: at least 24h since last consolidation and 5 touched sessions)\n7. If the gate passes, it runs a background consolidation pass to merge/prune memories\n8. Maintenance runs **in the background** unless `OPENCODE_MEMORY_FOREGROUND=1`\n9. Terminal maintenance logs are shown in foreground mode by default, or can be forced on/off with `OPENCODE_MEMORY_TERMINAL_LOG=1|0`\n\n### Runtime dependencies\n\nThe wrapper expects `python3` to be available at runtime.\n\nIt is used for:\n\n- scoped session selection from `opencode session list`\n- parsing `opencode export` output to resolve session directories\n- safely identifying and cleaning up forked extraction / auto-dream sessions\n\nWithout `python3`, the plugin tools still load, but wrapper maintenance is degraded and fork cleanup is intentionally skipped to avoid deleting the wrong session.\n\n### Compatibility details\n\nThe implementation ports core logic from Claude Code for path hashing, git-root/worktree handling, memory format, and memory prompting behavior, so both tools can operate on the same files safely.\n\nKey modules ported from Claude Code's `src/memdir/`:\n\n| Module | Source | Purpose |\n|---|---|---|\n| `memoryScan.ts` | `memoryScan.ts` | Recursive directory scan + frontmatter header parsing |\n| `recall.ts` | `findRelevantMemories.ts` | Memory recall via keyword scoring (heuristic, no LLM side-query) |\n| `prompt.ts` | `memoryTypes.ts` + `memdir.ts` | System prompt sections, type taxonomy, truncation |\n| `memory.ts` | `memdir.ts` | `truncateEntrypoint()` aligned with `truncateEntrypointContent()` |\n\n## 👥 Who this is for\n\n- You use **both Claude Code and OpenCode**.\n- You want **one shared memory context** across both tools.\n- You prefer **file-based, local-first memory** you can inspect in Git/worktrees.\n- You don’t want migration overhead or lock-in.\n\n## ❓ FAQ\n\n### Is this a new memory system?\n\nNo. It is a compatibility layer that lets OpenCode use Claude Code-compatible memory layout and conventions.\n\n### Do I need to migrate existing memory?\n\nNo migration required. If you already have Claude Code memory files, OpenCode can work with them directly.\n\n### Where is data stored?\n\nIn local files under Claude-style project memory directories (for example, under `~/.claude/projects/\u003cproject\u003e/memory/`).\n\n### Why file-based memory?\n\nFile-based memory is transparent, local-first, easy to inspect/diff/back up, and works naturally with existing developer workflows.\n\n### Can I disable auto extraction?\n\nYes. Set `OPENCODE_MEMORY_EXTRACT=0`.\n\n### Can I disable auto-dream?\n\nYes. Set `OPENCODE_MEMORY_AUTODREAM=0`. You can also tune gates with:\n- `OPENCODE_MEMORY_AUTODREAM_MIN_HOURS`\n- `OPENCODE_MEMORY_AUTODREAM_MIN_SESSIONS`\n\n## 🔧 Configuration\n\n### Environment variables\n\n- `OPENCODE_MEMORY_EXTRACT` (default `1`): set `0` to disable automatic memory extraction\n- `OPENCODE_MEMORY_FOREGROUND` (default `0`): set `1` to run maintenance in foreground\n- `OPENCODE_MEMORY_TERMINAL_LOG` (default `foreground-only`): set `1` to force terminal logs on, `0` to force them off\n- `OPENCODE_MEMORY_MODEL`: override model used for extraction\n- `OPENCODE_MEMORY_AGENT`: override agent used for extraction\n- `OPENCODE_MEMORY_AUTODREAM` (default `1`): set `0` to disable auto-dream consolidation\n- `OPENCODE_MEMORY_AUTODREAM_MIN_HOURS` (default `24`): min hours between consolidation runs\n- `OPENCODE_MEMORY_AUTODREAM_MIN_SESSIONS` (default `5`): min touched sessions since last consolidation\n- `OPENCODE_MEMORY_AUTODREAM_MODEL`: override model used for auto-dream\n- `OPENCODE_MEMORY_AUTODREAM_AGENT`: override agent used for auto-dream\n\n### Logs\n\nLogs are written to `$TMPDIR/opencode-memory-logs/`:\n- `extract-*.log`: automatic memory extraction\n- `dream-*.log`: auto-dream consolidation\n\nBy default, terminal log lines are only printed when maintenance runs in foreground (`OPENCODE_MEMORY_FOREGROUND=1`). Background runs stay quiet unless you explicitly set `OPENCODE_MEMORY_TERMINAL_LOG=1`.\n\n### Concurrency safety\n\nLock files prevent concurrent extraction/consolidation runs per project root. Stale locks are cleaned up automatically.\n\n## 📝 Memory format\n\nEach memory is a Markdown file with YAML frontmatter:\n\n```markdown\n---\nname: User prefers terse responses\ndescription: User wants concise answers without trailing summaries\ntype: feedback\n---\n\nSkip post-action summaries. User reads diffs directly.\n\n**Why:** User explicitly requested terse output style.\n**How to apply:** Don't summarize changes at the end of responses.\n```\n\nSupported memory types:\n- `user`\n- `feedback`\n- `project`\n- `reference`\n\n## 🔧 Tools reference\n\n- `memory_save`: save/update a memory\n- `memory_delete`: delete a memory by filename\n- `memory_list`: list memory metadata\n- `memory_search`: search by keyword\n- `memory_read`: read full memory content\n\n## 🧪 Development\n\n```bash\n# Run tests\nbun test\n\n# Build published artifacts\nbun run build\n\n# Release: push to main triggers semantic-release → npm publish\n```\n\n## 📄 License\n\n[MIT](LICENSE) © [kuitos](https://github.com/kuitos)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuitos%2Fopencode-claude-memory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkuitos%2Fopencode-claude-memory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuitos%2Fopencode-claude-memory/lists"}