Get memo version info — the package version and the backend protocol version. Use this to check which version of memo is running.

Navigate the entity knowledge graph (read-only).

One consolidated explorer over memo's corpus graph. Pick a verb:

• "path": shortest entity path from a to b (fewest hops).

• "why": weighted shortest path a->b as evidence — the same route with each hop's edge weight (how many memories bridge it), so a connection is explained, not just asserted.

• "neighbors": direct neighbours of entity (or a).

• "explore": a rich "what's around X" view of entity (or a) — degree, neighbours, and the memories that mention it.

• "communities": clusters of related entities (limit caps count).

• "impact": changed code plus linked durable memories for cwd.

• "architecture": a bounded CodeContextPack for cwd. entity (or a) selects a symbol/path focus; mode is scout, verify, or audit and cursor continues an incomplete page.

By default this navigates the MEMORY graph only (entities linked through shared memories). Set include_code=True to also fold in the codegraph code-structure layer (call/extends/etc. edges between code symbols).

Persist content to memo.

Use memo_save for a durable curated fact, decision, or preference; use memo_offload for bulk dumps of working context.

When extract is true (defaults to the MEMO_SAVE_EXTRACT flag, off), the helper LLM decomposes content into atomic facts and saves each as its own memory (mem0 ADD-model) instead of one opaque blob; tags propagate to every fact. Returns an extraction summary (status, saved ids, saved_titles, counts) rather than a single record. If nothing extractable is found, the blob is saved verbatim. Normal saves add action (created, corroborated, or revised) and index_pending so callers can distinguish evidence from a new record.

scope controls the auto project:<repo> tag for THIS call only: "global" skips it (the memory lands untagged → the global recall tier, +0.10 boost everywhere); "project" or None keep the default auto-detection. An explicit project: tag in tags always wins either way.

defer_embed mirrors CLI memo save --defer-embed: it persists markdown + BM25 immediately and marks the semantic vector pending for memo_reindex. Extraction mode ignores it, matching the CLI.

List recent memories, optionally filtered by memory type.

Read-only. Use this to browse the corpus before choosing an id for memo_get, memo_update, memo_rename, memo_delete, or history tools. limit caps the number of returned records.

Fetch one memory by id or unique id prefix.

Read-only. Returns the full memory record, None when it does not exist, or an ambiguity error when the prefix matches multiple records. Use memo_search or memo_list first when you do not know the id.

When MEMO_EMITTED_LEDGER is on and the resolved id already has an entry in this session's emission ledger, this call counts as a recovery against the feature's net-saving estimate (see memo_cache_stats's emit_ledger.memo_get_after_digest) -- the conservative rule the spec calls for, not proof this call actually followed a digest pointer.

Patch fields on a memory. content replaces the whole body; replace_old+replace_new is a surgical exact-string edit (old must occur exactly once — unchanged text stays byte-identical); append adds a paragraph. All three are versioned (memo_version_rollback).

Rename one memory title without changing its body or tags.

Destructive metadata edit. Use after memo_save or memo_search when a record has the right content but the wrong title. Pass id for a specific memory; omit it only immediately after a save, when memo can target the most recent local save. Use memo_update instead when you need to edit content, type, or tags.

Rebuild memo's searchable index from the markdown vault.

Writes only derived index state; markdown remains the source of truth. Use after hand-editing vault files or changing indexing behavior. force reprocesses records even if memo thinks they are current.

Permanently delete one memory by id or unique prefix.

Destructive and irreversible (no trash). Elicitation-capable clients are asked to confirm before the delete runs; other clients proceed unchanged. Resolves ambiguous short ids safely and returns an error instead of guessing. When cross-reference indexing is enabled, the response warns about memories that linked to the deleted record.

Mark one memory as forgotten without deleting its history.

Destructive in retrieval behavior: the memory is hidden from normal recall/search surfaces until memo_unforget restores it. Pass reason to record why the memory should no longer be surfaced.

Restore a previously forgotten memory to normal retrieval.

Idempotent write. Accepts a full id or unique prefix and returns whether a matching forgotten record was restored. Use after deciding a memory should participate in search and recall again.

Detect near-duplicate clusters and propose merges.

Read-only — returns proposals without modifying the corpus. Uses the AdvancedConsolidator under the hood (same as memo_consolidate_list_archived). With client sampling enabled, merge synthesis runs on the calling model up to MEMO_SAMPLING_MAX_CALLS (see synthesizer field). max_clusters bounds how many clusters come back; a single cluster's member list is bounded separately by member_limit -- same-topic memories cluster by design, so one cluster can hold most of the corpus.

Both defaults are derived from MEMO_MCP_RESPONSE_BUDGET_TOKENS rather than picked for round numbers: a returned member carries a 600-char body_preview, so the response costs roughly max_clusters * member_limit * 850 chars and the previous 20 x 20 spent ~47k tokens against a 10k cap -- 20 clusters cannot be returned with any useful member detail at all. 10 x 2 measures 3,978 tokens on the conformance corpus and ~9,039 projected for a corpus whose bodies actually reach the 600-char preview cap. Two sample members are what it takes to SEE a duplicate; total still reports the cluster's real size, and memo_get fetches any member by id. Raise either argument to see more and accept a larger response (the budget middleware refuses one that overruns rather than silently truncating it).

Inspect the memory corpus for maintenance issues.

Read-only. Returns grouped lint findings such as malformed metadata or other records that may need cleanup, capped at limit per category — the findings scale with the corpus and a whole report runs past any client's response budget. Use memo_update, memo_delete, or vault edits separately to fix findings.

Offload a bulky payload (tool output, log, dump) out of the context window: memo stores it content-addressed as a reference-tier memory and returns {id, sha256, kind, synopsis, deduplicated, drill_down}.

Use memo_offload for bulk working-context dumps; use memo_save for curated durable facts meant to be recalled. Idempotent per payload: re-offloading identical content returns the existing id with deduplicated: true instead of writing a new memory.

The synopsis is deterministic (no LLM): JSON keys, CSV headers, code symbols, or compressed text. Reference tier is excluded from auto-recall, so offloaded blobs never appear in the recall hook. Fetch the full payload later with memo_get(id).

Return the active embedding model profile.

Read-only. Use this to inspect the model id, vector dimensions, normalization, and provider that memo uses for semantic search. Useful when verifying compatibility with stored vectors or external retrieval components.

Load a compact startup briefing from Memo's durable and operational state.

Read-only. Call before deciding or answering so prior durable facts can ground the task. Pass cwd to bias project context and source to attribute consult logs to the calling client.

Search durable memories by text, vector similarity, or hybrid mode.

Read-only. Returns raw ranked hits — source records with ids, dates, tags, and excerpts. Use memo_context instead for a budgeted prompt-ready pack, memo_search_trace for scoring diagnostics, and memo_rerank to reorder hits you already have.

Build prompt-ready memory context without calling the answer LLM.

Read-only. Unlike memo_search's raw hit list, this returns a budgeted, prompt-ready context pack for direct injection: static profile, dynamic recent context, query hits, omissions, and a readonly prompt wrapper.

Search memories and include retrieval trace diagnostics.

Read-only. Debug variant of memo_search: use it when investigating ranking, filters, or recall misses rather than for normal lookup. Returns the same style of hits as memo_search plus trace metadata that explains how candidates were selected and scored at each stage.

Rerank candidate memory hits for a query.

Read-only. Performs no retrieval of its own (unlike memo_search) — it only reorders caller-supplied hit dictionaries, e.g. after memo_search or another retrieval source, when you need the most relevant subset ordered for answer synthesis. When reranking is disabled in this install, hits pass through in input order without scores.

Embed one query string with memo's query embedding path.

Read-only. Use for diagnostics or integrations that need the exact vector memo would use for retrieval queries. Rejects empty text and returns the vector, dimension, and model id.

Embed one or more document strings with memo's document embedder.

Read-only. Use for diagnostics or external indexing when you need document vectors from the same model memo uses internally. Pass a list of strings; an empty list returns no vectors without error.

Answer a question using memo retrieval and citations.

Read-only. Use when you want a synthesized answer grounded in durable memories instead of raw hit lists. k, type, and snippet_chars tune retrieval; source attributes consult logging. With client sampling enabled, synthesis runs on the calling model (see synthesizer field).

Answer a conversational question with optional history and context.

Read-only. Use instead of memo_ask when prior turns or explicit context should shape retrieval and synthesis. history is a list of chat messages; session_id links the answer to a tracked memo session. With client sampling enabled, synthesis runs on the calling model (see synthesizer field).

Return provenance metadata for one memory.

Read-only. Use with a full id or unique prefix when you need origin, lineage, file path, or related audit details for a record before trusting, editing, or citing it.

Return recent history events for one memory in chronological order.

Read-only. Use to inspect how a memory changed over time before editing or rolling back. Accepts a full id or unique prefix; limit caps returned events and has_more reports truncation.

List recent memory history events.

Read-only. Use for audit trails across the corpus or filter by op and memory id when investigating a specific write, update, delete, forget, or reindex action. Short ids are resolved safely.

List tracked memo sessions.

Read-only. Use to find recent session ids, transcript paths, and project context for capture or inspection. project narrows results and limit caps the number of sessions returned.

Fetch metadata for one tracked memo session.

Read-only. Use after memo_session_list or memo_start_session when you need the stored transcript path, project, checkpoints, or other session details. Returns None when the session id is unknown.

Return local memo corpus and runtime statistics.

Read-only. Use for diagnostics, health checks, and environment inspection. Includes corpus count, storage paths, embedder model, history error count, and recall daemon health when available.

Run idle capture on the current session.

Write tool. Extracts durable insights from the newest tracked session transcript and saves them as memo records. Use after a meaningful unit of work, or periodically for clients without Stop hooks. Do not use for normal lookup; call memo_search, memo_ask, or memo_unified_briefing when you only need to read existing memories. With dry_run=True, no memories are written and the response only reports what would run.

Read and dismiss pending idle-capture notification.

Destructive only for the notification queue: returns the pending idle-capture message, then removes that transient notification so it is not shown twice. It never deletes memories or session transcripts. Use after memo_idle_capture or before replying to surface auto-saved insights; use memo_search or memo_list to read durable memory records.

Start a new session for this client.

Write tool. Creates or refreshes a tracked session checkpoint used by capture, grounding, and transcript lookup. Call once at the beginning of a task or conversation. Pass session_id to continue a known session; omit it to create one. Pass cwd to bind the session to a project directory; omit it to use the current process directory. Do not use this to save memories directly; call memo_save or memo_save_text for durable content.

Save a memory from text.

Write tool. Persists one plain note from text and returns the saved memory id. Use for quick client-agnostic saves when you already have the exact content to remember. Prefer memo_save when you need tags, type, extraction, conflict handling options, or project/global scope. Prefer memo_idle_capture for transcript-derived session insights. title is optional; when omitted memo uses the first text line.

Return bounded, cited evidence for a question, or an explicit abstention.

Read-only, no side effects. Every snippet carries a memo:// citation; when retrieval coverage stays under min_coverage the result is an explicit abstention, never a fabricated answer.

Read current focus, handoffs, attention items, conflicts, and outcomes.

Read-only snapshot of the operational journal's current state. Returns only what is still open unless include_closed is set, and only the newest limit entries per section — open items awaiting human triage accumulate faster than they settle, so an unbounded snapshot eventually costs more context than the memories it describes.

Preview the exact memories an ACL would allow into a signed bundle.

Verify every native operational hash chain.

Remember a durable, idempotent operational watcher marker.

List durable watcher markers, newest epoch first.

Set the current focus for a project.

Replaces the project's previous focus; the change is journaled with the acting agent's identity. Safe to repeat with the same summary.

Clear a project's current focus.

Idempotent: returns {'cleared': false} when no focus was set.

Create a durable handoff for another agent or session.

Writes a journaled handoff record that surfaces in memo_operational_state until some agent consumes it.

Mark a handoff consumed so it stops surfacing to later agents.

Idempotent: returns {'consumed': false} when the id is unknown or the handoff was already consumed; true only on the first consume.

Add an item that must be surfaced to later agents.

Writes a journaled attention record; severities outside low|medium|high|critical are rejected.

Acknowledge an attention item so it stops being surfaced.

Idempotent: returns {'acknowledged': false} when the id is unknown or already acknowledged; true only on the first acknowledgement.

Open a local, auditable reality conflict.

Writes a 'detected' conflict record to the hash-chained journal. Resolution is human-only — memo_conflict_resolve reports the CLI command a human must run.

Report the local human action required to resolve a conflict.

Read-only: never resolves anything itself — it returns the memo operational conflict resolve command a human must run locally.

Record whether recalled memories helped a task succeed.

Feeds success/failure back into each cited memory's outcome stats — the signal behind procedure promotion. Idempotent per idempotency_key.

List outcome-backed memories ready for procedural promotion.

Promote grounded memories into a reusable procedure/failure pattern.

Creates a new durable memory citing the sources; rejects sources whose outcome stats don't meet the kind threshold.

List deliverable terminals; empty while legacy TTY input is disabled.

Return bounded stable and active memory with evidence metadata.

List records whose explicit review date passed or have an open conflict.

Record review evidence, verify the memory, and schedule its next review.

Replaying the latest still-current review with identical evidence and actor is a no-op, so retries are idempotent.

Close one memory's truth-validity interval without deleting it.

Sets invalid_at in the record's frontmatter and index; the record itself is retained and stays readable.

Close the old memory at the successor's validity start.

Only the old record is modified; the close time never precedes the old record's own validity start.

Return process-local MCP write queue depth, waits, and rejections.