Bunshin Memory

Your past is yours. AI is just the lens.

A personal memory engine that ingests your emails, files, chats, notes, photos, and browser history — then lets any LLM you choose read it, locally. Japanese-first.

The CLI binary is still bunshin for backwards compatibility. "Bunshin Memory" is the product name; "Bunshin" alone gets confused with bunshin.app (a Claude Code desktop wrapper — different category, same anime root).

Download for macOS ↓ · 日本語版 README · Architecture · Contributing

ChatGPT and Claude are personal assistants — replaceable. Bunshin is your brain's extension — yours.

Why Bunshin

Today's AI products tie your memory to the vendor:

ChatGPT remembers you, but you can't take that memory elsewhere
Claude has memory features, but only in Anthropic's ecosystem
Mem0, Letta, etc. are cloud-based services by default (OSS self-host variants exist, but the hosted offering is the mainline product)

If your AI vendor changes pricing, shuts down, or you simply want to switch, all your accumulated memory is gone.

Bunshin inverts this: your memory lives on your machine, in a standard SQLite file. Any LLM that speaks the MCP protocol can use it. If Anthropic disappears tomorrow, your memory survives.

Where Bunshin Memory fits

Bunshin Memory sits in a space that local-first AI projects are starting to converge on. We're not the only entrant:

Stanford's open-source OpenJarvis covers similar local + AI-agnostic ground (English-first).
bunshin.app (frankkk96 — same anime name, different category: a Tauri desktop wrapper that puts a UI around Claude Code for developers). If you came here looking for a coding-agent host, that's the one you want, not this one.

Bunshin Memory's differentiation is:

Axis	Detail
🇯🇵 Japanese-first sources	LINE chat history, iMessage, Photos.app albums + GPS clusters, Apple Notes — built for what Japanese users actually use day-to-day
📸 Deep Photos integration	GPS-tagged photos auto-cluster into `place` entities (Wikipedia-resolved: 壱岐市 / Long-march City / etc.) and contiguous photo days collapse into trip events
🕸 Knowledge graph with type colors	Entities color-coded by kind (person / place / organization / project / concept / tool) — visible at a glance
🔌 MCP-native	Claude Code / Claude Desktop / any MCP client can call `search_memory`, `get_today_hero` and 5 other tools
🔒 Local + offline-capable	SQLite + sqlite-vec for storage, Ollama for inference. Everything works without internet (cloud AI optional for the describe pass)

What it does

🔍 Search anything you've ever encountered

Hybrid (semantic + BM25) search across every record. Japanese and English. Source filters, period filters, click-to-expand whole sessions, click-the-badge for sibling chunks.

💬 Chat with offline LLM grounded in your past

Local Ollama with auto-injected past-record context. Citations link back to source records. No data leaves your machine.

💡 Auto-generated daily insights

Dormant projects, upcoming calendar events, recent file changes, pending questions from past assistants. One tab to start your day.

📅 Timeline

Every record grouped by day and source. Today / yesterday markers. Per-source pill icons (💬 Claude, 📧 Gmail, 📓 notes, 📷 photos, 🌐 browser …). Click a pill to drill into that day, hover a record to expand it.

🕸 Knowledge graph

LLM-extracted entities (people, projects, organizations) with specificity-scored relations.

🔁 Always up to date

File watcher catches edits in seconds. launchd / systemd / cron syncs every hour. Automatic daily backups (VACUUM INTO).

🤖 MCP for any AI

Claude Code, Claude Desktop, or any MCP-aware LLM can call 8 MCP tools against your records: search_memory, recall_session, get_flashback, list_top_entities, get_today_hero, get_recent_chat, pin_entity_context, get_server_info.

📌 Pin off-screen reality

Some entities have a real-life role that doesn't show up in textual records (e.g. an island that hosts your e-commerce + drone services + ocean-education businesses, but your records mostly capture AI research chat). Pin a 1–2 sentence override on that entity from the relationships tab, settings list, CLI (bunshin pin-context), or MCP (pin_entity_context) — describe will treat it as a hard constraint on the next regeneration.

Why it exists. Bunshin Memory's describe pass reads what the records say, not what you actually do. If you spend Monday–Friday talking to Claude about AI research and Saturday–Sunday running your farm, your "farm" entity's records will be dominated by AI research context — the describe reflects that lopsidedness. A pin says "regardless of what the records imply, this entity is X" and every downstream consumer (relationships graph description, MCP search_memory, get_today_hero briefing, list_top_entities metadata) inherits your framing. Pins round-trip via bunshin export-pins / import-pins so you can carry your declared reality between machines.

Ingestion sources (11 paths)

Source	What goes in	Path
💬 Claude	Every Claude Code / Claude Desktop transcript	`~/.claude/projects/*/.jsonl`
📧 Gmail	Last 90 days of mail (incremental after that)	Gmail API + App Password
📄 Files	`.md` / `.txt` / `.pdf` / `.docx` under a watched root	Walkable directory
📓 Apple Notes	Every note from Notes.app via AppleScript (no FDA)	macOS only
💌 iMessage / SMS	`chat.db` joined with handles + group names	macOS, FDA required
📷 Photos	EXIF (date, GPS, camera) + macOS Vision OCR (JP + EN)	`~/Pictures` or any dir
📷 Photos.app library	All media items from Photos.app via AppleScript	macOS only
🌐 Browser	Safari / Chrome / Arc visit history	macOS
📅 Calendar	Next 14 days from any iCal URL	iCloud, Google, etc.
🔊 Audio	Whisper transcription (3 backends: faster-whisper, openai-whisper, whisper-cpp)	Any audio file
💭 Manual	`bunshin note "…"` or `覚えといて: …` in chat	Anywhere

PDFs without an embedded text layer (scanned documents) are automatically routed through macOS Vision OCR via PDFKit + CoreGraphics page rendering — including business cards, quote sheets, and receipts.

Quick start

Install the Mac app (recommended)

Download the latest DMG from Releases:
- Apple Silicon (M1/M2/M3/M4): Bunshin-x.y.z-arm64.dmg
- Intel Mac: Bunshin-x.y.z.dmg
Open the DMG, drag Bunshin to /Applications.
First launch: right-click → Open (macOS quarantine).

The app handles initial setup, runs bunshin web in the background, and gives you the full UI immediately.

Or install from source

git clone https://github.com/Marine923/bunshin-ai.git
cd bunshin
python3.11 -m venv ~/.bunshin/venv
~/.bunshin/venv/bin/pip install -e .

# Initialize
~/.bunshin/venv/bin/bunshin init

# Pull what you have (Claude history is the fastest first import)
~/.bunshin/venv/bin/bunshin import-claude
~/.bunshin/venv/bin/bunshin embed

# Open the web UI
~/.bunshin/venv/bin/bunshin web
# → http://127.0.0.1:8000

# Check setup health any time
~/.bunshin/venv/bin/bunshin doctor

# Clean up NER duplicates (e.g. "Bunshin" + "分身（Bunshin）" → one entity)
~/.bunshin/venv/bin/bunshin find-duplicates
~/.bunshin/venv/bin/bunshin merge-entities <source> <target> --dry-run

See docs/SETUP.md for Gmail, Calendar, Ollama, MCP, and scheduler setup.

Architecture

┌──────────────────────────────────────────────────────────┐
│ Entry points: CLI · Web UI · MCP server · Electron app   │
├──────────────────────────────────────────────────────────┤
│ Core: search · chat · insights · knowledge graph         │
├──────────────────────────────────────────────────────────┤
│ Storage: SQLite + sqlite-vec  (~/.bunshin/data.db)       │
│ Embeddings: intfloat/multilingual-e5-large (1024d, ONNX) │
│ Hybrid search: vector + FTS5 BM25 via reciprocal-rank    │
├──────────────────────────────────────────────────────────┤
│ Ingestion: Claude · Gmail · files · Notes · iMessage     │
│            photos · Photos.app · browser · calendar      │
│            audio · manual                                │
└──────────────────────────────────────────────────────────┘
        ↑                                          ↑
    Ollama (offline)                Claude / GPT / Gemini (via MCP)

Details in docs/ARCHITECTURE.md.

Real-world numbers

A live install on the developer's MacBook holds:

Source          Records
─────────────  ────────
claude          ~2,400   conversation turns
gmail           ~1,650   messages
photos_app      ~2,700   media items (1,113 with GPS)
file              ~900   docs (.md, .txt, .pdf, .docx)
browser           ~600   visits
notes             ~490   Apple notes
photo              ~99   loose images (with OCR text)
manual              1
─────────────  ────────
Total           ~8,650   records
Embeddings      ~9,200   (1024-d, e5-large)

OCR on the photo set recovered, among other things, an entire DJI T25P quote sheet (¥4,028,264, with vendor address, item breakdown, and bank details) — fully searchable.

Documentation

docs/SETUP.md — Full setup guide
docs/COMMANDS.md — All CLI commands
docs/CLEANUP.md — Weekly DB maintenance cheatsheet
docs/ARCHITECTURE.md — Internal design
docs/TROUBLESHOOTING.md — Common issues
CHANGELOG.md — Release notes

What's new in v0.10 (65 releases across a week)

Curated summary: docs/RELEASE_HIGHLIGHTS.md — the arcs narrated as a story.

The current minor version line is unusually deep — a tight feedback loop with a single power user produced 65 patch releases. The v0.10.42–46 arc solved a structured 9-of-9 evaluation; the v0.10.47–65 arc hardened the β-distribution path so silent failures (undownloaded models, broken sqlite-vec, off-list Ollama, stale build artifacts) show up loud instead of leaving the user confused. Headline themes:

UX polish + observability (v0.10.61–65):
- Chat citation term-highlight (v0.10.61, hotfixed v0.10.62) — hover a [1] chip in chat, get a floating preview with the last user-query's words <mark>-highlighted so "why is this cited" is instantly readable
- build.sh fail-fast (v0.10.63) — post-build DMG assertion + prefix-agnostic dist/ clean, so a lint fail can no longer let a stale prior-version DMG masquerade as the new build
- Per-record copy button (v0.10.64) — green icon on each search result card, one-click writes [timestamp] source\n<body> to the clipboard (Claude / ChatGPT / notes quote extraction)
- bunshin status --json + entities + timespan (v0.10.65) — pulse-check without doctor's 11 probes; adds entity count and oldest→newest span (e.g. 2015-03-18 → 2026-07-06 (4,127 days))
CLI-less β-distribution polish (v0.10.47–60):
- doctor 4 項目 (v0.10.47) — embed cache / rerank cache / disk free / Python version 追加
- bunshin warm (v0.10.48) — 5-10 分の silent モデル DL を進捗表示付きの明示的作業に変換
- sqlite-vec ❌ escalation (v0.10.49) — except: pass を削除、ベクトル検索が死んでる状態を doctor で ❌ 表示
- Off-list Ollama models flag (v0.10.50) — dolphin-phi など PREFERRED に無いモデルだけ入れてる silent 品質崩壊を info 提示
- doctor --deep (v0.10.51) — end-to-end search smoke test
- Settings tab warm GUI + wizard warm integration (v0.10.52–53)
- GitHub Issue prefill (v0.10.54) — 診断情報 URL 埋込みで 5→2 手順
- Search empty-state active filter chips (v0.10.55)
- doctor --fix (v0.10.56) — safe in-process auto-repair
- /api/doctor endpoint + GUI 診断ボタン (v0.10.57 broken → v0.10.58 hotfix)
- Wizard Anthropic API key hint (v0.10.59)
- /api/doctor parse fix + regression pytest (v0.10.60)
Retrieval quality: Honda 100-test 9/9 solved (v0.10.42–46):
- Cascade retrieval (v0.10.42) — auto-retry at min_relevance thresholds 20 → 10 → 0 when hit count is 0
- Temporal query router (v0.10.43) — 「昨日」「3ヶ月前」等の time phrases がヒットするクエリで get_recent_chat / get_flashback への recall_suggestion を返す
- signal_score filter in flashback (v0.10.44) — newsletter noise が朝の flashback を汚さないよう floor 30 でカット
- Cross-lingual query expansion (v0.10.45) — LLM expand prompt が英↔日相互翻訳を必ず含める形に (Iki Gold potato ↔ 壱岐黄金じゃがいも)
- Partial-match rerank boost (v0.10.46) — 4+ token queries で ≥50% 一致に比例ブースト (hits/total * 0.5)、8-token 自然文で 6/8 一致が 0 → +0.375 に
Bunshin Memory rename (v0.10.27) — disambiguates from the similarly-named bunshin.app (a Tauri-based Claude Code wrapper, different category). The CLI binary stays bunshin for backwards compatibility.
Pin-context (v0.10.28–32) — user-authored hard constraint on an entity's AI description, reachable from CLI / relationships tab / settings panel / MCP. Solves "the records reflect what I've been talking about, not what this entity actually is."
Nominatim geocoder + photos-relabel-places (v0.10.23–26) — GPS-based place entities now use modern admin names (諫早市) instead of historical Wikipedia article titles (小栗村 (長崎県)) or building names (Barcelona City Hall).
Entity hygiene trio (v0.10.18–19, v0.10.21) — find-duplicates detects NER variants, merge-entities collapses them, doctor surfaces the count so you know when cleanup is due.
MCP self-introspection (v0.10.22) — get_server_info exposes record / entity / source counts so a connecting LLM can decide whether to lean on search_memory at all.
Entity-extraction prompt revamp (v0.10.11–12) — startup migration heals existing miscategorized entities (websites flagged as places, software features flagged as places, ML concepts flagged as places).
Hidden Honda-DB cleanups already applied — 8 photo place entities renamed via Nominatim, 5 merged into canonical forms, 6 main-business entities pinned with off-screen reality.

Testing

78 pytest cases run on every push against a matrix of Ubuntu × macOS × Python 3.10/3.11/3.12 (see the CI badge above). New v0.10 features have dedicated regression suites:

test_entity_hygiene.py (4) — merge-entities SQL, find-duplicates normalize, pin round-trip, tool-keyword reclassify
test_pin_surfacing.py (12) — pin-list endpoint, search_memory substring match, get_today_hero LIMIT+sort, list_top_entities batched lookup, export/import round-trip, cascade retrieval threshold order, temporal query router, flashback signal filter, bilingual expansion prompt, partial-match boost tiers
test_photos_place_regex.py (4) — v0.10.14 dab-tail regex regression protection
test_doctor_json.py (9) — doctor --json/--deep/--fix output contracts, status --json shape, CliRunner path (v0.10.58 regression guard), off-list Ollama predicate

Plus the existing 46 covering storage, chunking, iMessage, PDF OCR, insights, notes, scheduler, knowledge graph. Run locally: uv run pytest.

Status

Phase 0  Prototype                        ━━━━━━━━━━━━━━━━━━━━ 100%
Phase 1  MVP (search / chat / ingest)     ━━━━━━━━━━━━━━━━━━━━ 100%
Phase 2  Native Mac app (Electron)        ━━━━━━━━━━━━━━━━━━━━ 100%
Phase 3  Multi-source ingestion polish    ━━━━━━━━━━━━━━━━━━━━ 100%   ← v0.3.x
Phase 4  Pro / Team features              ░░░░░░░░░░░░░░░░░░░░   0%

Known limitations

macOS only for now. Linux scheduler exists (systemd --user / cron); UI works in any browser. Windows untested.
macOS code signing not configured — first launch needs right-click → Open, or xattr -dr com.apple.quarantine /Applications/Bunshin.app.
iMessage requires Full Disk Access on the terminal / Python process. The CLI prints a Japanese guide when it can't read chat.db.
Photos.app OCR is opt-in via --with-ocr because each item has to be exported through Photos.app first (slow).
Whisper backends need a separate pip install (we don't ship one by default).

Customizing for your context

Bunshin ships with no personal data. To make the knowledge graph aware of your own organizations, places, and concepts, create ~/.bunshin/entities.json:

[
  {
    "name": "My Company",
    "type": "organization",
    "aliases": ["MyCo", "MCO"],
    "description": "My main company"
  },
  {
    "name": "Tokyo",
    "type": "place",
    "aliases": ["東京"]
  }
]

Then run bunshin graph rebuild to link existing records.

Types: project, organization, person, place, tool, concept, topic.

License

MIT — see LICENSE.

Contributing

Open issues for bugs and feature requests. PRs welcome — please discuss substantial changes in an issue first.

Acknowledgments

Built on the shoulders of:

SQLite + sqlite-vec
FastEmbed (ONNX, no torch)
FastAPI + Uvicorn
Ollama
MCP protocol from Anthropic
Electron + electron-builder
macOS Vision framework (text recognition)
Claude Code (used to write 90% of this)

日本語ドキュメント

完全な日本語版は README.ja.md。

Name		Name	Last commit message	Last commit date
.github		.github
docs		docs
electron-app		electron-app
scripts		scripts
src/bunshin		src/bunshin
tauri-app		tauri-app
tests		tests
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.ja.md		README.ja.md
README.md		README.md
bunshin.spec		bunshin.spec
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Navigation Menu

Repository files navigation

Bunshin Memory

Your past is yours. AI is just the lens.

Why Bunshin

Where Bunshin Memory fits

What it does

🔍 Search anything you've ever encountered

💬 Chat with offline LLM grounded in your past

💡 Auto-generated daily insights

📅 Timeline

🕸 Knowledge graph

🔁 Always up to date

🤖 MCP for any AI

📌 Pin off-screen reality

Ingestion sources (11 paths)

Quick start

Install the Mac app (recommended)

Or install from source

Architecture

Real-world numbers

Documentation

What's new in v0.10 (65 releases across a week)

Testing

Status

Known limitations

Customizing for your context

License

Contributing

Acknowledgments

日本語ドキュメント

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Bunshin Memory

Your past is yours. AI is just the lens.

Why Bunshin

Where Bunshin Memory fits

What it does

🔍 Search anything you've ever encountered

💬 Chat with offline LLM grounded in your past

💡 Auto-generated daily insights

📅 Timeline

🕸 Knowledge graph

🔁 Always up to date

🤖 MCP for any AI

📌 Pin off-screen reality

Ingestion sources (11 paths)

Quick start

Install the Mac app (recommended)

Or install from source

Architecture

Real-world numbers

Documentation

What's new in v0.10 (65 releases across a week)

Testing

Status

Known limitations

Customizing for your context

License

Contributing

Acknowledgments

日本語ドキュメント

About

Topics

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages