# vault-go

MCP server and installer for **[Vault Memory](https://vault.resolveup.com.br)** — 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.

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

Or without a global install:

```sh
bunx --bun vault-go@latest
```

Requires [Bun](https://bun.sh/) (`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.

```sh
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:

```sh
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, Warp, Goose, Hermes, and Vault Desktop (Crystal).

Goose and Hermes are configured by editing a single entry in their `config.yaml` (`extensions.vault-go` and `mcp_servers.vault-go`). Comments and other lines are left as they are. A file with a shape that cannot be edited safely, such as an inline mapping, is left unchanged and reported.

```sh
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:

```json
{
  "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:

```sh
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
```

```json
{
  "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

```text
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:

```sh
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.

When the background queue hits an exhausted quota, Vault AI Resume and the Claude subscription stand in for each other. Other failures never switch engines. Set `VAULT_GO_ENGINE_FALLBACK=off` to disable this.

## 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

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

Open [http://localhost:38850](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.

Helper threads that clients generate themselves are never captured: Codex titles, suggestions and memory consolidation, Grok research briefings, and turns that are only a `<task-notification>`.

**File Read Gate (Claude Code).** In some cases a whole-file `Read` is denied, and the denial lists the file's memories. This happens only when the file is a code file of 32 KB or more, inside the workspace, and Vault memories about it are newer than its last change. Claude is pointed to `vault_go_smart_outline` / `vault_go_smart_unfold` or to a `Read` with `offset`/`limit` instead; partial reads always pass. Subagents and other clients are never gated, and any lookup failure lets the read through. Turn it off with `VAULT_GO_FILE_READ_GATE=off` or the `fileReadGate: false` preference.

## 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.

```sh
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

```sh
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](https://vault.resolveup.com.br)
- Source: [https://github.com/resolveup-cloud/vault-go](https://github.com/resolveup-cloud/vault-go)
- npm: [https://www.npmjs.com/package/vault-go](https://www.npmjs.com/package/vault-go)