Memtomem

View or update memtomem configuration values. Args: key: Dot-notation key to read or write (e.g. "search.default_top_k"). If omitted, returns the full configuration as JSON. value: New value to assign. Omit to read the current value. persist: If True, save the change to ~/.memtomem/config.json so it survives server restarts. Default is runtime-only.

Check for potential contradictions with existing memories. Finds chunks with high semantic similarity but low text overlap, which may indicate conflicting information. Args: content: Content to check against existing memories. threshold: Minimum similarity score to consider (default 0.75).

Find groups of related chunks that could be consolidated into summaries. Analyzes chunks by source file and semantic similarity to identify groups that an agent can summarize. Chunks an existing summary covers are left out. This is a dry-run — no mutations. Args: namespace: Scope to this namespace source_filter: Only analyze chunks from matching sources max_groups: Maximum number of groups to return min_group_size: Minimum chunks per group (default 3)

Apply a consolidation by creating a summary chunk for a group. The agent writes the summary; this tool persists it via the normal ``mem_add`` path — the summary becomes a real markdown entry in a file of its own under ``consolidated/`` in its scope's memory directory, and each original chunk gets a ``consolidated_into`` relation pointing to the summary. This preserves the file-based mental model: consolidation events are visible in the filesystem and in git history, and the summary can be hand-edited like any other markdown entry. ADR-0011 cross-scope rejection: source chunks are loaded by `…

Migrate canonical context artifacts (agents / commands / skills). Mirrors the CLI ``mm context migrate`` verb's two modes, selected by whether ``to_scope`` is set (``cli/context_cmd.py:migrate_cmd``). Reuses the same pure functions (``classify_migrate`` / ``migrate_one`` / ``migrate_scope``) and the SAME gate semantics as the CLI — no logic is re-implemented. For *memory*-tier migration use ``mem_context_memory_migrate``. Two modes: * **Flat→dir layout** (``to_scope`` omitted) — converts pre-PR-C ``agents/<name>.md`` to ``agents/<name>/agent.md``. ``asset_type=""`` (the default) batches…

Move or copy one canonical artifact between tiers and/or projects. Headless parity for ``mm context copy`` / ``mm context move`` and the web transfer endpoint — the same :func:`memtomem.context.transfer.transfer_artifact` engine call with the same gate semantics; no logic is re-implemented. The three verbs in one view: **move** consumes the source and cleans its stale runtime fan-out (destination fan-out is NOT generated — run the follow-up sync command the result prints); **copy** never touches the source and supports a renamed copy via ``as_name``; ``mem_context_artifact_migrate`` stays the…

Compose Pinned Context first, then fill the remaining budget by retrieval. Args: query: Retrieval query for the remaining budget (omit for pinned-only) agent_id: Restrict pinned blocks to this agent max_chars: Total character budget for the bundle (default 12,000) top_k: Number of retrieval results to consider (default 10) namespace: Namespace scope for retrieval context_window: Expand each retrieved hit with ±N adjacent chunks. Neighbours obey visibility rules (hidden namespaces, project scope, validity) but not tag/type/date filters rerank: Per-ca…

Detect agent configuration files in the current project. Scans for CLAUDE.md, .cursorrules, GEMINI.md, AGENTS.md, and .github/copilot-instructions.md. Pass ``include="skills,agents,commands"`` to also list runtime skill directories, sub-agent files, and slash-command files. Args: include: Comma list of extra kinds to report — ``skills``, ``agents``, ``commands``, ``settings``. ``settings`` lists the resolved-scope settings file of each available runtime (Claude, Codex, Gemini, Kimi), including ones not yet created. Empty (default) reports agent files only.…

Show sync status between context.md and agent files. Pass ``include="skills,agents,commands"`` to also compare canonical skills, sub-agents, and slash commands against their runtime counterparts. Args: include: Comma-separated extra artifact kinds (``skills``, ``agents``, ``commands``, ``settings``). scope: ADR-0011 canonical artifact tier for the skills / agents / commands diff (``project_shared`` default, ``user``, or ``project_local``). The same value is also forwarded as the ADR-0010 host-write target-scope override for ``settings``, mirror…

Generate agent configuration files from .memtomem/context.md. Args: agent: Agent name (claude, cursor, gemini, codex, copilot) or "all". include: Comma-separated extra artifact kinds (``skills``, ``agents``, ``commands``, ``settings``). label: ADR-0022 — fan out the frozen version at this label (e.g. ``"production"``) or a bare version tag (``"v2"``) for the versioned kinds (``agents`` / ``commands``) instead of the working canonical. ``""`` (default) / ``"latest"`` means the working file (today's behavior, unchanged). Ineligible included ki…

Seed canonical context artifact directories. Args: include: Comma-separated runtime artifact kinds to pull into canonical storage (``skills``, ``agents``, ``commands``). ``settings`` is accepted for parity with other context tools but has no init-time pull action. overwrite: Overwrite existing canonical entries during runtime import. Does **not** govern ``.memtomem/context.md`` rewrite — see ``overwrite_context_md``. overwrite_context_md: Allow rewriting an existing ``.memtomem/context.md`` from detected agent files. Kept sep…

Move markdown memory file(s) between ADR-0011 memory scope tiers. Renamed from ``mem_context_migrate`` in #1147 (B5-2): this tool only ever covered *memory*-tier migration, but the bare name implied it mirrored the full CLI ``mm context migrate`` (which also does artifact flat→dir and scope-tier moves — see ``mem_context_artifact_migrate``). The old name was a deprecated alias and was removed in v0.5.0 (#1619). Mirrors the CLI ``mm context memory-migrate <SOURCE> --from <scope> --to <scope> [--apply] [--confirm-project-shared]`` (``cli/context_cmd.py:2574-2659``). Chunk-id-stable single-DB r…

Move or drop a label pointer over an artifact's versions (ADR-0022). Headless-agent parity for ``mm context version promote`` and the web ``PUT/DELETE /context/{type}/{name}/labels/{label}`` routes. A *label* (``production`` / ``staging`` / …) is a movable pointer over the immutable versions created by ``mem_context_version``. Promote and rollback are the same act — both just move the pointer; pass ``delete=True`` to drop a label entirely. Covers ``agents`` and ``commands`` only. Moving a pointer only updates the manifest — it does NOT fan out to the runtimes by itself. Deploy the pointed-at…

Pull one runtime's copy of an artifact into the canonical Store. Headless parity for ``mm context pull`` and the web Pull route — the reverse of Push/fan-out (``mem_context_sync``): it brings a runtime's on-disk copy (Claude Code / Gemini CLI / Codex CLI / Kimi) of a ``skills`` / ``agents`` / ``commands`` artifact back into the ``.memtomem`` canonical Store, over the same source-selectable, privacy-gated :mod:`context.pull_apply` engine. No logic is re-implemented; refusals are the engine's typed result codes. Dry-run by default (``apply=False``) returns a preview: each runtime's content rel…

Push .memtomem/context.md to all detected agent files. Args: include: Comma list of extra kinds to fan out alongside context.md. ``skills`` / ``agents`` / ``commands`` come from ``.memtomem/skills/``, ``.memtomem/agents/``, ``.memtomem/commands/``; ``settings`` comes from the single file ``.memtomem/settings.json``. Targets are the runtimes registered for that kind (Claude Code, Gemini CLI, Codex CLI, Kimi CLI for settings). Empty (default) syncs context.md only. strict: Legacy alias for ``on_drop="error"``. When both are given, …

List or freeze per-artifact version snapshots (ADR-0022). Headless-agent parity for the ``mm context version list|create`` CLI commands and the web ``GET/POST /context/{type}/{name}/versions`` routes: freeze a known-good working canonical into an immutable ``versions/vN.md`` snapshot, then point a label at it with ``mem_context_promote`` — so editing the canonical and deploying it become two acts with instant rollback. Writable for ``agents`` and ``commands``; ``skills`` are READ-ONLY here (``action="list"`` only, ADR-0030 §10) because a skill version is a ``versions/vN/`` directory-tree snap…

Delete chunks older than max_age_days from the index. Defaults to dry_run=True for safety -- set dry_run=False to actually delete. Args: max_age_days: Chunks older than this many days are expired. source_filter: Only expire chunks from sources containing this substring. dry_run: If True (default), preview without making any changes.

Preview chunks that would be expired by TTL (dry-run, no deletions). Args: max_age_days: Chunks older than this many days are listed as candidates. source_filter: Only scan chunks from sources containing this substring.

Merge duplicate chunks: keep keep_id, delete delete_ids. Tags from deleted chunks are merged into the kept chunk. Defaults to dry_run=True for safety -- set dry_run=False to actually delete. Mirrors the safety-first defaults on mem_decay_expire and mem_cleanup_orphans so a wrong UUID in a maintenance script can't silently destroy data on first call. Args: keep_id: UUID of the chunk to keep delete_ids: UUIDs of chunks to delete dry_run: If True (default), preview without making any changes.

Scan for duplicate chunk candidates (dry-run, no mutations). Args: threshold: Dense score 1/(1+L2) threshold (0-1, default 0.92) limit: Maximum number of candidate pairs to return max_scan: Maximum chunks to inspect for near-duplicate search

Delete memory entries from the index (and optionally from the source file). When chunk_id is given, the specific chunk's line range is removed from the markdown file and the file is re-indexed. When source_file is given, all chunks from that file are removed from the index (the file itself is NOT deleted). When namespace is given, all chunks in that namespace are removed from the index. ADR-0011: deleting project_shared chunks requires ``confirm_project_shared=True``. Bulk source deletes are all-or-nothing: if any matched chunk is project_shared, the whole source delete is rejected. Args: …

Execute a memtomem action by name. This is the gateway to all advanced memtomem features beyond the core tools (search, add, index, recall, status, stats, list, read). action="help" lists every action grouped by category; params={"category": "<name>"} adds per-parameter detail and, for some categories, usage notes. Common aliases resolve automatically (e.g. "orphans" → "cleanup_orphans", "health" → "eval"). Args: action: The action name (e.g. "session_start", "tag_list", "help") params: Optional dict of parameters for the action

Edit an existing memory entry in its source markdown file. ``new_content`` is treated as body-only: the heading line and the section-leading ``> created:`` / ``> tags:`` blockquote header are preserved automatically. To override the heading explicitly, prefix ``new_content`` with ``## `` and the call reverts to a full replacement of the chunk's line range. Editing an agent consolidation summary keeps its originals covered: the re-index moves their ``consolidated_into`` edges to the summary's new chunk, when the summary is the only chunk of its own file. ``new_content`` passes through the sa…

Check or resolve embedding configuration mismatches between DB and current config. Args: mode: One of: - "status" (default): Show DB stored values vs current config. - "apply_current": Reset DB to current config. DESTRUCTIVE — deletes all vectors, re-index required. - "revert_to_stored": Switch runtime embedder to match DB stored values. Non-destructive.

Scan indexed chunks and extract structured entities (people, dates, decisions, etc.). Entities are stored in a searchable index for later retrieval via mem_entity_search. Args: namespace: Only scan chunks in this namespace source_filter: Only scan chunks from matching source files (glob) entity_types: Entity types to extract (default: all). Options: person, date, decision, action_item, technology, concept overwrite: Replace existing entities for scanned chunks (default: false, skip already-scanned) dry_run: Preview extraction without saving (default: false)

Search for chunks containing specific entities. Find chunks that mention a person, date, decision, action item, or technology. Args: entity_type: Filter by type (person, date, decision, action_item, technology, concept) value: Search for entities matching this value (substring match) namespace: Namespace scope limit: Maximum results (default 20) scope: ADR-0011 tier filter — value, comma list (``user,project_local``) or glob (``project_*``), not both. Omitted, the default merge applies: inside a project ``user`` + that project's tiers, outside one …

Evaluate memory system health and effectiveness. Analyzes search patterns, access frequency, tag coverage, and indexing activity to produce a health report. Args: since: Only analyze activity after this date (YYYY-MM-DD or ISO) namespace: Scope analysis to this namespace

Expand a chunk with adjacent context from the same source file. Use this after mem_search when you need more surrounding context for a specific result. Returns ±N adjacent chunks ordered by line number. Neighbours inherit the same visibility rules as mem_search's context_window: system namespaces, the project-scope boundary, and temporal validity are enforced, so a hidden neighbour shrinks the window rather than surfacing. The chunk id does not widen that — expanding a chunk in a hidden namespace returns the chunk with little or no context. Use mem_search(namespace=..., context_window=N) to …

Export indexed memory chunks to a JSON bundle file. Args: output_file: Destination path for the JSON export (e.g. ~/backup.json). source_filter: Only export chunks whose source file path contains this substring. tag_filter: Only export chunks that carry this exact tag. since: ISO 8601 datetime lower bound on created_at (e.g. "2026-01-01T00:00:00Z"). namespace: Only export chunks in this namespace. Path policy (ADR-0006 Axis G): ``output_file`` is an unrestricted resolved path by design — local-tool authority, not a traversal bug. This is intentionally asymmetric with the …

Fetch a URL, convert to markdown, and index it for search. Supports HTML pages (converted to markdown), plain text, and raw content. The fetched content is saved as a .md file in the first memory directory and immediately indexed. Args: url: The URL to fetch and index tags: Optional tags to apply to indexed chunks namespace: Namespace for indexed chunks (default: config default) force_unsafe: Bypass the redaction guard when the fetched page matches a secret pattern. The bypass is recorded with a ``bypassed`` outcome and an audit line (see ``mem_add_redaction_s…

Generate review candidates from one exact session's events; writes no long-term memory. Classifies the session's recorded events and queues the ones that look memory-worthy as ``pending`` candidates. Events that carry a privacy hit are skipped rather than queued. Approval is a separate step (``mem_candidate_review``) — nothing durable is written here. Args: session_id: Session whose events to scan. Only this session's events are considered; there is no "scan everything" mode.

Import memory chunks from a JSON bundle file (produced by mem_export). Each chunk is re-embedded with the current embedder and upserted to storage. Args: input_file: Path to the JSON bundle file to import. namespace: Override the namespace for all imported chunks. on_conflict: How to resolve content-hash collisions against the existing DB. ``"skip"`` (default) drops records whose content already exists (idempotent re-import). ``"update"`` overwrites the existing row's metadata while preserving its UUID. ``"duplicate"`` is the pre-v2 behaviour: ever…

Import a Notion export (ZIP or directory) into memtomem. Cleans Notion-specific artifacts (UUID filenames, property tables, broken links) and indexes the imported files for search. Args: path: Path to Notion export ZIP file or extracted directory. namespace: Namespace for imported content (default: "notion"). tags: Tags to apply to all imported chunks. force_unsafe: Bypass the redaction guard when an exported page matches a secret pattern. The bypass is recorded with a ``bypassed`` outcome and an audit line (see ``mem_add_redaction_stats``). It never a…

Import an Obsidian vault into memtomem. Converts Obsidian-specific syntax ([[wikilinks]], ![[embeds]], callouts) to standard markdown and indexes for search. Args: vault_path: Path to Obsidian vault root directory. namespace: Namespace for imported content (default: "obsidian"). tags: Tags to apply to all imported chunks. force_unsafe: Bypass the redaction guard when a vault note matches a secret pattern. The bypass is recorded with a ``bypassed`` outcome and an audit line (see ``mem_add_redaction_stats``). It never applies to a ``project_shared`` dest…

Compute and update importance scores for all chunks. Importance = weighted combination of access_count, tag_count, relation_count, and recency. Args: namespace: Optional namespace filter.

Index or re-index markdown files for hybrid search. Args: path: File or directory path to index recursive: Whether to recurse into subdirectories (default True) force: If True, re-index all files even if unchanged (default False) namespace: Assign all indexed chunks to this namespace auto_tag: If True, run keyword-based auto-tagging on newly indexed chunks

Create a bidirectional link between two chunks. Links are stored as cross-references and shown when viewing related chunks. Common relation types: "related", "supersedes", "depends_on", "contradicts". Both ends must be inside the caller's project boundary (ADR-0011); an id from another project reads as not-found (ADR-0036). Args: source_id: UUID of the first chunk target_id: UUID of the second chunk relation_type: Type of relationship (default: "related")

List indexed source files with chunk counts, one page at a time. Args: source_filter: Filter by source file path (substring match, or glob pattern with *, ?, []) namespace: Only list sources containing chunks in this namespace limit: Files per page (1-500, default 50) cursor: Where to resume; copy it from the previous page's "More:" line Examples: mem_list(source_filter="*.md") — markdown files (glob) mem_list(namespace="work") — files in the "work" namespace

Assign existing chunks to a namespace without re-indexing. Filter chunks by source path and/or current namespace, then move them to the target namespace. If a selected chunk already exists there, the default call refuses before writing. Pass ``merge=True`` to keep the target's copy and remove redundant selected copies on purpose. Both ``namespace`` and ``old_namespace`` (when provided) are run through :func:`validate_namespace` so a hostile-shaped target cannot land verbatim in the chunks rows via the assign path. See issue #500. Args: namespace: Target namespace to assign chunks to …

Delete all chunks in a namespace from the index. The source files are NOT modified -- only the index entries are removed. Args: namespace: The namespace to delete.

Get the current session namespace.

List all namespaces and their chunk counts.

Rename a namespace (SQL UPDATE, no re-indexing needed). Refuses when ``new`` already exists (holds chunks or a metadata row) so a rename can't silently fold two namespaces together. Pass ``merge=True`` to consolidate on purpose: chunks move into ``new`` and the *target's* description/color are kept. Both ``old`` and ``new`` are run through :func:`validate_namespace` so a hostile-shaped string cannot land verbatim in the chunks / namespace_metadata rows via the rename path. See issue #500. Args: old: Namespace to rename. A namespace that exists only as metadata (registered, zero …

Set the session-default namespace. Subsequent search / add / recall use it unless they pass namespace=. One exception: while a session is active this is the *read* default only — resolver-backed writes go to agent-runtime:<agent_id> unless the call passes namespace= explicitly. Either way a re-index (mem_index) applies the bound namespace only to files with no stored rows; an already-indexed file keeps its own (#2104). ``namespace`` is run through :func:`validate_namespace` before the write, mirroring ``mem_session_start(namespace=...)``. Without the gate, an attacker who controls the value…

Update namespace metadata (description and/or color). ``namespace`` is run through :func:`validate_namespace` so the lookup key cannot carry a hostile shape into the ``namespace_metadata`` write. See issue #500. Args: namespace: The namespace to update description: Optional description text color: Optional color hex code (e.g. "#6c5ce7")

Delete one exact Pinned Context block. Exact deletion, no shadowing: only the block in the given scope and agent slot is removed, so deleting an agent block re-exposes the general one. Returns ``{"deleted": false}`` when nothing was there. Args: block_id: Block identifier. scope: ADR-0011 residency tier — ``user`` (default), ``project_shared``, or ``project_local``. agent_id: Delete the agent-scoped block instead of the general one. confirm_project_shared: Required consent for deleting from the git-tracked ``project_shared`` tree.

Read one exact Pinned Context block. Exact lookup, no shadowing: the block is read from the given scope and agent slot, and missing returns ``null`` rather than falling back to a wider scope. Use ``mem_pinned_list`` for the effective view. Args: block_id: Block identifier (the filename stem under the pinned store). scope: ADR-0011 residency tier — ``user`` (default), ``project_shared``, or ``project_local``. agent_id: Read the agent-scoped block instead of the general one.

List effective Pinned Context blocks after scope and agent shadowing. Returns the winner per block_id, not every stored copy: an agent-specific block shadows the general one, and a narrower scope shadows a wider one. Results are ordered by descending priority, then block_id. Args: agent_id: Include blocks pinned to this agent alongside the general ones, and let them shadow same-id general blocks. Omit to see the general blocks only.

Create or replace a Pinned Context block after privacy and scope gates. Writes are whole-block replacements — the block at ``(scope, agent_id, block_id)`` is overwritten, not merged. Args: block_id: Block identifier (becomes the filename stem). content: Block body. Rejected above 2,000 characters — pinned context is a bounded prelude to retrieval, not a place to park documents. scope: ADR-0011 residency tier — ``user`` (default), ``project_shared``, or ``project_local``. agent_id: Pin the block to one agent. Agent blocks shadow the general block of the…

Create a memory lifecycle policy. Policies automate memory management: archiving old memories, expiring unused ones, auto-tagging untagged chunks, or consolidating related chunks into heuristic summaries. Args: name: Unique policy name policy_type: One of 'auto_archive', 'auto_consolidate', 'auto_expire', 'auto_promote', 'auto_tag' config: JSON config string; the keys depend on policy_type — auto_archive: max_age_days, archive_namespace (or archive_namespace_template), age_field, min_access_count, max_importance_score; auto_consolidate: min_group_s…

Delete a memory lifecycle policy. Args: name: Policy name to delete

List all memory lifecycle policies. Args: runs: Also show the last N applied (non-dry-run) runs per policy, newest first, with status, source and what each run changed (default: 0 = none, max 20)

Run memory lifecycle policies. Args: name: Run specific policy by name. If omitted, runs all enabled policies. dry_run: Preview what would happen without making changes (default: true)

List all saved procedures.

Save a reusable procedure (workflow/pattern) to memory. Procedures capture "how to do something" — successful workflows, tool usage patterns, or step-by-step processes for future reuse. Args: name: Name of the procedure (e.g. "deploy-to-production") steps: Step-by-step instructions (numbered list recommended) trigger: When to use this procedure (e.g. "when deploying a new version") tags: Additional tags (procedure tag is added automatically) namespace: Namespace for the procedure

Replay stored evaluation cases into a deterministic retrieval-quality report. Runs each selected case through the search pipeline in no-side-effects mode and returns the canonical JSON replay report (advisory). Retrieved rows carry no chunk text and no absolute paths — content hashes + scores + metrics only. The report DOES include each case's name (secret-scanned at promotion, and defensively redacted at emit if a legacy row carries a secret or path) and its raw query text, which is NOT sanitized: a report is only as sensitive as the queries promoted into it, so treat it accordingly. Check `…

Read a chunk's content and metadata by UUID. Inspect a chunk before editing, or see the text behind a search preview. Ids resolve in the current project's scope; another's reads as not found. Args: chunk_id: The chunk's UUID (from mem_search results)

Recall memories created within a date range. Returns chunks ordered by creation date (newest first). Args: since: Inclusive start date (YYYY, YYYY-MM, YYYY-MM-DD, or ISO datetime) until: Exclusive end date — same formats as *since* source_filter: Filter by source file path (substring match, or glob pattern with *, ?, []) tag_filter: Comma-separated tags, matching ANY; applied before *limit*. namespace: Namespace scope — single, comma list, or glob ("project:*"), not both. limit: Maximum number of chunks to return (default 20) output_format: Output format — "compac…

Analyze recent memory activity and surface patterns for reflection. Returns a statistical report of memory usage patterns that an agent can analyze to derive higher-level insights. Based on the Stanford Generative Agents reflection pattern. Args: namespace: Scope analysis to this namespace since: Only analyze activity after this date (YYYY-MM-DD) limit: Maximum items per category

Save a reflection insight derived from memory analysis. After reviewing a mem_reflect report, use this to save higher-level observations and patterns as new memories. Args: insight: The insight or observation to save related_chunks: Optional list of chunk UUIDs that informed this insight tags: Additional tags (reflection and insight tags added automatically)

Find all chunks linked to the given chunk. Returns related chunks with their relationship type and content preview. Args: chunk_id: UUID of the chunk to find relations for

Delete ALL data (chunks, sessions, history, etc.) and reinitialize the DB. Embedding configuration is preserved. A re-index is required afterwards. Args: confirm: Must be True to proceed. Prevents accidental data loss.

Delete a registered schedule by id. Paired with ``schedule_register`` so a bad cron entry can be removed without editing SQLite directly. ``disable``/``enable`` are deferred to Phase C. Args: id: Schedule id to delete.

List all registered schedules with last-run status.

Register a cron-scheduled job (direct-cron mode). Args: cron: Five-field cron expression interpreted in UTC (e.g. ``"0 3 * * 0"``). job_kind: One of the registered ``JOB_KINDS`` keys (e.g. ``"compaction"``). params: Optional dict of parameters validated against the job's ``params_model`` before storage.

Run a registered schedule synchronously (out-of-band). Routes through the same ``JOB_KINDS[...].runner`` path as the dispatcher with the same per-job timeout, and records the outcome via ``schedule_mark_run`` so the next ``schedule_list`` reflects it. Args: id: Schedule id returned by ``schedule_register``.

Retrieve a value from working memory, or list all entries if no key given. Args: key: The key to look up. Omit to list all entries.

Promote a working memory entry to long-term memory. Saves the entry via mem_add and marks it as promoted in the scratchpad. Args: key: The working memory key to promote title: Optional title for the long-term entry tags: Optional tags file: Target file for the entry

Store a value in working memory (scratchpad). Working memory is for temporary data during a task. Entries can have a TTL or be bound to the current session for auto-cleanup. Args: key: Unique key for this entry value: The value to store ttl_minutes: Auto-expire after this many minutes (omit for manual cleanup)

Search across indexed memory files using hybrid BM25 + semantic search. Args: query: Natural language search query top_k: Number of results to return (default 10) source_filter: Source path filter — substring, or glob with *, ?, [] tag_filter: Comma-separated tags; matches chunks carrying ANY of them namespace: Namespace scope — value, comma list (``work,personal``) or glob (``proj:*``), not both. Omitted, system namespaces are hidden; naming one includes it. as_of: Temporal bound for retroactive search — ``YYYY-MM-DD`` or ``YYYY-QN``, default n…

Record or list relevance judgments for one observed search run. With ``judgment`` (requires ``chunk_id``): record "relevant" or "not_relevant" for that snapshotted result. Resubmitting the same judgment is a no-op; a different judgment needs ``replace=True``. Without ``judgment``: list the run's current judgments. Args: run_id: The query_run_id returned by a ranked search. chunk_id: Chunk from that run's result snapshot to judge. judgment: One of "relevant" / "not_relevant"; omit to read. replace: Allow overwriting a different existing judgment.

List past search queries with result counts. Args: limit: Maximum number of queries to return (default 20). since: ISO date filter — only queries after this date.

Autocomplete search queries from history. Args: prefix: The query prefix to match. limit: Maximum suggestions (default 5).

End the current episodic memory session. Closes the session, saves an optional summary, and records event statistics. Working memory bound to this session is cleaned up. Resets both ``current_session_id`` and ``current_agent_id`` so the next ``mem_agent_search`` falls back to ``current_namespace``. The session is *claimed* atomically under ``_session_lock`` at entry by recording its id in ``_ending_session_ids``, so a concurrent or client-retried ``mem_session_end`` returns ``"No active session."`` instead of re-running the effectful phase — the summarize/persist work runs **at most once** p…

List recent episodic memory sessions. Args: agent_id: Filter by agent (omit for all agents) since: Only sessions started after this date (YYYY-MM-DD or ISO) limit: Maximum sessions to return (default 10)

Start a new episodic memory session. Creates a session record and sets it as the current session. All subsequent tool calls will be tracked as session events. A **named** ``agent_id`` is recorded on ``AppContext.current_agent_id`` so that multi-agent tools (``mem_agent_search`` and friends) can resolve the active agent without the caller passing it on every call. Omitting ``agent_id`` — or passing the reserved ``"default"`` — starts an *unbound* session: no agent is bound, so ``mem_add`` / ``mem_batch_add`` / ``mem_index`` route exactly as they would with no session at all (``app.current_nam…

Return current memory index statistics: total chunks, sources, and storage backend. Use this to quickly assess how many memories are indexed before searching.

Show indexing statistics and current configuration summary. Reports storage backend, embedding info, chunk/source counts, and warns about orphaned source files (indexed but gone from disk — run mem_cleanup_orphans). Configuration drift adds a ``Warnings`` block. Each entry has ``kind`` (an open enum — tolerate unrecognised values rather than erroring), ``fix`` and an optional ``doc`` link. Some kinds add their own keys: embedding mismatches carry ``stored``/``configured``; ``concurrent_server_writers`` may carry ``same_parent``. These keys are stable across versions, so probes can pattern-ma…

Remove a tag from all visible chunks that use it. The chunks themselves are not deleted — only the tag is removed. Args: tag: The tag name to remove dry_run: If True, return the count + a sample of affected chunks without writing. Defaults to True (preview); pass dry_run=False to perform the removal.

List visible tags and their usage counts, ordered by frequency. Use this to see which tags exist in the index and how many chunks use each tag.

Fold multiple source tags into a single target tag across all visible chunks. Each chunk that carries any source tag gets the source replaced with ``target``; the resulting per-chunk tag list is deduplicated. Chunks that already only carry ``target`` are not affected. Args: sources: List of source tags to fold into ``target``. target: The tag every source should be rewritten to. dry_run: If True, return the candidate count + a sample without writing. Defaults to True (preview); pass dry_run=False to perform the merge.

Rename a tag across all visible chunks that use it. Args: old_tag: The current tag name to replace new_tag: The new tag name dry_run: If True, return the count + a sample of affected chunks without writing. Defaults to True (preview); pass dry_run=False to perform the rename.

Show how memories about a topic evolved over time. Groups matching memories into time periods (weeks or months) and shows the progression of knowledge on that topic. Args: topic: Subject to track through time since: Start date (YYYY, YYYY-MM, YYYY-MM-DD) until: End date namespace: Namespace scope limit: Maximum chunks to analyze (default 50) scope: ADR-0011 tier filter — value, comma list (``user,project_local``) or glob (``project_*``), not both. Omitted, the default merge applies: inside a project ``user`` + that project's tiers, outside one …

Remove a link between two chunks. Both ends must be inside the caller's project boundary (ADR-0011); an id from another project reads as not-found (ADR-0036). Args: source_id: UUID of the first chunk target_id: UUID of the second chunk

Health watchdog: view status, trends, or force a check run. Args: command: "status" (default), "history", "run" check: Filter by check name (for history command) hours: Hours of history to return (default 24)