{"id":50345049,"url":"https://github.com/geco/opencode-mempalace-persistence","last_synced_at":"2026-05-29T19:30:24.165Z","repository":{"id":358052246,"uuid":"1239744364","full_name":"geco/opencode-mempalace-persistence","owner":"geco","description":"OpenCode plugin — real-time memory sync to MemPalace with auto-categorization and Knowledge Graph","archived":false,"fork":false,"pushed_at":"2026-05-15T14:08:58.000Z","size":33,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-15T15:15:18.963Z","etag":null,"topics":["ai-memory","memory","mempalace","opencode","opencode-plugin","typescript"],"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/geco.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":null,"dco":null,"cla":null}},"created_at":"2026-05-15T11:53:45.000Z","updated_at":"2026-05-15T14:09:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/geco/opencode-mempalace-persistence","commit_stats":null,"previous_names":["geco/opencode-mempalace"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/geco/opencode-mempalace-persistence","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geco%2Fopencode-mempalace-persistence","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geco%2Fopencode-mempalace-persistence/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geco%2Fopencode-mempalace-persistence/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geco%2Fopencode-mempalace-persistence/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/geco","download_url":"https://codeload.github.com/geco/opencode-mempalace-persistence/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geco%2Fopencode-mempalace-persistence/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33668185,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"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","memory","mempalace","opencode","opencode-plugin","typescript"],"created_at":"2026-05-29T19:30:21.644Z","updated_at":"2026-05-29T19:30:24.154Z","avatar_url":"https://github.com/geco.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# opencode-mempalace-persistence\n\nAn OpenCode plugin that automatically saves every conversation to MemPalace and uses stored memory to provide better, context-aware responses. Real-time, zero cron, zero external scripts.\n\n\u003e **It just works** — install, use OpenCode, the plugin handles the rest.\n\n[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n---\n\n## How it works in 3 seconds\n\n| Without plugin | With plugin |\n|---|---|\n| Every session starts from scratch | The model knows who you are and what you've done |\n| You repeat context each time | Memory is automatic |\n| Model starts from scratch each time | Memory persists across sessions |\n\nThe model searches MemPalace on every question (via AGENTS.md + MCP), and the plugin saves every response. A perfect feedback loop.\n\n---\n\n## Installation\n\n### 1. Plugin (saves conversations)\n\n```json\n{\n  \"plugin\": [\"opencode-mempalace-persistence\"]\n}\n```\n\nAdd this line to your `~/.config/opencode/opencode.json` and restart OpenCode.\n\n### 2. Instructions for the model (uses memory)\n\nCreate `~/.config/opencode/AGENTS.md`:\n\n```markdown\n# Memory \u0026 Knowledge instructions\n\n## CRITICAL: You MUST follow these steps BEFORE every response.\n\n### Step 1 — Search MemPalace\nCall `mempalace_mempalace_search` with the user's question or key topics as query. Get the top 5-10 most relevant memory drawers.\n**This is mandatory. Never skip this step. No exceptions.** Every question — even seemingly trivial ones — may relate to past conversations, projects, or preferences you've forgotten. Searching costs ~nothing; skipping costs continuity.\n\n### Step 2 — Query Knowledge Graph\nCall `mempalace_mempalace_kg_query` for entity \"user\". Then filter the returned facts — keep only those whose text contains keywords from the user's question, so irrelevant facts are excluded.\n\n### Step 3 — Use the context\nIncorporate relevant memory and facts into your response. If the user's question relates to a past conversation, project, or decision, reference it naturally. If the search returned nothing useful, you are done — do NOT skip steps 1-2 just because you *expect* nothing.\n\n### Naming reminder\nAll MemPalace tools use the prefix `mempalace_mempalace_*` (not `mempalace_*`). Examples:\n- `mempalace_mempalace_search` (NOT `mempalace_search`)\n- `mempalace_mempalace_kg_query` (NOT `mempalace_kg_query`)\n- `mempalace_mempalace_add_drawer`\n- `mempalace_mempalace_get_drawer`\n- `mempalace_mempalace_list_wings`\nIf you ever catch yourself typing `mempalace_search` or `mempalace_kg_query`, STOP — the correct prefix is `mempalace_mempalace_`.\n\n## Note\n\nThe KG stores structured facts like: decision (choices made), milestone (completed tasks), problem (issues encountered), preference (likes/dislikes), emotional (feelings). Use these to understand the user's history and context better.\n\n### Knowledge Graph management\n\nWhen you discover structured facts during conversation (decisions made, milestones reached, problems encountered, preferences expressed, emotional states), record them in the Knowledge Graph:\n\n- **New facts**: Call `mempalace_mempalace_kg_add` with subject → predicate → object (e.g. `subject=\"user\"`, `predicate=\"preference\"`, `object=\"prefers TypeScript over Python\"`)\n- **Changed facts**: First call `mempalace_mempalace_kg_invalidate` on the old fact, then `mempalace_mempalace_kg_add` for the new one\n- **Retrieval**: Call `mempalace_mempalace_kg_query` for entity \"user\" to see all known facts\n\nThis is optional but recommended — the more facts you record, the better the model understands the user's history and preferences.\n```\n\n### 3. Identity (who you are)\n\nCreate `~/.mempalace/identity.txt`:\n\n```\nI am [name], a [role]. I work with [technologies]. My main projects are [projects].\n```\n\nThis is loaded automatically at session start via `instructions` in opencode.json.\n\n### 4. Complete configuration\n\n`~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"model\": \"opencode/deepseek-v4-flash-free\",\n  \"instructions\": [\"AGENTS.md\", \"~/.mempalace/identity.txt\"],\n  \"plugin\": [\"opencode-mempalace-persistence\"],\n  \"mcp\": {\n    \"mempalace\": {\n      \"type\": \"local\",\n      \"command\": [\"mempalace-mcp\"],\n      \"enabled\": true\n    }\n  }\n}\n```\n\n### 5. MemPalace (if not already installed)\n\n```bash\n# Install (requires mempalace\u003e=3.3.5 for HNSW corruption fix)\nuv tool install \"mempalace\u003e=3.3.5\"\n# or\npipx install \"mempalace\u003e=3.3.5\"\n\n# Create palace\nmempalace init ~/opencode-memory\n\n# Configure MCP\nmempalace mcp\n```\n\nThe `mempalace mcp` command gives you the exact MCP setup string for your configuration.\n\n---\n\n## What happens after installation\n\n```\nYou ask a question\n  → AGENTS.md tells the model: \"search MemPalace first\"\n  → The model calls mempalace_search(\"question\") via MCP\n  → Finds relevant memories → gives a better answer\n\nThe model responds\n  → The opencode-mempalace-persistence plugin detects the response is complete\n  → Saves the conversation to MemPalace (flat export, no hardcoded wings)\n  → The model may record KG facts via MCP tools (optional, per-session)\n\nNext time you ask\n  → The model finds the previous memory → coherent responses\n  → The cycle continues, memory grows\n```\n\n---\n\n## What gets saved\n\nEvery turn (question + answer) is saved as a drawer in MemPalace. No forced categorization — MemPalace's own mining handles organization. The model can optionally record KG facts (decisions, milestones, preferences) during conversation via MCP tools.\n\n---\n\n## Architecture\n\n```\n                 ┌──────────────────────────┐\n                 │       OpenCode            │\n                 │                           │\n  User msg ─────►│  chat.message hook        │\n                 │    ↓                      │\n                 │  Query OpenCode DB        │\n                 │  (messages since lastSync)│\n                 │    ↓                      │\n                 │  Export sessions → flat   │\n                 │  (no wing subdirs)        │\n                 │    ↓                      │\n                 │  Save state immediately   │\n                 │    ↓                      │\n                 │  mempalace mine (async)   │\n                 │  single call, serialized  │\n                 │    ↓                      │\n  Session idle ─►│  session.idle hook        │\n                 │  (saves last turn)        │\n                 └──────────────────────────┘\n                            │\n                            ▼\n                 ┌──────────────────────────┐\n                 │      MemPalace            │\n                 │  ~/opencode-memory/       │\n                 │  Vector DB                │\n                 └──────────────────────────┘\n                            ▲\n                            │\n                 ┌──────────────────────────┐\n                 │  AGENTS.md + MCP          │\n                 │  The model searches       │\n                 │  MemPalace on every       │\n                 │  question. Optionally     │\n                 │  records KG facts via     │\n                 │  kg_add / kg_invalidate   │\n                 └──────────────────────────┘\n```\n\n---\n\n## Relevant files\n\n| File | Purpose |\n|---|---|\n| `~/.config/opencode/opencode.json` | OpenCode config with plugin + MCP + instructions |\n| `~/.config/opencode/AGENTS.md` | Tells the model to search MemPalace |\n| `~/.mempalace/identity.txt` | Your identity (loaded every session) |\n| `~/.mempalace/config.json` | MemPalace config (palace path, wings, keywords) |\n| `~/.mempalace/knowledge_graph.sqlite3` | Knowledge Graph (structured facts) |\n| `~/opencode-memory/` | MemPalace vector DB (all drawers) |\n| `~/.mempalace/sync_state.json` | Last sync state (plugin + Python script) |\n\n---\n\n## Install from npm\n\n```json\n{\n  \"plugin\": [\"opencode-mempalace-persistence\"]\n}\n```\n\n## Local development\n\n```json\n{\n  \"plugin\": [\"/path/to/opencode-mempalace-persistence/dist/index.js\"]\n}\n```\n\n## Debug logging\n\n```bash\nexport OPENCODE_MEMPALACE_DEBUG=1\n```\n\nWhen set, the plugin writes a debug log to `/tmp/opencode-mempalace.log`.\n\n---\n\n## Recommendations\n\n### Model choice affects memory retrieval reliability\n\nEmpirical data from the MemPalace community (Cat-9a diagnostic) shows that the model's tool-use discipline significantly impacts how reliably `mempalace_search` is invoked:\n\n| Model | Skips search | Mean recall |\n|-------|:-:|:-:|\n| gemma4:e4b (4B) | **60%** | 0.417 |\n| qwen3.5:4b (4B, Tau2-tuned) | **13%** | 0.717 |\n\nFor reliable read-side memory retrieval, **Qwen 3.5 4B+ or equivalent** is recommended as the minimum orchestrator. Smaller or older models may skip memory search on most questions regardless of AGENTS.md instructions.\n\n### Forced invocation (belt and suspenders)\n\nA plugin-level config flag that injects a mandatory `mempalace_search` directive into the system prompt (on top of AGENTS.md) can recover ~15pp of recall on low-discipline models. This is being evaluated as a future config option — suggestions welcome.\n\n### Complementary: upstream OpenCode source adapter\n\nThe MemPalace project has an upstream PR ([#1484](https://github.com/MemPalace/mempalace/pull/1484)) adding `mempalace mine --source opencode` — a pull-based adapter for retrospective ingest of existing OpenCode sessions. This plugin (push, real-time) and the adapter (pull, backfill) are complementary:\n\n| Approach | Direction | Captures |\n|----------|-----------|----------|\n| This plugin | Push | Live conversation turns |\n| `mempalace mine --source opencode` (PR #1484) | Pull | Existing OpenCode session files |\n\nFor full coverage: install this plugin for live capture, run `mempalace mine --source opencode` once for backfill, never think about it again.\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeco%2Fopencode-mempalace-persistence","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeco%2Fopencode-mempalace-persistence","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeco%2Fopencode-mempalace-persistence/lists"}