WhiteBox

The identity layer for AI agents. If Karpathy's LLM Wiki is what you know about the world, WhiteBox is what AI knows about you — plain markdown files on your disk that travel with you across every agent you use. Claude, ChatGPT, Gemini, Cursor, Desktop, Code — same identity, every session, no vendor lock-in.

Status: v1.0.0-prealpha.6 — feature-complete for the v1 design, unvalidated by external users. Expect breakage and iteration.

Just want to install it? If you're not a developer, the friendliest path is INSTALL_FOR_FRIENDS.md — five minutes, no terminal, no Node.js, no command-line. Just download a folder, load the browser extension, and walk through a wizard.

The problem

Every AI agent builds its own model of you, locked inside its own system. Switch from ChatGPT to Claude, you start over. Use Gemini at work and Claude at home, they don't share. The more you use AI, the more locked in you become — not to one agent, but to every agent separately.

WhiteBox breaks that lock-in. Memory becomes a folder on your disk that follows you.

Where WhiteBox fits in the landscape

The "user-owned markdown + AI reads it" design space is now crowded with serious players. Here's how WhiteBox relates:

• Karpathy's LLM Wiki pattern — An LLM-maintained markdown knowledge base about topics (finance, coding, a field you're studying). Solves "what do I know?" WhiteBox is complementary: use the LLM Wiki for knowledge, WhiteBox for identity.
• OpenBrain (OB1) — PostgreSQL + pgvector + MCP, database-backed memory with semantic search. Different storage philosophy (database vs. plain files). Works great for large-scale memory + semantic retrieval; WhiteBox works better if you want files you can open in a text editor and zero infrastructure cost.
• Anthropic's Import Memory + Claude Code memory.md — Markdown memory inside the Claude ecosystem. Official and well-integrated, but Claude-only. WhiteBox is cross-vendor from day one.
• mem0 / Letta / ChatGPT Memory / Claude Memory / Rewind — Vendor-owned or service-hosted memory layers. docs/COMPARISON.md details where each diverges.

WhiteBox's specific wedge: identity-focused memory with multi-agent attribution, verbatim-only discipline, a five-grade confidence scale, and anti-character-drift rules. Optimized for the case where 3+ AI agents write to the same vault about the same user over time. No one else centers that problem.

See docs/COMPARISON.md for the full honest comparison.

---

Quick install

WhiteBox has three independent components. Install whichever you'll actually use; they all read/write the same vault folder.

1. Create your vault (always do this first)

git clone https://github.com/FreyjaNellora/WhiteBox.git
cd WhiteBox/whitebox-cli
npm install && npm run build
node bin/whitebox.js init ~/whitebox-vault

This creates ~/whitebox-vault with AGENTS.md, identity.md, working-style.md, tags.md, and an empty observations/ folder. Open identity.md and working-style.md in your text editor and add a few sentences about who you are. Five minutes is enough.

2. Install the MCP server (for Claude Desktop / Claude Code / Cursor / Gemini CLI)

cd ../whitebox-mcp
npm install && npm run build

Then add to your MCP client config (e.g. ~/.config/Claude/claude_desktop_config.json for Claude Desktop):

{
  "mcpServers": {
    "whitebox": {
      "command": "node",
      "args": ["/absolute/path/to/WhiteBox/whitebox-mcp/dist/index.js"],
      "env": {
        "WHITEBOX_VAULT_ROOT": "/absolute/path/to/whitebox-vault"
      }
    }
  }
}

Restart your MCP client. You should see seven WhiteBox tools available: bootstrap, read_file, list_files, grep, append_observation, propose_stable_edit, list_conflicts.

3. Install the browser extension (for claude.ai, chatgpt.com, gemini.google.com)

Open chrome://extensions (or the equivalent in your Chromium browser):

1. Toggle Developer mode on (top right).
2. Click Load unpacked and select the whitebox-extension/ folder from this repo.
3. Pin the WhiteBox icon to your toolbar.
4. Click the icon → Open setup… and grant access to your vault folder.

Pick a style on first run (Office / Engineer / Gamer-Modder). Open claude.ai/new — your first message will automatically include vault context, and the agent will know who you are.

4. (Optional) Install the Claude Code skill

mkdir -p ~/.claude/skills
cp -r claude-code-skills/whitebox ~/.claude/skills/

Teaches Claude Code about the WhiteBox tool surface, the discipline rules, and the self-automation pattern.

---

What you get after install

• A vault of markdown files you own, on your disk, openable in any text editor.
• The same vault read by every AI agent you use — Claude Desktop, Claude Code, Cursor, Gemini CLI via MCP; claude.ai / chatgpt.com / gemini.google.com via browser extension.
• A marker protocol the agent emits in claude.ai replies ({wb-fetch:}, {wb-scope:}, {wb-bootstrap}, {wb-save}…{/wb-save}, {wb-context:}) that becomes clickable pills in the UI so every action is auditable.
• A floating HUD on claude.ai showing vault state, conflicts, lock status, agent bypass tier, danger badges.
• In-page help bubble with a 24-page wikibook + hover tooltips on every UI element. Press the popup's Help link to open it on the current tab.
• A vault lock with passphrase (Phase 1: UX gate; Phase 2 will add encryption underneath).
• Per-trigger danger toggles — lock on screen lock / idle / tab close / browser exit, each independently configurable.
• Agent bypass tiers for what the agent can still do while the vault is locked: none (default) / reads-only / reads-and-safe-writes / full-bypass.
• An autonomous-write audit log to audit/YYYY-MM-DD.md. Every save is one line; bypass-permitted writes are annotated.
• Source-stamping so agents can't lie about which platform they came from.
• Optional passive auto-log of full conversations to conversations/YYYY-MM-DD/<id>-part-N.md, chunked at 40K chars.

For the full setup walkthrough including platform-specific notes, see QUICKSTART.md. For everything WhiteBox does and doesn't do, see docs/GUARDRAILS.md. To uninstall (your vault folder is never touched), see UNINSTALL.md.

---

What WhiteBox is

A published schema and a thin set of integrations that let any AI agent read and write to a user-owned markdown vault on disk. The whole product is built around a small spec — anything that speaks the spec can read your memory; anything that doesn't can be made to with a thin adapter.

WhiteBox is responsible for vault integrity (sandbox, source stamping, audit log, lock + bypass) and user control (deletion, editing, scopes, guardrails). It is explicitly not responsible for content moderation — that's the LLM provider's job, handled in the conversation layer before content reaches us. See docs/GUARDRAILS.md for the full scope statement.

---

Contributing

See CONTRIBUTING.md for the official bar and docs/COMMUNITY.md for the softer welcome and good-first-contribution list. Selector updates for the browser extension, integration recipes for new tools, and canonical tag proposals are the easiest first PRs.

---

What's in this repo

Specs

• spec/WHITEBOX_v1.md — frozen schema 1.0
• spec/WHITEBOX_v1.1.md — current spec (passive + active memory layers, source/extract split, vault-wide chunking)
• spec/tags-canonical-v1.md — shared tag vocabulary

Reference content

• vault-example/ — reference vault showing the format in practice
• vault-example/AGENTS.md — the bootloader any agent reads first

Tools

• whitebox-mcp/ — MCP server. Tools: bootstrap, read_file, list_files, grep, append_observation, propose_stable_edit, list_conflicts.
• whitebox-cli/ — CLI. Commands: init, export, paste, conflicts, log, grep. (import still stubbed.)
• whitebox-extension/ — Chromium browser extension. Bootstrap injection, marker protocol with clickable pills, floating HUD with style presets, vault lock + agent bypass + danger toggles, in-page help wikibook, opt-in passive auto-log, observation capture, session digest.
• claude-code-skills/whitebox/ — Claude Code skill packaging.

Documentation

• QUICKSTART.md — end-to-end setup walkthrough (also AI-parseable; paste into any agent)
• docs/GUARDRAILS.md — what WhiteBox protects (and what it doesn't), per-source permission tiers, lock + bypass semantics
• docs/PITCH.md — product pitch
• docs/DESIGN.md — design rationale + research citations
• docs/COMPARISON.md — WhiteBox vs mem0 / Letta / ChatGPT Memory / Claude Memory / Rewind
• docs/EDITOR_GUIDE.md — using the vault with Obsidian / VS Code / Typora / plain text editors
• docs/STRATEGY.md — adversarial resilience
• docs/ADOPTION.md — GTM sequencing
• docs/PRICING.md — freemium split
• docs/MARKETING.md — recruitment + launch plan
• docs/COMMUNITY.md — contributor welcome + good-first list
• docs/VALIDATION.md — end-to-end test log
• docs/TEST_CHECKLIST.md — what still needs user validation
• CONTRIBUTING.md — contribution bar
• CHANGELOG.md — release history

Archive

• _old-design/ — earlier exploratory drafts, kept for reference

---

Roadmap

• v0.1–v0.3 — schema, MCP server, CLI, browser extension scaffold, community infrastructure. ✓
• v1.0.0-prealpha (current) — Marker protocol (read + write), MCP bootstrap/grep, vault lock + per-trigger danger toggles, agent bypass tiers, source stamping, audit log, in-page help wikibook + hover tooltips, Claude Code skill packaging. ✓
• v0.5 — Vault encryption Phase 2 (AES-GCM sensitive/ directory with passphrase + biometric unlock), per-source guardrails enforcement, Obsidian plugin (inspector UI for promotion review).
• v0.6+ — SSE transport for MCP (unlocks ChatGPT Desktop Developer Mode), DXT extension package for Claude Desktop install, VS Code / Logseq plugins, mobile companion app, paid-tier sync infrastructure.

---

Why now

• AI agents are proliferating. Users are using several at once. Memory lock-in is the next moat providers will build, and most users won't notice until they want to leave.
• Model Context Protocol gives a standard transport for the Claude ecosystem, with Gemini CLI already native and ChatGPT Desktop partially supporting it.
• Obsidian and similar markdown-vault tools have made user-owned local files mainstream enough to build on.
• No existing product owns this space — mem0, Letta, Rewind, Personal.ai all ship vendor silos with "portable" only as marketing. docs/COMPARISON.md has the details.

---

Status

Pre-alpha (v1.0.0-prealpha.6). Cross-vendor injection works on claude.ai, chatgpt.com, gemini.google.com from the same local vault. MCP server serves reads and writes live in Claude Desktop / Code / Cursor / Gemini CLI. Browser extension shipping marker protocol, floating HUD, vault lock, agent bypass tiers, audit log, in-page help. CLI commands working. Claude Code skill packaged.

Validated by the maintainer. Not yet validated by external users. Actively seeking first testers — see docs/MARKETING.md.