watashi-db

Personal context database you own. AI tools connect to it — not the other way around.

日本語版 README

[!NOTE] v0.x is early-stage. APIs and data structures may have breaking changes. All data is stored locally (~/.watashi-db/default.db). Nothing is sent externally (unless you explicitly opt in to the OpenAI embedding provider, which sends record summaries to the embedding API).

---

What is watashi-db?

Every time you start a new AI session, you start from zero — re-explaining your preferences, your tech stack, your past decisions. The AI is smart but knows nothing about you.

watashi-db fixes this. It's a local database that accumulates your preferences, decisions, and experiences, then serves them to any MCP-compatible AI tool at session start.

The AI stays stateless. You gain continuity.

Before / After

	Before	After
Session start	"I use TypeScript, prefer Japanese comments, and…" (every time)	AI loads your profile automatically via watashi_get(profile)
Past decisions	"I think we decided on X last week…" (from memory)	/recall DB design pulls up the exact Decision with reasoning
Lessons learned	Lost between sessions	Episodes distill into reusable Insights over time
Multi-tool	Each AI tool has its own silo	One database, any MCP client

---

Who is this for?

Developers who use MCP-compatible AI tools (Claude Code, Codex CLI, Antigravity, Claude Desktop, etc.) daily and want their AI to remember context across sessions — without handing their data to a vendor.

---

Key Features

• Zero-effort recording — AI records your preferences, decisions, and experiences in the background during normal conversation. You don't write anything manually.
• Experience distillation — Raw episodes are refined into reusable Insights, Models, and Theories over time (/groom). Not just a memo database.
• Fully local — SQLite + FTS5. No cloud, no external calls by default (the optional OpenAI embedding provider is opt-in). Your data stays on your machine.
• Vendor-neutral — Any MCP client can connect. Switch AI tools without losing context.
• Auditable — Every write is logged (who, what, why). Changes are retracted, never deleted.
• Multi-device sync — Optional snapshot sync via Google Drive or any cloud storage.

---

Quick Start

Step 1: Register the MCP server

# Claude Code
claude mcp add --scope user watashi-db -- npx -y watashi-db@latest

# Codex CLI
codex mcp add watashi-db -- npx -y watashi-db@latest

<details> <summary>Antigravity</summary>

Add to Antigravity's mcp_config.json (CLI: ~/.gemini/antigravity-cli/mcp_config.json, IDE: ~/.gemini/antigravity/mcp_config.json — open via Manage MCP Servers → View raw config):

{
  "mcpServers": {
    "watashi-db": {
      "command": "npx",
      "args": ["-y", "watashi-db@latest"]
    }
  }
}

</details>

<details> <summary>Claude Desktop</summary>

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "watashi-db": {
      "command": "npx",
      "args": ["-y", "watashi-db@latest"]
    }
  }
}

</details>

Step 2: Set up hooks and skills (Claude Code)

npx watashi-db setup

Restart Claude Code. That's it.

• Hooks auto-remind the AI to record decisions and experiences during conversation
• @nolog prefix on any prompt skips recording for that message
• /recall searches your past decisions, preferences, and experiences

Alternative: Plugin Marketplace (Claude Code)

If you use Claude Code, you can install everything (MCP server, hooks, skills, agents) in one step via the plugin marketplace — with automatic updates:

/plugin marketplace add bareforge/watashi-db
/plugin install watashi-db@watashi-db

This is equivalent to Steps 1-2 above but uses Anthropic's plugin system.

[!TIP] @latest ensures the latest version is used on every client restart.

For detailed setup (multi-device sync, Codex CLI policies, Cowork plugin, building from source), see the Setup Guide.

---

How It Works

┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│ Claude Code  │  │ Codex CLI   │  │ Antigravity │  │ Any MCP     │
│ (MCP Client) │  │ (MCP Client)│  │ (MCP Client)│  │   Client    │
└──────┬───────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘
       └─────────────────┼─────────────────┘
                         │ MCP (stdio)
               ┌─────────▼─────────┐
               │    watashi-db      │
               │   (MCP Server)     │
               │                    │
               │  SQLite + FTS5     │
               │  ~/.watashi-db/    │
               └────────────────────┘

1. You work normally. AI records your preferences, decisions, and experiences in the background.
2. Old records fade. Entries naturally lose search priority over time — no manual cleanup needed.
3. You run /groom occasionally. This distills recurring patterns into lasting Insights, so valuable lessons survive while noise disappears.

That's it. No entity types to learn, no manual tagging. Just use your AI tools and let watashi-db build your context over time.

---

How is this different?

Approach	Limitation	watashi-db's answer
CLAUDE.md / .cursorrules	Static instructions, manually maintained	Dynamic experience memory, auto-recorded by AI
ChatGPT Memory / Claude Projects	Vendor-locked, opaque, no export	You own the SQLite file. Any MCP client can read it
Obsidian + MCP	General-purpose notes, no structured experience model	Purpose-built for decisions, episodes, and distillation
Mem0 / Zep	Cloud-dependent memory layers	Fully local, zero external dependencies

watashi-db is complementary to CLAUDE.md — static rules go in CLAUDE.md, evolving experience goes in watashi-db.

---

Documentation

Document	Description
Setup Guide	Installation, multi-device sync, Cowork plugin
Config Guide	All config.json options
Why watashi-db	Philosophy: the statelessness problem in AI collaboration

<details> <summary>For contributors / deep-dive</summary>

Document	Description
Entity Taxonomy	How data is classified (Claim → Episode → Insight → Model)
Design Principles	Architectural decisions and review criteria (Japanese)
L1/L2 Theory	Theoretical foundation: structured reasoning languages (Japanese)
Runtime Schema / ER Diagram Source	Data model; canonical logical names are in the A5:SQL Mk-2 file (not viewable on GitHub; requires A5:SQL Mk-2)

</details>

---

Development

git clone https://github.com/bareforge/watashi-db.git && cd watashi-db
npm install && npm run build
npm test

---

License

Business Source License 1.1

• Personal / non-commercial / educational / evaluation use: Always free
• Commercial use: License required (bareforge.license@outlook.jp)
• Change Date: After 2029-03-16, automatically converts to Apache License 2.0

[!NOTE] Versions v0.0.12 and earlier were published under MIT License. If you obtained an MIT-licensed version, you may continue using that version under MIT terms.