{
  "markdown": "# Memory Vault\n\nYour 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.\n\n![Claude Code and Codex sharing one memory](demo.gif)\n\nMemory Vault stores facts as ordinary Markdown files. Each project gets an isolated memory space, while `shared/` holds facts that apply across projects. The files stay on your machine (or in your own GitHub repository with the hosted tier) and remain fully usable if you change models or agent harnesses — that's the point.\n\n## How it works\n\nThe 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.\n\nThe 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.\n\n```text\nmemory/\n  MEMORY.md          # index of project spaces\n  shared/\n    MEMORY.md        # cross-project facts\n    *.md\n  <project>/\n    MEMORY.md        # project index\n    *.md\n```\n\nA 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.\n\n## Requirements\n\n- Node.js 18 or newer\n- An MCP client that supports stdio (global install) or Streamable HTTP (per-repo install)\n\nMemory Vault has no runtime dependencies.\n\n## Install globally (recommended)\n\nWire every harness on your machine once:\n\n```sh\nnpx -y memory-vault install --global\n```\n\nFor 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).\n\n```sh\nnpx -y memory-vault install --global --dry-run        # preview changes\nnpx -y memory-vault install --global --store <dir>    # choose the store (default ~/.memory-vault)\nnpx -y memory-vault uninstall --global                # undo exactly what install wrote\n```\n\nRestart 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.\n\n## Install into a repository\n\nRun this from the repository you want to connect:\n\n```sh\nnpx -y memory-vault install\n```\n\nThis command:\n\n1. Starts the local server if it is not already running.\n2. Asks which harnesses to wire up, with the detected ones pre-selected (interactive terminals only — everywhere else the detected set is used as is).\n3. Writes each chosen harness's MCP config and the shared rules files.\n\nBy 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`.\n\n```sh\nnpx -y memory-vault install --dry-run                # preview changes\nnpx -y memory-vault install --project my-app         # choose the project name\nnpx -y memory-vault install --harness claude,codex   # skip the prompt, pick explicitly\nnpx -y memory-vault install --yes                    # skip the prompt, accept detected\n```\n\nRestart 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).\n\n## Uninstall from a repository\n\n```sh\nnpx -y memory-vault uninstall\n```\n\nRemoves 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`.\n\n## Check the wiring\n\n```sh\nnpx -y memory-vault status\n```\n\nShows 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.\n\n## Import native memory, project to memoryless harnesses\n\n```sh\nnpx -y memory-vault import     # Claude Code auto-memory + Codex sqlite → candidates/\nnpx -y memory-vault project    # regenerate the read-only shared/ block in dsh's AGENTS.md\n```\n\n`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`.\n\n### Supported harnesses\n\n| Harness | Files configured |\n|---|---|\n| Claude Code | `.mcp.json`, `CLAUDE.md` |\n| Cursor | `.cursor/mcp.json`, `AGENTS.md` |\n| Codex | `.codex/config.toml`, `AGENTS.md` |\n| DeepSeek Harness | `dsh-cordis.patch.yml` |\n| OpenCode | `opencode.json`, `AGENTS.md` |\n| Gemini CLI | `.gemini/settings.json`, `AGENTS.md` |\n| Antigravity | `AGENTS.md` (repo rules; MCP wires globally) |\n\nFor DSH, start a session with the generated patch:\n\n```sh\ndsh --patch ./dsh-cordis.patch.yml --profile headless \"your task\"\n```\n\n## Hosted tier\n\nThe hosted tier is the same server run for you: a remote MCP endpoint secured with OAuth 2.1, storing your memories as commits in a private GitHub repository **you own**. Connect it to Claude (claude.ai custom connector), ChatGPT (custom connector via the OpenAI search/fetch contract), Codex, or any remote-MCP client:\n\n```text\nhttps://memoryvault.click/mcp\n```\n\nEvery memory is a markdown file in your repo — clone it, grep it, take it anywhere. Losing access to the hosted tier never means losing your memory.\n\n## Run the server directly\n\n```sh\nMEMORY_DIR=~/.memory-vault npx memory-vault\n```\n\nThe server listens on `127.0.0.1:8787` by default.\n\n| Environment variable | Default | Purpose |\n|---|---|---|\n| `MEMORY_DIR` | `./memory` | Directory containing the vault |\n| `VAULT_PORT` | `8787` | Local HTTP port |\n\nFrom a cloned repository, `npm start` runs the same server.\n\n### MCP endpoints\n\n```text\nPOST /mcp/<project>  project memory plus shared memory\nPOST /mcp            whole-vault access\n```\n\nFor example, a manual Claude Code connection is:\n\n```sh\nclaude mcp add --transport http --scope project vault http://localhost:8787/mcp/my-project\n```\n\n## Memory format\n\nStore one durable fact per Markdown file:\n\n```md\n---\nname: preferred-language\ndescription: The project's preferred implementation language\n---\n\nUse TypeScript for new application code.\n```\n\nThe 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.\n\n## Current scope\n\nThe current release is a Markdown store (local folder or hosted GitHub-backed), 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.\n\n## Package\n\n- npm: [`memory-vault`](https://www.npmjs.com/package/memory-vault) (`memroam` on npm is a deprecated alias)\n- MCP registry: `io.github.apurv101/memory-vault`\n- License: MIT",
  "bytes": 9370,
  "sha": "cd563d48ad50147f0f4ca33a6f0cd973254082296bf6922a279fa990bbc13f1a",
  "repo_slug": "",
  "fonte": "npm",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_apurv101_memory_vault_77423dc9/readme"
}