{
  "markdown": "# remem: Local-first memory for Claude Code and OpenAI Codex\n\n[![MCP Toplist](https://mcptoplist.com/badge/io.github.majiayu000%2Fremem.svg)](https://mcptoplist.com/server/io.github.majiayu000%2Fremem)\n\n> Stop re-explaining your project every new coding-agent session.\n\nLanguage: **English** | [简体中文](README.zh-CN.md)\n\n`remem` automatically captures, distills, searches, and injects engineering\nmemory across Claude Code and OpenAI Codex CLI sessions. Decisions,\nbug-fix rationale, project patterns, and preferences stay available through\nhooks, MCP, CLI, and a localhost REST API.\n\n[![CI](https://github.com/majiayu000/remem/actions/workflows/ci.yml/badge.svg)](https://github.com/majiayu000/remem/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/majiayu000/remem?sort=semver)](https://github.com/majiayu000/remem/releases/latest)\n[![crates.io](https://img.shields.io/crates/v/remem-ai)](https://crates.io/crates/remem-ai)\n[![npm](https://img.shields.io/npm/v/%40remem-ai%2Fremem)](https://www.npmjs.com/package/@remem-ai/remem)\n[![License MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n![Remem recall demo showing a new session picking up an earlier bug fix](assets/remem-recall-demo.gif)\n\n*A new Claude Code session recalls the earlier root cause, commit, and open\nTODO with memory citations and no re-explaining.*\n\n## What remem gives you\n\n- Automatic session capture and background LLM distillation.\n- Project-scoped recall across Claude Code and Codex using one local store.\n- Searchable decisions, bug fixes, architecture notes, preferences, and raw\n  session evidence.\n- Source attribution, staleness labels, suppression, review queues, and\n  injection audits.\n- SQLite with SQLCipher encryption by default for fresh installs.\n- MCP, CLI, and authenticated localhost REST access from one Rust runtime.\n\nremem prioritizes memory quality. Automatic capture is the primary path;\nmanual `save_memory` calls supplement it when a decision needs to be recorded\nimmediately.\n\n## Install in five minutes\n\n### Homebrew\n\n```bash\nbrew install majiayu000/tap/remem\n\"$(brew --prefix remem)/bin/remem\" install --target codex\n```\n\nUse `--target claude` for Claude Code. `--target all` configures every known\nhost, including Cursor where its v1 renderer is supported.\n\n### Standalone installer\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/majiayu000/remem/main/install.sh | env REMEM_NO_CONFIG=1 sh\n~/.local/bin/remem install --target codex\n```\n\n### npm or Cargo\n\n```bash\nnpm install -g @remem-ai/remem\n# or\ncargo install remem-ai --bin remem\n\nremem install --target codex\n```\n\nGitHub Releases: prebuilt binaries for macOS and Linux on x64/arm64, with\npublished checksums. Use one canonical `remem` executable on `PATH`;\n`remem doctor` warns when hooks and terminals resolve different copies.\n\nFor channel-specific upgrades, platform boundaries, PATH drift, and manual\ninstall notes, read the [installation and upgrade guide](docs/installation.md).\nThe broader [documentation guide](docs/README.md) links plugin and operational\nmaterial.\n\n## Verify the installation\n\nRestart the selected coding agent, then run:\n\n```bash\nremem doctor\nremem status\nremem search \"last decision\"\n```\n\nA healthy Claude Code or Codex installation injects relevant project memory at\nSessionStart and queues durable session distillation at Stop. Codex also uses\n`UserPromptSubmit` to capture each prompt and surface compact optional memory\ncandidates. `remem doctor` checks the schema, encryption key, database, hooks,\nMCP registration, worker, and common install-path drift.\n\nRepository contributors can verify duplicate SessionStart suppression with the\n[isolated executable smoke fixture](scripts/ci/smoke_sessionstart_context_gate.sh).\n\nFor a focused, read-only view of current-memory truth:\n\n```bash\nremem doctor truth --cwd .\n```\n\n## Host support\n\n| Capability | Claude Code | Codex CLI | Cursor v1 |\n|---|---|---|---|\n| MCP memory tools | Yes | Yes | Yes on macOS/Linux |\n| SessionStart injection | Yes | Yes | Not supported |\n| Automatic session memory | Yes | Yes, Stop-based and low-noise | Not enabled by the v1 installer |\n| Tool-event capture | Installed hooks | No high-frequency Bash hook by default | Runtime command exists; no installed hook |\n| Compiled command-rule enforcement | Optional warn/block on Bash | Not supported | Not supported |\n| Windows | Supported | Supported | Not supported |\n\nCursor's v1 installer registers MCP only. The verified `observe` and\n`summarize` runtime commands exist, but `remem install --target cursor` does\nnot install automatic capture hooks or SessionStart injection.\n\nThe repository also includes a Codex plugin wrapper. See\n[plugins/remem/README.md](plugins/remem/README.md) for local plugin runtime and\nexplicit hook activation instructions.\n\n## Why use remem alongside built-in memory\n\nBuilt-in `MEMORY.md`, `CLAUDE.md`, and agent instruction files are ideal for a\nsmall set of stable facts that should always be visible. remem covers the\nengineering history that is too large, dynamic, or evidence-heavy to maintain\nby hand.\n\n| Need | Built-in files | remem |\n|---|---|---|\n| Stable project rules | Excellent | Supported |\n| Automatic session capture | Manual upkeep | Hook-driven |\n| Search older rationale | Limited by loaded text | Curated and raw search |\n| Branch, time, and staleness handling | Manual | Built in |\n| Provenance and injection audit | Git history | Database-backed audit |\n| Review, suppression, and lifecycle governance | Manual edits | First-class commands |\n\nUse both. Keep concise rules in native files and let remem retain the long tail\nof decisions, failures, evidence, and changing project state.\n\nThe broader ecosystem comparison lives in the dated\n[memory-tool survey](docs/research/claude-memory-mcp-ecosystem-2026-03.md).\n\n## How it works\n\n```text\nClaude Code / Codex hooks\n          |\n          v\nappend-only captured_events ledger\n          |\n          v\ncoalesced background extraction and session rollup\n          |\n          v\ngoverned candidates -> curated memories + workstreams + raw archive\n          |\n          v\nFTS, entity, temporal, vector, graph, and optional local rerank retrieval\n          |\n          v\nbudgeted, source-attributed SessionStart context\n```\n\nHooks return quickly after durable capture or queueing. Background workers\nperform extraction, candidate governance, compression, retrieval enrichment,\nand lifecycle cleanup. MCP, CLI, REST, and SessionStart share the same local\nstore and governance model, but apply surface-specific eligibility policies.\nExplicit search is an inspection and recovery surface, so it may return\nlabeled `legacy_unverified` memories; default SessionStart and CurrentTruth\nexclude those rows and record the reason.\n\nGenerated memory is treated as untrusted until it passes source-support,\nsecret, instruction-pattern, scope, and lifecycle checks. Unsafe content is\ndropped or routed to review with a diagnosable reason.\n\nFor module ownership and current data flow, read\n[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).\n\nThe experimental MCP `context_bundle` tool exposes the versioned, budgeted\ncompiler to explicit callers. The experimental `remem context-plan` command\nprints a request-specific retrieval plan. These opt-in interfaces are tracked\nby the [Context Bundle](docs/specs/GH932/PRODUCT.md) and\n[retrieval-router](docs/specs/GH934/PRODUCT.md) contracts.\n\nThe default Codex integration stays low-noise: `SessionStart` provides stable\ncontext, `UserPromptSubmit` provides a compact candidate index, and `Stop`\nqueues background summarization. Prompt candidates contain IDs, titles,\nstate, retrieval reason, estimated read cost, and a detail lookup hint, but no\nmemory bodies. They are optional leads that Codex may ignore, open, or search\nbeyond. The first prompt may also receive up to two continuity anchors so a\nprompt such as `continue` does not depend on lexical overlap. Existing hybrid\nRRF ranks memory candidates; no final confidence threshold decides relevance\nfor the model.\n\n## Everyday workflows\n\n### Recall and inspect\n\n```bash\nremem search \"database encryption\"\nremem search \"deployment decision\" --branch main --explain\nremem show <memory-id>\nremem why <memory-id>\nremem current <state-key>\n```\n\n`remem search` keeps the terminal clean: per-query `[INFO] [search-perf]`\ndiagnostics are written to the log file, not stderr, in normal use. Set\n`REMEM_DEBUG=1` to mirror them to stderr while debugging.\n\nAgents can use MCP `search` for compact results, then `get_observations` for\nselected details. Use raw recall only when curated memory misses exact\ntranscript evidence:\n\n```bash\nremem raw search \"exact phrase\" --since 2026-06-01 --json\n```\n\nList complete host-bound sessions before reading an exact transcript:\n\n```bash\nremem raw sessions --latest 20 --json\nremem raw messages --host codex-cli --source-root local \\\n  --project \"/path/to/project\" --session-id SESSION_ID --json\nremem ingest-sessions --root codex-cli:archive=/path/to/sessions --json\n```\n\nCopy `host`, `source_root`, `project`, and `session_id` unchanged from one\n`raw sessions` summary into `raw messages`. Existing scripts must add the\nrequired `--host` selector and replace `--root LABEL=PATH` with\n`--root HOST:LABEL=PATH`; the same root format applies to `raw reconcile`.\nThe JSON envelope reports `excluded_legacy_rows`, `excluded_legacy_sessions`,\nand `excluded_legacy_identities` when some archive rows cannot enter the\nhost-bound session contract. Listing still returns healthy sessions;\n`--latest N` fills that bound from healthy sessions only and does not let\nunresolved rows occupy those slots. Use the skipped identities (`source_root`,\n`project`, `session_id`, and `host` when known) to inspect or repair those\nrows. Exact `raw messages` for a skipped selector stays fail-closed. Do not\nre-ingest a skipped row unless ingest can actually claim it — many legacy\nrows have no trusted host provenance.\n`HOST` is `claude-code` or `codex-cli`, and `LABEL` becomes the persisted\n`source_root`. Cursor snapshot evidence requires a manually configured and\nverified `remem summarize --host cursor` Stop integration; filesystem `--root`\ningestion and reconciliation reject `cursor` explicitly.\n\n### Review and govern\n\n```bash\nremem review list\nremem review approve <candidate-id>\nremem memory suppress memory:<id> --reason \"no longer relevant\"\nremem govern --action stale --dry-run --json <id>\n```\n\nMutating governance commands expose previews, explicit confirmations, or\nreview boundaries according to their risk. Run `remem <command> --help` for\nthe current contract instead of relying on a copied command inventory.\n\nMCP tools share that store with stricter wire contracts. The canonical MCP\ncontract is [GH981](docs/specs/GH981/PRODUCT.md), including the #1061\nmutation and scope boundary:\n\n- `save_memory`: pass `host` when the calling host is known. An omitted host is\n  recorded as `unknown`, never inferred as `codex-cli`.\n- `govern_memory`: dry-run first to preview IDs and current versions from that\n  governance transaction. Non-dry-run mutations require `expected_versions`\n  for every ID, `confirm_destructive=true`, and an explicit reason.\n- `recall_user_context`: supply `project` or `cwd`. The server does not infer\n  this scope from its own process working directory.\n\n### Configure memory AI and retrieval\n\n```bash\nremem config show\nremem model current\nremem model use balanced --dry-run\nremem embedding status\nremem embedding download --model multilingual-e5-small\nremem embedding backfill --limit 1000\n```\n\n`auto` embedding mode stays local unless a remem-specific API key is selected.\nThe verified local model is optional; the labeled feature-hash fallback remains\navailable. The second-stage local reranker is also optional and disabled until\nconfigured.\n\nUse the [current configuration routes](docs/README.md#configuration), the\n[local embedding contract](docs/specs/local-semantic-embedding/PRODUCT.md), and\n`remem config`, `remem embedding`, or `remem reranker` help for details.\n\n### Share or edit memory outside the database\n\n<!-- remem-doc-contract:current-project-export:start -->\n```bash\nremem sync-memory --cwd .\nremem export --markdown --output ./remem-memory\nremem export --pack .remem-pack\n```\n<!-- remem-doc-contract:current-project-export:end -->\n\nMarkdown mirrors are human-editable. Project memory packs are deterministic,\ngit-committable exports with provenance-aware import and quarantine behavior.\nSee the [memory usage guide](docs/memory-usage-guide.md) and\n[project memory pack contract](docs/specs/project-memory-pack/PRODUCT.md).\n\n## Evidence and benchmarks\n\nThe checked-in public suite separates memory-system capability evidence from\ncoding-agent outcome evidence. Verify it locally with:\n\n```bash\ncargo run -- bench verify --root eval/public --json-out /tmp/remem-bench-verify.json\n```\n\nVerification resolves `claims/registry.json` beside the parent of `--root`, so\nan external bundle keeps `public/` and `claims/` as siblings and is independent\nof the caller's working directory.\n\nPublic adversarial SQLite snapshots are capped at 64 MiB and must be canonical\n`VACUUM` images; verifier-consumed artifact targets must also resolve inside the\ndeclared public root.\n\nThe current public report does not support public benchmark claims and is\ndeliberately labeled\n`directional_only_no_public_claim`. The historical isolated coding baseline is\nuseful engineering evidence, but its preloaded-memory condition is not\ncomparable with the current SessionStart retrieval path.\n\nReproduction commands, artifact schemas, claim boundaries, and current gates\nlive in:\n\n- [eval/README.md](eval/README.md)\n- [eval/public/README.md](eval/public/README.md)\n- [eval/coding-bench/README.md](eval/coding-bench/README.md)\n\nREADME claims intentionally exclude unsealed local metrics that have no\nchecked-in report.\n\n## Security and privacy\n\n- Fresh installs create a SQLCipher-encrypted database and private key file.\n- The data directory and key use restrictive per-user permissions.\n- The REST API binds to `127.0.0.1` and requires a bearer token.\n- Hook-captured event previews are redacted before durable storage.\n- Memory candidates and injected content pass secret and poisoning defenses.\n- `remem doctor` reports encryption, plaintext residue, schema, and audit\n  failures without printing memory payloads.\n\nRead [SECURITY.md](SECURITY.md) for reporting and security policy. Operational\ncontracts for [SQLite tuning](docs/specs/GH949/PRODUCT.md) and\n[memory-poisoning defense](docs/specs/memory-poisoning-defense/PRODUCT.md) are\nkept outside the landing page.\n\n## REST API\n\n```bash\nremem api --port 5567\nTOKEN=$(cat ~/.remem/.api-token)\ncurl -H \"Authorization: Bearer $TOKEN\" http://127.0.0.1:5567/api/v1/health\ncurl -H \"Authorization: Bearer $TOKEN\" http://127.0.0.1:5567/api/v1/capabilities\n```\n\nClients should feature-detect through `/api/v1/capabilities`. The current\nendpoint and compatibility contract is maintained in\n[docs/specs/SPEC-web-api.md](docs/specs/SPEC-web-api.md).\n\n## Documentation\n\nUse [docs/README.md](docs/README.md) as the jump page for installation,\nconfiguration, memory lifecycle, retrieval, governance, API, plugin,\noperations, architecture, and benchmark material.\n\nThe most common destinations are:\n\n- [Architecture and data flow](docs/ARCHITECTURE.md)\n- [Memory usage guide](docs/memory-usage-guide.md)\n- [Memory lifecycle](docs/memory-lifecycle.md)\n- [Codex plugin](plugins/remem/README.md)\n- [REST API contract](docs/specs/SPEC-web-api.md)\n- [Current spec index](docs/specs/README.md)\n- [Changelog](CHANGELOG.md)\n- [Contributing](CONTRIBUTING.md)\n\n## Uninstall\n\nPreview and remove host hooks and MCP registration without deleting memory:\n\n```bash\nremem uninstall --dry-run\nremem uninstall\n```\n\nThe encrypted database remains in the configured `REMEM_DATA_DIR`. Back it up\nbefore manually deleting that directory if data removal is intended. Ordinary\nfile deletion removes remem's local data but does not guarantee secure erasure\nfrom filesystem snapshots, backups, or the underlying storage media.\n\n## License\n\nMIT\n",
  "bytes": 16145,
  "sha": "cffc7f7bba153452bc5551d895232fa37dc1f82b62b64b6c9b99dd12570b3e3e",
  "repo_slug": "majiayu000/remem",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_majiayu000_remem_6d8697c3/readme"
}