agent-kernel: Markdown-File Memory for Any AI Coding Agent
Minimal kernel to make any AI coding agent stateful. Clone, point your agent, go.
At a glance
- What is it?
- agent-kernel is a git repository of three markdown files that gives a coding agent persistent identity and memory. It installs by cloning the repo, and its memory model splits mutable facts from append-only session notes.
- Who is it for?
- agent-kernel suits anyone who wants an agent with continuity but does not want to run a database or adopt a framework: clone the repo, open your coding agent in it, and the agent maintains IDENTITY.md, KNOWLEDGE.md, knowledge/ and notes/ itself. It is the wrong tool if you need structured queries over memory, cross-agent shared state, or a hosted runtime, because the README describes plain markdown files in a git repo and nothing else.
- Can I use it commercially?
- Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
- Is it still maintained?
- Yes. The repository last received commits 177 days ago.
- What is it written in?
- GitHub does not report a main language for this repository.
Answers come from the project's GitHub data, last synced on September 18, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem agent-kernel solves: amnesia between sessions
A coding agent opened in a fresh directory starts from zero. It does not know what it decided yesterday, what it learned about your infrastructure, or who it is supposed to be. The usual fixes are a framework, a vector store, or a database, and each of those adds a runtime you have to keep alive.
agent-kernel takes the opposite route. The README states the project is "just three markdown files and a git repo", with no framework and no database. The intended user is someone who already runs a coding agent such as OpenCode, Claude Code, Codex, Cursor or Windsurf and wants that agent to remember across sessions. The repository is a template: you clone it once per agent, and the clone becomes the agent's home directory and its memory store at the same time. The README frames each clone as its own agent, giving the examples of a homelab agent, an investing agent and a health agent running "the same OS".
How the kernel works: AGENTS.md as the memory instruction
The mechanism is not a plugin or an API. Coding agents already read project instruction files such as AGENTS.md, CLAUDE.md or .cursorrules when they start in a directory. agent-kernel exploits that: AGENTS.md is the kernel, and the README says it is generic and should not be edited. Everything else in the repository is data the agent writes.
The memory is split into two kinds, and the distinction is the most interesting design decision in the project. knowledge/ holds state, described as facts about how things are right now, and the agent updates those files when reality changes. notes/ holds narrative, the daily session logs recording decisions, actions and open items. The README says notes/ is append-only and never modified after the day ends. That is a deliberate constraint: it keeps a chronological record that later sessions can read without a merge conflict, while mutable facts live in separate files. IDENTITY.md holds who the agent is, and KNOWLEDGE.md is an index of the knowledge files. Both are maintained by the agent, not by you.
The top-level repository entries confirm the layout: AGENTS.md, IDENTITY.md, KNOWLEDGE.md and README.md, with knowledge/ and notes/ as directories. Persistence is git's job. The README does not describe any commit, push or sync automation, so how memory survives a machine change depends on you committing the repository.
Installing agent-kernel and starting a first agent
There is no package to install for the base project. The README's quick start is a clone followed by launching your coding agent inside the clone. The clone directory name becomes the agent's directory, so name it after the agent you want.
git clone https://github.com/oguzbilgic/agent-kernel.git my-agent
cd my-agent
opencode # or claude, codex, cursor, etc.After the agent starts, the README says it reads the kernel, realizes it is new, and asks who you want it to be. You answer in the conversation, and the agent writes that answer into IDENTITY.md. That file is the first thing to inspect afterwards: if the agent has recorded an identity there, the kernel is working as documented.
For a second agent, the README repeats the same clone with a different directory name, which is the whole multi-agent story: same kernel, different identity, different knowledge.
git clone https://github.com/oguzbilgic/agent-kernel.git another-agent
cd another-agent
opencode # or claude, codex, etc.The README also points to a separate project, kern-ai, described as a runtime built for agent-kernel with daemon mode and Telegram and Slack channels. That one is initialized differently, and the README gives the command as npx kern-ai init my-agent followed by npx kern-ai tui. Note that kern-ai is a different repository from agent-kernel.
What agent-kernel does not do
The memory is text, and the retrieval is whatever your coding agent does with files it reads. There is no index, no embedding, no query language, and no schema. As the knowledge directory grows, the agent's ability to find the relevant file depends on KNOWLEDGE.md staying a useful index, and the README does not describe any mechanism that enforces or rebuilds it.
The append-only rule for notes/ is a constraint the agent is instructed to follow, not one the filesystem enforces. Nothing in the repository layout prevents an agent from rewriting a past session log. The same applies to the separation between knowledge/ and notes/: it holds only as long as the agent respects the kernel's instructions, and the README does not document a validation step or a repair command for a memory directory that has drifted.
There is also no documented rollback story. Because memory is a git repository, reverting a bad edit is a git operation on your side, but the README does not describe how an agent should behave if its own memory is reverted underneath it. Teams that need concurrent writers to one memory store, or structured queries across many agents, should look elsewhere; a shared markdown directory with no locking is the wrong substrate for that. Finally, the project is a template, so upgrading means reconciling your edited clone with a newer AGENTS.md, and the README does not describe an upgrade path.
How this differs from memory layers like Mem0 or Letta
The obvious alternative is a memory service that stores agent state in a database and retrieves it through an API, with Mem0 and Letta being well-known examples of that shape. The difference is where the memory lives and who reads it. A memory service owns the store, exposes retrieval over an API, and typically needs a process or a hosted endpoint running. agent-kernel owns nothing: the store is a directory of markdown files, retrieval is the agent reading files the way it already reads project instructions, and the runtime is your existing coding agent.
That trade buys portability and inspectability. You can open notes/ in any editor, diff a session in git, and move the whole agent by moving a directory. It costs you everything a database gives you: no similarity search over past sessions, no schema, no concurrent access guarantees, and no programmatic API for another system to query the agent's knowledge. A memory service is the better choice when several services need to read the same memory or when the corpus outgrows what an agent can scan. agent-kernel is the better choice when the agent is the only reader and you want the memory to be plain files in a repository you already know how to version.
Maintenance, licence and what to check before adopting
The repository is not archived, and the last push was on 2026-03-25. There are no releases recorded, which fits a template repository: there is no versioned artifact to upgrade, only the files themselves.
The README states the licence is MIT. The repository listing does not record a licence, so if the licence matters to your organisation, confirm it against the LICENSE file in the clone rather than the README line. MIT permits commercial use and modification with the copyright notice retained, but that is a description of the licence text, not legal advice for your situation.
Because the base project is a clone-and-edit template, the maintenance cost sits with you. Your clone will diverge from upstream as soon as the agent writes IDENTITY.md and knowledge files, so pulling later changes to AGENTS.md means merging kernel instructions into a repository full of your agent's memory. Decide early whether you treat the clone as a fork you own or as something you intend to track, because the two choices lead to different git habits. The repository topics list claude-code, codex-cli, opencode and openclaw, which is the set of agents the project positions itself around.
Editorial conclusion
agent-kernel suits anyone who wants an agent with continuity but does not want to run a database or adopt a framework: clone the repo, open your coding agent in it, and the agent maintains IDENTITY.md, KNOWLEDGE.md, knowledge/ and notes/ itself. It is the wrong tool if you need structured queries over memory, cross-agent shared state, or a hosted runtime, because the README describes plain markdown files in a git repo and nothing else. Before adopting it, verify what the kernel actually instructs by reading AGENTS.md in the repository, and confirm the MIT licence text in the LICENSE file, since the README states MIT but the licence metadata is not recorded in the repository listing.
Frequently asked questions
What is agent-kernel and why is it used?
agent-kernel is a minimal kernel that makes an AI coding agent stateful, distributed as a git repository of markdown files. It is used so an agent remembers between sessions, takes notes, and builds on past work without a framework or database.
Which AI coding agents does agent-kernel work with?
The README states it works with any AI coding agent and names OpenCode, Claude Code, Codex, Cursor and Windsurf as examples. The mechanism is the project instruction file the agent already reads, such as AGENTS.md, CLAUDE.md or .cursorrules.
How do I download and start agent-kernel?
Clone the repository into a directory named after your agent, then launch your coding agent there. The README's quick start is git clone https://github.com/oguzbilgic/agent-kernel.git my-agent, cd my-agent, then opencode or claude or codex.
What is the kernel in an LLM agent context?
In agent-kernel, the kernel is the AGENTS.md file, described in the README as generic and not meant to be edited. It teaches the agent how to remember, while IDENTITY.md, KNOWLEDGE.md, knowledge/ and notes/ hold what the agent remembers.
Community notes