KIOKU v0.7.0: completing multi-agent — Gemini and Codex CLI now get automatic session logging

Context

I've been building KIOKU — a memory / second-brain OSS for Claude Code, Claude Desktop, and (since v0.6) Codex CLI / OpenCode / Gemini CLI. The v0.6 post introduced "multi-agent support" — but I want to be honest about what that meant in v0.6, and what's actually different in v0.7.

In v0.6, I shipped setup-multi-agent.sh to symlink KIOKU's skill directory into each agent's skills location. So /wiki-ingest and friends became callable from Codex and Gemini. But the automatic session logging pipeline — the hooks that capture every conversation and quietly grow session-logs/ in the background — was still Claude Code-only. You could call KIOKU's tools from Gemini, but the second-brain didn't grow on its own there.

v0.7.0 (shipped 2026-04-28) closes that gap. The headline:

In v0.6 the skills were shared. In v0.7 the memory is shared too.

What that took, and what else came along:

🔀 Multi-agent automatic session logging — Gemini CLI and Codex CLI now write to session-logs/ automatically, via a refactor that turns session-logger.mjs from a 591-line monolith into a core + three adapters
📚 Multi-agent MCP install docs — three agents' worth of config snippets, verification commands, and explicit "unverified in delegation environment" banners
🎬 Visualizer α (kioku_generate_viz MCP tool) — first user-callable surface for "see your wiki along a time axis," the alternative to Obsidian's Graph View
✅ verify-multi-agent-e2e.sh — interactive 6-step sanity checker for post-install reassurance

Plus a security-implementation pass that takes the formal policy from v0.6 and threads it through the multi-agent boundary.

https://github.com/megaphone-tokyo/kioku

1. Hook port: from monolith to core + adapters

This is the centerpiece of the release.

What was missing in v0.6

setup-multi-agent.sh (v0.6) symlinked skills, not hooks. The hook layer — hooks/session-logger.mjs, 591 lines, monolithic — was written against Claude Code's specific event schema (UserPromptSubmit / Stop / PostToolUse / SessionEnd with their particular stdin/stdout shapes). Other agents have hook systems too, but with different schemas, so the same script wouldn't run there.

The honest framing: in v0.6, "multi-agent" was a half-finished narrative. Skills moved; the automatic memory layer didn't.

The refactor

session-logger.mjs got split into a core + three adapters:

hooks/
├── session-logger.mjs         (core: agent-agnostic, processes NormalizedEvent)
├── adapters/
│   ├── claude.mjs             (normalizes Claude Code's hook schema)
│   ├── gemini.mjs             (normalizes Gemini CLI's hook schema)
│   └── codex.mjs              (normalizes Codex CLI's hook schema)
└── _common.mjs                (safeMain — exit-0 contract, shared helpers)

Each adapter takes its agent's specific hook input and produces a NormalizedEvent — a common shape the core knows how to handle. The core does masking (API key / token redaction), frontmatter generation, and file placement. The adapter doesn't get to make those decisions.

Three properties I cared about

I want to call out three design decisions because they each guard against a specific failure mode that scales poorly across multi-agent contexts.

(a) safeMain exit-0 contract

_common.mjs exports a safeMain wrapper that every adapter goes through. Whatever throws inside, the process exits 0. The reason: a misbehaving second-brain hook should never crash the agent CLI it's hooking into.

If KIOKU's hook throws unhandled, Claude / Gemini / Codex might treat it as a hook failure and propagate the error upward. Worst case: a tool the user doesn't even know they have crashes their main CLI. So KIOKU swallows its own errors and writes them to session-logs/.kioku-errors.log for the user to find later. The agent CLI never sees turbulence from KIOKU's side.

(b) Masking pipeline lives in core, not adapters

applyMasks() (regex-based redaction for API keys, bearer tokens, PEM blocks, etc.) runs once, in the core, on every event. Adapters can't bypass it. New adapters will inherit the same masking guarantees.

This pattern matches a rule I extracted in v0.5 (LEARN#9 — "external schema migrations need grep-driven full-site audits"): keep security-critical logic centralized so new sites of the same shape can't drift away from it.

(c) NormalizedEvent gets re-validated in the core

Adapters are untrusted. Even though I write the adapters and they hand NormalizedEvent to the core, the core revalidates the type, ranges, and field consistency before acting. The threat model: someone could craft a hostile event from the agent process side, smuggle it through an adapter, and try to coerce the core into writing where it shouldn't.

By treating adapters as schema-converters only — never as trust roots — adding a fourth or fifth adapter has a small security review surface. The core stays the only thing security-reviewed in depth.

Setup

# Gemini CLI hook
bash scripts/install-hooks-gemini.sh --apply

# Codex CLI hook
bash scripts/install-hooks-codex.sh --apply

# Diff-only preview (no writes)
bash scripts/install-hooks-gemini.sh --probe

--apply is a jq-driven idempotent merge into the agent's config file. Existing hook entries don't get clobbered.

2. Multi-agent MCP install docs

KIOKU's MCP server has been agent-agnostic since v0.5 (stdio, JSON-RPC) — technically usable from Codex / Gemini / OpenCode out of the box. What it lacked, until v0.7, was documentation telling users how.

docs/install-guide-multi-agent.md (and its .ja.md sibling) now ship with, for each of three agents:

Config location (~/.codex/config.toml, ~/.gemini/settings.json, ~/.config/opencode/opencode.json)
Setup snippet (copy-pasteable JSON / TOML)
Verification command (the agent's equivalent of mcp ls)
Troubleshooting (known constraints, workarounds)

The "unverified" banner

Each agent section opens with:

Verification status: unverified (install not possible in delegation environment)

This is honest signage that I couldn't fully verify the install steps end-to-end on my own machine for those agents — partly because of how my dev environment is set up, partly because some agents have install paths I don't personally use. Rather than write "this works" and hope, I'd rather say "this should work, here's the recipe, please report back."

OSS that ships multi-agent docs without acknowledging where verification was theoretical tends to age badly. I'd rather lose a little marketing polish to be transparent. When users report that a section's recipe works, the banner comes off.

3. Visualizer α — `kioku_generate_viz`

Internal scaffolding for the Visualizer landed in v0.6 (mcp/lib/git-history.mjs + mcp/lib/wiki-snapshot.mjs), but no user-facing tool called it. v0.7 makes it callable as an MCP tool:

# In Claude Desktop or Claude Code:
"Use kioku_generate_viz to make a growth timeline for wiki/some-page"
→ Generates vault/wiki/some-page.html

The HTML walks the page's git history and renders snapshots in chronological order. If Obsidian's Graph View shows you "how pages relate to each other in space," this shows you "how this page grew over time." Different question, complementary tool.

Hardening notes

The generated HTML lands in the user's vault and gets opened by Obsidian. That's a trust boundary I treated carefully:

Snapshot JSON serialized through safeJsonForScript — escapes </, U+2028, U+2029, blocks </script> injection
DOM construction uses createElement + textContent only; zero innerHTML
Inline styles are static CSS, never derived from user content

Why ship it as α

The current UI is rough. It's a static HTML page listing snapshots — no animation, no diff coloring. The polished versions (Timeline Player with playback, Diff Viewer with added/modified/removed coloring) are slated for v0.8 α.

I shipped the rough version anyway because I wanted users to have a first contact with the "wiki along a time axis" idea before v0.8 lands. It's also the first screenshotable surface KIOKU has produced — useful for the LP β work, useful as a marker that "yes, this differentiation axis exists."

4. `verify-multi-agent-e2e.sh`

After running install-hooks-gemini.sh --apply, users will reasonably want to know whether session logging actually works for them. v0.6 had no good answer beyond "look in session-logs/ after a session and see if a file appeared."

v0.7 ships an interactive 6-step verifier:

bash scripts/verify-multi-agent-e2e.sh --agent=gemini

# Step 1: gemini --version present
# Step 2: auth reminder (logged in?)
# Step 3: install-hooks --probe diff → confirm prompt
# Step 4: jq-verifies the config has the required event keys
# Step 5: prompts user to run a session in another terminal
# Step 6: inspects the latest session-logs/ file:
#   - frontmatter agent tag (says gemini)
#   - masking spot check (a planted test API key got *** redacted)
#   - Codex: per-turn git-sync count matches expected

Step 6's green output for "masking spot check pass" or "per-turn git-sync 1 commit confirmed" gives the user concrete evidence to dogfood with. Install docs alone leave a "I think it's working" feeling. The verifier upgrades that to "yes, it's working, with these specific signals."

Security implementation pass

v0.6 formalized the security policy (CVE classification, Safe Harbor, 90-day coordinated disclosure). v0.7 spends complementary effort on carrying that posture across the agent boundary:

Agent-aware self-recursion guard (§43) — buildContext({ agent }) only fires the self-recursion guard for Claude (where claude -p spawning could recurse via auto-ingest); Gemini and Codex don't have that recursion path, so the guard is narrowed there. Wider guarding would have produced false positives in non-Claude contexts.
Adapter exit-0 contract (the safeMain discussed above) — guards against DoS-by-self-fault, where a buggy adapter takes down the agent CLI.
Masking pipeline applied uniformly — applyMasks() is single-source-of-truth in the core, can't be bypassed by adding new adapters.
NormalizedEvent re-validation in core — adapters can't smuggle hostile events past the core's checks.

"Hardened LLM Wiki for Professionals" got policy backing in v0.6; v0.7 makes the implementation honor that policy at every agent boundary KIOKU now spans.

What's not in v0.7 (next up)

OpenCode hook adapter — MCP install path is documented, but the hook port is not in v0.7. It's slated as demand-driven (v0.7.x) since I haven't hit OpenCode use cases that warranted it yet. Email me if you do.
Visualizer Timeline Player + Diff Viewer UI — v0.8 α. v0.7 ships the MCP tool that produces the HTML; v0.8 polishes the HTML into the actual product.
agent: frontmatter field on session logs — currently inferred from session_id structure; v0.7.1 will add a first-class field for easier indexing.
SECURITY.ja.md remaining sections — three sections still EN-only, due by v0.7.1.

Tests / audit

All Node + Bash suites green
npm audit reports 0 vulnerabilities in runtime deps
New test suites:
- tests/hooks/adapters/{claude,gemini,codex}.test.mjs — adapter event normalization
- tests/hooks/_common.test.mjs — safeMain exit-0 contract; forged event rejection
- tests/mcp/tools-generate-viz.test.mjs — HTML escaping, zero innerHTML, </script> injection blocked
- tests/install-hooks-{gemini,codex}.test.sh — idempotent merge, jq doesn't clobber existing hooks

Full details in the v0.7.0 release notes.

Install / upgrade

New install:

# Preferred
claude plugin marketplace add megaphone-tokyo/kioku
claude plugin install kioku@megaphone-tokyo

# Or .mcpb (Claude Desktop-only users)
# Download kioku-wiki-0.7.0.mcpb from Releases, drag into Settings → Extensions

v0.6 → v0.7 upgrade:

git pull origin main
bash scripts/setup-vault.sh                      # Idempotent
bash scripts/install-hooks-gemini.sh --apply     # If you use Gemini CLI
bash scripts/install-hooks-codex.sh --apply      # If you use Codex CLI
bash scripts/verify-multi-agent-e2e.sh --agent=gemini   # Recommended sanity check

The arc

If you've been reading along, the story so far:

v0.5: ingest → persist (unified document ingestion + hot cache for cross-compaction memory)
v0.6: opening up — plugin marketplace, multi-agent skills, dashboard, formal security policy
v0.7: completing what v0.6 promised — hook layer ported across agents, multi-agent install docs, first Visualizer surface

v0.6's narrative claim was wider than v0.6's implementation reach. v0.7 closes the gap. Next cycle (v0.8 α) is about polishing what v0.7 alpha-shipped (Visualizer UI) and starting to absorb external feedback through Discord and the LP β.

If you try v0.7 with Gemini or Codex and something feels off — masking didn't redact something it should have, the verifier reports a mismatch, the install-guide steps don't reproduce in your environment — I'd genuinely love to hear about it. The "unverified" banner on the docs is meant to be removed; user reports are how it gets removed.

Summary

v0.7.0: in v0.6 the skills were shared; in v0.7 the memory is shared too
Hook port — session-logger.mjs 591-line monolith split into core + three adapters (claude / gemini / codex); Gemini and Codex CLI now auto-write session-logs/
Multi-agent MCP docs — install snippets for Codex / Gemini / OpenCode, English + Japanese, with explicit "unverified" banners
Visualizer α — kioku_generate_viz MCP tool produces an HTML viewer for a page's git history (rough UI, polished version is v0.8)
verify-multi-agent-e2e.sh — interactive 6-step post-install verifier
Security implementation pass — masking unified in core, adapter exit-0 contract, NormalizedEvent re-validated in core, Claude-only self-recursion guard
MIT licensed, feedback very welcome

https://github.com/megaphone-tokyo/kioku

Read alongside the first, second, third, fourth (v0.4), fifth (v0.5), and sixth (v0.6) posts for the full KIOKU arc.

Questions I'd love feedback on:

For agent-portable hook layers: how do you handle the case where each agent has a slightly different stdin/stdout schema for the "same" event? Adapter pattern feels right but I'm curious whether others have hit the limits of it.
For "unverified" banners on docs: have you used them in OSS, and do they help or hurt user trust? My hypothesis is that explicit honesty beats implicit hope, but I'd love counter-data.
For agent-aware security guards (e.g., my self-recursion guard that fires only on Claude): is there a clean way to test "this guard fires for agent A and not for agent B" beyond tabulating cases by hand?

Other projects

hello from the seasons.

A gallery of seasonal photos I take, with a small twist: you can upload your own image and compose yourself into one of the season shots using AI. Cherry blossoms, autumn leaves, wherever. Built it for fun — photography is a long-running hobby, and mixing AI into the workflow felt right.

Built by @megaphone_tokyo — building things with code and AI. Freelance engineer, 10 years in. Tokyo, Japan.

KIOKU v0.7.0: completing multi-agent — Gemini and Codex CLI now get automatic session logging

Context

1. Hook port: from monolith to core + adapters

What was missing in v0.6

The refactor

Three properties I cared about

Setup

2. Multi-agent MCP install docs

The "unverified" banner

3. Visualizer α — kioku_generate_viz

Hardening notes

Why ship it as α

4. verify-multi-agent-e2e.sh

Security implementation pass

What's not in v0.7 (next up)

Tests / audit

Install / upgrade

The arc

Summary

Other projects

hello from the seasons.

3. Visualizer α — `kioku_generate_viz`

4. `verify-multi-agent-e2e.sh`