vault-go

MCP server and installer for Vault Memory — search, capture, and use account memory across AI clients.

Memories live in your Vault Memory cloud account. This package installs the local MCP server, signs you in, registers clients, and runs an optional local worker that turns captured events into memories.

npm install -g vault-go@latest
vault-go setup

Or without a global install:

bunx --bun vault-go@latest

Requires Bun (bun --version) and Node.js 20+.

Sign in

vault-go setup and vault-go login open the Vault Memory sign-in page in your browser. Email, password, and MFA stay in the portal. The CLI receives a one-time code on 127.0.0.1 and exchanges it with PKCE. Tokens never appear in the URL or terminal. The listener closes when login finishes or after five minutes.

vault-go login --force              # switch account
vault-go login --force --api-key    # paste a scoped API key instead

If the browser does not open, use the loopback URL printed in the same session.

Credentials are stored in ~/.memvault/auth.json (0600). The directory is 0700. Passwords and MFA codes are not saved.

Install MCP

Install private skills directly

After vault-go login, install private skill packages from the authenticated Vault account with one command:

vault-go skills list
vault-go skills install --skill my-skill
vault-go skills install --all

Installation defaults to ~/.agents/skills, shared by Codex and other compatible agents. Use --target claude or --target grok for those clients' own skill directories. The command downloads the real package through your Vault account and verifies its integrity. With --all, existing skills that Vault did not install are preserved and reported as skipped; selecting one of them explicitly returns a conflict. The person with access to the target machine can read the installed files.

Full local server (capture + write)

The setup wizard:

1. Reuses an existing session in ~/.memvault, or opens Vault Memory sign-in.
2. Detects installed clients and registers the MCP server.
3. Leaves other client config in place.
4. Installs the local dashboard on port 38850 (starts at login on macOS).

Supported clients: Codex, ChatGPT Desktop, Claude Code, Claude Desktop, Grok, Agy / Antigravity, Gemini CLI, Cursor, Windsurf, VS Code + GitHub Copilot, Copilot CLI, Roo Code, OpenCode, and Vault Desktop (Crystal).

vault-go setup
vault-go setup --clients codex,claude,copilot
vault-go setup --engine openrouter
vault-go setup --engine claude --model sonnet
vault-go serve

Generic MCP config:

{
  "mcpServers": {
    "vault-go": {
      "command": "bunx",
      "args": ["--bun", "vault-go@latest", "serve"]
    }
  }
}

Override the home directory with VAULT_GO_HOME. Restart clients that were already open after the first install.

Read-only remote MCP

For search and context without a local runtime, create an API key with memory:read under Security → API keys, then:

export VAULT_GO_TOKEN='<memory-read-key>'
codex mcp add vault-go \
  --url https://vaultmemoryai.com/api/mcp \
  --bearer-token-env-var VAULT_GO_TOKEN

{
  "mcpServers": {
    "vault-go": {
      "type": "http",
      "url": "https://vaultmemoryai.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${VAULT_GO_TOKEN}"
      }
    }
  }
}

Remote MCP exposes projects, search, context, recents, feed, timeline, tool I/O, file context, stats, embeddings, and knowledge-base queries. Automatic capture, knowledge-base writes, import, and delete require the local Bun server.

VAULT_GO_TOKEN accepts a session token or a vg_live_... key. Use only the scopes you need: memory:read, memory:write, memory:delete. VAULT_GO_API_URL changes the API host. Browser login refreshes automatically; API keys are for scoped automation.

Vault Desktop (Crystal)

On an updated Vault Desktop, enable Crystal → MCP → Enable in Vault MCP and reconnect the MCP client. Crystal note tools (vault_go_crystal_list, read, search, write, delete, sync, status) appear next to memory tools. Desktop must stay open on the same machine. No second server or copied secret is required. Disabling the integration revokes that connection.

How it works

AI client  →  vault-go (local MCP)
                  ↓
           Vault Memory API (authenticated)
                  ↓
           Memory engine  →  your account store

The engine has no public route. The API authenticates you, then scopes every query to that account. Clients cannot read another account’s memories.

Setup also installs session hooks on Claude Code, Codex, Grok, Agy, and Gemini CLI. Those hooks load project context and capture supported events. The local worker at http://localhost:38850 generates memories with the selected engine and writes them to Vault Memory. OpenCode 1.x gets a context-only plugin; it does not capture automatically.

Prefer three-step retrieval to keep context small:

1. vault_go_search_index with project, type, concepts, files, or dates.
2. vault_go_timeline only around the hits that need nearby context.
3. vault_go_observations for the selected IDs.

Context engines

List and select engines without putting API keys in MCP tools:

vault-go engine list
vault-go engine use openrouter
vault-go engine use codex --model terra
vault-go engine key openrouter

| Engine | How it authenticates | | --- | --- | | Vault AI Resume | Vault account entitlement | | Claude | claude auth login (subscription CLI) | | Codex / ChatGPT | codex login — models terra, luna, sol (CLI 0.155.1+) | | OpenRouter | key stored with vault-go engine key openrouter | | Gemini | key stored with vault-go engine key gemini |

MCP tools never accept secrets. Store keys with the CLI or the local dashboard. Provider usage limits apply. Managed Vault AI generation still depends on server configuration and quota.

MCP tools

Account and health: vault_go_status, vault_go_cloud_health, vault_go_preferences, vault_go_preferences_update.

Projects and sessions: vault_go_projects, vault_go_project_create, vault_go_session_start, vault_go_session_end, vault_go_session_start_context.

Capture and recall: vault_go_event, vault_go_remember, vault_go_forget, vault_go_search, vault_go_search_index, vault_go_retrieve, vault_go_observations, vault_go_timeline, vault_go_context, vault_go_file_context, vault_go_feed, vault_go_memory, vault_go_tool_uses, vault_go_stats.

Projects are matched by path first and then by repository: vault-go reads the checkout's origin remote, normalizes it to host/owner/repo and records it as the project's repoKey. A clone on another machine or user joins the oldest project with the same repoKey instead of creating a new one, and projects created before this are backfilled the first time a capture matches them by path.

A folder without git joins the nearest existing project above it instead of becoming a project of its own; a git checkout always keeps its own project.

Read tools (vault_go_search, vault_go_search_index, vault_go_feed, vault_go_retrieve and query-anchored vault_go_timeline) are scoped to the project of the MCP server's working directory when no projectId is given; a git worktree maps to its main checkout. Pass scope: "account" to search every project of the account. Outside a known project they fall back to the account, and no project is created. Memories marked private stay out of search and feed results unless includePrivate: true is set.

vault_go_retrieve lets the central memory engine choose a bounded retrieval path while every explicit retrieval tool remains available. vault_go_decision_status reports sanitized rollout/circuit state. Jev and its credential remain in the engine; a healthy deployment does not by itself prove provider availability or decision quality. vault_go_decide sends a caller-authored state plus up to 8 typed questions (noul, choice, score) to the central Jev and returns probabilities; it runs only in full rollout, one call at a time, refuses secrets, e-mails, identifiers, URLs and absolute local paths before anything leaves Vault, and persists nothing. The caller still owns the decision.

Knowledge bases: vault_go_knowledge_bases, vault_go_knowledge_base, vault_go_knowledge_build, vault_go_knowledge_rebuild, vault_go_knowledge_query, vault_go_knowledge_delete, vault_go_prime_corpus, vault_go_query_corpus, vault_go_reprime_corpus.

Jobs and backup: vault_go_jobs, vault_go_job, vault_go_job_retry, vault_go_job_cancel, vault_go_processing_status, vault_go_observer_status, vault_go_export, vault_go_import, vault_go_backup_create, vault_go_backup_restore, vault_go_embedding_status, vault_go_embedding_backfill.

Engines and updates: vault_go_engines, vault_go_engine_select, vault_go_generate_context, vault_go_update_status, vault_go_update_check, vault_go_update_install, vault_go_update_configure.

Graph and local code: vault_go_graph, vault_go_graph_link, vault_go_graph_link_delete, vault_go_graph_presets, vault_go_graph_preset_save, vault_go_smart_outline, vault_go_smart_unfold, vault_go_smart_search, vault_go_smart_languages.

Workflows: vault_go_workflow, vault_go_modes, vault_go_mode, plus named prompts such as vault_go_babysit. Loading a mode gives the agent instructions; it does not start a background job.

Optional local integrations (explicit consent): Telegram alerts, custom mode taxonomies, Claude/Codex transcript watchers, multi-project context chains, and Grok awareness logs. See vault_go_capabilities for what is configured on this machine.

The vault-go://status resource is a sanitized JSON summary.

Local dashboard

vault-go local install
vault-go local open
vault-go local status
vault-go local stop
vault-go local uninstall

Open http://localhost:38850 and choose Connect to Vault. The service listens only on 127.0.0.1:38850. local open proves the local process cryptographically, then uses an HttpOnly / SameSite=Strict cookie. There is no CORS and no inbound path from the cloud to localhost.

The dashboard follows the browser language (pt / en / es) and can switch locale. It shows local search, recent MCP activity, and cloud projects/memories for the signed-in account. While visible it refreshes the UI every 5 seconds and the cloud every 15 seconds. Offline, it keeps the last cache for that account.

On macOS, local install registers a user LaunchAgent. On Linux and Windows it starts for this session; use local start after reboot. Runtime files live in ~/.memvault/local-runtime. Uninstall removes autostart and keeps auth, cache, and activity.

Sign out ends this browser session and cancels its context previews. Disconnect device revokes the cloud device credential and, after success, removes local auth and cache. Personal files are left in place. Reconnect through the browser.

Capture and processing

SessionStart hooks load project context on start, resume, and compact when the client offers those events. File-read hooks are synchronous so context can be injected. vault_go_session_start_context is the same reader, using the account contextItems and contextMaxChars budget.

Claude, Codex, and Gemini confirm that context loaded without printing memory contents. Git worktrees reuse the canonical repository project. Submodules keep their own project.

Capture honors automaticCapture, captureMode, and whether tool results are included. A preference lookup failure disables that capture. Private events are not sent. Sensitive fields and private markers are stripped before processing (heuristic redaction, not a guarantee for every secret format).

The worker drains a private queue with the selected engine. Successful generation is cached so a network retry does not call the model again. Import uses an idempotency key. Account switches do not move jobs between accounts. summaryMode=off stores captured text without calling a model. vault_go_processing_status reports counts, not contents.

Opt-in Claude/Codex transcript watchers and project context chains are configured with MCP/CLI and stay bound to the current account.

Automatic updates

The worker checks the official npm registry daily for a stable vault-go release, stages an exact version under ~/.memvault/releases without running package install scripts, validates it, and activates when idle. A failed start rolls back. Auth, preferences, and the queue are kept. Open MCP clients must reconnect to load new tools.

vault-go update status
vault-go update check
vault-go update install
vault-go update off
vault-go update on

Security

• Tools and resources never return access or refresh tokens.
• HTTPS only, except HTTP on localhost.
• Access tokens refresh from a private local refresh token.
• Tool schemas bound sizes, lists, and windows.
• stdout is reserved for the MCP protocol.
• The dashboard cache uses AES-256-GCM (macOS Keychain, elsewhere a 0600 file). Encrypted cache is not the same as end-to-end encryption of every memory.

Install this MCP only on clients you trust: a connected client can search, write, and delete memories in the signed-in account.

Development

npm install
bun run typecheck
bun test src
bun run build
npm run pack:check
npm run pack:smoke

CI and release currently run only when the CI workflow is started manually in GitHub Actions. The default run validates only. To publish after the checks pass, start it on main with the publish input enabled; pushes alone do not start it. The package smoke check installs the actual tarball in a temporary directory and checks the CLI and MCP handshake without account credentials. Conventional commits determine the version (fix → patch, feat → minor, BREAKING CHANGE → major). NPM_TOKEN lives only in GitHub Actions.

Links

• Product: https://vault.resolveup.com.br
• Source: https://github.com/resolveup-cloud/vault-go
• npm: https://www.npmjs.com/package/vault-go