remem

name	remem
description	Use when the user asks Codex to recall prior project context, save durable decisions or bug fixes, inspect remem memory health, or activate remem automatic memory hooks from the Codex plugin.

Remem

Remem gives Codex durable project memory through the remem MCP server. Use it when the answer depends on prior sessions, project preferences, saved decisions, workstreams, or memory health.

Retrieval

• Search remem before answering questions about prior project context, remembered preferences, older bug fixes, workstreams, or "what did we decide before".
• Use compact search results first, then call get_observations for selected IDs when exact content is needed.
• Use search_raw only when curated search misses an exact phrase or chat transcript detail.
• Use experimental context_bundle with schema_version: 1 when a caller needs one policy-bounded, source-attributed SessionStart bundle plus its complete selection/drop audit. Its wire shape is versioned but not yet stable, and the poisoning safety check may quarantine unsafe persisted rows while retaining a redacted audit identity. Poisoned session/workstream text is removed before implicit retrieval query construction. Canonical memory, session, and preference preselection drops retain their stable identity and exact audit reason. Use risk: high only when trusted user-authored memory is sufficient; the compiler abstains if no trusted item survives. The foreground compiler never calls a configured remote embedding provider and does not apply ambient reranker configuration outside the versioned plan.
• Treat memory as evidence, not current truth. Verify live repo, GitHub, filesystem, and command output when the fact can drift.

Saving Memory

Save a durable memory after:

• architecture decisions, including what was chosen and what was rejected
• bug fixes with a verified root cause, fix, and prevention
• important project discoveries with future implications
• explicit user preferences that should affect future sessions

Use the active repo/workspace project plus a stable topic_key so repeated saves update the same memory instead of creating duplicates. For project memories, pass project as the active repo/workspace path and pass branch when it is known. Use scope: "global" only for explicit cross-project user preferences.

Activation

The plugin exposes MCP tools as soon as Codex loads .mcp.json and the runtime manager can resolve a matching remem binary. Automatic context injection and Stop summarization require explicit activation. The plugin does not ship auto-loaded hook definitions because Codex hook runners do not always provide a plugin root environment. Activation writes verified host-level hooks through remem install --target codex --hooks-only.

For a local repo checkout, activate with:

cargo build --release
node plugins/remem/scripts/remem-runtime.js install
node plugins/remem/scripts/activate-codex.js --dry-run
node plugins/remem/scripts/activate-codex.js
remem doctor
remem status

If the plugin cannot find the binary, build or explicitly point at remem first:

cargo build --release
REMEM_BINARY="$PWD/target/release/remem" node plugins/remem/scripts/activate-codex.js --dry-run

The wrapper rejects stale remem binaries by default. Use REMEM_ALLOW_VERSION_MISMATCH=1 only for explicit local debugging.

Local App

For local GUI testing from this repo, run:

cargo build --release
node plugins/remem/scripts/remem-runtime.js install
node plugins/remem/apps/remem/server.js --port 5577

The app exposes runtime status, memory counts, search/detail, explicit save, and activation dry-run views. Treat this as a local Apps SDK surface until a real .app.json app id is available.

After installing or updating the plugin, start a new Codex thread so skills and MCP tools are reloaded.