{"id":44399079,"url":"https://github.com/kunickiaj/codemem","last_synced_at":"2026-04-10T04:07:31.223Z","repository":{"id":336526147,"uuid":"1133829259","full_name":"kunickiaj/codemem","owner":"kunickiaj","description":"A lightweight persistent-memory companion for OpenCode","archived":false,"fork":false,"pushed_at":"2026-03-04T09:23:00.000Z","size":4343,"stargazers_count":7,"open_issues_count":7,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-04T13:51:23.515Z","etag":null,"topics":["ai","ai-agents","ai-memory","ai-memory-system","memory","opencode","opencode-plugin","p2p"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@kunickiaj/codemem","language":"Python","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/kunickiaj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"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-01-13T21:51:11.000Z","updated_at":"2026-03-04T07:43:43.000Z","dependencies_parsed_at":"2026-02-05T09:11:32.316Z","dependency_job_id":null,"html_url":"https://github.com/kunickiaj/codemem","commit_stats":null,"previous_names":["kunickiaj/opencode-mem","kunickiaj/codemem"],"tags_count":60,"template":false,"template_full_name":null,"purl":"pkg:github/kunickiaj/codemem","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kunickiaj%2Fcodemem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kunickiaj%2Fcodemem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kunickiaj%2Fcodemem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kunickiaj%2Fcodemem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kunickiaj","download_url":"https://codeload.github.com/kunickiaj/codemem/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kunickiaj%2Fcodemem/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30276609,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-08T20:45:49.896Z","status":"ssl_error","status_checked_at":"2026-03-08T20:45:49.525Z","response_time":56,"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":["ai","ai-agents","ai-memory","ai-memory-system","memory","opencode","opencode-plugin","p2p"],"created_at":"2026-02-12T05:52:32.261Z","updated_at":"2026-04-10T04:07:31.216Z","avatar_url":"https://github.com/kunickiaj.png","language":"Python","readme":"# codemem\n\n[![CI](https://github.com/kunickiaj/codemem/actions/workflows/ci.yml/badge.svg)](https://github.com/kunickiaj/codemem/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/kunickiaj/codemem/branch/main/graph/badge.svg)](https://codecov.io/gh/kunickiaj/codemem) [![Release](https://img.shields.io/github/v/release/kunickiaj/codemem)](https://github.com/kunickiaj/codemem/releases)\n\nPersistent memory for [OpenCode](https://opencode.ai) and [Claude Code](https://claude.ai/code). codemem captures what you work on across sessions, retrieves relevant context using hybrid search, and injects relevant context automatically in OpenCode.\n\n- **Local-first** — everything lives in SQLite on your machine\n- **Hybrid retrieval** — FTS5 BM25 lexical search + sqlite-vec semantic search, merged and re-ranked\n- **Automatic injection** — the OpenCode plugin injects context into every prompt, no manual steps\n- **Claude Code plugin support** — install from the codemem marketplace source\n- **Built-in viewer** — browse memories, sessions, and observer output in a local web UI\n- **Peer-to-peer sync** — replicate memories across machines without a central service\n\n| Light | Dark |\n|-------|------|\n| ![codemem viewer – light theme](docs/images/codemem-light.png) | ![codemem viewer – dark theme](docs/images/codemem-dark.png) |\n\n## Quick start\n\n**Prerequisites:** Node.js 24+ and npm (or pnpm)\n\n### OpenCode\n\n1. Install the OpenCode plugin and MCP config:\n\n```text\nnpx -y codemem setup --opencode-only\n```\n\n2. Restart OpenCode.\n\nThe OpenCode plugin manages backend execution automatically — no separate global install is required.\n\n3. Verify:\n\n```text\n# Works on fresh installs (no global codemem needed)\nnpx -y codemem stats\nnpx -y codemem db raw-events-status\n```\n\nThat's it. The plugin captures activity, builds memories, and injects context from here on.\n\nIf you want `codemem` available directly on your `PATH` for manual commands, install the CLI globally:\n\n```text\nnpm install -g codemem\n```\n\nOpenCode plugin and CLI are now split intentionally:\n\n- `@codemem/opencode-plugin` — OpenCode plugin package\n- `codemem` — CLI and MCP commands\n\n### Claude Code (marketplace install)\n\n1. Install codemem's Claude MCP config:\n\n```text\nnpx -y codemem setup --claude-only\n```\n\n2. In [Claude Code](https://claude.ai/code), add the codemem marketplace source and install the plugin:\n\n```text\n/plugin marketplace add kunickiaj/codemem\n/plugin install codemem\n```\n\nThe Claude plugin starts MCP with the TS CLI (`codemem mcp`).\n\nClaude hook ingestion is HTTP enqueue-first (`POST /api/claude-hooks`) and falls back to direct local DB enqueue via `codemem claude-hook-ingest` when the local server path is unavailable.\n\nClaude hook events share the same raw-event queue pipeline used by OpenCode. `UserPromptSubmit` runs\ncapture ingest in the background and injects memory context via Claude `additionalContext` using\nlocal pack generation by default, with optional HTTP `/api/pack` fallback.\n\n\u003e Migrating from `opencode-mem`? See [docs/rename-migration.md](docs/rename-migration.md).\n\n## How it works\n\nAdapters hook into runtime event systems (OpenCode plugin and Claude hooks). They capture tool calls and conversation messages, flush them through an observer pipeline that produces typed memories, and surface retrieval context for future prompts.\n\n```mermaid\nsequenceDiagram\nparticipant OC as OpenCode\nparticipant PL as codemem plugin\nparticipant ST as MemoryStore\nparticipant DB as SQLite\n\nOC-\u003e\u003ePL: tool.execute.after events\nOC-\u003e\u003ePL: experimental.chat.system.transform\nPL-\u003e\u003eST: build_memory_pack with shaped query\nST-\u003e\u003eDB: FTS5 BM25 lexical search\nST-\u003e\u003eDB: sqlite vec semantic search\nST-\u003e\u003eST: merge rerank and section assembly\nST--\u003e\u003ePL: pack text\nPL-\u003e\u003eOC: inject codemem context\n```\n\n**Retrieval** combines two strategies: keyword search via SQLite FTS5 with BM25 scoring and semantic similarity via sqlite-vec embeddings. In the pack-building path, results from both are merged, deduplicated, and re-ranked using recency and memory-kind boosts.\n\n**Injection** happens automatically. The plugin builds a query from the current session context (first prompt, latest prompt, project, recently modified files), calls `build_memory_pack`, and appends the result to the system prompt via `experimental.chat.system.transform`.\n\n**Memories** are typed — `bugfix`, `feature`, `refactor`, `change`, `discovery`, `decision`, `exploration` — with structured fields like `facts`, `concepts`, `files_read`, and `files_modified` that improve retrieval relevance. Low-signal events are filtered at multiple layers before persistence.\n\nFor architecture details, see [docs/architecture.md](docs/architecture.md).\n\n## CLI\n\n| Group | Command | Description |\n|-------|---------|-------------|\n| **Core** | `codemem stats` | Database statistics |\n| | `codemem recent` | Recent memories |\n| | `codemem search \u003cquery\u003e` | Search memories |\n| | `codemem pack \u003ccontext\u003e` | Build a context-aware memory pack |\n| | `codemem pack trace \u003ccontext\u003e` | Inspect retrieval and pack assembly for a manual query |\n| | `codemem embed` | Backfill semantic embeddings |\n| **Memory** | `codemem memory show \u003cid\u003e` | Print a memory item as JSON |\n| | `codemem memory forget \u003cid\u003e` | Deactivate a memory item |\n| | `codemem memory remember` | Manually add a memory |\n| | `codemem memory inject \u003ccontext\u003e` | Raw pack text for prompt injection |\n| | `codemem memory export \u003coutput\u003e` | Export memories by project |\n| | `codemem memory import \u003cfile\u003e` | Import memories (idempotent) |\n| **Viewer** | `codemem serve [start\\|stop\\|restart]` | Launch / manage the web viewer |\n| **Sync** | `codemem sync enable\\|disable` | Enable or disable peer-to-peer sync |\n| | `codemem sync status` | Device info and peer health |\n| | `codemem sync pair` | Generate or accept a pairing payload |\n| | `codemem sync once` | Run one immediate sync pass |\n| | `codemem sync doctor` | Diagnose sync configuration issues |\n| | `codemem sync bootstrap` | Bootstrap sync from a peer snapshot |\n| **Coordinator** | `codemem coordinator` | Self-hosted coordinator admin (groups, devices, invites) |\n| **Database** | `codemem db prune-memories` | Deactivate low-signal memories (`--dry-run` to preview) |\n| | `codemem db prune-observations` | Deactivate low-signal observations |\n| | `codemem db backfill-tags` | Populate missing `tags_text` values |\n| | `codemem db raw-events-status` | Show raw-event queue status |\n| **Config** | `codemem config` | View or update configuration |\n| | `codemem setup` | Interactive first-run setup |\n| **Plumbing** | `codemem mcp` | MCP stdio server |\n| | `codemem claude-hook-ingest` | Claude hook event ingestion (stdin) |\n\nRun `codemem --help` for the full list. Legacy top-level aliases (`export-memories`, `import-memories`, `show`, `forget`, `remember`) still work but are hidden from help.\n\n## MCP tools\n\nTo give the LLM direct access to memory tools (search, timeline, pack, remember, forget):\n\n```text\ncodemem setup --opencode-only\n```\n\nThis updates your OpenCode config to install the plugin and register the MCP server. Restart OpenCode to activate.\n\n## Configuration\n\nConfig resolution precedence for runtime commands is:\n\n1. explicit `CODEMEM_CONFIG`\n2. workspace-scoped config derived from `CODEMEM_RUNTIME_ROOT` or `CODEMEM_WORKSPACE_ID`\n3. legacy global config at `~/.config/codemem/config.json{c}`\n\nEnvironment variables still override file values once a config file has been selected.\n\nCommon overrides:\n\n| Variable | Purpose |\n|----------|---------|\n| `CODEMEM_DB` | SQLite database path |\n| `CODEMEM_INJECT_CONTEXT` | `0` to disable automatic context injection |\n| `CODEMEM_VIEWER_AUTO` | `0` to disable auto-starting the viewer |\n\nThe viewer includes a grouped Settings modal (`Connection`, `Processing`, `Device Sync`) with shell-agnostic labels and an advanced-controls toggle for technical fields.\n- Settings show effective values (configured or default) and only persist changed fields on save.\n- The viewer HTTP service is intended for localhost-only use. It does not currently provide a general-purpose auth/session layer for safe public exposure.\n\nObserver runtime/auth:\n\n- Runtime options: `api_http` and `claude_sidecar`.\n- `api_http` defaults to `gpt-5.1-codex-mini` (OpenAI path) unless you set `observer_model`.\n- Anthropic direct API calls accept Anthropic model IDs/aliases. codemem maps the common Claude shorthand `claude-4.5-haiku` to Anthropic's direct API alias `claude-haiku-4-5`; you can also set a pinned snapshot like `claude-haiku-4-5-20251001` explicitly.\n- `claude_sidecar` defaults to `claude-4.5-haiku`; if the selected `observer_model` is unsupported by Claude CLI, codemem retries once with Claude's CLI default model.\n- `claude_sidecar` command is configurable with `claude_command` (`CODEMEM_CLAUDE_COMMAND`) as a JSON argv array.\n  - Config file example: `\"claude_command\": [\"wrapper\", \"claude\", \"--\"]`\n  - Env var example: `CODEMEM_CLAUDE_COMMAND='[\"wrapper\",\"claude\",\"--\"]'`\n- Auth sources: `auto`, `env`, `file`, `command`, `none`.\n- `observer_auth_command` must be a JSON string array (argv), not a space-separated string.\n  - Config file example: `\"observer_auth_command\": [\"iap-auth\", \"--audience\", \"example\"]`\n  - Env var example: `CODEMEM_OBSERVER_AUTH_COMMAND='[\"iap-auth\",\"--audience\",\"example\"]'`\n- Header templates support `${auth.token}`, `${auth.type}`, and `${auth.source}` (for example `Authorization: Bearer ${auth.token}`).\n- Queue cadence is configurable with `raw_events_sweeper_interval_s` (seconds) in Settings/config.\n\n## Export and import\n\nShare project knowledge with teammates or back up memories across machines.\n\n```text\n# Export current project\ncodemem export-memories project.json\n\n# Import on another machine (idempotent, safe to re-run)\ncodemem import-memories project.json --remap-project ~/workspace/myproject\n```\n\nSee `codemem export-memories --help` and `codemem import-memories --help` for full options.\n\n## Peer-to-peer sync\n\nReplicate memories across devices without a central server.\n\n```text\ncodemem sync enable        # generate device keys\ncodemem sync pair          # generate pairing payload\ncodemem sync start         # start the viewer-backed sync runtime\ncodemem sync once          # run one immediate sync pass\n```\n\nThe viewer now includes actor management for mapping multiple peers to one logical person, plus owned-memory visibility controls so project-filtered memories share by default while `Only me` stays a per-memory local override.\n\nProject filters, peer-to-actor assignment, visibility controls, and config keys are documented in [docs/user-guide.md](docs/user-guide.md).\n\nFor cross-network setups where peer addresses change frequently or mDNS does not cross VPN/network boundaries, codemem also supports optional coordinator-backed discovery with a self-hosted coordinator. The preferred deployment path is the built-in `codemem coordinator` service; see [docs/coordinator-discovery.md](docs/coordinator-discovery.md).\n\n## Semantic recall\n\nEmbeddings are stored in sqlite-vec and written automatically when memories are created. Use `codemem embed` to backfill existing memories. If sqlite-vec cannot load, keyword search still works.\n\n## Alternative install methods\n\n\u003cdetails\u003e\n\u003csummary\u003eLocal development, npx, git install\u003c/summary\u003e\n\n### Local development\n\n```text\npnpm install\npnpm build\npnpm run codemem --help\n```\n\n### Via npx (no install)\n\n```text\nnpx -y codemem stats\n```\n\n### Plugin for development\n\nStart OpenCode inside the codemem repo directory — the plugin auto-loads from `.opencode/plugin/`.\n\n\u003c/details\u003e\n\n## Documentation\n\n- [Architecture](docs/architecture.md) — data flow, retrieval, observer pipeline, design tradeoffs\n- [Coordinator-backed discovery](docs/coordinator-discovery.md) — self-hosted cross-network peer discovery\n- [User guide](docs/user-guide.md) — viewer usage, sync setup, troubleshooting\n- [Plugin reference](docs/plugin-reference.md) — plugin behavior, env vars, stream reliability\n- [Migration guide](docs/rename-migration.md) — migrating from `opencode-mem`\n- [Contributing](CONTRIBUTING.md) — development setup, tests, linting, releases\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkunickiaj%2Fcodemem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkunickiaj%2Fcodemem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkunickiaj%2Fcodemem/lists"}