Agent Kernel: Three Markdown Files for Stateful AI Agents

What Agent Kernel Does

Agent Kernel is a minimal implementation that makes AI coding agents stateful using three markdown files and a git repository. Instead of requiring databases, vector stores, or custom frameworks, it leverages the existing mechanism where agents read project instructions from files like AGENTS.md, CLAUDE.md, or .cursorrules.

Core Components

The kernel consists of three markdown files:

• AGENTS.md – The kernel itself (generic, don't edit)
• IDENTITY.md – Defines who the agent is (maintained by the agent)
• KNOWLEDGE.md – Index of knowledge files (maintained by the agent)

Two directory structures handle different types of memory:

• knowledge/ – Contains state information: facts about how things are right now. The agent updates these when reality changes.
• notes/ – Contains narrative information: daily session logs that record decisions, actions, and open items. These are append-only and never modified after the day ends.

Setup and Usage

Basic setup with any coding agent:

git clone https://github.com/oguzbilgic/agent-kernel.git my-agent
cd my-agent
opencode # or claude, codex, cursor, etc.

With kern-ai (a runtime built for agent-kernel that adds daemon mode, Telegram, and Slack integration):

npx kern-ai init my-agent
npx kern-ai tui

When an agent first reads the kernel, it recognizes it's new and asks who you want it to be. Once configured, it remembers across sessions.

Multiple Agents and Architecture

Each agent runs in its own repository. To create another agent:

git clone https://github.com/oguzbilgic/agent-kernel.git another-agent
cd another-agent
opencode # or claude, codex, etc.

This allows running multiple specialized agents (homelab, investing, health) with the same kernel but different identities and knowledge bases.

How It Works

The approach works because AI agents already read files like AGENTS.md as project instructions. The kernel teaches the agent how to remember by providing a file that says "you are stateful, here's how" and using the git repository to store memory in plain markdown files.