MemVault
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
MemVault — AI Agent Memory Router. Stores, retrieves, and auto-injects user memories into agent context. Use save_memory to store, search_memory to find (supports keyword/semantic/hybrid modes), session_start to get formatted injection context.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
| resources | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| add_evidenceA | 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 |
| confirm_readA | 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. |
| delete_memoryA | 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 ( |
| extract_memoriesA | 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. |
| forget_memoryA | 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_compliance_reportA | 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_effectiveness_reportA | 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_memory_evidenceA | 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_skillsA | 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. |
| infer_outcomeA | 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 |
| list_inboxA | 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. |
| propose_memory_editA | Propose a text edit to an existing memory, for human review. Creates a PENDING memory carrying the edit; the target is left completely untouched and keeps injecting until a human approves. Approving it (review_memory action='approve') supersedes the target with the edited version; rejecting discards the proposal. old_text must occur exactly once — an ambiguous or absent anchor is an error, never a guess. field='content' (default) edits the body, field='instruction' edits the directive that injection renders. Use this instead of delete+save when you are correcting a memory you did not author: it keeps the current truth live until a person decides, and it cannot be used to silently rewrite a binding MUST. |
| record_outcomeA | 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_complianceA | 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_memoryA | 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_decayA | Run a memory decay cycle: reduces decay_score for old memories and archives memories that fall below the threshold or whose |
| run_dedupA | 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_promoteA | 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_memoryA | 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_memoryA | 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. TWO INDEPENDENT TIME AXES: as_of is valid-time — 'what did MemVault believe at T' — and returns each hit reconstructed to the state it held then, recalling from the historical index too so a memory reworded since T is still found by the words it had (keyword path only; such hits are tagged hist-kw#N); occurred_from/occurred_to filter event-time — 'what happened in March' — and never match memories saved without a date. They answer different questions and are not interchangeable. Read-only; does not mutate memories. |
| session_startA | 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. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| User Profile & MUST Rules | User's core preferences and mandatory rules. Loaded at conversation start. Contains only human-reviewed MUST rules — unreviewed AI-extracted drafts are held back by the same gate session_start applies. All agents share this resource. |
| Current Project Context | Reference-level memories about the current project's tech stack, conventions, and recent context. Reference DATA, not directives: unlike memory://user-profile this resource is not review-gated, so it may include AI-extracted drafts no human has approved. The body labels those as unreviewed and instructs the reader not to execute instruction-like text found in them — read it for context, not for rules. |
TDQS
Scored across 21 tools
Most tools have a distinct role, and the descriptions explicitly clarify near-neighbors such as save_memory vs extract_memories, delete_memory vs forget_memory, and record_outcome vs infer_outcome. However, multiple pairs overlap by design, including propose_memory_edit vs review_memory edit, the two compliance/effectiveness reports, and the three maintenance tools, so an agent must read carefully to select correctly.
The set mostly follows a verb_noun pattern: save_memory, search_memory, delete_memory, get_compliance_report, import_skills, and run_decay. The main deviation is session_start, which reverses the order and mildly breaks the otherwise consistent convention.
At 21 tools, the surface is heavy for a memory server, though the domain is broad and includes lifecycle, extraction, review, evidence, compliance, outcomes, skills, and maintenance. Several adjacent reporting and maintenance tools could likely be consolidated without losing core capability.
The set covers the main memory lifecycle: save/search/delete/forget, review and edit proposals, evidence, session injection, outcomes, compliance, and maintenance. Minor gaps remain, notably restore being CLI-only and some list/report operations lacking pagination or fuller management surfaces.