{"id":49499611,"url":"https://github.com/zer020/opencode-mem0","last_synced_at":"2026-05-01T12:01:43.093Z","repository":{"id":354888567,"uuid":"1225470108","full_name":"ZeR020/opencode-mem0","owner":"ZeR020","description":"OpenCode plugin that gives coding agents persistent memory using local vector database","archived":false,"fork":false,"pushed_at":"2026-04-30T18:52:54.000Z","size":2140,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-30T19:16:48.594Z","etag":null,"topics":["ai","coding-agent","local-first","memory","opencode","plugin","sqlite","vector-database"],"latest_commit_sha":null,"homepage":"https://github.com/ZeR020/opencode-mem0","language":"JavaScript","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/ZeR020.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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-04-30T10:03:08.000Z","updated_at":"2026-04-30T18:52:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ZeR020/opencode-mem0","commit_stats":null,"previous_names":["zer020/opencode-mem0"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/ZeR020/opencode-mem0","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZeR020%2Fopencode-mem0","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZeR020%2Fopencode-mem0/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZeR020%2Fopencode-mem0/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZeR020%2Fopencode-mem0/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ZeR020","download_url":"https://codeload.github.com/ZeR020/opencode-mem0/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZeR020%2Fopencode-mem0/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32495949,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"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","coding-agent","local-first","memory","opencode","plugin","sqlite","vector-database"],"created_at":"2026-05-01T12:01:14.045Z","updated_at":"2026-05-01T12:01:43.075Z","avatar_url":"https://github.com/ZeR020.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# opencode-mem0\n\n[![npm version](https://img.shields.io/npm/v/opencode-mem0.svg)](https://www.npmjs.com/package/opencode-mem0)\n[![npm downloads](https://img.shields.io/npm/dm/opencode-mem0.svg)](https://www.npmjs.com/package/opencode-mem0)\n[![license](https://img.shields.io/npm/l/opencode-mem0.svg)](https://github.com/ZeR020/opencode-mem0/blob/main/LICENSE)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/ZeR020/opencode-mem0)\n\n\u003e **An advanced cognitive fork/enhancement of [tickernelz/opencode-mem](https://github.com/tickernelz/opencode-mem).** Built on their excellent foundation of local vector memory for coding agents, then upgraded with a full cognitive architecture.\n\n**A persistent memory system for AI coding agents** that enables long-term context retention across sessions using local vector database technology — now with intelligent scoring, dual-store lifecycle, conflict resolution, and transcript capture.\n\n---\n\n## Quick Start\n\n```bash\n# Install\nnpm install opencode-mem0\n\n# Or use with OpenCode — add to ~/.config/opencode/opencode.json:\n{\n  \"plugin\": [\"opencode-mem0\"]\n}\n```\n\n```bash\n# Store a memory\nmemory add \"User prefers TypeScript strict mode and avoids implicit any\"\n\n# Search memories\nmemory search \"typescript strict mode\"\n\n# List recent memories\nmemory list\n\n# Access the web UI\nopen http://localhost:4747\n```\n\n---\n\n## Screenshots\n\n**Project Memory Timeline:**\n\n[![Project Memory Timeline](https://github.com/ZeR020/opencode-mem0/raw/main/.github/screenshot-project-memory.png)](https://github.com/ZeR020/opencode-mem0)\n\n**User Profile Viewer:**\n\n[![User Profile Viewer](https://github.com/ZeR020/opencode-mem0/raw/main/.github/screenshot-user-profile.png)](https://github.com/ZeR020/opencode-mem0)\n\n\u003c!-- TODO: Add screenshot of Conflict Resolution UI for v2.14.0 --\u003e\n\n---\n\n## What's New in v2.14.0\n\n### Transcript Storage Layer\n\nEvery conversation is captured, stripped of synthetic noise, and stored in a dedicated FTS5-indexed database. Searchable, retrievable, and auto-purged by age.\n\n### 7-Factor Memory Scoring\n\nEvery memory is scored on seven dimensions:\n\n| Factor           | What It Measures                       | Weight |\n| ---------------- | -------------------------------------- | ------ |\n| **Recency**      | How old is the memory?                 | 20%    |\n| **Frequency**    | How often is it accessed?              | 15%    |\n| **Importance**   | Code, technical keywords, file paths?  | 25%    |\n| **Utility**      | Accessed recently in relevant context? | 20%    |\n| **Novelty**      | How unique vs existing memories?       | 10%    |\n| **Confidence**   | Manual, auto-captured, or imported?    | 10%    |\n| **Interference** | Contradicts other memories?            | −10%   |\n\nRolls up into a single **Strength** score (0-1) that drives ranking, promotion, and archival.\n\n### STM / LTM Dual-Store Lifecycle\n\n- **Short-Term Memory (STM)** — Ephemeral, conversational. Decays fast (5%/day). Archived below strength 0.2 after 30 days.\n- **Long-Term Memory (LTM)** — Preferences, architecture, constraints. Slow decay (1%/day) or **zero decay** for critical rules.\n\n**Auto-promotion**: STM memories exceeding strength 0.7 with 3+ accesses get promoted to LTM. No manual tagging needed.\n\nDecay follows the **Ebbinghaus curve**: `strength *= e^(-decay_rate * age_in_days)`.\n\n### Intelligent Conflict Resolution\n\nWhen a new memory contradicts an existing one, opencode-mem0 detects it — first with an **LLM-powered structured check**, then with a **heuristic fallback** using negation patterns and action-verb analysis.\n\nFour resolution strategies: `keep_newer`, `keep_both`, `merge`, `manual`. All conflicts tracked in `memory_conflicts` with resolution history.\n\n### Hybrid Search \u0026 Context-Aware Retrieval\n\nNot just \"nearest neighbor.\" A multi-stage pipeline:\n\n1. **Vector + Tag Similarity** — Content vectors 60%, tag vectors 40%\n2. **FTS5 Boost** — Text matches get ranking bonus\n3. **Multi-Factor Ranking** — `strength * 0.4 + recency * 0.3 + similarity * 0.3`\n4. **Context Boost** — Current project or recent files get up to 50% boost\n5. **Diversity Filtering** — Jaccard similarity penalty prevents redundant results (threshold 0.9)\n\nEvery result includes transparent score breakdown: `vectorSimilarity`, `recencyWeight`, `strengthWeight`, `diversityPenalty`, `contextBoost`, `finalScore`.\n\n---\n\n## Architecture\n\n```\nsrc/\n├── index.ts                    # Plugin entry point, lifecycle hooks, background jobs\n├── config.ts                   # Configuration loading and validation\n├── services/\n│   ├── client.ts               # LocalMemoryClient (add/search/list/delete)\n│   ├── memory-scoring.ts       # 7-factor scoring algorithms\n│   ├── memory-scoring-service.ts  # Background score recalculation job\n│   ├── memory-lifecycle.ts     # STM/LTM classification, decay, promotion, archival\n│   ├── memory-conflicts.ts     # LLM + heuristic contradiction detection \u0026 resolution\n│   ├── retrieval-context.ts    # ContextTracker, context boost, diversity penalty\n│   ├── transcript-capture.ts   # Session transcript lifecycle hook\n│   ├── sqlite/\n│   │   ├── vector-search.ts       # Hybrid FTS5 + vector search with multi-factor ranking\n│   │   ├── transcript-manager.ts  # Transcript DB with FTS5, triggers, cleanup\n│   │   ├── shard-manager.ts       # Database sharding and v2 schema migration\n│   │   └── ...\n│   └── web/                    # Built-in management UI\n│       ├── index.html\n│       ├── app.js\n│       └── styles.css\n```\n\n---\n\n## Configuration\n\nEdit `~/.config/opencode/opencode-mem.jsonc`:\n\n```json\n{\n  \"storagePath\": \"~/.opencode-mem/data\",\n  \"webServerEnabled\": true,\n  \"webServerPort\": 4747,\n  \"autoCaptureEnabled\": true,\n\n  \"transcriptStorage\": {\n    \"enabled\": true,\n    \"maxAgeDays\": 30\n  },\n\n  \"memoryScoring\": {\n    \"enabled\": true,\n    \"recalculationIntervalMinutes\": 60,\n    \"recencyHalfLifeDays\": 7,\n    \"utilityHalfLifeDays\": 3\n  },\n\n  \"memoryLifecycle\": {\n    \"stmDecayDays\": 7,\n    \"ltmDecayDays\": 90,\n    \"promotionThreshold\": 0.7,\n    \"archiveThreshold\": 0.2,\n    \"archiveAfterDays\": 30,\n    \"checkIntervalMinutes\": 60\n  },\n\n  \"retrieval\": {\n    \"maxResults\": 20,\n    \"diversityThreshold\": 0.9,\n    \"contextBoost\": 1.5\n  }\n}\n```\n\n### Memory Scope\n\n- `scope: \"project\"` — query only current project (default)\n- `scope: \"all-projects\"` — query across all project shards\n\n### Auto-Capture AI Provider\n\nRecommended: use opencode's built-in providers (no separate API key):\n\n```json\n{\n  \"opencodeProvider\": \"anthropic\",\n  \"opencodeModel\": \"claude-haiku-4-5-20251001\"\n}\n```\n\n---\n\n## Examples\n\nSee [`examples/basic-usage.ts`](examples/basic-usage.ts) and [`examples/custom-scoring.ts`](examples/custom-scoring.ts) for full walkthroughs.\n\n---\n\n## Migrating from opencode-mem v1\n\nIf you have an existing opencode-mem database:\n\n```bash\nbun run scripts/migrate-v1-to-v2.ts ~/.opencode-mem/data\n```\n\nThis will:\n\n- Detect v1 schema and add all v2 columns safely\n- Backfill recency scores for existing memories\n- Create `memory_conflicts` and `transcripts` databases\n- Add performance indexes\n- Heuristically promote old, high-quality memories to LTM\n\nThe migration is **idempotent** — safe to run multiple times.\n\n---\n\n## Web UI API\n\nThe built-in web server exposes a REST API:\n\n| Endpoint                        | Method | Description               |\n| ------------------------------- | ------ | ------------------------- |\n| `/api/memories`                 | GET    | List all memories         |\n| `/api/memories/search?q=...`    | GET    | Search memories           |\n| `/api/memories`                 | POST   | Add a new memory          |\n| `/api/memories/:id`             | DELETE | Delete a memory           |\n| `/api/conflicts`                | GET    | List unresolved conflicts |\n| `/api/conflicts/:id`            | POST   | Resolve a conflict        |\n| `/api/conflicts/stats`          | GET    | Conflict statistics       |\n| `/api/transcripts`              | GET    | List transcripts          |\n| `/api/transcripts/search?q=...` | GET    | Search transcripts        |\n\nAccess the UI at `http://localhost:4747`.\n\n---\n\n## Testing\n\n```bash\n# Run all tests\nbun test\n\n# Run specific feature tests\nbun test tests/memory-engine.test.ts\n\n# Type check\nbun run typecheck\n\n# Build\nbun run build\n```\n\n29 integration tests cover transcript storage, conflict resolution, hybrid search, diversity ranking, and STM/LTM decay.\n\n---\n\n## Development\n\n### Platform Requirements\n\n**Linux / macOS**: Native support. Requires [Bun](https://bun.sh/) runtime.\n\n**Windows**: Not natively supported. Bun does not currently run on Windows. Use [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) with a Linux distribution, then install Bun inside WSL.\n\n### Prerequisites\n\n- [Bun](https://bun.sh/) 1.x\n- TypeScript 5.7+\n\n### Build\n\n```bash\nbun run build\n```\n\nOutput goes to `dist/`. Web UI assets are copied to `dist/web/`.\n\n### Format\n\n```bash\nbun run format        # auto-fix\nbun run format:check  # verify\n```\n\n---\n\n## License\n\nMIT License - see [LICENSE](LICENSE)\n\n- **Repository**: [https://github.com/ZeR020/opencode-mem0](https://github.com/ZeR020/opencode-mem0)\n- **Issues**: [https://github.com/ZeR020/opencode-mem0/issues](https://github.com/ZeR020/opencode-mem0/issues)\n- **Original Project**: [https://github.com/tickernelz/opencode-mem](https://github.com/tickernelz/opencode-mem)\n\nInspired by [tickernelz/opencode-mem](https://github.com/tickernelz/opencode-mem) and [opencode-supermemory](https://github.com/supermemoryai/opencode-supermemory).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzer020%2Fopencode-mem0","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzer020%2Fopencode-mem0","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzer020%2Fopencode-mem0/lists"}