Kernel Agent Memory

Shared project memory for Claude Code, Codex, and OpenCode.

Kernel gives Claude Code, Codex, and OpenCode a small shared memory layer for a project. It installs session hooks that read recent context at startup and write high-signal session notes plus estimated token usage at shutdown.

Kernel is intentionally small: no server, no database, no background daemon, and no runtime dependencies. Each project gets a local .kernel/MEMORY.md file that agents can share through their native hook systems.

Stack

Layer	Technology	Why it is here
Runtime	Node.js	Portable CLI and hook execution across local agent tools
Language	TypeScript	Strict, typed source for maintainable hook parsing
CLI	kernel bin	One command to initialize project memory and register hooks
Storage	Markdown + JSONL	Human-readable memory and append-only local token estimates
Hooks	Claude Code, Codex, OpenCode	Native startup/shutdown integration without a daemon
Testing	Vitest	Fast unit tests for scanners, hook input parsing, memory, and registry behavior
Local Models	Ollama	Token-free Claude Code/OpenCode experiments with local models such as Gemma
Packaging	npm	Public distribution through kernel-agent-memory
Hosting	GitHub	Public source, issues, and release history

Features

• Shared memory store — human-readable .kernel/MEMORY.md
• SessionStart context — injects the five most recent memories into new agent sessions
• SessionEnd capture — extracts decision, implementation, fix, architecture, avoid, and code-snippet lines
• Local token tracking — appends estimated usage to .kernel/token-log.json
• Agent hook registration — updates Claude Code, Codex, and OpenCode hook surfaces while preserving existing settings
• Zero runtime dependencies — offline-first and project-local

Status

• Codex hook registration has been verified with a real Codex CLI smoke test.
• Codex session capture works even when the hook payload does not include a transcript path; Kernel discovers the matching ~/.codex/sessions/**/*.jsonl file by session id or project cwd.
• OpenCode write-back reconstructs assistant messages from local ~/.local/share/opencode/storage JSON files.
• Claude Code startup injection uses SessionStart additionalContext; OpenCode startup injection uses its chat system transform hook.
• Live Claude Code and OpenCode conversation tests depend on those CLIs and the selected model provider being available locally. For token-free Claude Code testing, use Ollama as shown below.

Installation

npm install kernel-agent-memory

Setup

Build the CLI:

npm run build

Install hooks for the current user and create .kernel/MEMORY.md in the current project:

npm link
kernel init

After publishing, users can run it without cloning:

npx kernel-agent-memory init

Quick Smoke Test

Create a scratch project, install hooks, run Codex once, then inspect the shared memory file:

mkdir /tmp/kernel-smoke
cd /tmp/kernel-smoke
npx kernel-agent-memory init
codex exec --skip-git-repo-check -C "$PWD" \
  "Reply exactly: Decided: kernel smoke test memory works."
cat .kernel/MEMORY.md

You should see a codex memory entry containing the Decided: line.

Using Claude Code Without Anthropic Tokens

If you have Claude Code installed but want to route it through a local Ollama model, launch it through Ollama's Claude Code integration:

ollama launch claude --model gemma4:e4b --yes -- \
  -p "Reply with the Kernel project context you received. Do not inspect files."

OpenCode can be launched through Ollama in the same style:

ollama launch opencode --model gemma4:e4b

Development

Watch TypeScript files for changes:

npm run dev

Testing

npm test

Type Checking

Verify TypeScript without emitting files:

npm run typecheck

Architecture

Kernel consists of:

1. CLI — kernel init creates project memory and registers hooks.
2. Memory Store — .kernel/MEMORY.md stores timestamped entries by agent.
3. Session Scanner — deterministic regex heuristics extract useful snippets from transcripts.
4. Token Log — .kernel/token-log.json stores newline-delimited usage estimates.
5. Hook System — SessionStart/SessionEnd integration with Claude Code, Codex, and OpenCode.

Required Environment Variables

None. Kernel runs entirely offline.

Optional variables used by hooks:

• KERNEL_PROJECT_ROOT — project directory to read/write; defaults to process.cwd()
• AGENT_TYPE — agent label stored with memory and token entries
• KERNEL_MODEL, CLAUDE_MODEL, or OPENAI_MODEL — model label for token entries

Agent Support

• Claude Code: installs SessionStart and Stop command hooks in ~/.claude/settings.json. Claude passes JSON on stdin with cwd and transcript_path; Kernel returns hookSpecificOutput.additionalContext at startup and parses the transcript at shutdown.
• Codex: installs SessionStart and Stop command hooks in ~/.codex/hooks.json, and enables features.codex_hooks = true in ~/.codex/config.toml. Kernel also discovers Codex JSONL transcripts from ~/.codex/sessions when Codex does not pass a transcript path directly.
• OpenCode: installs a global plugin at ~/.config/opencode/plugins/kernel-memory.js. Kernel injects memory through OpenCode's experimental.chat.system.transform hook and reconstructs assistant text from local ~/.local/share/opencode/storage JSON files when the session becomes idle.

Project Structure

.
├── src/                    # TypeScript source files
│   ├── cli.ts             # CLI entry point
│   ├── agent-registry.ts  # Agent config hook registration
│   ├── memory.ts          # File-based memory store
│   ├── session-scanner.ts # Transcript snippet extraction
│   ├── token-log.ts       # Local token usage log
│   └── hooks/             # SessionStart and SessionEnd commands
├── dist/                  # Compiled JavaScript (generated)
├── .kernel/               # Kernel runtime directory (generated)
│   ├── MEMORY.md
│   ├── token-log.json
├── package.json
├── tsconfig.json
├── VERSION.md
└── README.md

Roadmap

• MCP memory tools for explicit agent reads/writes
• Dashboard for token and memory trends
• More agent adapters as hook APIs stabilize
• SQLite backend and cross-project memory index

License

MIT