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

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"]
    }
  }
}

Add to claude_desktop_config.json:

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

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 |

| 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) | | ER Reference | Complete tool reference and data model (Japanese) |

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 ([email protected])
• 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.