{"passport":{"unfragile":{"@version":"1.0","version":"2026-05","artifact":{"id":"hn-47486287","slug":"agent-kernel-three-markdown-files-that-make-any-ai","name":"Agent Kernel – Three Markdown files that make any AI agent stateful","type":"repo","url":"https://github.com/oguzbilgic/agent-kernel","page_url":"https://unfragile.ai/agent-kernel-three-markdown-files-that-make-any-ai","categories":["ai-agents"],"tags":["hackernews","show-hn"],"pricing":{"model":"open_source","free":true,"starting_price":null},"status":"active","verified":false},"capabilities":[{"id":"hn-47486287__cap_0","uri":"capability://memory.knowledge.markdown.based.agent.state.persistence","name":"markdown-based agent state persistence","description":"Stores agent execution state, conversation history, and decision logs in plain markdown files rather than databases, enabling version control integration and human-readable state inspection. Uses a three-file markdown schema to separate concerns: agent metadata, execution context, and interaction history. State mutations are appended as markdown sections, creating an immutable audit trail without requiring external persistence layers.","intents":["I want my AI agent to maintain state across multiple invocations without setting up a database","I need to version control my agent's decision history and be able to audit what happened","I want to inspect and manually edit agent state in a human-readable format","I need my agent state to be portable and work offline without external dependencies"],"best_for":["solo developers building lightweight LLM agents","teams prototyping multi-turn agent systems with git-based workflows","developers who want state management without database operational overhead"],"limitations":["markdown parsing adds latency for large state files (>10MB); no built-in indexing or query optimization","concurrent writes to same markdown file will cause conflicts; requires external locking mechanism for multi-agent scenarios","no built-in schema validation; markdown format is unstructured and prone to manual corruption","state retrieval requires full file reads; no partial state queries or efficient filtering"],"requires":["any markdown parser (built-in to most languages)","file system write access","git or version control system (optional but recommended)","agent framework that can be extended with custom state backends"],"input_types":["agent execution context (JSON or structured data)","conversation turns (text)","decision logs (structured text)"],"output_types":["markdown files","structured state objects (parsed from markdown)","audit trails (markdown sections)"],"categories":["memory-knowledge","automation-workflow"],"confidence":0.5,"matches":0,"success_rate":0},{"id":"hn-47486287__cap_1","uri":"capability://memory.knowledge.three.file.markdown.schema.for.agent.decomposition","name":"three-file markdown schema for agent decomposition","description":"Defines a standardized three-file markdown structure that separates agent metadata, execution context, and interaction history into distinct concerns. Each file serves a specific role: metadata file contains agent configuration and capabilities, context file holds current execution state and variables, history file logs all interactions and decisions chronologically. This schema enables agents to understand their own structure and enables external tools to parse and manipulate agent state deterministically.","intents":["I want a standard way to represent agent state that any tool can understand","I need to separate agent configuration from runtime state from interaction history","I want to enable external tools to read and modify agent state without tight coupling","I need a schema that's both machine-parseable and human-editable"],"best_for":["teams building multi-agent systems with shared state formats","developers creating agent orchestration tools that need to inspect arbitrary agents","projects requiring agent state portability across different frameworks"],"limitations":["schema is markdown-based and lacks formal validation; no JSON Schema or TypeScript types provided","no versioning mechanism for schema evolution; breaking changes require manual migration","three-file split can be inefficient for agents with minimal state or very large interaction histories","no built-in support for nested or hierarchical state structures"],"requires":["markdown parser","ability to create and manage three separate files","agent framework with pluggable state backends"],"input_types":["agent configuration (YAML or JSON frontmatter in markdown)","execution variables (key-value pairs)","interaction logs (structured text)"],"output_types":["three markdown files (metadata, context, history)","parsed state objects","agent capability manifests"],"categories":["memory-knowledge","data-processing-analysis"],"confidence":0.5,"matches":0,"success_rate":0},{"id":"hn-47486287__cap_2","uri":"capability://automation.workflow.git.integrated.agent.state.versioning","name":"git-integrated agent state versioning","description":"Leverages git's native version control to track all changes to agent state markdown files, enabling rollback, branching, and audit trails without additional infrastructure. Each state mutation is committed as a git changeset with a message describing the agent action, creating a queryable history of agent decisions. Agents can inspect their own git history to understand past decisions and context, and developers can use standard git tools (blame, log, diff) to analyze agent behavior.","intents":["I want to see exactly what changed in my agent's state at each step","I need to roll back my agent to a previous state if something went wrong","I want to branch my agent's execution to explore alternative decision paths","I need to audit which agent actions led to which state changes"],"best_for":["development teams using git-based workflows","agents that need to explain their decision history to users","projects where agent behavior auditing is a compliance requirement"],"limitations":["git commit overhead adds latency per state mutation; not suitable for high-frequency state updates (>100/sec)","large binary files or very long interaction histories can bloat git repository size","requires git to be installed and initialized; adds operational complexity for cloud-deployed agents","merge conflicts in markdown files require manual resolution; no automatic conflict resolution for concurrent agent branches"],"requires":["git 2.0+","initialized git repository","agent framework that can trigger git commits on state changes"],"input_types":["agent state changes (markdown file mutations)","action descriptions (commit messages)"],"output_types":["git commit history","diffs showing state changes","branched agent execution paths"],"categories":["automation-workflow","memory-knowledge"],"confidence":0.5,"matches":0,"success_rate":0},{"id":"hn-47486287__cap_3","uri":"capability://memory.knowledge.agent.readable.state.introspection","name":"agent-readable state introspection","description":"Enables agents to parse and query their own markdown state files to understand their current context, past decisions, and available capabilities without requiring external APIs or database queries. Agents can extract structured data from markdown sections using simple parsing logic, enabling self-aware behavior where agents can reason about their own state and history. This creates a feedback loop where agents can inspect what they've done and adjust future behavior based on past patterns.","intents":["I want my agent to understand what state it's currently in and what it has done before","I need my agent to learn from its own execution history and avoid repeating mistakes","I want my agent to explain its decisions by referencing its own state and history","I need my agent to make decisions based on patterns in its own past behavior"],"best_for":["agents that need to be self-aware or explain their reasoning","multi-turn agents that benefit from learning from past interactions","systems where agents need to avoid repeating failed actions"],"limitations":["markdown parsing is fragile; agents may misinterpret malformed markdown or inconsistent formatting","no built-in query language; agents must implement custom parsing logic for each state structure","large state files can exceed context windows of LLMs, requiring summarization or filtering logic","agents may hallucinate or misinterpret their own state if markdown format is ambiguous"],"requires":["markdown parser accessible to the agent","agent framework that can read local files","LLM with sufficient context window to reason about state"],"input_types":["markdown state files","agent queries (natural language or structured)"],"output_types":["parsed state objects","agent reasoning based on state","decisions informed by history"],"categories":["memory-knowledge","planning-reasoning"],"confidence":0.5,"matches":0,"success_rate":0},{"id":"hn-47486287__cap_4","uri":"capability://tool.use.integration.framework.agnostic.state.backend.integration","name":"framework-agnostic state backend integration","description":"Provides a minimal interface that allows any agent framework (LangChain, AutoGPT, custom implementations) to use markdown files as a pluggable state backend without requiring framework-specific adapters. The three-file markdown schema is framework-neutral, enabling agents built with different tools to share and read each other's state. Integration requires only basic file I/O and markdown parsing, minimizing coupling and enabling rapid adoption across heterogeneous agent systems.","intents":["I want to use markdown state storage with my existing agent framework without rewriting it","I need multiple different agent frameworks to share and understand each other's state","I want to migrate my agent from one framework to another without losing state history","I need a state backend that doesn't lock me into a specific agent framework"],"best_for":["teams using multiple agent frameworks in the same project","developers building agent orchestration layers that need to work with diverse agents","projects with long-term requirements where framework lock-in is a risk"],"limitations":["no built-in adapters for popular frameworks; each framework requires custom integration code","framework-specific state structures may not map cleanly to the three-file markdown schema","no standardized interface definition; integration patterns are implicit rather than formally specified","debugging framework-specific state serialization issues requires understanding both the framework and markdown format"],"requires":["ability to implement custom state backend in target framework","understanding of framework's state management API","markdown parser for target language/framework"],"input_types":["framework-specific state objects","markdown files"],"output_types":["framework-compatible state objects","markdown state files"],"categories":["tool-use-integration","memory-knowledge"],"confidence":0.5,"matches":0,"success_rate":0},{"id":"hn-47486287__cap_5","uri":"capability://memory.knowledge.human.editable.agent.state.mutation","name":"human-editable agent state mutation","description":"Allows developers and non-technical users to directly edit markdown state files to modify agent state, inject context, or correct errors without requiring API calls or database tools. Markdown format is human-readable and editable in any text editor, enabling manual state corrections, testing scenarios, or rapid prototyping. Changes are immediately visible to agents on next execution, enabling tight feedback loops between human and agent decision-making.","intents":["I want to manually fix my agent's state when it gets into a bad state","I need to inject test data or scenarios into my agent without writing code","I want to edit my agent's context or instructions directly in a text editor","I need to prototype agent behavior by manually modifying state and observing results"],"best_for":["developers debugging agent behavior","non-technical users who need to adjust agent state","rapid prototyping and testing scenarios","teams where state inspection and modification is part of the workflow"],"limitations":["no validation on manual edits; users can introduce malformed markdown that breaks agent parsing","no schema enforcement; users can add arbitrary fields that agents don't understand","manual edits bypass any state mutation logic or validation in the agent framework","concurrent manual edits and agent execution can cause conflicts or data loss"],"requires":["text editor (any editor works)","understanding of markdown format and agent state schema","ability to save files"],"input_types":["markdown files (edited manually)"],"output_types":["modified agent state","updated markdown files"],"categories":["memory-knowledge","automation-workflow"],"confidence":0.5,"matches":0,"success_rate":0}],"trust":{"score":36,"verified":false,"data_access_risk":"high","permissions":["any markdown parser (built-in to most languages)","file system write access","git or version control system (optional but recommended)","agent framework that can be extended with custom state backends","markdown parser","ability to create and manage three separate files","agent framework with pluggable state backends","git 2.0+","initialized git repository","agent framework that can trigger git commits on state changes"],"failure_modes":["markdown parsing adds latency for large state files (>10MB); no built-in indexing or query optimization","concurrent writes to same markdown file will cause conflicts; requires external locking mechanism for multi-agent scenarios","no built-in schema validation; markdown format is unstructured and prone to manual corruption","state retrieval requires full file reads; no partial state queries or efficient filtering","schema is markdown-based and lacks formal validation; no JSON Schema or TypeScript types provided","no versioning mechanism for schema evolution; breaking changes require manual migration","three-file split can be inefficient for agents with minimal state or very large interaction histories","no built-in support for nested or hierarchical state structures","git commit overhead adds latency per state mutation; not suitable for high-frequency state updates (>100/sec)","large binary files or very long interaction histories can bloat git repository size","builder identity is not verified yet","no observed match outcomes yet"],"rank_breakdown":{"adoption":0.46,"quality":0.22,"ecosystem":0.46,"match_graph":0.25,"freshness":0.6,"weights":{"adoption":0.3,"quality":0.2,"ecosystem":0.15,"match_graph":0.3,"freshness":0.05}},"observed_outcomes":{"matches":0,"success_rate":0,"avg_confidence":0,"top_intents":[],"last_matched_at":null},"maintenance":{"status":"active","updated_at":"2026-06-17T09:51:04.692Z","last_scraped_at":"2026-05-04T08:09:59.925Z","last_commit":null},"community":{"stars":null,"forks":null,"weekly_downloads":null,"model_downloads":null,"model_likes":null}},"distribution":{"claim_url":"https://unfragile.ai/submit?claim=agent-kernel-three-markdown-files-that-make-any-ai","compare_url":"https://unfragile.ai/compare?artifact=agent-kernel-three-markdown-files-that-make-any-ai"}},"signature":"lMXdzZ47xDOQ6r+24liiH8IiLTEV3cf/JOtQgDVMT0bi/6u2d4T9M2zRYsFT8e6Qq3zMqApNqmBWATYFlJRJDw==","signedAt":"2026-06-22T06:38:18.737Z","signedBy":"unfragile.ai","version":1},"_links":{"self":"https://unfragile.ai/api/v1/passport/agent-kernel-three-markdown-files-that-make-any-ai","artifact":"https://unfragile.ai/agent-kernel-three-markdown-files-that-make-any-ai","verify":"https://unfragile.ai/api/v1/verify?slug=agent-kernel-three-markdown-files-that-make-any-ai","publicKey":"https://unfragile.ai/api/v1/trust-passport-public-key","spec":"https://unfragile.ai/trust","schema":"https://unfragile.ai/schema.json","docs":"https://unfragile.ai/docs"}}