remem
remem is a local-first memory MCP server for coding agents that captures, searches, governs, and injects project/session memory.
List and update workstreams with status, progress, blockers, and next actions.
Resolve stable current-state keys with history, facts, conflicts, and why-linked memories.
Search curated memories and raw archived conversations with filters, pagination, explain, multi-hop, and task-aware retrieval plans.
Save or upsert memories with topic keys, types, scope, branch, files, timestamps, and optional local markdown backups.
Retrieve observation or session-summary details and build chronological timelines or project timeline reports.
Compile experimental budgeted context bundles and recall task-aware user context with source attribution and drop audits.
Govern memories through auditable delete, reject, stale, or acknowledge-pattern actions with dry runs and version checks.
List raw sessions, search raw archive turns, and look up commits or commits linked to a session.
Provides persistent memory for OpenAI Codex and Codex CLI sessions, enabling memory of project decisions and patterns across sessions.
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.
DeepSeek Harness
The optional DSH adapter injects project context
and captures live prompts, assistant text, and tools using the existing CLI.
It targets published DSH 0.2.0-rc.2; the npm adapter is not yet published.
Build the DSH-enabled remem 0.7.0 source before installing the adapter.
Assistant-only claims remain available for review and cannot auto-promote without
independent supporting evidence. Snapshot updates and removals respect the published
DSH session invariant; remem preparation failures retain uncommitted prompts for an
explicit retry, while cancellation leaves durable capture available to flush.
Recovery across unload lasts until the in-flight remem callback exits; while
loaded, agent/error also recovers later preparation failures. Host prepareCall
runs after agent/request returns: after unload, failure can lose claimed input,
while success still commits once without remem capture. Reload does not recover
lost input or import events committed while unloaded. Oversized prompts, assistant
messages, turn summaries and tool observations retain bounded evidence with explicit
omissions before core redaction. Arbitrary DSH tool names retain their provenance
but are external evidence; their names alone never authorize automatic promotion.
Related MCP server: Longhand
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; the key file lives next to the database (see Security and privacy).
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 codexUse --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 codexnpm or Cargo
npm install -g @remem-ai/remem
# or
cargo install remem-ai --bin remem
remem install --target codexCodex installation, detection, doctor, uninstall, transcript scanning and
default native-memory import all honor CODEX_HOME; the default is
~/.codex. Set it to an absolute directory before running these commands
to select another Codex profile. Empty or relative overrides fail visibly
before installation writes. Unrelated profile files stay untouched.
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. Codex also uses
UserPromptSubmit to capture each prompt and surface compact optional memory
candidates. remem doctor checks the schema, encryption key, database, hooks,
MCP registration, worker, and common install-path drift.
Its diagnostics do not create the data directory or write or rotate log files;
findings and stderr warnings remain visible, and existing log health is inspected.
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 .Why wasn't something remembered?
Use one read-only report to follow capture, extraction, review, current validity, and the latest recorded context run:
remem doctor memory "original phrase" --cwd .
remem doctor memory --host codex-cli --source-root local \
--project PROJECT_KEY --session-id SESSION_ID --jsonCopy the exact selector from remem raw sessions --json. Use
--injection-run-id RUN_ID to inspect a specific destination context emission.
The source session and destination context run are distinct. Each evidence
source is bounded at 20 rows; omitted evidence is marked. Terminal output shows
retained source/status counts and three samples per source; --json includes
all retained evidence. A missing match or
per-item audit is unknown, not proof that capture failed or a guessed drop
reason. Query discovery combines raw search with literal stored-text matches;
try an original phrase or the exact session when a paraphrase finds no evidence.
See the diagnosis contract.
Remem helps an Agent continue work; Refine helps people inspect and reuse knowledge; agent-sessions parses native source formats. Refine consumes Remem's existing session references, content fingerprints and commit/session links instead of collecting another transcript copy.
Host support
Capability | Claude Code | Codex CLI | Cursor v1 |
MCP memory tools | Yes | Yes | Yes on macOS/Linux |
SessionStart injection | Yes | Yes | Not supported |
Automatic session memory | Yes | Yes, Stop-based and low-noise | Not enabled by the v1 installer |
Tool-event capture | Installed hooks | No high-frequency Bash hook by default | Runtime command exists; no installed hook |
Compiled command-rule enforcement | Optional warn/block on Bash | Not supported | Not supported |
Windows | Supported | Supported | Not supported |
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.
Need | Built-in files | remem |
Stable project rules | Excellent | Supported |
Evolving context | Handwritten instructions; Claude Code auto memory also writes notes | Hook-driven session capture and background distillation |
Search older rationale | Limited by loaded text | Curated and raw search |
Branch, time, and staleness handling | Manual | Built in |
Provenance and injection audit | Git history | Database-backed audit |
Review, suppression, and lifecycle governance | Manual edits | First-class commands |
Claude Code auto memory already saves notes automatically. The distinction is the memory surface and its evidence, retrieval, and lifecycle controls, rather than automatic persistence alone.
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 contextHooks 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.
Malformed generated extraction responses retry with the existing bounded backoff while keeping the same source evidence. Invalid stored evidence still requires repair; exhausted model attempts preserve raw capture and replay ranges for inspection instead of accepting incomplete output.
Observation extraction and session rollup split large backlogs into bounded event chunks. Each model call budgets system instructions, prompt formatting, and evidence together; completion advances only through the processed chunk. Raw evidence remains available when per-event prompt content is clipped. Exact recovery retains the original range and resumes verified successful chunks under the explicitly selected profile and one overall timeout. Already-existing linked successors resume from their own original bounds and checkpoints; a completed primary task does not hide a failed successor. Archived exact recovery claims the existing family atomically, suppresses new follow-up work, and archives unfinished members again if the attempt fails.
Workers persist fair queue and stage/project claim order, so continuing capture in a busy project leaves room for downstream extraction and durable jobs across once-worker restarts. The existing once-worker admission budget still applies.
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. Complete, user-supported security prohibitions, research activities and explicitly analytical quotations can enter human review in English or Chinese; they never auto-promote. Secret values, harmful instructions and unsupported external text remain excluded.
Automatically promoted summary decisions and discoveries can enter current context at their original summary confidence when captured local evidence, the current summary gate, and the exact activation receipt still validate. External content and missing or changed proof remain review-gated or excluded. New trusted evidence can reconsider identical content that is still pending review: remem preserves the original snapshot and links it to a fresh candidate. Repeated evidence, human review decisions, quarantine, and suppression are preserved. Expired operational state needs fresh evidence before renewal.
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.
The default Codex integration stays low-noise: SessionStart provides stable
context, UserPromptSubmit provides a compact candidate index, and Stop
queues background summarization. Prompt candidates contain IDs, titles,
state, retrieval reason, estimated read cost, and a detail lookup hint, but no
memory bodies. They are optional leads that Codex may ignore, open, or search
beyond. The first prompt may also receive up to two continuity anchors so a
prompt such as continue does not depend on lexical overlap. Existing hybrid
RRF ranks memory candidates; no final confidence threshold decides relevance
for the model. Automatic extraction asks for short, specific candidate titles
without a redundant project-name prefix; existing stored titles remain intact.
For your own Codex sidebar, an optional rename convention is
MMDD|TYPE|Topic, such as 0903|FIX|FTS5 tokenizer mismatch. If you use a
separate host-supported rename workflow, preview its proposed names before
applying a batch. This is host-sidebar organization only: Remem does not rename
host conversations or import those names as intent overrides. Remem's structured
session/workstream fields remain authoritative, and a host title does not change
memory types or workstream identity. See the
session intent contract and
implementation epic #1065.
Session/workstream label corrections use authenticated
POST /api/v1/session-intent/preview, then explicit confirmation through
POST /api/v1/session-intent/apply. Keep each sensitive option or Bearer
prefix and its value on the same logical line in the proposed topic and reason.
For example, curl --oauth2-bearer\nexample-value is rejected with HTTP 400
session_intent_cross_line_sensitive_argument; put the option and value on one
line before retrying. Rejection creates no preview token or audit entry and
changes no labels. Same-line sensitive values are redacted before preview.
Everyday workflows
Recall and inspect
remem search "database encryption"
remem search "deployment decision" --branch main --explain
remem show <memory-id>
remem why <memory-id>
remem current <state-key>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.
Project aliases for Git worktrees
When a worktree has its own project key, preview an alias to the main checkout, then apply it after checking the paths and Git proof:
remem project alias add /path/to/worktree --canonical /path/to/main \
--actor you --reason "same project"
remem project alias add /path/to/worktree --canonical /path/to/main \
--actor you --reason "same project" --apply
remem project alias list
remem search "decision" --project /path/to/main
remem project alias revoke /path/to/worktree \
--actor you --reason "worktree retired" --applyThe main checkout must already have a project row from normal remem capture.
The alias keeps historical rows at their recorded paths while CLI and MCP
project searches include the worktree's memories. add and revoke preview
without database writes unless --apply is present. Revocation removes the
worktree from the main project's search scope; list reports active aliases
with the actor and reason from their latest activation.
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 --jsonList 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 --jsonDefault transcript scans use $CLAUDE_CONFIG_DIR/projects and
$CODEX_HOME/sessions, falling back to ~/.claude and ~/.codex.
An explicitly empty override is an error. Explicit override directories must exist
and be readable; only absent inferred defaults are skipped. Explicit --root directories remain
supported; descendant subagents directories are excluded from batch scans.
Codex session modes use native source evidence: IDE is interactive, explicit
exec is unattended even with a Desktop originator, and subagent evidence
takes precedence. These are source labels, not proof of who initiated a run.
Existing saved modes upgrade once after checking the original classification
evidence; genuine provenance conflicts still fail the batch. This adds schema
v093: retain a database backup before upgrading; older binaries cannot open
the upgraded schema. Raw message identities and cursors are preserved.
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, excluded_legacy_sessions,
and excluded_legacy_identities when some archive rows cannot enter the
host-bound session contract. Each listed session also carries additive nullable
mmdd, session_intent, session_topic, display_label, and
session_intent_source fields. mmdd is derived from the session created epoch
in the machine's local timezone; set session_labels.timezone in
config.toml or REMEM_SESSION_LABEL_TIMEZONE to UTC or a fixed offset such
as +08:00 to pin it. The zone is read once per process, and mmdd is computed
at read time, so stored rows are never rewritten. The full {MMDD}|{INTENT}|{topic} label is present only when
both intent and topic are known. Stop summaries may fill those fields with
source summary; unknown, empty, too-long, or redacted values abstain instead
of blocking the rest of the summary. Automatic Stop rollups preserve manual
label overrides, including explicit clears, across later turns. Listing still returns healthy sessions;
--latest N fills that bound from healthy sessions only and does not let
unresolved rows occupy those slots. Use the skipped identities (source_root,
project, session_id, and host when known) to inspect or repair those
rows. Exact raw messages for a skipped selector stays fail-closed. Do not
re-ingest a skipped row unless ingest can actually claim it — many legacy
rows have no trusted host provenance.
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 <candidate-id>
remem memory suppress memory:<id> --reason "no longer relevant"
remem govern --action stale --dry-run --json <id>Mutating governance commands expose previews, explicit confirmations, or
review boundaries according to their risk. Run remem <command> --help for
the current contract instead of relying on a copied command inventory.
MCP tools share that store with stricter wire contracts. The canonical MCP contract is GH981, including the #1061 mutation and scope boundary:
save_memory: passhostwhen the calling host is known. An omitted host is recorded asunknown, never inferred ascodex-cli.govern_memory: dry-run first to preview IDs and current versions from that governance transaction. Non-dry-run mutations requireexpected_versionsfor every ID,confirm_destructive=true, and an explicit reason.recall_user_context: supplyprojectorcwd. The server does not infer this scope from its own process working directory.
The local Remem app shows session/workstream labels or explicit abstention. Sessions can be filtered by intent and created date in the browser's local timezone. Operators can correct labels in batches with a Before/After preview, explicit confirmation, and an audit; workstream identity and host conversation titles stay stable.
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 1000auto 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.
Vector indexes keep each model and artifact revision in its own vector space. Project, branch, type, and lifecycle filters apply before nearest-neighbor selection. Automatic context uses the same vector executor as search, so old memories remain eligible by similarity as a project grows. While a derived index is rebuilding, an exact local scan preserves recall; large stores may take longer until that profile's index is ready.
Use the current configuration routes, the
local embedding contract, and
remem config, remem embedding, or remem reranker help for details.
remem usage reports every dispatched memory-AI attempt, including failures.
Observed zero, partial, missing, invalid, and text-estimated token counts remain
distinct. Reported USD is the known priced portion; coverage counts show when
unknown rates or missing counter details make it incomplete. Failed attempts
without provider counters do not receive guessed token estimates. Historical
usage remains labeled as unverified rather than being silently reclassified.
Share or edit memory outside the database
remem sync-memory --cwd .
remem export --markdown --output ./remem-memory
remem export --pack .remem-packMarkdown 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.jsonVerification 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:
README claims intentionally exclude unsealed local metrics that have no checked-in report.
Security and privacy
Fresh installs create a SQLCipher-encrypted database (
remem.db) and a random key file (.key) in the same data directory (~/.rememorREMEM_DATA_DIR). Encryption at rest protects a copy of the database file on its own. It does not protect against anyone who can read the whole data directory or act as your user account, because the key is stored beside the database.REMEM_CIPHER_KEYcan supply the key at runtime, butremem installstill expects the persisted.keyfile.On Unix, the data directory is set to
0700and the key file is created0600; other platforms rely on the default permissions of the user profile.The REST API binds to
127.0.0.1and requires a bearer token.Hook-captured event previews are redacted before durable storage.
MCP and CLI workstream listings project redacted text: credential-like assignments, short inline secrets, and sensitive command options are replaced with
[REDACTED]in returned fields (and CLI--jsonenvelopeproject), while ordinary filesystem project paths stay readable. Stored workstream rows keep their canonical values for matching and scope checks, so queried output can differ from the database when secrets were present.Memory candidates and injected content pass secret and poisoning defenses.
remem doctorreports 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/capabilitiesClients 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:
Uninstall
Preview and remove host hooks and MCP registration without deleting memory:
remem uninstall --dry-run
remem uninstallThe 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
Available Tools
15 toolscommits_for_sessionList Session CommitsADestructive
List git commits linked to a content session ID or remem memory session ID. Its poisoning gate may quarantine the newest eligible unsafe linked session summary. Returns link evidence plus git metadata; it does not guess commit intent when no link exists.
Inputs: session_id (required), limit, project. Returns: commits
context_bundleCompile Context Bundle (Experimental)ADestructive
Experimental Context Bundle v1 compiler. Requires schema_version=1 and a non-blank task. Returns a policy-bounded, source-attributed ContextBundle with a complete selection/drop audit; project is explicit or derived from cwd, and role/risk/token budget have deterministic defaults. Historical as_of_epoch pins and include_superseded=true fail loudly until the canonical loader supports them. This reuses the production SessionStart canonical loader, performs no foreground LLM or network call, and returns canonical load failures as a blocked audited bundle. Its poisoning safety check may quarantine unsafe persisted rows, so callers must not treat it as side-effect-free. The JSON shape is versioned but remains experimental.
Inputs: task (required), schema_version (required), cwd, risk, +7 more. Returns: Closed output-only mirror of the experimental Context Bundle v1 wire contract.…
current_stateCurrent StateARead-onlyIdempotent
Read-only. Resolve one stable state_key to a JSON object with status=current, no_current, not_found, ambiguous, or unresolved_conflict, plus answer, compact history, and why edges. state_key must be non-blank; project/owner/type/as_of filters narrow the resolution. Use this instead of search when the durable key is known; use timeline for chronological observation context. Invalid input or database failures return a tool error.
Inputs: state_key (required), type, project, owner_key, +2 more. Returns: why, facts, state, status, +6 more
get_observationsGet Observation DetailsADestructive
Fetch full details for explicit IDs and record last-accessed metadata for returned memory or observation rows. Use after search, not for discovery; prompt-time anchors may also direct this exact lookup. Pass selected IDs and the exact source from the result. source defaults to 'memory'; source='memory' returns curated memory details and requires its access update to succeed, source='observation' returns current extracted observations and records its access update best-effort (a failed update is logged but details still return), and source='session_summary' returns exact safe session-summary rows without confusing their IDs with observation IDs. Unsupported sources, any missing requested ID, detail-read failures, or memory access-update failures return a tool error.
Inputs: ids (required), source, project, include_suppressed. Returns: details
govern_memoryGovern MemoryADestructive
Auditably delete, reject, or mark curated memories stale. Use dry_run=true first to preview affected IDs and their current versions. Non-dry-run mutations require confirm_destructive=true, an explicit reason, and expected_versions containing every target ID. This never deletes raw archive data.
Inputs: ids (required), action (required), actor, reason, +5 more. Returns: action, reason, dry_run, affected, +1 more
list_raw_sessionsList Raw SessionsARead-onlyIdempotent
List sessions with raw archive messages inside a time window, grouped by (source_root, host, project, session_id) with a stable session_ref, content_hash, first/last message epoch, message count, and optional role=user message samples. Unresolved or conflicted provenance is skipped and reported in excluded_legacy_identities; latest fills at most that many newest healthy sessions and does not spend slots on skipped rows. Use for recap-style summaries of what happened in a period. Output fields match remem raw sessions --json.
Inputs: since, until, latest, sample, +1 more. Returns: count, latest, sample, project, +6 more
lookup_commitLookup CommitADestructive
Look up git commit metadata and linked memory sessions by full or short SHA. Its poisoning gate may quarantine the newest eligible unsafe linked session summary. The response separates git metadata from memory-derived summaries so missing links are not inferred.
Inputs: sha (required), project. Returns: commits
recall_user_contextRecall User ContextADestructive
Assemble task-aware user context from safe claims, profile summary, repo memories, requested current-state keys, workstreams, and recent sessions. Its poisoning gate may quarantine an unsafe legacy or session summary. Requires a non-blank query and an explicit project or cwd scope. Returns a compact source-attributed JSON object with included items, dropped items, reason codes, and budget metadata. Use search for exhaustive memory matches and current_state for one exact stable key; this tool selects a bounded context bundle instead. Invalid or missing scope input and database failures return a tool error.
Inputs: query (required), cwd, host, limit, +9 more. Returns: host, empty, query, context, +6 more
save_memorySave MemoryADestructive
Save a memory for future sessions. MUST be called after: (1) architecture decisions — record what was chosen, why, and what was rejected, (2) bug fixes with root cause — record symptom, root cause, fix, and prevention, (3) important discoveries — record finding and its implications, (4) user preferences — record preference and reasoning. Use topic_key for cross-session dedup (same project+topic_key updates existing memory). By default also writes a local markdown backup.
Inputs: text (required), host, files, scope, +13 more. Returns: id, scope, branch, status, +15 more
searchSearch MemoriesARead-onlyIdempotent
Read-only. Search or list curated memories: query is optional for standard search, while project/type/branch and visibility flags filter results. Optional task_intent/role/risk/token_budget/include_superseded compiles a GH-934 RetrievalPlan, applies its search/rerank/fallback policy, and returns retrieval_plan audit metadata. Returns a compact JSON object with results, source='memory', pagination, and next_step for get_observations(ids, source); limit defaults to 20 and offset to 0. Use current_state when an exact stable state_key is known, timeline for chronological observation context, and search_raw for literal chat recall. explain and multi_hop each require a non-blank query, and explain cannot be combined with multi_hop=true. Invalid combinations or curated-search database failures return a tool error; an automatic raw-archive fallback failure preserves the curated results and adds raw_hits_error to the successful response.
Inputs: risk, role, type, limit, +11 more. Returns: mode, explain, results, has_more, +8 more
search_rawSearch Raw ArchiveARead-onlyIdempotent
Search the raw archive (every user/assistant turn captured by the Stop hook). Use this when search returns no curated match or you need to recall a literal phrase from past chats. Returns the untreated conversation content — expect noise. The raw archive is what guarantees 'what was said remains searchable' even when summarize/promote skip a turn.
Inputs: query (required), role, limit, since, +4 more. Returns: note, role, count, limit, +10 more
timelineMemory TimelineARead-onlyIdempotent
Read-only. Return a JSON array of observations before and after one center point; provide anchor or query, and anchor takes precedence when both are set. depth_before and depth_after default to 5, and project limits both anchor lookup and results. Use this for local chronological context around an observation; use timeline_report for an aggregated project report, search for curated memories, or current_state for a stable fact. Missing anchors/queries, no query match, or database failures return a tool error.
Inputs: query, anchor, project, depth_after, +1 more. Returns: observations
timeline_reportTimeline ReportARead-onlyIdempotent
Read-only. Generate an aggregated Markdown report for the required project with activity history, type distribution, and Token ROI analysis. full defaults to false for the compact report; full=true adds the detailed timeline and monthly breakdown. Use this for project-level reporting, not observation lookup; use timeline for chronological context around one observation. Database failures return a tool error.
Inputs: project (required), full.
update_workstreamUpdate WorkstreamADestructive
Mutates one existing workstream by id. At least one of status, next_action, or blockers is required; omitted fields remain unchanged. status accepts only active, paused, completed, or abandoned. Returns a JSON object with id and updated, where updated=false means no row matched. Use workstreams to list/read rows first. This tool does not create or delete workstreams; an empty update, an unknown status, or a database failure returns a tool error.
Inputs: id (required), status (required), blockers, next_action. Returns: id, updated
workstreamsList WorkstreamsARead-onlyIdempotent
Read-only. List existing high-level workstreams for a required project, optionally filtered by status=active, paused, completed, or abandoned. Returns a JSON array with each workstream's status, progress, next action, blockers, and timestamps. Use update_workstream to mutate an existing row; this tool does not create, update, or delete workstreams. A missing project or database failure returns a tool error.
Inputs: status (required), project. Returns: workstreams
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Most tools include explicit positioning guidance, but the set has several overlapping retrieval/context-assembly tools: search, search_raw, current_state, timeline, context_bundle, and recall_user_context could all plausibly match a lookup request. The long descriptions help disambiguate them, but an agent scanning names alone would likely confuse context_bundle with recall_user_context or timeline with timeline_report.
The set mixes verb-led names like save_memory, update_workstream, and lookup_commit with noun-led names like workstreams, timeline, and context_bundle, plus the odd commits_for_session. There is no single predictable naming pattern, though the names are individually readable and avoid chaotic style mixing.
Fifteen tools is at the upper edge of a compact surface, but the set covers memory management, raw sessions, git commit links, workstreams, and reporting without feeling padded. A few retrieval helpers could be consolidated, so it is slightly heavy rather than perfectly minimal.
The core memory lifecycle is covered: save_memory creates/updates, search and get_observations retrieve, and govern_memory handles deletion/staleness. The main gap is workstreams, which can be listed and updated but not created or deleted, though that is a workable omission for the primary memory-centric workflow.
Maintenance
Related MCP Connectors
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
Persistent cross-session memory shared by Codex, Claude Code, ChatGPT, and other AI agents.
Shared work memory for Claude Code, Codex, Cursor and chat, scoped to each repository.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Related MCP Servers
- AlicenseAqualityDmaintenancePersistent memory for Claude Code. Automatically indexes every conversation and provides production-grade hybrid search (BM25 + vectors + reranker) via MCP tools. 100% local, zero config, zero API keys, zero invoice.1642 npm8MIT
- AlicenseAqualityBmaintenancePersistent local memory for Claude Code that indexes every session's JSONL file verbatim into SQLite + ChromaDB. Exposes 17 MCP tools for semantic recall, deterministic file replay, and fuzzy "do you remember when..." queries across your entire session history — no API calls, nothing leaves the machine.17122 PyPI16MIT
- AlicenseBqualityBmaintenancePersistent, local memory for AI coding agents that learns how you work, not just what you said. Supports Claude Code, Codex CLI, Cursor, and any MCP client.7998 PyPI77MIT
- AlicenseAqualityBmaintenanceLocal-first shared memory and task coordination for AI coding agents. One Go binary, MCP server, markdown files you own. Hooks for Claude Code and Codex CLI (and their desktop apps).306MIT