hivevault

Beta. hivevault 0.3.x works end to end (the suites below run on every push), and it is early: commands and the tool surface may still change between releases, and updates will be frequent. Found something, or want something? Bug reports, feature requests, new-client requests and questions are all welcome.

See it: what two sessions remembered, as git log -p shows it (an animated recording: two MCP sessions, one as claude-code and one as cursor, writing to one vault; scripts/record-svg.mjs --capture records it again), one decision remembered and read back, two overlapping claims, both kept, two vaults, no network, the same notes, npx from a pack of this checkout, npm into a throwaway prefix, the Homebrew formula's install, ./install.sh in a clone, a container built from this checkout, and the one-page site.

One memory, shared by every AI session you run. Any session that runs hivevault reads what every other session wrote: what was learned, decided, tried and left open, in any tool, on any machine. Every write is a git commit attributed to the client that made it, and writes from two machines converge.

Claude Code, Claude Desktop, claude.ai, Cursor, Windsurf, VS Code, Codex, Gemini CLI, Zed, Cline: each keeps its own private memory today, so what you decided at 10:00 in one tool is gone at 10:05 in another. hivevault turns memory into a store that every tool is a client of.

flowchart LR
    S1["Claude Code<br/>(laptop)"] --> V[("hivevault<br/>one memory")]
    S2["claude.ai<br/>(phone)"] --> V
    S3["Claude Desktop"] --> V
    S4["Cursor / Codex / Gemini CLI"] --> V
    S5["Claude Code on the web<br/>Cowork"] --> V
    S6["Your other machine"] --> V
    V --> S1
    V --> S2
    V --> S3
    V --> S4
    V --> S5
    V --> S6

Sixty seconds

npx hivevault init

One command. It creates your memory in ~/hivevault (a git repository of plain Markdown), mints a token per client, starts the daemon on 127.0.0.1:7788, connects every AI tool it finds on the machine and installs the Claude Code session-start hook (it lists the files that changes and asks first), and proves the loop with a demo. The output, shortened:

$ npx hivevault init
hivevault 0.3.3 installer at ~/hivevault
  ✓ Prerequisites: git, Node v22.12.0, ~/hivevault writable
  ✓ Vault files: created from the template (16 new)
  ✓ Git: repository initialised with a first commit
  ✓ Vault state: admin token saved to .vault/admin-token.txt (mode 600); shown once, here:
      vmt_…
  ✓ Default vault: recorded as the default vault (~/.config/hivevault/default)
  ✓ Client tokens: minted for Claude Code, any other MCP client (Codex, Gemini CLI, Cursor, ...)
  ✓ Clients: Claude Code (hivevault; launcher entries: no paths, no token)
  ✓ Claude Code hooks: SessionStart (every session loads the memory); Stop hook off (answer yes when init asks, or --capture; --no-capture skips the question)
  ✓ Remote access: tunnel key generated (.vault/tunnel-key.txt)
  ✓ Daemon: http://127.0.0.1:7788 (pid 51421)
  ✓ Private remote guard: pre-push hook installed; no private remote yet (hivevault remote create <name>)
  ✓ Isolation check: clean: this vault shares nothing with another vault
  ✓ Demo: remembered one decision and recalled: brain/decisions.md › 2026-10-09 14:05:12.345Z · mcp-client: "We chose hivevault as the shared memory for every AI session."
  ✓ Start on login: login item installed (launchd): the daemon is live after every login

Done
  Vault: ~/hivevault    daemon: http://127.0.0.1:7788    the default vault (~/.config/hivevault/default): hivevault status works from anywhere
  Connected: Claude Code (as hivevault).
  Next: open a Claude Code or Claude Desktop session. It loads your memory when the session starts and uses it while answering. You do not have to ask.
  Edit brain/north-star.md to tell agents who you are. Health check any time: hivevault doctor   (hivevault init --verbose shows every detail)
  For a permanent hivevault command and one engine: npm install -g hivevault && hivevault init   (safe to run again; npx hivevault <command> works too)

Other ways in, same result: git clone https://github.com/mgillr/hivevault.git && cd hivevault && ./install.sh; brew install mgillr/tap/hivevault && hivevault init; or the container, docker run -d -p 127.0.0.1:7788:7777 -v ~/hivevault:/vault ghcr.io/mgillr/hivevault. Which one: npx to try it (the clients start a copy of the engine kept in your vault, so nothing breaks when the npx cache goes); npm install -g hivevault && hivevault init for a permanent hivevault command; Homebrew for the same on macOS and Linux; the clone when you want the code next to the notes; the container for a server. Windows: WSL or the container, or natively in PowerShell with Node 22 (a beta until the windows workflow's first green run is recorded: docs/19-windows.md). Walkthrough: docs/01-quickstart.md; the decision as a table, with the clients that start a session on their own: docs/which-install.md.

For cloud sessions (claude.ai on your phone, Claude Code on the web, Cowork, ChatGPT), run hivevault tunnel and add the printed URL once as a connector. That single add per account is the only step a platform does not let a script do.

Why

• One context for every session. Every session that runs hivevault reads and writes the same memory, so each one has access to all the information and context of all the others: a session starts with your goals, active work, latest decisions and open questions already loaded, whichever tool or machine produced them. No re-explaining.
• Disagreement can be recorded. hivevault conflicts stores an assertion or a resolution in the operation log. It does not change the note. Overlapping incompatible claims stay visible, and a resolution does not erase an assertion. A vault that records none of these operations behaves as before. This is on main and is not a release. The command is in docs/04-commands.md.
• Nothing is lost. Every write is a git commit and a CRDT operation, so every version of every note is in the history; every entry the memory writes says when and by which tool (### 2026-10-09 14:05:12.345Z · claude-code). The memory verbs append; two vaults that sync converge to the same notes: appends from both sides survive, an append made while the other side rewrote the note survives the rewrite, a delete or move made while the other side appended gives the note back with the append, and between two concurrent rewrites of one note the larger operation hash wins while the other stays in the operation log and in git. A file edited outside hivevault (an editor, git pull) is recorded before any merge touches it.
• It is an Obsidian vault too. Wikilinks, frontmatter and folders are the ones Obsidian reads: open the directory in Obsidian for the graph and the editor, and git log -p shows what your AI remembered, as a diff you can revert.
• Any tool, any machine. Local tools connect over MCP; cloud tools connect over HTTPS through a tunnel you control. Same notes, same tokens, same audit log.
• Yours. Plain Markdown in a git repo you own. No account, no database, no vendor, no telemetry: the daemon makes no network call except the ones you configure (optional semantic search downloads its model once, at hivevault search enable). Node.js 22 and git are the only requirements.
• Shared when you want. hivevault invite alice --paths 'work/shared/**' prints one line; Alice runs it (hivevault join hv1...) and her vault syncs with yours, both ways, through a token that covers only the folder you share.

How it works, in four ideas: memory is files; files live in git; one daemon serves every agent (MCP over stdio for local tools, Streamable HTTP for cloud tools, a web UI for you); a CRDT makes concurrent writes converge. With diagrams: docs/03-how-it-works.md.

Every client

| Client | How | Status | |---|---|---| | Claude Code | hivevault connect claude-code (done by init) | verified live; the hook and the instruction block make every session start on its own | | Codex CLI, Gemini CLI | hivevault connect codex, hivevault connect gemini | verified live; sessions start on their own through AGENTS.md and GEMINI.md | | Claude Desktop | hivevault connect claude-desktop (done by init) | config file verified by the e2e; the handshake needs the app; the protocol reaches it as the MCP instructions field | | Windsurf | hivevault connect windsurf | documented format; starts on its own through global_rules.md | | Cursor, VS Code, Zed, Cline | hivevault connect <client>, or paste the snippet from examples/ | documented formats; the protocol reaches them as the MCP instructions field; paste examples/CLAUDE.md.snippet into the client's rules file for an always-on start | | Junie, JetBrains AI Assistant, Continue, OpenCode, Goose, Amp, Claude Agent SDK, Aider | hivevault connect <client> (JetBrains AI Assistant and the Agent SDK: it prints the entry to paste; Aider has no MCP client and reads the memory files) | documented formats; the protocol reaches them as the MCP instructions field | | claude.ai, Claude mobile, Claude Code on the web, Cowork, ChatGPT, your other machines | hivevault tunnel, then the URL as a connector (token or OAuth) | from the daemon's source |

Details and every snippet: docs/13-clients.md. A session sees a core profile of 14 tools (13 tools plus a catalogue tool): 20,466 bytes of tool listing, about 5.1k tokens, instead of about 10.2k for all 34 with --tools full. The whole fixed cost of a session (the initialize answer, the tool list, the session start) is a table in docs/13-clients.md, measured from the code by scripts/token-costs.mjs.

In Claude Code, a session also keeps what you say without being asked: the Stop hook (on only where you said yes — init asks and no is the default, --capture is the scripted yes, connect claude-code installs it as an explicit act; --no-capture leaves it out) writes the decisions, gotchas and open items you state into a session note under work/sessions/ for you to review, and shows one line when it kept something (hivevault recent lists what was written lately). Every client sees notes as MCP resources (hivevault://note/<path>): a client that subscribes hears when another session changes a note. init (or connect <client>) writes the client entry as a launcher by default (0.3.3): the same on every machine, with no node path, no engine path and no token in it (--no-launcher writes the explicit entry instead).

Compared with the alternatives

| | hivevault | mem0, Letta, Zep | Claude's built-in memory | |---|---|---|---| | Data lives | in your directory, in git | mem0 and Zep: a store or service you run or rent; Letta: a git repository per agent, local or hosted | in your Claude account | | Format | Markdown you can open | mem0: records in a vector store; Zep: a temporal graph; Letta: Markdown files | topics you read and edit in Settings | | Works across tools | any MCP client, any machine | their SDKs, plus plugins or MCP servers (mem0's and Letta's hosted ones need an account) | Claude's own apps | | Concurrent writers, several machines | CRDT convergence, audit log | one shared store or service | one account | | Cost, licence | free, Apache-2.0 | open source plus paid hosted plans | included in Claude's plans |

The full tables, every hivevault cell linked to its test and every other column to its sources: docs/14-compare.md. Coming from mem0? Its plugins and hosted MCP for Claude Code, Cursor, Codex and Antigravity are compared there too.

How it is secured

• The daemon binds to localhost on its own port (7788); remote access only through a tunnel you run, gated by a password on top of the token (the X-Vault-Key header, or the OAuth consent page, which asks for it once and grants read only, a folder and a lifetime if you choose).
• A token per client, hashed at rest, checked in constant time, with scopes and path globs matched on canonical paths; every write is a hash-chained audit entry that stores note paths as salted hashes; machine state (.vault/, .git/) and symbolic links are unreachable through the API.
• Every CRDT operation is signed by the vault that made it (Ed25519) and checked when it arrives from a peer: a forged, altered or malformed operation is refused on its own, never applied.
• hivevault purge <path> --git erases a note from the operation log, the files, the index, the audit paths and the git history, and peers drop it on their next sync.
• A secrets guard: a note that looks like it holds a credential (API key, token, private key, password) is refused unless you say allow_secrets, and the refusal is audited.
• One vault is one directory and shares nothing with any other vault on the machine (hivevault isolation proves it).
• Your notes can only be pushed to a private repository: the push guard refuses the public code repo, any public GitHub repo, and any remote it cannot verify until you confirm it.
• Releases carry npm provenance once the repository is public; the container image is built in CI from the tagged commit. Every release carries SHA256SUMS and a CycloneDX SBOM, and the image is signed with cosign keyless.

All of it, including what the daemon does not do: docs/05-security-and-encryption.md.

For organisations

One brain for a whole team, with trust per member, encryption between members, SSO and seat licensing, is the planned commercial tier: a separate, proprietary package, with a free edition for one organisation of up to five users; paying licensees receive its source under the licence, with escrow. This repository stays Apache-2.0 and is never relicensed. The design is docs/15-team-tier.md; the use cases, examples, architecture flows, licensing and pricing structure are under commercial/; the schedule is docs/ROADMAP.md. Nothing paid lives in this repository.

Documentation

| Read this | When | |---|---| | 01 Quickstart | npm, clone, Docker or Homebrew, step by step | | 02 Connect your sessions | Tokens, tunnels, cloud sessions | | 03 How it works | Files, git, CRDT, MCP, the session lifecycle, with diagrams | | 04 Commands | Every tool and CLI command, grouped | | 05 Security and encryption | Tunnel key, tokens, audit, private repo, encrypted backups, limits and the threat model | | 06 Sync across machines | The push guard, git, CRDT op exchange, upgrading | | 07 Architecture | Daemon internals | | 08 API | HTTP routes and MCP tools | | 09 Agent protocol | The operating contract an agent follows | | 11 Encrypted vault mode | Design of full encryption at rest | | 12 Scripts | Every script and wrapper command, what it touches | | 13 Every client | One section per client, with the exact config | | 14 How it compares | hivevault next to mem0, Letta, Zep and built-in memory | | 16 The expert review | Two passes: seven reviewers on 0.3.2, eleven on the release; what they measured, every finding with its issue, what was fixed, what would make hivevault novel, and the roadmap | | 17 Using it with personal data | Notes about people: lawful basis, retention, erasure, the DPIA; PRIVACY.md says what leaves your machine | | Which install, 10 Upgrading | Pick an install; upgrade it, or go back | | Troubleshooting, Day 2 | Something is wrong: by symptom; after the first week: backups, sync, tokens, recovery | | Recipes | A team folder, a second machine, Obsidian side by side, an agent you build | | Format specification | The vault format and the operation record, with a conformance suite | | FAQ | Short answers | | MAP | Every file in the repository and where it came from |

Repository layout

hivevault/
├── cli/                    the hivevault command: init, connect, demo, start, stop, token, tunnel, doctor, upgrade, uninstall
├── scripts/                bootstrap, push guard, isolation check, backup, e2e, link and publish checks
├── install.sh, bin/hivevault   the clone flow: shims that run the same command in this checkout
├── server/                 the daemon (Node 22+, zero dependencies, tests included)
├── docker/, docker-compose.yml, .github/, packaging/   the image, the compose file, CI and release, the Homebrew formula
├── docs/clients/, scripts/gen-client-docs.mjs   one generated guide per client, checked against the code in CI
├── docs/DEPENDENCY-MAP.md, INTEGRATION-RULES.md, ROADMAP.md   what depends on what, the rules every change follows, what is next
├── commercial/                    the planned organisation tier: use cases, examples, architecture, licensing and pricing, FAQ
├── scripts/stranger/              the stranger suite: fresh-account runs of every install path and the live client runs
├── vault.json, vault.system-prompt.md, brain/ work/ org/ reference/ thinking/   the vault template
├── examples/               ready-to-paste client configs, hook, project instructions
└── docs/                   numbered guides, start at 01

Lineage

hivevault's convergence layer (server/src/crdt.mjs) is an independent implementation of the two-layer architecture of crdt-merge: an OR-Set of proof-carrying operations with a vector clock and per-path Merkle provenance, materialised by a deterministic function. That architecture is patent pending (UK Patent Application No. 2607132.4). hivevault contains no crdt-merge code and does not implement the E4 Recursive Trust-Delta Protocol (UK Patent Application No. GB2608127.3), which belongs to the planned organisation tier. For hivevault's own code, the patent terms are those of the Apache License 2.0, section 3. crdt-merge (Business Source License 1.1, converting to Apache License 2.0 on 2028-03-29) publishes a PATENTS file granting a licence under both applications to users of crdt-merge who comply with its Business Source License 1.1; using crdt-merge itself is governed by its own LICENSE and PATENTS files.

The full notice: NOTICE.

License

Apache License 2.0. See LICENSE and NOTICE.