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=1before callingclaude -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.
https://github.com/megaphone-tokyo/kioku
Feedback, issues, and PRs are very welcome. I'm especially interested in hearing about:
- Is the wiki directory structure intuitive?
- How should the ingest selection criteria be tuned?
- Which LLM backends should be prioritized for multi-LLM support?
Built by @megaphone_tokyo — building things with code and AI. Freelance engineer, 10 years in. Tokyo, Japan.
