MemVault - Local-First Agent Memory

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 through delta-write (near-identical memories are merged or skipped, not duplicated) and requires agent auth when the agent has a registered key. Use save_memory instead when you already know the exact memory to store. 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: with inject_session_id, followed/violated/pending counts plus compliance_rate for that session; without it, an aggregate summary (total_sessions, overall_rate, must_rate, recent_sessions) filtered by optional agent_id and limit (default 10). compliance_rate/overall_rate/must_rate are null when no real MUST verdict exists yet (all pending/unknown); null never means 100%. Use report_compliance to record follow/violation status — this tool only reads it.

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. Use add_evidence to write a new relation or source — this tool only reads the existing chain. 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. Use infer_outcome instead when the host supplies structured evidence rather than a transcript; use add_evidence to attach provenance to an existing memory. Returns status (recorded | duplicate), the episode id, and any distilled lesson. 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. Requires L1 memories to exist; run run_dedup first so near-duplicates don't become separate scenarios. Source memories are archived to L0 after promotion (not deleted). A maintenance step, not a substitute for run_decay. 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.