io.github.memtomem/memtomem

Add a new memory entry to a markdown file and immediately index it. The entry is appended to the target file (or a new timestamped file is created in the first configured memory directory), then re-indexed so it is immediately searchable. All content is scanned for secrets before any filesystem write; a match rejects the write. See ``force_unsafe`` below for the one escape hatch and ``mem_add_redaction_stats`` for the outcome counters. Args: content: The memory content to store title: Optional heading title for the entry tags: Optional tags for categorisation file: Target .md filename (relative or absolute). If omitted, a timestamped file is created in the first memory_dir. namespace: Assign indexed chunks to this namespace (default: config default) template: Use a built-in template (adr, meeting, debug, decision, procedure). Content can be JSON with field values or plain text. force_unsafe: When True, bypass the redaction guard for this call even when content matches a secret pattern. Use only when matches are known false positives (e.g., documenting an example credential schema). The bypass is recorded with a ``bypassed`` outcome and an audit line, and it never applies to ``scope="project_shared"`` — that combination is hard-refused, because git history cannot be retracted from clones. scope: Write tier: ``user`` (default), ``project_local``, or ``project_shared``. confirm_project_shared: Required explicit consent for a Git-tracked ``project_shared`` write. idempotency_key: Optional key (max 256 chars) making this write idempotent for 24h — a retry with the same key returns the original result and writes nothing. Only successful writes are recorded, so a f…

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

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

List all indexed source files with chunk counts and metadata. Args: source_filter: Filter by source file path (substring match, or glob pattern with *, ?, []) namespace: Only list sources containing chunks in this namespace Examples: mem_list() — all indexed files mem_list(source_filter="*.md") — markdown files (glob) mem_list(source_filter="docs/") — files with "docs/" in path (substring) mem_list(namespace="work") — files in the "work" namespace

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 — "compact" (default, human-readable) or "structured" (JSON for machine parsing, includes trust-UX hints as a "hints" field). scope: ADR-0011 scope-axis filter — single, comma list (``user,project_local``), or glob (``project_*``), not both. Omitted, the default merge applies: in-project recalls return ``user`` + that project's tiers, out-of-project ``user`` only. Examples:: mem_recall(since="2025-01", until="2025-03") mem_recall(since="2025-06-01", source_filter="notes") mem_recall(namespace="work", limit=10)

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 now. Chunks whose ``valid_from`` / ``valid_to`` frontmatter excludes that point drop out; chunks without those keys are always valid. Time decay anchors here, not to the wall clock. bm25_weight: RRF weight for keyword matches (default 1.0; raise to favor) dense_weight: RRF weight for meaning matches (default 1.0). Both must be finite and >= 0, not both zero; 0 disables that leg context_window: Expand each result with ±N adjacent chunks (0 = off). Neighbours follow the namespace/scope/validity visibility rules, not the tag/type/date filters verbose: Deprecated — use output_format="verbose" output_format: "compact" (default), "verbose" (adds UUID / pipeline stats), or "structured" (JSON). A non-default value overrides ``verbose``. 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 ``user`` only. Pass ``project_shared`` from outside a project to search across projects. rerank: ``false`` skips the cross-encoder stage and collapses the pool to ``top_k`` — the fast path for latency-bounded callers, so it narrows recall as well as changing the score scale. Omitted/``true`` follows server config;…

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-match on them.