Record evidence for a memory. relation="supports"/"contradicts" links evidence_id → memory_id (a memory supporting or contradicting it); relation="sourced_from" records memory_id's external provenance via source (URL/document). Writes one relation and returns its relation_id; an identical relation is rejected rather than duplicated. Contradictions accelerate the contradicted memory's decay; superseded or archived evidence stops counting. Requires agent auth when the agent has a registered key.

Confirm that one or more memories have been read by the agent. Increments access_count and sets last_read_at for the specified memory IDs; unknown IDs are skipped and the response reports how many rows were confirmed. Repeated calls increment the counters again (not idempotent). Requires agent auth when the agent has a registered key.

Soft-delete one memory by its ID: removes its live row, FTS entry, and cascaded evidence relations so it is no longer searchable or injected. A full snapshot is written to memory_history first; restore is available through the CLI (memvault restore), not through this MCP tool. Use forget_memory for an irreversible GDPR-style purge. Requires agent auth when the agent has a registered key; a second delete of the same ID returns NotFound.

Extract structured memories from conversation text. mode="rule" (default) detects preferences, facts, and skills via keyword pattern matching. mode="llm" instead understands the full context (optionally pairing assistant_text) semantically — uses the configured LLM extraction provider, and degrades to rule-based extraction (reported via fallback_used/fallback_reason) when no provider is configured or the LLM call fails. Returns extracted items; with auto_save=true it also writes them and requires agent auth when the agent has a registered key. Invalid occurred_at is an error, never a silent drop.

Permanently erase (GDPR-style) one memory by id or a bulk set matched by criteria (namespace/namespace_prefix/source_agent_id/tag/memory_type/before_days). Unlike delete_memory, this also purges memory_history snapshots and any orphaned compliance rows, leaving only a content-hash audit entry in the forgotten-log — irreversible. dry_run defaults to true: call once to preview, then again with dry_run=false to execute. Priority::Must memories are excluded unless allow_must=true. Gated by the same per-agent API-key auth as delete_memory — there is no separate admin tier at the MCP layer.

Get a compliance report for injection sessions. Shows follow/violation rates for MUST memories. Provide inject_session_id for one session, or omit it for an aggregate summary filtered by optional agent_id and limit (default 10). Read-only; returns JSON and does not change compliance records.

Get automatic effectiveness judgments for injected memories: useful/neutral/harmful/insufficient_context rates, judged automatically from record_outcome — independent of manual report_compliance. Optional agent_id filters the summary and limit defaults to 10. Read-only; returns JSON and does not change records.

Get the raw-evidence chain a memory was distilled from (its L0 trace rows), plus its evidence profile. Read-only grounding: lets an agent quote the original session text and name its sources. Missing or pruned evidence yields an empty chain rather than a write; requires agent auth when the agent has a registered key.

Import skills from a Markdown SOP document. Each #/## heading becomes a skill (trigger:/verification: metadata lines + list-item steps). Sections without steps are skipped. Imported skills enter the review inbox unless approve=true. Writes new skill memories; repeating the same import can create duplicates. Requires agent auth when the agent has a registered key.

Classify and record a task outcome from host-provided evidence rather than raw transcript text — for hosts whose event model doesn't produce a Claude-Code-shaped JSONL transcript (e.g. dsh/Cordis session events). Pass pre-computed friction counts and terminal state in evidence; this runs the same rule-floor-plus-optional-LLM-judge classification as the Claude Code Stop hook's outcome --infer, then records exactly like record_outcome. Returns status 'skipped' (not an error) when nothing was inferred — a clean session, below the friction threshold, or no task evidence at all. Repeated calls for the same session/evidence are deduped. Requires agent auth when the agent has a registered key.

List memories pending human review, sorted by created_at ascending (oldest first). Read-only. Supports an optional namespace and limit (default 20); there is no offset/pagination, so a full page silently truncates older pending memories. Requires agent auth when the agent has a registered key.

Record the outcome of a task you just executed (episodic memory). Call this after finishing a task so past successes and failures can inform future sessions. Status must be 'success', 'failure', or 'partial'. Failures with a cause are reflected into lessons that get injected into similar future tasks. Repeated calls for the same session/outcome are deduped rather than creating a second episode. Requires agent auth when the agent has a registered key.

Report compliance for a previous injection session returned by session_start. Call this to mark which injected memories were followed or violated, with optional evidence. Reports are processed item by item: a bad item is logged and skipped while the call still succeeds, so the response's updated/total counts must be checked rather than assuming all reports were stored. Requires a compliance-enabled server; no agent API key is required by this tool.

Review or edit a memory. action='approve' marks it human-reviewed; action='edit' updates content/instruction and re-embeds or clears the stale vector (this also works on already-approved memories); action='reject' soft-deletes a pending memory and is rejected for already-approved memories (use delete_memory instead). Approved memories rank higher in future injections. Writes immediately; requires agent auth when the agent has a registered key.

Run a memory decay cycle: reduces decay_score for old memories and archives memories that fall below the threshold. MUST memories are exempt from decay. This is not purely reversible: if MEMVAULT_FORGET_AUTO_ENABLED=1, the same run also permanently forgets archived memories older than MEMVAULT_FORGET_RETENTION_DAYS (default 90); otherwise auto-forget is off. Requires agent auth when the agent has a registered key. Returns updated/archived/contradicted/harmful_flagged/auto_forgotten counts.

Scan for duplicate memories and report findings. Uses lexical text similarity (Jaccard) to detect near-duplicates in one namespace or all namespaces. Read-only: reports existing_id/new_content/similarity/action but does not merge or delete anything. Returns at most 20 duplicate findings.

Run the promote pipeline: consolidates atomic L1 memories into L2 scenario summaries, and promotes stable L2 memories into L3 core persona rules. Source memories are archived to L0 after promotion (not deleted). Mutates the store, is not idempotent, and requires agent auth when the agent has a registered key. Returns promoted/consolidated/merged/source counts.

Save a new memory. Memories are persistent user preferences, facts, episodes, or skills that should be recalled in future conversations. Embeddings are generated automatically for semantic search. Delta-write is on by default: near-duplicate saves are skipped and similar existing memories absorb the new content instead of a new row being created (status in the response: saved | merged | skipped). Pass force_insert=true to bypass. Writes persist immediately; requires agent auth when the agent has a registered key.

Search stored memories. mode defaults to 'hybrid' (keyword + vector via RRF); 'keyword' is text-only and 'semantic' is vector-only. Semantic/hybrid need an embedding provider — when embeddings are unavailable the query falls back to keyword and each result reports search_mode='keyword'. Supports namespace, type_filter, priority_filter, top_k (default 10), min_score, and optional expand_relations for one-hop relation context. Read-only; does not mutate memories.

Start an agent session. Returns relevant memories filtered by agent identity, formatted as MUST/REF instructions ready for injection into the conversation context; overflow memories are summarized with a hint to use search_memory for details. If this agent's canonical inject channel is not MCP, returns a skip explanation instead of injecting. When compliance tracking is enabled, records the injected memories and returns inject_session_id in structured_content for a later report_compliance call. Not read-only; requires agent auth when the agent has a registered key.