Memory Vault

Your memory shouldn't be locked to one model. Memory Vault gives every AI agent you use — Claude Code, Codex, Cursor, ChatGPT, and friends — one shared, portable memory: teach a convention in one harness, switch to another mid-task, and it picks up exactly where you stopped. No database, no embeddings: plain Markdown files you own, wired to every agent over MCP with one command.

Memory Vault stores facts as ordinary Markdown files. Each project gets an isolated memory space, while shared/ holds facts that apply across projects. The files live in a private GitHub repository you own (hosted tier) or on your machine (local tier) and remain usable if you change models or agent harnesses.

Quick start

Hosted tier (recommended) — nothing to install. Add the remote MCP endpoint to any client:

claude mcp add --transport http --scope user vault https://memoryvault.click/mcp

or add https://memoryvault.click/mcp as a custom connector in claude.ai, ChatGPT, Codex, or any Streamable-HTTP MCP client (the server speaks OAuth 2.1 and implements the OpenAI search/fetch contract). On first connect you sign in with GitHub and install the memory-vault GitHub App on exactly one private repository you own — your memories live there as plain Markdown commits. The service keeps no copy of your memories and no standing credentials: repo access uses short-lived installation tokens minted per request, and uninstalling the App from the repository revokes everything.

Another computer — or another harness on the same computer — just adds the same connector: same memories, nothing to sync. And because every memory is a plain Markdown file in your repo, you can clone it, grep it, edit it by hand, or take it anywhere. Losing access to the hosted tier never means losing your memory.

Local tier — run the server on your own machine instead:

npx -y memory-vault install --global   # wire every detected harness on this machine

Restart your agent sessions, approve the vault MCP server if prompted, and verify the wiring:

npx -y memory-vault status

Memories accumulate in ~/.memory-vault as plain Markdown — see Set up on another computer to carry them to a second machine with a GitHub repo.

Related MCP server: auxly-memory-cli

How it works

The MCP server gives an agent six file operations — view, create, str_replace, insert, delete, and rename — plus search, a vault-wide keyword search over frontmatter and bodies.

The agent writes small memory files; each space's MEMORY.md index is generated by the server from the files' frontmatter after every change (editing it directly is refused). Every new memory gets an immutable UUIDv7 id: stamped at creation, and create refuses to replace an existing file unless told to overwrite. There is no database or embedding model. The Markdown files are the source of truth, so you can read, edit, grep, or version them yourself.

memory/
  MEMORY.md          # index of project spaces
  shared/
    MEMORY.md        # cross-project facts
    *.md
  <project>/
    MEMORY.md        # project index
    *.md

A project connection reads and writes its own space by default, but the whole vault stays visible — other spaces are addressable by path, and the root listing shows every space. Scope is a routing default, not a wall. An unscoped connection starts at the vault root for cross-project maintenance.

Local tier

Everything below runs the same server on your own machine, storing memories in a local folder (default ~/.memory-vault). Requirements — hosted tier needs none of this:

• Node.js 18 or newer

• An MCP client that supports stdio (global install) or Streamable HTTP (per-repo install)

Memory Vault has no runtime dependencies.

Install globally

Wire every harness on your machine once:

npx -y memory-vault install --global

For each detected harness this writes a user-level stdio MCP registration and the memory ritual in its global rules file — Claude Code (~/.claude.json + ~/.claude/CLAUDE.md), Cursor (~/.cursor/mcp.json), Codex (~/.codex/config.toml + ~/.codex/AGENTS.md), DeepSeek Harness (~/.dsh/AGENTS.md + a stdio mount in every profile's cordis.patch.yml), OpenCode (~/.config/opencode/opencode.json + AGENTS.md), Gemini CLI (~/.gemini/settings.json + ~/.gemini/GEMINI.md), and Antigravity (~/.gemini/config/mcp_config.json + an always-on rule in ~/.gemini/config/rules/). After that, every session in every repository gets the vault with no per-repo setup: the harness spawns memory-vault stdio in the session's directory, and the server derives the project space from that directory automatically (the nearest .git, else the shallowest package manifest; no marker means the default space). The rule is the same for every harness: a MEMORY_SPACE env var on the server entry pins the space explicitly, else the client's MCP workspace roots name it (for harnesses that spawn MCP servers outside the session directory), else the directory decides. Detected spaces are recorded in ~/.memory-vault-connections.json so they stay stable (an existing ~/.memroam-connections.json from the memroam-era releases is read and migrated on the next write).

npx -y memory-vault install --global --dry-run        # preview changes
npx -y memory-vault install --global --store <dir>    # choose the store (default ~/.memory-vault)
npx -y memory-vault uninstall --global                # undo exactly what install wrote

Restart your sessions after installing. Per-repo install (below) remains for team-shared, committed configs or a custom space name. An existing ~/.memroam store from the memroam-era releases is detected and kept — nothing moves without you.

Install into a repository

Run this from the repository you want to connect:

npx -y memory-vault install

This command:

1. Starts the local server if it is not already running.

2. Asks which harnesses to wire up, with the detected ones pre-selected (interactive terminals only — everywhere else the detected set is used as is).

3. Writes each chosen harness's MCP config and the shared rules files.

By default, install stores memory in ~/.memory-vault (an existing ~/.memroam store is honored) and derives the project name from the current directory. connect is an alias for install.

npx -y memory-vault install --dry-run                # preview changes
npx -y memory-vault install --project my-app         # choose the project name
npx -y memory-vault install --harness claude,codex   # skip the prompt, pick explicitly
npx -y memory-vault install --yes                    # skip the prompt, accept detected

Restart your agent session after installing and approve the vault MCP server if prompted (installs from the memroam-era releases registered it as memroam; rerunning install renames it).

Uninstall from a repository

npx -y memory-vault uninstall

Removes everything install wrote to the repository — the MCP entries, the rules sections, the dsh patch — deleting a file only when it held nothing else. Your memories are never touched, and the server keeps running for other projects. disconnect is an alias for uninstall.

Check the wiring

npx -y memory-vault status

Shows whether the server is up and which store it serves, how the current repository is wired per harness, and every repository recorded by install (kept in ~/.memory-vault-connections.json). If the server is up and the repo is wired but your agent session has no vault tools, the remaining cause is session attachment — status prints how to fix it.

Connect without the installer

install is a convenience, not a requirement. Any MCP client can connect by spawning the exact command the installer registers:

claude mcp add --scope user vault -- npx -y memory-vault stdio

or, in any client's JSON MCP config:

{
  "mcpServers": {
    "vault": { "command": "npx", "args": ["-y", "memory-vault", "stdio"] }
  }
}

No flags or environment are needed: memory-vault stdio resolves the store on its own (MEMORY_DIR env var, else the store recorded by a previous install, else ~/.memory-vault), detects the project space from the session's working directory, and carries its own usage instructions over MCP. A manual connection and an installed one therefore talk to the same vault and behave the same in-session.

What install adds on top of a bare MCP connection: the memory ritual written into each harness's rules file (CLAUDE.md, AGENTS.md, …), which makes agents check and save memories much more reliably, and a record in ~/.memory-vault-connections.json so status can report the wiring. If you started with a manual connection, running npx -y memory-vault install --global later layers those on without changing the MCP entry.

Set up on another computer

On the hosted tier there is nothing to set up: add the connector on the new machine and sign in — your memories are already there. The rest of this section is for the local tier.

The vault is nothing but a directory of Markdown files, so moving or sharing it is a file-copy problem, not a migration. The natural way to keep two machines in sync is to make the store a git repository hosted on GitHub.

On the machine that already has memories:

cd ~/.memory-vault
git init && git add -A && git commit -m "memory vault"
git remote add origin git@github.com:<you>/memory-vault-store.git   # a private repo
git push -u origin main

On the new computer, clone the store first, then run the same global install against it:

git clone git@github.com:<you>/memory-vault-store.git ~/.memory-vault
npx -y memory-vault install --global

install --global defaults to ~/.memory-vault, so cloning to that path needs no extra flags; a store kept elsewhere (a synced folder, a different clone path) is selected with --store <dir>. Restart your sessions and both machines read and write the same memories — git pull / git push when you switch computers, and because every memory is a small self-contained file, merges rarely conflict. If a generated MEMORY.md index does conflict, resolve it either way: it is a projection of the files' frontmatter, never read as source of truth, and the server rewrites it on the next change in that space.

A plain synced folder (Dropbox, iCloud, Syncthing) works the same way — the server never assumes git; it just reads and writes Markdown.

Import native memory, project to memoryless harnesses

npx -y memory-vault import     # Claude Code auto-memory + Codex sqlite → candidates/
npx -y memory-vault project    # regenerate the read-only shared/ block in dsh's AGENTS.md

import copies each harness's native memory into the matching space's candidates/ directory — searchable and labeled [candidate], excluded from the index, never written into canonical memory automatically. The Codex reader is read-only and refuses unknown database schema versions. Both commands print a capability report of what they can and cannot move, and take --dry-run / --json.

Supported harnesses

For DSH, start a session with the generated patch:

dsh --patch ./dsh-cordis.patch.yml --profile headless "your task"

Run the server directly

MEMORY_DIR=~/.memory-vault npx memory-vault

The server listens on 127.0.0.1:8787 by default.

From a cloned repository, npm start runs the same server.

MCP endpoints

POST /mcp/<project>  project memory plus shared memory
POST /mcp            whole-vault access

For example, a manual Claude Code connection is:

claude mcp add --transport http --scope project vault http://localhost:8787/mcp/my-project

Memory format

Store one durable fact per Markdown file:

---
name: preferred-language
description: The project's preferred implementation language
---

Use TypeScript for new application code.

The server stamps an id: and regenerates the space's MEMORY.md index line from the description: automatically. It instructs agents to check for an existing memory before creating one, update facts instead of duplicating them, and remove memories that become incorrect.

Current scope

The current release is a Markdown store (local folder, or your own GitHub repository on the hosted tier), an MCP interface with keyword search, OAuth 2.1 on the hosted tier, a cross-harness setup command, and one-shot import/projection adapters. There is no automatic extraction, semantic search, or automated deduplication.

Package

• npm: memory-vault (memroam on npm is a deprecated alias)

• MCP registry: io.github.apurv101/memory-vault

• License: MIT