memo

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).

RAG question against a past snapshot. Same contract as `memo_ask` but the corpus view is rewound to `as_of`. The LLM is told explicitly that the view is historical so it doesn't smuggle in facts that only became known later. Args: question: Free-text question. as_of: `YYYY-MM-DD` or full ISO 8601. k: Top-k memories to feed the model as context.

RAG answer grounded in memories VALID at a past instant (valid-time). Same contract as ``memo_ask`` but retrieval is filtered to records whose world-validity interval contains ``as_of`` (see ``memo_search_valid_as_of``). Distinct from ``memo_ask_as_of``, which rewinds the *whole corpus* via transaction-time snapshot replay. Args: question: Free-text question. as_of: ``YYYY-MM-DD`` or full ISO 8601. k: Top-k memories fed to the model as context. type: Optional record-type filter. source: Attributes the consult log to the calling layer. Returns: the ``memo_ask`` answer env…

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.

Add an item that must be surfaced to later agents. Writes a journaled attention record; severities outside low|medium|high|critical are rejected.

Create a backup of the entire vault. Creates a compressed tar.gz archive of all memory files and databases. Returns metadata including checksum and size. Args: compress: Whether to compress the backup. name: Optional backup name (defaults to timestamp).

List all available backups. Returns a list of all backup archives with their metadata including timestamp and size.

Restore from a backup. Restores memory files and/or databases from a backup archive, overwriting the current store. Irreversible: elicitation-capable clients are asked to confirm first. Args: backup_name: Name of the backup to restore. restore_memories: Whether to restore memory files. restore_dbs: Whether to restore databases.

Force a capacity-bound eviction pass now (coldest-first, per MEMO_CACHE_EVICTION). Dirty entries are flushed to the backing store before removal. Evicted memories are deleted permanently, so elicitation-capable clients are asked to confirm when the pass would actually evict. Returns the evicted memory ids. No-op unless MEMO_CACHE_MODE != off and MEMO_CACHE_MAX_ENTRIES > 0.

Push all dirty (write-back, un-persisted) memories to the backing store and clear their dirty flags. Returns {flushed, failed, dirty_remaining}. No-op when cache mode is off or no backend exists.

Cache-tier status: mode, backend, entry count, capacity, overflow. When MEMO_CACHE_MODE=off (the default) `enabled` is False and memo is behaving as a durable store with no eviction. When MEMO_EMITTED_LEDGER is on, also carries `emit_ledger`: this session's emission-ledger scorecard (digests served, tokens suppressed/spent on digest stubs, memo_get recoveries, and the resulting `net_saved_est`) -- see `emitted_ledger.stats`. Surfaced here rather than as its own tool: a new MCP tool costs schema tokens on every request, which would spend back part of what this feature saves. Absent (not zeroe…

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).

Get shared connections for an entity. Args: entity: Entity of interest. Returns: List of SharedConnection objects.

Get top voted insights from the community. Args: limit: Max results. Returns: List of CollectiveInsight objects.

Get recommended connections based on collective patterns. Args: entity: Entity of interest. limit: Max results. Returns: List of recommended SharedConnection objects.

Share a discovered connection with the community. Args: user_id: User ID who discovered the connection. entity_a: First entity. entity_b: Second entity. relationship: Type of relationship. confidence: Confidence score. Returns: Shared connection data.

Share an insight with the community. Args: user_id: User ID. content: Insight content. Returns: Shared insight data.

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.

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_TOK…

List all archived memories. Returns a list of archived memory entries with metadata including the replacement memory ID and archival timestamp.

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.

Build a composed context pack for a question without calling the LLM. Returns current facts, supporting context, stale/conflicting context, and a compact summary. Use this when search hits need interpretation before answering. `source` attributes consult logging.

Show recent conversation history used for contextual recall. Returns the N most recent prompts with their recalled memories. This history is used to build context for search re-ranking. Args: limit: Number of recent prompts to return.

Show learned user preferences for memory recall. Returns the current preference scores for memory types, entities, and recency/diversity weights. Useful for understanding what the system has learned about the user's preferences.

Record that the user clicked/viewed a memory (for preference learning). Use this when the user explicitly selects a memory from search results. This teaches the system which memory types and entities the user prefers. Args: memory_id: The memory ID that was clicked/viewed.

Record a search in the conversation history for learning. Use this after each search to build context for future searches. The system learns from which memories are recalled to improve future contextual ranking. Args: query: The search query that was used. memory_ids: List of memory IDs that were recalled.

Search with contextual re-ranking based on conversation history. Uses conversation context and learned user preferences to re-rank search results. Boosts memories that overlap with recent context and aligns with user preferences. Args: query: Search query. limit: Max results. mode: Search mode (vec, bm25, hybrid).

List contradiction pairs from the sidecar DB. Args: status: One of open|fused|kept_newer|kept_older|evolved|dismissed. limit: Max rows. min_confidence: Filter to pairs at/above this LLM confidence. relationship: Optional 'contradiction' or 'evolution' filter.

Mark a contradiction pair as resolved. Valid statuses (excluding `open`): - `fused` — both merged into a new memory - `kept_newer` — newer side won, older deleted/archived - `kept_older` — older side won - `evolved` — legitimate evolution, both kept - `dismissed` — false positive This tool only updates the sidecar; it does NOT itself delete the memories or run a merge. Use `memo_consolidate` or `memo_delete` first if the resolution implies destructive ops. Args: pair_id: The integer pair_id returned by `memo_contradict_list`. status: One of the valid statuses…

Scan the corpus for contradiction / evolution pairs and persist them. Unlike `memo_temporal_contradictions`, which requires an entity name and returns ephemeral results, this walks all memories, uses vec neighborhoods to surface candidate pairs, and persists detected contradictions to a sidecar DB. The same pair is never re-classified once the user resolves it. Args: top_k: Neighbors to consider per memory. sim_floor: Cosine floor for candidate pairs. confidence_threshold: Min LLM confidence to persist. min_days_apart: Skip pairs whose `updated` are within N days. max_mem…

Return counts of contradiction pairs grouped by status.

Retrieve original content from crush cache. When memo crushes a large JSON array during ingest, it offloads low-relevance rows to cache and embeds only the top-K rows. The context-compression proxy reuses the same cache to make a cut reversible. This tool recovers the original from either. Args: hash_marker: Either the ingest-time wrapped form, "<<memo-crush:abc123def456>>", or the proxy's bare hex key, "abc123def456" — both name the same cache. Returns: {"original": <full_original_string>, "hash": <hash_val>} on success, or {"error": <message>} o…

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.

Diff the corpus between two snapshots — added, removed, updated. Args: from_ts: Start date — YYYY-MM-DD or full ISO 8601. to_ts: End date (defaults to "now" when omitted).

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.

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.

Top entities in the knowledge graph, ranked by mention count. Args: limit: Max entities. Default 30. type: Optional filter (`person`/`project`/`technology`/ `file`/`org`/`concept`).

Memory IDs that mention `name` (and optionally a specific entity type). Returns a list of full UUIDs, capped at `limit`. `graph.entity_memories` runs an unfiltered `SELECT` — one row per mention, no LIMIT — so a hub entity's id list tracks the corpus. The conformance gate measured 12,429 tokens for a single entity with 700 mentions, over the 10,000-token MCP response cap, which makes the tool unusable on exactly the entities most worth looking up. The library and CLI paths still return everything; only the MCP surface, the one with a token budget, is trimmed.

Find past work *sessions* by meaning — memo's episodic memory. Distinct from `memo_search` (durable facts/decisions): this searches the semantic index of your *sessions* — what you were working on, across agents — and returns each as a resumable session. Use it to answer "which session was about X" or "where did I work on Y". Args: query: Free-text description of the session you're looking for. limit: Max sessions to return. Returns: `{"query", "results": [{session_id, agent, score, summary, cwd, resume_command}]}`. Empty `results` ⇒ the index is empty (run `memo episodes index`) or…

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.

Zoom into one entity: its degree, the neighbours it connects to (with how many memories bridge each link), and the memories that mention it — one rich "what's around X" view over the merged entity + code graph. Args: entity: Entity or code-symbol name. max_neighbors: Max neighbours to return. max_memories: Max mentioning memories to return.

Export memories to CSV file. Exports all memories to a CSV file with columns for id, title, body, tags, type, created, updated. Args: output_path: Path to write CSV file (under current dir, Downloads, Desktop, or Documents).

Export memories to JSON file. Exports all memories to a JSON file with complete metadata. Args: output_path: Path to write JSON file (under current dir, Downloads, Desktop, or Documents).

Export memories to Markdown bundle (zip). Exports all memories to a zip file containing individual .md files with frontmatter metadata. Args: output_path: Path to write zip file (under current dir, Downloads, Desktop, or Documents).

Export a versioned, vendor-neutral memory passport (memo.passport.v1). Higher fidelity than JSON: a stable schema header plus the provenance / verification `extra` bag, so another memo (or tool) can validate and re-import the canonical record intact. See docs/PASSPORT.md. Args: output_path: Path to write the passport file (under current dir, Downloads, Desktop, or Documents).

Extract named entities (person/project/technology/file/org/concept) from memory bodies via the configured helper LLM and write them to the graph DB. Args: ids: Specific memory ids to process (full UUID hex). Mutually exclusive with `all_`. all_: Process every memory in the store. force: Re-extract even if entity links already exist (default skips already-indexed memories). Returns counts: `{processed, entities_extracted, links_written, skipped, errors}`. Cost: ~0.5-1s per memory. Use `all_=True` once after a fresh install, then incrementally on new memories.

Invalidate one temporal fact edge without deleting its provenance. Sets the edge's ``invalid_at`` (overwriting any prior value); re-invoking just re-stamps the timestamp. Returns ``invalidated: false`` when the id does not exist.

Save one temporal fact edge. Re-saving the same subject/predicate/object/source/valid_at combination is idempotent. Passing ``supersedes`` invalidates older fact ids at this fact's ``valid_at`` timestamp.

List temporal fact edges, optionally as-of a timestamp. Fact edges are explicit subject/predicate/object facts with ``valid_at``/``invalid_at``/``expired_at`` windows. This is a lower-level temporal substrate than memo_search: use it when the question is about fact validity over time, not general semantic recall.

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

Drop all feedback rows for `source_id`. Returns count deleted. Deletes every ranking-feedback row recorded for the memory (the memory itself is untouched). Irreversible — these user signals are deliberately preserved by reindex — so elicitation-capable clients are asked to confirm. Idempotent: a repeat call deletes 0 rows.

Flag a surfaced memory whose CONTENT is no longer true. Distinct from `memo_feedback_record` (which teaches the retriever per query): this routes to the memory lifecycle, not ranking. kind="outdated" — archive the memory (stale, not contradicted). kind="wrong" — archive it; pass `superseded_by` (id or prefix of the replacement memory) to record the supersede. Archive is reversible (the `memo maintain`/`dream` primitive), never a hard delete — an over-eager flag is recoverable. Use this when you find a recalled memory that is stale or contradicted rather than silen…

List recorded source-level feedback, newest first. Args: source_id: optional filter (full id or unique prefix). limit: max rows.

Record a feedback signal on a memory for a given query text. Supported signal values for `rating`: "thumbs_up" / "up" — explicit positive vote; boosts score ~0.15 per vote. "click" — implicit positive (user used/viewed this result); ~0.08 boost. "thumbs_down" / "down" — explicit rejection; hard-excludes from future similar queries. "ignore" — implicit negative (user skipped); soft 0.7× score penalty. Idempotent on (source_id, query, rating). Recording a different signal for the same (source, query) pair replaces the prior vote. Args: source_id: meta.id …

Clear a project's current focus. Idempotent: returns {'cleared': false} when no focus was set.

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.

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.

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.

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.

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"``: cluste…

Compute centrality metrics for all entities. Returns degree centrality (number of connections) and betweenness centrality (how often entity lies on shortest paths). Useful for identifying hub entities in the graph. Args: top: Return top N entities by degree centrality.

Detect communities (connected components) in the entity graph. Uses connected components to find clusters of related entities. Useful for discovering thematic clusters in the knowledge graph. Bounded on both dimensions that scale with the corpus: the list is capped at `limit` (largest first) and each community's `entities` at `max_entities`. `size` is always the community's TRUE entity count, so `size > len(entities)` means the entity list was trimmed and `entities_truncated` says so outright. Past those counts the response is trimmed again to fit the MCP response budget, so a default call a…

Discover bounded curated communities and bridges with exact evidence.

Export a bounded slice of the entity graph for visualization. Returns graph data in the specified format. Use with external tools like Graphviz (dot format) or web visualization libraries (JSON format). The slice is sized to the MCP response budget, so a default call always returns a graph instead of a `response_budget_exceeded` error. Scope: the code layer merged into this graph comes from the codegraph index resolved from the CURRENT WORKING DIRECTORY (nearest .codegraph/codegraph.db), not from MEMO_DATA_DIR/MEMO_STATE_DIR, so results can include symbols from a repo outside the configured …

Get direct neighbors of an entity in the graph. Returns entities directly connected to the given entity, along with the memories that connect them. Args: entity: Entity name. max_neighbors: Maximum neighbors to return.

Find shortest path between two entities in the entity graph. Uses BFS to find the shortest path. Two entities are connected if they share a memory. Returns the path including intermediate entities. Args: source: Source entity name. target: Target entity name. max_length: Maximum path length to search.

Trace evidence from one memory to code, or one code reference to memories. Provide exactly one of ``memory_id`` or ``code``. Code accepts a stable codegraph URI, symbol id, qualified name, or file path.

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.

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.

Report memory health: lowest-confidence and highest-ROI memories. Returns two ranked lists drawn from the memory_health table: - `low_confidence`: memories most penalised by open contradictions. - `high_roi`: memories most frequently recalled (promoted by access). Memories not yet in the health table have neutral scores (1.0/1.0) and won't appear here. Run `memo dream run` or `memo contradict scan` to populate scores. Args: top_n: How many memories to return in each list (default 10).

Operational health snapshot: corpus size, index dims, embedder profile, health-score coverage, feedback volume, and warnings. Read-only. Mirrors the `memo health` CLI. Args: probe_embedder: if True, times one embed_query (loads the model).

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.

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. Args: dry_run: Preview what would be saved without writing anything.

Import memories from CSV file. Imports memories from a CSV file, creating new entries for each row in the file. Args: input_path: Path to CSV file (under current dir, Downloads, Desktop, or Documents).

Import memories from JSON file. Imports memories from a JSON file, creating new entries for each item in the file. Args: input_path: Path to JSON file (under current dir, Downloads, Desktop, or Documents).

Import a versioned memo.passport.v1 file (validated, high-fidelity). Preserves content/title/type/tags/created and the provenance / verification `extra` bag; ids and derived indexes are rebuilt by this store. Rejects a malformed / wrong-schema passport before writing. Args: input_path: Path to the passport file (under current dir, Downloads, Desktop, or Documents).

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.

Verify every native operational hash chain.

Show all memories that reference this one. Returns backlinks (incoming links) to the specified memory. Useful for understanding how a memory is connected to others. Args: memory_id: The memory ID to find backlinks for.

Format a memory ID as a wikilink. Returns a wikilink string like [[memory-id]] or [[memory-id|Title]]. Use this to insert links into memory content. Args: memory_id: The memory ID to format as a wikilink. title: Optional display title for the link.

Show all memories that this one references. Returns outlinks (outgoing links) from the specified memory. Useful for understanding what a memory connects to. Args: memory_id: The memory ID to find outlinks for.

Suggest links to existing memories based on content. Returns suggested memories to link to, based on semantic similarity and other heuristics. Useful when saving a new memory to discover related existing content. Args: content: The memory content being saved. title: Optional title of the memory. tags: Optional tags of the memory. limit: Maximum suggestions to return.

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.

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.

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.

Run Apple Vision OCR on an image and return extracted text. Cached by SHA256 in `<state_dir>/ocr_cache`. Intended as an on-demand fallback for screenshots that have not been picked up by the indexer yet. Returns empty `text` if Vision is unavailable (non-macOS or missing PyObjC) or the file is missing. Args: image_path: Absolute path to the image file. The caller is responsible for resolving Obsidian `![[...]]` syntax to a real path on disk. Must live under the configured vault/data dir, the current working directory, Downloads, Desktop, or Documents.

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,…

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.

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`.

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.

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.

Return bounded stable and active memory with evidence metadata.

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.

Delete a saved query. Removes a saved query by name. Args: name: The name of the query to delete.

List all saved queries. Returns a list of all saved queries with their parameters. Useful for discovering available queries to execute.

Execute a saved query. Executes a previously saved query by name and returns the results. Args: name: The name of the saved query to execute.

Save a query for reuse. Stores a query with its parameters so it can be executed later by name. Useful for frequently-used complex searches. Args: name: Query name (unique). query_text: The search query text. type_filter: Optional type filter. tags_filter: Optional tag filter. date_from: Optional start date (ISO format). date_to: Optional end date (ISO format). search_mode: Search mode (vec, bm25, hybrid). limit: Result limit. description: Optional description.

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.

Synthesize a past coding session into durable memories. Reads the full session transcript and extracts decisions, facts, bugs, and follow-ups as structured memories, then saves a session arc note linking them. With client sampling enabled, synthesis runs on the calling model (see `synthesizer` field). Args: session_id: Specific session id (full or prefix). Omit to use the most recent. last: When session_id is omitted, use the most recent session (default True). if_due: Skip silently if the session was already reflected. dry_run: Preview what would be saved without writing any…

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. `errors` counts files that FAILED to index (parse error, embed failure, refused path) — a subset of `skipped`, which also counts deliberate skips (archives, chronicle, secrets). A non-zero `errors` means the index is incomplete: fix the cause and re-run.

Memories structurally connected (via the entity/code graph) to a memory or query.

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.

Delete one indexed repo and optionally remove memo's managed clone. Removal is permanent (elicitation-capable clients are asked to confirm); an unknown repo returns deleted=false instead of raising.

Embed pending repo chunks. Runs automatically during repo index by default. Idempotent: without `force` only chunks lacking a stored vector are embedded, so re-running on a fully embedded repo writes nothing.

Return indexed text for one repo file or line range.

Clone/fetch a Git repo and index all included text files. Auth is delegated to local `git`: public repos work directly; private repos work when SSH agent / credential helpers / tokens already let `git clone <url>` succeed on this machine.

List indexed repositories.

Search indexed repositories. `unified` adds CodeGraph and Git co-change providers to the semantic/lexical fusion. Scope can isolate production, tests, or vendored code without treating missing structural data as negative evidence.

Return index counts plus coverage/freshness evidence for one repo.

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.

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

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`, `corrobora…

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. Args: text: The content to save as a memory. title: Optional title (auto-generated from first line if not provided).

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.

Search the corpus as it existed on a past date (time-machine). Reconstructs a snapshot by replaying `history.db` events in reverse from "now", then runs the live search and post-filters to the snapshot's record set. Use this when you want to know what the user knew (or had decided) at a specific past point. Args: query: Free-text query. as_of: `YYYY-MM-DD` (interpreted as end-of-day UTC) or a full ISO-8601 timestamp. limit: Max results. type: Optional record-type filter. mode: `hybrid` (default), `vec`, or `bm25`. Returns: `{"as_of", "snapshot_size", "results": […

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.

Search durable memories as they were VALID at a past instant (valid-time). Unlike ``memo_search_as_of`` (transaction-time snapshot replay), this filters each record by its world-validity interval: a record surfaces only when ``as_of`` falls in ``[valid_at (or created), invalid_at)``. Use it to recall what was TRUE at a date even after the fact was later superseded — a since-invalidated record resurfaces at its historical instant instead of being hidden by the default now-gate. Args: query: Free-text query. as_of: ``YYYY-MM-DD`` or full ISO-8601 timestamp — the world-time to v…

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.

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.

List durable watcher markers, newest epoch first.

Remember a durable, idempotent operational watcher marker.

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. Args: session_id: Optional session ID (auto-generated if not provided). cwd: Current working directory (defaults to cu…

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.

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.

Not supported in the replay sync model. Sync replays the remote audit log into the local store; there is no precomputed file diff. Use ``memo_sync_pull`` to apply remote events. Args: remote: Path to remote memo state dir (unused).

Pull remote changes by replaying the remote audit log. Applies events missing from this machine that exist in the remote ``history.db``. Returns counts of applied / conflicting / errored events. Args: remote: Path to remote memo state dir (or its ``history.db``).

Not supported in the replay sync model. Sync is pull-only: each machine replays the other's audit log locally. To propagate local changes, the remote machine pulls from this one. Args: remote: Path to remote memo state dir (unused).

Delete a synthesis memory by ID. Only deletes memories of type=synthesis. Raises an error if the given ID belongs to a non-synthesis memory, preventing accidental deletion of regular memories through this tool. Irreversible: elicitation-capable clients are asked to confirm first. Args: id: The ID (or unambiguous prefix) of the synthesis memory to delete. Returns: {"deleted": True, "id": "<full-id>"} on success, {"deleted": False, "reason": "<reason>"} on failure, or {"error": "ambiguous", "prefix", "matches"} when the prefix matches multiple records.

List all existing synthesis memories with their provenance. Returns synthesis memories (type=synthesis) including the source memory IDs that contributed to each insight. Args: confidence: Optional filter by confidence level: "low", "medium", or "high". When None (default), all synthesis memories are returned regardless of confidence. scan_limit: Maximum number of synthesis memories to read from the index before applying the confidence filter (most recent first). Bounds rows scanned, not rows returned — the returned list may be smaller when conf…

Generate emergent insights from semantically related memory clusters. Unlike consolidation (which merges duplicates), synthesis asks: "what do these memories collectively imply that none states alone?" Results are saved as type=synthesis memories with provenance links to the contributing source memories. Safe by default (dry_run=True). With client sampling enabled, synthesis runs on the calling model up to MEMO_SAMPLING_MAX_CALLS, then local MLX (list return — no synthesizer field). Each result's `sources` list is a sample of the cluster that produced it; `total` carries the cluster's real …

Detect contradictions among memories mentioning a specific entity. Uses the helper LLM to classify pairs of memories as contradiction, evolution, consistent, or unrelated. Returns only contradictions and evolutions above the confidence threshold. Args: entity: The entity name to analyze (e.g. "ollama", "mlx"). entity_type: Optional entity type filter from graph. confidence_threshold: Minimum confidence (0-1). Default 0.7. max_pairs: Maximum number of pairs to analyze (LLM is expensive).

Analyze high-level temporal patterns across the entire corpus. Returns metrics including: - memories_per_month: histogram of creation activity - type_distribution_over_time: how memory types change over time - most_active_entities: entities with most temporal churn

Find memories that may be stale based on age and lack of access. Returns potentially stale memories with metadata including days since update and access count. Useful for identifying outdated information that may need review. Args: days_threshold: Days since last update to consider stale. min_access_count: Minimum access count to exclude (frequently-accessed old memories may still be relevant).

Build a chronological timeline of memories mentioning an entity. Returns a timeline with events ordered by date, including first/last seen timestamps. Useful for tracking evolution of decisions or opinions over time. Bounded: `build_entity_timeline` emits ONE event per mention, each carrying a 200-char snippet, so a hub entity's timeline tracks the corpus rather than the request. The conformance gate measured 110,326 tokens for an entity with 700 mentions, against a 10,000-token MCP response cap. The library and CLI paths still build the whole timeline; only the MCP surface, the one with a t…

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

Press Return through an authenticated receiver-bound PTY session.

Send through an authenticated receiver-bound PTY session.

Look up a tool's live description and parameter schema by name. Use this when a tool you expect (from a prior session, or from documentation) is missing from your current tool list: memo's proxy prunes schemas of recently-unused tools from context to save tokens — memo's own tools stay registered and callable regardless; other servers' tools are still reachable exactly as they were before pruning. Call this with the tool's name to get back what its full schema would have shown, then call the tool directly by name. Args: name: The tool name, e.g. "memo_graph" or "mcp__octocode__lo…

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.

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.

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).

Search explicitly indexed transcript turns with FTS5. Read-only and excluded from automatic recall. Results are bounded to 100; `session_id` and ISO8601 `since` narrow the private local index.

Show diff between two versions of a memory. Returns a unified diff between two versions. If version_a or version_b is None, uses the latest and latest-1 versions respectively. Args: memory_id: The memory ID to diff. version_a: First version ID (or None for latest). version_b: Second version ID (or None for latest-1).

Show version history for a memory. Returns a list of all versions of the specified memory, most recent first. Each version includes title, type, tags, body snapshot, and change reason. Args: memory_id: The memory ID to get history for. limit: Maximum versions to return.

Rollback a memory to a previous version. Restores the memory to the specified version by updating its content, title, type, and tags to match the version snapshot. Args: memory_id: The memory ID to rollback. version_id: The version ID to rollback to. reason: Optional reason for the rollback.

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