Vault Agent Memory
Website · · · · ·
接入你的智能体
從發布者安裝。不是 PlugMCP 端點。
遠端 URL 還是本機指令? 兩種安裝方式的差異
Vault is a local-first, backend-agnostic memory governance layer for AI agents.
Vault Agent Memory gives Codex, Claude Code, Hermes, OpenClaw, n8n, Coze, and other agents one governed memory vault to share. It is not trying to be another notes app or vector database. It helps agents decide what should be remembered, who can use it, whether it is still current, and how to roll it back when it is wrong.
Vault's product boundary is the governance contract, not a specific backend. The same candidate-first review model can run on local SQLite, a self-hosted central memory host, a Supabase cloud adapter, or a future managed Vault Cloud backend.
Vault works standalone, and it can also become the governed memory backend for other agent memory frameworks. You can use Vault by itself with CLI, MCP, Gateway, and local SQLite; or let frameworks such as Hermes, OpenClaw, Letta, mem0, Claude Code, and Codex connect through Vault APIs while Vault keeps the review, audit, lifecycle, and backend boundaries consistent.
The core multi-agent model is single-host sharing, multi-host governed sync: agents on one trusted machine can share the same local Vault, while agents on other machines or hosted runtimes can read approved memory and submit candidates. Only a trusted sync host promotes official memory, runs lifecycle jobs, and pushes reviewed read copies back out.
The Python package and existing install path remain vault-for-llm.
Vault is for people already building or working with agents. The main interface should still not be a long CLI manual: ask an agent to install Vault, answer a few setup questions, then read a short daily memory report.
New here? Start with the public website. It explains why Vault is a memory foundation—not merely another memory system—and publishes paired A vs A + Vault evidence with the full method and raw artifacts.
Vault Agent Memory v0.10.2 is a Public Beta / Developer Preview release. The local-first path is ready for agent developers to try in real projects, and the multi-agent model is intentionally conservative:
The package is pre-1.0. Advanced Supabase, Gateway, central vector, automation, and benchmark surfaces are useful for developer preview deployments, but should be enabled deliberately and monitored with the generated reports.
Deployment is intentionally layered:
Agents / Apps / Memory Frameworks
-> Vault Memory API plus MCP / Gateway / OpenAPI adapters
-> Vault Gateway / Vault Governance Contract
-> Memory Provider Interface / Backend adapter
-> Local SQLite / Self-host central host / Supabase / future Vault Cloud
Vault Agent Memory exists because agent memory fails in practical ways:
flowchart TB
subgraph Agents["🤖 Your Agents"]
C[Codex]
CL[Claude Code]
H[Hermes]
CO[Coze]
N[n8n]
end
subgraph Vault["🔐 Vault — Governed Memory Layer"]
direction TB
Pipeline["Review Pipeline<br/>Privacy · Duplicates · Quality · Source"]
Report["Daily Report<br/>Auto-promote low-risk · Review high-risk"]
subgraph Layers["Memory Layers"]
L0["L0 Bootstrap"]
L1["L1 Rules"]
L2["L2 Context"]
L3["L3 Knowledge"]
end
Ledger["Task Ledger<br/>Live workbench · Handoffs"]
Storage["SQLite / Markdown<br/>Local-first · Zero dependencies"]
end
subgraph Adapters["🔌 Adapters / Backends"]
Obs[Obsidian Sync]
Sup[Supabase]
GW[Gateway API]
SH[Self-host Host]
VC[Vault Cloud Future]
end
Agents -->|propose| Pipeline
Agents -->|search / bounded read| Layers
Agents -->|update status| Ledger
Pipeline --> Report
Report --> Layers
Layers <--> Ledger
Layers --> Storage
Adapters <-->|import / export / sync / managed backend| Vault
style Agents fill:#e1f5fe,stroke:#0288d1
style Vault fill:#f3e5f5,stroke:#7b1fa2
style Adapters fill:#e8f5e9,stroke:#388e3c
The core workflow is:
propose -> review -> promote -> search -> bounded read -> rollback -> audit
In plain language:
Vault is not about helping agents remember everything. It is about helping teams govern what agents remember, trust, share, forget, and roll back.
Copy this prompt into an agent that can run local commands:
Install Vault Agent Memory for this project. Use vault-for-llm[mcp]==0.10.2.
Use the agent-assisted governed-auto memory mode.
Do not show advanced CLI flags first. Ask me only four questions:
1. Which language should Vault use: Traditional Chinese, Simplified Chinese, or English?
2. Should this be an independent vault or a shared vault for multiple agents?
3. Should Vault connect to Obsidian, Supabase, both, or neither?
4. What time should the daily memory report run?
After setup, run a smoke check and tell me:
- where the vault lives
- how I read the daily memory report
- where the local GUI or next action is
Daily rule:
safe, low-risk, sourced memories can be kept automatically;
uncertain, sensitive, conflicting, or strategic memories should go into the
daily report for my review.
The agent will usually run:
python3 -m venv .venv
source .venv/bin/activate
pip install "vault-for-llm[mcp]==0.10.2"
vault quickstart
You can also print the install prompt from Vault itself:
vault guide --intent install
To check for a newer release without changing the environment:
vault upgrade --check
Vault detects common pip, pipx, uv tool, and editable installs and prints the
appropriate upgrade command. This first-stage command is check-only: it does
not install packages or migrate vault.db.
vault quickstart is the small first-run wizard. It asks only for language,
independent/shared memory, optional Obsidian/Supabase connections, and daily
report time. See docs/quickstart.md for the 5-minute
walkthrough and FAQ. Advanced integration flags stay under vault setup-agent.
Agent-assisted quickstart uses governed-auto by default. Internally this is
still the consumer setup path, but that does not mean Vault is a zero-learning
consumer app. Low-risk, sourced candidates that pass privacy, duplicate,
metadata, and quality gates may enter the active vault. Strategy, private,
sensitive, conflicting, or low-trust memories stay in the daily report for
human review. Nothing is hard-deleted automatically.
The intended human surface is small:
The report should answer:
That is the product shape: more automatic over time, but still governed.
Vault is not an Obsidian replacement.
Obsidian is great for humans reading notes. Vault helps agents use those notes safely, with source ranges and review boundaries.
Vault is not just RAG.
RAG usually focuses on retrieving context. Vault focuses on the memory lifecycle: who wrote it, whether it was reviewed, which agents can read it, when it stops being current, and how to roll it back.
Vault is not a raw chat-history landfill.
It is candidate-first. Agents can suggest memory, but long-term memory should stay source-backed, reviewable, and clean.
Vault is not a zero-setup app-store product for people who do not use agents.
The first public audience is agent-assisted builders: people using Codex, Claude Code, Hermes, OpenClaw, n8n, Coze, or similar systems who want one governed memory layer without studying every internal command.
Vault is complementary to memory services and agent runtimes, not a drop-in replacement for all of them.
If you need a managed memory API for an app, Mem0 may be the faster starting point. If you want a single stateful agent that owns its memory and grows over time, Letta may be the better fit. If you already use several agents and want a local, reviewable, auditable memory foundation between them, Vault is designed for that layer.
That difference matters most across machines: Vault treats remote agents as approved-memory readers and candidate submitters, not as direct writers to the official shared memory.
Vault does not currently claim a LoCoMo/LongMemEval-style leaderboard score. Those benchmarks measure end-to-end memory QA and should only be published for Vault after running the same benchmark harness under comparable conditions. Vault now has a neutral external-memory comparison harness for retrieval-only runs across Vault, mem0, Letta, and compatible run artifacts; treat current numbers as source-hit evidence recall unless a fixed reader and judge are explicitly included.
What Vault does publish today is reproducible verification for its own product contract:
A versus engine-plus-Vault A+B Valid Recall,
forbidden-exposure, latency, and cost deltas, plus a fixed-clock dynamic
governance suite. Synthetic contract evidence is labelled separately from
full provider-product claims. A retrieval-only VaultGovBench bundle with five
distinct clean-state repeats per track for Vault keyword retrieval and mem0
2.0.12 controlled raw insertion is published under
benchmarks/results/vaultgovbench-retrieval-v0.1/89b9156.See Search QA benchmarking and External memory benchmarks for the current retrieval-only evidence model. The README claim matrix tracks which public claims are positioning, product-contract checks, or implemented runtime capabilities.
Run the local demo:
vault demo agent-governance --json
It simulates Codex, Claude Code, and Hermes sharing one governed vault:
The generated demo pack also includes three follow-up guides:
consumer-mode-demo.md, automation-mode-demo.md, and
multi-host-sync-demo.md.
Start here:
🎬 A 3-minute walkthrough GIF is coming soon.
In the meantime, here's what it will show:
- Install —
pip install vault-for-llm[mcp]andvault quickstart- Configure — Answer 4 simple questions (language, vault type, integrations, report time)
- Propose — An agent suggests a memory with
vault_memory_propose- Review — The daily report surfaces candidates for human approval
- Promote & Search — Approved memory shows up in
vault_searchwith bounded readsPrefer a text walkthrough? → 5-Minute Quickstart
curl -sSL https://raw.githubusercontent.com/zycaskevin/Vault-Agent-Memory/main/scripts/install.sh | bash
irm https://raw.githubusercontent.com/zycaskevin/Vault-Agent-Memory/main/scripts/install.ps1 | iex
After the installer finishes, run vault quickstart to complete setup.
These raw GitHub URLs are available from main and install the pinned release
version used by this README. If you prefer release-tagged documentation, use
the next release that includes these installer scripts.
Source: scripts/install.sh · scripts/install.ps1
pip install "vault-for-llm[mcp]==0.10.2"
vault init ~/Vaults/demo
vault add "First lesson" \
--content "The bug was caused by a missing cache key. The fix was adding provider metadata." \
--project-dir ~/Vaults/demo
vault compile --project-dir ~/Vaults/demo --no-embed
vault search "cache key" --project-dir ~/Vaults/demo
vault --project-dir ~/Vaults/demo map build
vault --project-dir ~/Vaults/demo map read 1 --lines 1-20
vault --project-dir ~/Vaults/demo gui
vault add takes content through --content or --file. For bounded source
reads, use vault map read <knowledge_id> --lines START-END.
For MCP-capable runtimes:
vault-mcp --project-dir ~/Vaults/demo --tool-profile core
Start most agents with core:
vault_searchvault_read_rangevault_memory_proposevault_statsvault_update_statusvault_automation_handoffUse larger MCP profiles only when needed:
Detailed MCP docs:
Vault uses L0-L3 for memory depth:
New projects create L0-bootstrap. Existing L0-identity paths remain
read-compatible and are never renamed automatically. L0 is startup/project
context, not a Vault-owned identity or human model.
Task Ledger is not L2. It is the live workbench for blockers, next actions, evidence links, due dates, and handoff notes. Only durable lessons, decisions, and summaries should be promoted into L2/L3 after review.
Access is not controlled by layer alone. Use governance metadata:
scope: private, project, shared, publicsensitivity: low, medium, high, restrictedowner_agentallowed_agentsmemory_typeexpires_atvalid_from / valid_untilsupersedes_idTemporal fact windows are separate from expiry. expires_at means "move this
out of normal recall later." valid_until means "this fact stopped being true,
but keep it for history and audit."
vault memory temporal status
vault memory temporal list --state past
vault search "office location" --exclude-expired
More detail: docs/memory_governance.md.
Automation is report-first by default. It can rank candidates, summarize stale memory, suggest consolidation, and prepare a short review queue without silently rewriting long-term memory.
vault daily-report --language en
vault automation brief --pretty
vault automation review-summary --write-summary
vault automation handoff
Enable stronger automation deliberately:
vault setup-agent \
--automation-schedule cron \
--automation-apply \
--automation-auto-promote-low-risk
That path can promote only low-risk, sourced candidates that pass the normal gates, with a per-run cap. Private, high-sensitivity, duplicate, weak, or sourceless candidates stay in review.
Automation docs:
Start here:
Import an existing Obsidian vault:
vault import obsidian --vault ~/Documents/ObsidianVault --project-dir ~/Vaults/my-project --dry-run
vault import obsidian --vault ~/Documents/ObsidianVault --project-dir ~/Vaults/my-project --compile
Export reviewed Vault knowledge back into Obsidian-readable notes:
vault export obsidian --project-dir ~/Vaults/my-project --vault ~/Documents/ObsidianVault --dry-run --json
vault export obsidian --project-dir ~/Vaults/my-project --vault ~/Documents/ObsidianVault
The conflict inbox uses explicit resolver choices: accept Obsidian, accept Vault, or keep both.
Local SQLite remains the simplest source of truth, but Vault does not require one backend forever. Choose the deployment mode that fits the trust boundary:
The governance rules do not change between modes: remote writes enter as candidates, approved memory is the read surface, and a trusted reviewer or policy gate promotes durable memory.
Supabase is an optional cloud adapter. It is useful when hosted agents or other machines need a filtered read copy and candidate inbox without operating a central host:
pip install "vault-for-llm[supabase]==0.10.2"
vault remote status --project-dir ~/Vaults/my-project
python -m scripts.sync_to_supabase --db ~/Vaults/my-project/vault.db --document-map --health
Gateway / Remote Server is the self-host path, also called the Trusted Local Central Memory Host pattern. Use it when many agents can reach one trusted central memory host:
# Set VAULT_GATEWAY_TOKEN from your shell or secret manager before serving.
vault remote-server health --project-dir ~/Vaults/my-project --json
vault remote-server openapi --project-dir ~/Vaults/my-project --json
vault remote-server serve --project-dir ~/Vaults/my-project --host 0.0.0.0
Remote contributions should enter as review candidates. This is centralized sharing, not offline multi-master sync. Vault Cloud is the future managed backend for the same Vault Governance Contract; it should not change the memory semantics that local, self-hosted, and Supabase deployments use.
The trust model is:
For multi-agent or multi-device memory, use the Central Memory Station surface:
vault start
vault daily-loop run --write-report --json
vault daily-loop report --refresh --write-report --json
vault memory-sync run-once --push-read-copy --push-central-store --pull-candidates --dry-run --json
vault memory-sync run-once --central-backend self-host --pull-candidates --dry-run --json
vault memory-sync migrate-candidates --direction self-host-to-supabase --json
vault memory-sync export-snapshots --bundle ./vault-snapshots.json --json
vault memory-sync verify-snapshots --bundle ./vault-snapshots.json --json
vault memory-sync import-snapshots --bundle ./vault-snapshots.json --json
vault memory-review inbox --json
vault memory-lifecycle status --json
vault ops security --json
vault daily-loop run is the daily orchestrator: it refreshes sync freshness,
automation cycle handoff, inbox, review cards, learning health, and the human
daily report in one report-first pass. Use
vault daily-loop report --refresh --write-report when you only need to rebuild
the latest daily-loop report from read-only status surfaces without capture or
new candidate writes. The detailed remote, sync, dream, usage, and
automation commands stay available as advanced tools. The central surface is
the smaller operator entry for Supabase or self-hosted deployments.
Docs:
Import memory from other tools as candidates, not as trusted active memory:
vault import memory --source ~/Downloads/chatbox-export.json --format auto --dry-run
vault import memory --source ~/Downloads/chatbox-export.json --write-candidates --only summaries,decisions,preferences
Imported items pass the same privacy, duplicate, metadata, and quality gates.
For backend moves or a self-host bootstrap, reviewed snapshot bundles can move approved memory evidence without direct active-memory writes:
vault memory-sync export-snapshots --bundle ./vault-snapshots.json --json
vault memory-sync export-snapshots --bundle ./vault-snapshots.json --include-content --json
vault memory-sync verify-snapshots --bundle ./vault-snapshots.json --require-content --json
vault memory-sync import-snapshots --bundle ./vault-snapshots.json --apply --json
By default snapshot bundles exclude raw memory content. --include-content
should be used only over a trusted, encrypted transfer path. The verify command
checks the bundle manifest, snapshot digest, content hashes, and missing-content
state without writing memory. Import still writes local memory_candidates for
review; it does not write active knowledge or promote memory.
Vault includes Search QA so retrieval can be measured instead of trusted by intuition alone.
vault search-qa run \
--qa-file benchmarks/search_qa/basic.en.json \
--mode keyword \
--output /tmp/vault-searchqa.json
Current public claims should be read as retrieval evidence, not final answer quality:
More detail:
Vault Agent Memory is pre-1.0. The core local path is intentionally conservative. Advanced remote and automation paths are powerful, but should be enabled deliberately.
Known limitations for the Public Beta / Developer Preview:
Common Python path:
git clone https://github.com/zycaskevin/Vault-Agent-Memory.git
cd Vault-Agent-Memory
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,mcp]"
pytest -q
Reproducible Agent/developer environment:
git clone https://github.com/zycaskevin/Vault-Agent-Memory.git
cd Vault-Agent-Memory
uv sync --extra dev --extra mcp
uv run pytest -q
pip install vault-for-llm remains the public user install path. The uv workflow
is for source development, CI smoke checks, and agents that need to rebuild the
same local environment reliably.
Vault is ready for small, bounded contributions from Agent-assisted builders. Start with CONTRIBUTING.md, the good first issue ideas, and the Code of Conduct. Please do not include real secrets, private chats, customer records, medical data, or production vault exports in public issues or pull requests.
Apache-2.0. See LICENSE.
Local-first memory governance for AI agents: shared, reviewable, auditable memory via SQLite and MCP.
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Vault Agent Memory 透過 stdio 在本機執行。
上次檢查時間:2026-10-28。 Local-first memory governance for AI agents: shared, reviewable, auditable memory via SQLite and MCP.