iroha

Sessions scatter. iroha remembers.

English | 日本語

Persist Claude Code sessions to Notion as a living, queryable team memory — decisions (with rationale and rejected alternatives), work-state, chat-style highlights, and per-project architecture profiles. So humans and future Claude sessions can recall what was decided, why, what's unfinished, and how things are built.

Why

Claude Code now ships its own memory — but it lives on one developer's disk and is written for the agent to read back, not for a team to browse. iroha is the layer on top: it turns each session into a team-shared, human-browsable record in Notion — a decision ledger with the rationale and the rejected alternatives, a supersede history (a change of mind is itself memory), work-state, and per-project architecture. So the next session — yours or a teammate's — and any human opening Notion can see what was decided, why, what was ruled out, what's unfinished, and how things are built. The more the team uses it, the more it grows: ask "have we built something like this before?" and iroha points at the prior session, the files it changed, and why.

How it works

• The runtime is Bun + TypeScript (scripts/**/*.ts, run directly with no build step): it does the deterministic extraction (changed files, commands, metadata) from the session transcript. The intelligence (summary, decisions, classification, chat highlights) is produced by Claude inside the skills.
• All Notion reads/writes go through the Notion MCP — there is no API token. Auth is the MCP's OAuth, so setup is a single connection. Works on the free Notion plan.
• Recall is two-stage. On every prompt, a UserPromptSubmit hook runs a cheap, local BM25 search (search.ts, CJK-aware, no LLM and no network) over a tiny on-disk index and proactively surfaces the most relevant past decisions — so Claude consults them before rebuilding, at zero per-prompt latency or token cost. When that pointer isn't enough, /iroha:recall escalates to Notion's own semantic search (notion-search; on a free workspace it is scoped to your own pages — all iroha needs — full ranking may want Notion AI) for the full rationale and rejected alternatives. The local BM25 is the always-on proactive net at zero cost; the semantic stage is Notion's own search (no local models) — so recall stays dependency-free with nothing to install, and the deep /iroha:recall runs as a forked subagent to keep its bulky lookups out of the main context. On a brand-new project the proactive net stays quiet until the memory has grown enough for the ranking to be trustworthy (a cold-start gate) — better silence than a confident-but-coincidental match.
• A SessionStart hook injects the project's State (from a small repo mirror) so Claude proactively tells you where you left off and what's unfinished. After /compact or auto-compact it also re-injects the current session's own thread (your prompts + a capped recent tail), so the conversation survives compaction.
• A write-time check (a PreToolUse hook on git commit) runs the same cheap local recall over the commit subject + staged paths and, if Active decisions govern that area, adds an advisory to verify you are not silently reversing one (and to run /iroha:check). It is purely advisory — it never blocks or auto-approves the commit — and catches a course-reversal at the last moment before code lands.
• Each saved session also carries a metrics dashboard (turns, tool calls, files, duration), a collapsed full-chat audit trail, and — when the branch has one — a link to its GitHub PR (found via a bounded, fail-soft gh lookup, so a missing PR or no gh never blocks the save). /iroha:digest rolls a week or month into one page; /iroha:audit keeps the growing memory clean (duplicate decisions, State drift, stale items).

Memory model — three layers + State

graph TD
  CC["Claude Code session"] -->|/iroha:save-session| SK["save-session skill"]
  SK -->|deterministic| EX["extract.ts (Bun)"]
  SK -->|intelligence| CL["Claude"]
  SK -->|Notion MCP / OAuth| N[("Notion")]
  N --> SES["Sessions — what happened"]
  N --> DEC["Decisions — why"]
  N --> PRJ["Projects — current stack"]
  N --> ST["State — where we are"]
  ST -->|repo .iroha/state.md| HK["SessionStart hook"]
  DEC -->|notion-search| RC["/iroha:recall"]

• Sessions — what happened each session: summary, decisions made, chat highlights, changed files.
• Decisions — why the project is the way it is: rationale + rejected alternatives, with supersession history (a change of mind is itself memory).
• Projects — what the project is now: languages, key libraries, dev tooling, CI, an architecture diagram — for onboarding and cross-project search.
• State page — the always-current "where are we / what's unfinished", injected at session start.

Requirements

• Claude Code
• Bun ≥ 1.1 — the runtime for iroha's hooks and skills. Claude Code does not bundle it, so install it first (curl -fsSL https://bun.sh/install | bash) and check bun --version. Without Bun every hook and skill fails with bun: command not found.
• A Notion account with the hosted Notion MCP connected (OAuth). Works on the free plan: the always-on proactive recall and your project State are fully local (no Notion, no Notion AI). The deep /iroha:recall uses Notion's own search — on a free workspace it is scoped to your own pages (which is all iroha needs); full semantic ranking may require Notion AI.

Install

In Claude Code:

/plugin marketplace add iroh4-labs/iroha-for-memory
/plugin install iroha@iroha-for-memory

Getting started

1. Connect Notion MCP — run /mcp, pick notion, and complete the OAuth in your browser.
2. /iroha:init — creates the Sessions / Decisions / Projects databases (plus Recent / Active / By-Language views) under a Notion page you choose. Re-running it on a shared page lets a teammate join the same workspace.
3. /iroha:save-session — save the current session.
4. /iroha:recall <query> — "did we decide against X? why?" / "have we built this before?".
5. /iroha:project — record (or refresh) the project's tech stack. Manual, engineer-reviewed.

Commands

Command	What it does
/iroha:init	One-time setup (idempotent): create or join the Notion databases + views.
/iroha:save-session	Save this session: summary, decisions, rules changed, work-state, highlights, changed files.
/iroha:decide "<topic>: <choice>"	Record one decision (rationale + rejected alternatives) the moment you make it — the lightweight capture that grows the ledger between full saves.
/iroha:recall <query>	Semantic search over Sessions + Decisions for past decisions and similar prior work.
/iroha:history <topic>	Walk a decision's supersede lineage — how and why the choice evolved (v3 ← v2 ← v1), with the reason at each step. Read-only.
/iroha:project	Capture/update this project's architecture profile (manual).
/iroha:digest [week|month|range]	Roll a period up into one digest: decisions, sessions, aggregate metrics, what's still open, and a timeline.
/iroha:audit [--fix]	Health-check the memory (duplicate decisions, State drift, stale items); optionally apply safe, reversible fixes.
/iroha:check	Check the current working changes (git diff + new files) against the project's Active decisions and flag conflicts before you commit. Read-only.

What iroha is not

• No secrets. No API token to manage — Notion auth is MCP OAuth only; only non-secret ids are cached locally.
• No relation properties. Session↔Decision links use a URL property (a known relation-write bug in the Notion MCP); promotable to native relations once stable.
• No verbatim transcript dump. The curated highlights are the headline — their You lines anchored to your real messages (never invented). A cleaned, per-turn-capped full-chat audit trail sits collapsed underneath, with thinking and tool noise stripped.
• No save coercion. Hooks remind, they don't block.

Design

• Architecture invariants: .claude/rules/architecture.md
• Project notes & scope: CLAUDE.md
• Contributing: CONTRIBUTING.md · Security: SECURITY.md

License

MIT © Shunichi Hirata