megaphone

Posted on Apr 17

I built KIOKU — an OSS memory system for Claude Code

#claudecode #ai #obsidian #opensource

The Problem

I use Claude Code every day. It's an incredible tool — but it has one major weakness.

Every new session starts from zero.

The project context I explained yesterday? Gone. The design decision we debated for 30 minutes? Forgotten. The tech stack rationale? I'm explaining it again.

I got tired of repeating myself, so I built a memory system.

KIOKU — Memory for Claude Code

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

"KIOKU" means "memory" in Japanese. The concept: a "second brain" that grows as you use Claude Code, and feeds your past knowledge back into every new session.

Inspiration

The core idea comes from Andrej Karpathy's LLM Wiki gist — the concept of growing a structured wiki from LLM conversations.

When I read it, I thought: "This is exactly what I need." But the gist is a concept, not an implementation. So I built it specifically for Claude Code, with full automation.

What Happens When You Install KIOKU

🗣️  You chat with Claude Code as usual
         ↓  (everything is recorded automatically — you do nothing)
📝  Session logs saved locally
         ↓  (a scheduled job asks AI to read the logs and extract knowledge)
📚  Wiki grows with each session — concepts, decisions, patterns
         ↓  (synced via Git)
☁️  GitHub keeps your Wiki backed up and shared across machines

The key point: you don't do anything. No note-taking, no log management. Just use Claude Code normally, and the wiki grows in the background.

Architecture

KIOKU has a 4-layer design.

L0: Auto-Capture

Claude Code's Hook system captures session I/O. I use four hook events:

UserPromptSubmit — your prompts
Stop — Claude's responses
PostToolUse — tool execution results
SessionEnd — session finalization

These write Markdown logs to session-logs/ in your Obsidian Vault. The hook script is a zero-dependency .mjs file with no network access whatsoever.

L1: Structuring

A scheduled job (macOS LaunchAgent / Linux cron) runs periodically. It feeds unprocessed logs to claude -p, which generates structured wiki pages:

Concept pages — technical concepts and patterns
Project pages — project-specific context, tech stack, design principles
Decision pages — why a specific decision was made (with context and rationale)
Session analyses — per-session knowledge extraction

L2: Integrity Checks

Monthly health checks scan the entire wiki. Broken wikilinks, missing frontmatter, orphaned pages — all detected and reported in wiki/lint-report.md. Automatic secret leak detection is included here too.

L3: Sync

The Vault itself is a Git repository. SessionStart runs git pull, SessionEnd runs git commit && git push. This syncs the wiki across machines via a GitHub private repo.

Crucially, session-logs/ never reach Git. They're excluded via .gitignore and stay local per machine. Only the distilled wiki/ is shared.

Wiki Context Injection — The Core

This is the heart of KIOKU.

At SessionStart, wiki/index.md is injected into the system prompt. This means Claude starts every new session already knowing what you've worked on before.

Design decisions from yesterday? Already in Claude's head. Your project's tech stack? No need to explain again.

Technical Deep Dives

Secret Masking

This is where I spent the most effort.

Claude Code sessions can contain API keys and tokens in prompts and tool output. Logging these raw would be a security risk.

session-logger.mjs implements regex-based masking for tokens from:

Anthropic / OpenAI / GitHub / AWS
Slack / Vercel / npm / Stripe
Supabase / Firebase / Azure
Bearer / Basic auth tokens
URL-embedded credentials
PEM private keys

Detected tokens are replaced with *** before being written to disk.

However, regex masking isn't perfect. New token formats from new services can slip through. That's why there's a secondary defense: scan-secrets.sh runs monthly to detect masking failures.

.gitignore Guard

Excluding session-logs/ in .gitignore isn't enough on its own.

Before every git commit at SessionEnd, KIOKU verifies that .gitignore still contains session-logs/. If someone accidentally modifies .gitignore, this guard prevents session logs from being pushed to GitHub.

Hook Recursion Prevention

This one bit me hard.

The auto-ingest job calls claude -p to process logs. But claude -p is itself a Claude Code session, which triggers hooks. So you get logs of "the session that processes logs," which triggers another processing attempt... infinite recursion.

The fix is a double guard:

Env var guard: Set KIOKU_NO_LOG=1 before calling claude -p. The hook script checks this variable and returns early.
cwd check: If the current working directory is inside the Vault, skip logging.

If either guard fails, the other catches it.

LLM Permission Restriction

The claude -p calls in auto-ingest and auto-lint run with --allowedTools Write,Read,Edit.

Bash is not allowed.

Wiki generation only needs file read/write. Allowing Bash would create unnecessary risk — if there were ever a prompt injection issue, the blast radius would be much larger.

Real-World Usage

I run KIOKU on a two-Mac setup: a MacBook (primary dev machine) and a Mac mini.

session-logs/ stays local per machine
wiki/ syncs via Git
Ingest schedules are offset by 30 minutes to avoid Git conflicts (MacBook: 7:00/13:00/19:00, Mac mini: 7:30/13:30/19:30)

After running it for several weeks, the difference is bigger than I expected.

Where it helped most:

Design decision continuity: "Yesterday we chose Y over X for performance reasons" carries over automatically to the next session
No more tech stack explanations: The project's technology context is already there
Failure memory: "We tried approach Z before and it didn't work because..." is recorded and available

What I'd Do Differently

Looking back, a few things I'd change:

Start with a simpler wiki schema

I over-engineered the note templates from the start — concept pages, project pages, decision pages, all with detailed templates. In hindsight, starting with "just dump everything as notes" and organizing later would have been more natural.

Ingest prompt tuning matters more than I thought

Wiki page quality depends almost entirely on the ingest prompt. My first version said "extract all insights" — way too noisy. Narrowing it to "only extract what you'd actually need in the next session" made a huge difference. This tuning is still ongoing.

Setup

KIOKU has an interactive setup. Just enter this in Claude Code:

Please read skills/setup-guide/SKILL.md and guide me through the KIOKU installation.

Claude Code itself walks you through each step, explaining what it does and adapting to your environment. Manual setup instructions are also in the README — only 5 required steps.

Roadmap

Multi-LLM support: Currently Claude Code (Max plan) only. Planning to make the LLM backend pluggable (OpenAI API, local models via Ollama, etc.)
Morning Briefing: Auto-generated daily summary — yesterday's sessions, open decisions, new insights
Project-aware context injection: Filter injected wiki content by the current project (based on cwd)
Team Wiki: Multi-person wiki sharing (each member's session-logs stay local; only wiki/ syncs via Git)

Wrapping Up

Claude Code is a powerful tool, but the lack of cross-session memory is a significant gap. KIOKU fills that gap by automatically growing a knowledge base from your conversations and feeding it back into every new session.

It's an implementation of Karpathy's LLM Wiki concept, specialized for Claude Code and fully automated. MIT licensed.