remem: Local-first memory for Claude Code and OpenAI Codex

> Stop re-explaining your project every new coding-agent session.

Language: English | 简体中文

`remem` automatically captures, distills, searches, and injects engineering

memory across Claude Code and OpenAI Codex CLI sessions. Decisions,

bug-fix rationale, project patterns, and preferences stay available through

hooks, MCP, CLI, and a localhost REST API.

*A new Claude Code session recalls the earlier root cause, commit, and open

TODO with memory citations and no re-explaining.*

What remem gives you

• Automatic session capture and background LLM distillation.
• Project-scoped recall across Claude Code and Codex using one local store.
• Searchable decisions, bug fixes, architecture notes, preferences, and raw

session evidence.

• Source attribution, staleness labels, suppression, review queues, and

injection audits.

• SQLite with SQLCipher encryption by default for fresh installs.
• MCP, CLI, and authenticated localhost REST access from one Rust runtime.

remem prioritizes memory quality. Automatic capture is the primary path;

manual `save_memory` calls supplement it when a decision needs to be recorded

immediately.

Install in five minutes

Homebrew

brew install majiayu000/tap/remem
"$(brew --prefix remem)/bin/remem" install --target codex

Use `--target claude` for Claude Code. `--target all` configures every known

host, including Cursor where its v1 renderer is supported.

Standalone installer

curl -fsSL https://raw.githubusercontent.com/majiayu000/remem/main/install.sh | env REMEM_NO_CONFIG=1 sh
~/.local/bin/remem install --target codex

npm or Cargo

npm install -g @remem-ai/remem
# or
cargo install remem-ai --bin remem

remem install --target codex

GitHub Releases: prebuilt binaries for macOS and Linux on x64/arm64, with

published checksums. Use one canonical `remem` executable on `PATH`;

`remem doctor` warns when hooks and terminals resolve different copies.

For channel-specific upgrades, platform boundaries, PATH drift, and manual

install notes, read the installation and upgrade guide.

The broader documentation guide links plugin and operational

material.

Verify the installation

Restart the selected coding agent, then run:

remem doctor
remem status
remem search "last decision"

A healthy Claude Code or Codex installation injects relevant project memory at

SessionStart and queues durable session distillation at Stop. `remem doctor`

checks the schema, encryption key, database, hooks, MCP registration, worker,

and common install-path drift.

Repository contributors can verify duplicate SessionStart suppression with the

isolated executable smoke fixture.

For a focused, read-only view of current-memory truth:

remem doctor truth --cwd .

Host support

Cursor's v1 installer registers MCP only. The verified `observe` and

`summarize` runtime commands exist, but `remem install --target cursor` does

not install automatic capture hooks or SessionStart injection.

The repository also includes a Codex plugin wrapper. See

plugins/remem/README.md for local plugin runtime and

explicit hook activation instructions.

Why use remem alongside built-in memory

Built-in `MEMORY.md`, `CLAUDE.md`, and agent instruction files are ideal for a

small set of stable facts that should always be visible. remem covers the

engineering history that is too large, dynamic, or evidence-heavy to maintain

by hand.

Use both. Keep concise rules in native files and let remem retain the long tail

of decisions, failures, evidence, and changing project state.

The broader ecosystem comparison lives in the dated

memory-tool survey.

How it works

Claude Code / Codex hooks
          |
          v
append-only captured_events ledger
          |
          v
coalesced background extraction and session rollup
          |
          v
governed candidates -> curated memories + workstreams + raw archive
          |
          v
FTS, entity, temporal, vector, graph, and optional local rerank retrieval
          |
          v
budgeted, source-attributed SessionStart context

Hooks return quickly after durable capture or queueing. Background workers

perform extraction, candidate governance, compression, retrieval enrichment,

and lifecycle cleanup. MCP, CLI, REST, and SessionStart share the same local

store and governance model, but apply surface-specific eligibility policies.

Explicit search is an inspection and recovery surface, so it may return

labeled `legacy_unverified` memories; default SessionStart and CurrentTruth

exclude those rows and record the reason.

Generated memory is treated as untrusted until it passes source-support,

secret, instruction-pattern, scope, and lifecycle checks. Unsafe content is

dropped or routed to review with a diagnosable reason.

For module ownership and current data flow, read

docs/ARCHITECTURE.md.

The experimental MCP `context_bundle` tool exposes the versioned, budgeted

compiler to explicit callers. The experimental `remem context-plan` command

prints a request-specific retrieval plan. These opt-in interfaces are tracked

by the Context Bundle and

retrieval-router contracts.

Everyday workflows

Recall and inspect

remem search "database encryption"
remem search "deployment decision" --branch main --explain
remem show 
remem why 
remem current

`remem search` keeps the terminal clean: per-query `[INFO] [search-perf]`

diagnostics are written to the log file, not stderr, in normal use. Set

`REMEM_DEBUG=1` to mirror them to stderr while debugging.

Agents can use MCP `search` for compact results, then `get_observations` for

selected details. Use raw recall only when curated memory misses exact

transcript evidence:

remem raw search "exact phrase" --since 2026-06-01 --json

List complete host-bound sessions before reading an exact transcript:

remem raw sessions --latest 20 --json
remem raw messages --host codex-cli --source-root local \
  --project "/path/to/project" --session-id SESSION_ID --json
remem ingest-sessions --root codex-cli:archive=/path/to/sessions --json

Copy `host`, `source_root`, `project`, and `session_id` unchanged from one

`raw sessions` summary into `raw messages`. Existing scripts must add the

required `--host` selector and replace `--root LABEL=PATH` with

`--root HOST:LABEL=PATH`; the same root format applies to `raw reconcile`.

The JSON envelope reports `excluded_legacy_rows` and

`excluded_legacy_sessions` when pre-identity transcript rows are retained in

the raw archive but cannot safely enter the host-bound session contract.

`HOST` is `claude-code` or `codex-cli`, and `LABEL` becomes the persisted

`source_root`. Cursor snapshot evidence requires a manually configured and

verified `remem summarize --host cursor` Stop integration; filesystem `--root`

ingestion and reconciliation reject `cursor` explicitly.

Review and govern

remem review list
remem review approve 
remem memory suppress memory: --reason "no longer relevant"
remem govern --action stale --dry-run --json

Mutating governance commands expose previews, explicit confirmations, or

review boundaries according to their risk. Run `remem --help` for

the current contract instead of relying on a copied command inventory.

Configure memory AI and retrieval

remem config show
remem model current
remem model use balanced --dry-run
remem embedding status
remem embedding download --model multilingual-e5-small
remem embedding backfill --limit 1000

`auto` embedding mode stays local unless a remem-specific API key is selected.

The verified local model is optional; the labeled feature-hash fallback remains

available. The second-stage local reranker is also optional and disabled until

configured.

Use the current configuration routes, the

local embedding contract, and

`remem config`, `remem embedding`, or `remem reranker` help for details.

Share or edit memory outside the database

remem sync-memory --cwd .
remem export --markdown --output ./remem-memory
remem export --pack .remem-pack

Markdown mirrors are human-editable. Project memory packs are deterministic,

git-committable exports with provenance-aware import and quarantine behavior.

See the memory usage guide and

project memory pack contract.

Evidence and benchmarks

The checked-in public suite separates memory-system capability evidence from

coding-agent outcome evidence. Verify it locally with:

cargo run -- bench verify --root eval/public --json-out /tmp/remem-bench-verify.json

Verification resolves `claims/registry.json` beside the parent of `--root`, so

an external bundle keeps `public/` and `claims/` as siblings and is independent

of the caller's working directory.

Public adversarial SQLite snapshots are capped at 64 MiB and must be canonical

`VACUUM` images; verifier-consumed artifact targets must also resolve inside the

declared public root.

The current public report does not support public benchmark claims and is

deliberately labeled

`directional_only_no_public_claim`. The historical isolated coding baseline is

useful engineering evidence, but its preloaded-memory condition is not

comparable with the current SessionStart retrieval path.

Reproduction commands, artifact schemas, claim boundaries, and current gates

live in:

• eval/README.md
• eval/public/README.md
• eval/coding-bench/README.md

README claims intentionally exclude unsealed local metrics that have no

checked-in report.

Security and privacy

• Fresh installs create a SQLCipher-encrypted database and private key file.
• The data directory and key use restrictive per-user permissions.
• The REST API binds to `127.0.0.1` and requires a bearer token.
• Hook-captured event previews are redacted before durable storage.
• Memory candidates and injected content pass secret and poisoning defenses.
• `remem doctor` reports encryption, plaintext residue, schema, and audit

failures without printing memory payloads.

Read SECURITY.md for reporting and security policy. Operational

contracts for SQLite tuning and

memory-poisoning defense are

kept outside the landing page.

REST API

remem api --port 5567
TOKEN=$(cat ~/.remem/.api-token)
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:5567/api/v1/health
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:5567/api/v1/capabilities

Clients should feature-detect through `/api/v1/capabilities`. The current

endpoint and compatibility contract is maintained in

docs/specs/SPEC-web-api.md.

Documentation

Use docs/README.md as the jump page for installation,

configuration, memory lifecycle, retrieval, governance, API, plugin,

operations, architecture, and benchmark material.

The most common destinations are:

• Architecture and data flow
• Memory usage guide
• Memory lifecycle
• Codex plugin
• REST API contract
• Current spec index
• Changelog
• Contributing

Uninstall

Preview and remove host hooks and MCP registration without deleting memory:

remem uninstall --dry-run
remem uninstall

The encrypted database remains in the configured `REMEM_DATA_DIR`. Back it up

before manually deleting that directory if data removal is intended. Ordinary

file deletion removes remem's local data but does not guarantee secure erasure

from filesystem snapshots, backups, or the underlying storage media.

License

MIT