Khaos Brain

Product Introduction

1. Definition: Khaos Brain is a local-first, predictive memory system for AI agents, specifically categorized as an AI agent experience layer and a structured knowledge management system. It functions as a brain-inspired cognitive architecture that organizes task execution evidence into a searchable, Git-versioned library of experience cards.
2. Core Value Proposition: It exists to solve the shallow and opaque nature of typical AI agent memory by transforming raw task data—such as workflow lessons, user preferences, and skill-use evidence—into reusable, observable, and maintainable predictive models. Its primary value is enabling AI agents to learn from cumulative experience, leading to more reliable and context-aware task execution over time.

Main Features

1. Card-Based Experience Library: The system's core is a file-based library of experience "cards." Each card is a structured, human-readable unit (like a JSON or Markdown file) that encapsulates a lesson, model, or skill dependency. These cards are not stored in a black-box vector database but as plain files within a Git repository, making them fully observable, diff-able, and mergeable. Technologies used include custom schemas (likely JSON Schema) for validation and a Git-based version control system for history and rollback.
2. Brain-Inspired Maintenance Rhythms (Sleep/Dream/Architect): Khaos Brain automates library maintenance through distinct, scheduled processes. KB Sleep handles consolidation: it merges duplicate cards, splits overly broad ones, and repairs low-confidence lessons. KB Dream performs bounded exploration, generating and testing new, under-validated hypotheses to expand the knowledge base safely. KB Architect is a meta-review process that audits the health of the installer, automation scripts, proposal queues, and the maintenance machinery itself.
3. Dual-Mode Operation (Personal & Organization): The system operates in two integrated modes. Personal Mode maintains a private, local knowledge base (KB) on each machine, preserving individual context and history. Organization Mode optionally connects to a shared GitHub repository, enabling teams to contribute and curate shared experience models and skills. The design is local-first; organization cards sync to a local cache and only become adopted after actual use, preventing the shared library from overwriting personal preferences.
4. Skill Registry with Contextual Sharing: Skill sharing is not merely file distribution. When a card depends on a skill (e.g., a Python script), the skill is bundled with the experience card that explains its purpose, applicable task classes, and boundaries. The organization's maintenance pipeline reviews both the card and the skill together. Approved skills are registered with pinned versions and content hashes, ensuring safe, versioned installation across team members' machines.
5. Desktop Card Viewer: Includes a standalone desktop application (KhaosBrain.exe for Windows, or a Python script) for visually browsing the card library. This viewer directly reads the file-based KB without requiring a web server, Electron, or Node.js. It displays metadata like source (local/organization), author, confidence score, status, and skill dependencies, providing full transparency into the agent's "memory."

Problems Solved

1. Pain Point: Traditional AI agent memory is often a shallow, opaque log or a static prompt, failing to capture the nuanced "experience models" needed for complex, real-world tasks. This leads to agents repeating mistakes and operating with limited context.
2. Target Audience: The primary users are developers and teams utilizing AI agent platforms like Codex (the initial integration target) for software development, DevOps, and system maintenance. It is particularly valuable for AI Agent Engineers, DevOps Teams, and Engineering Managers seeking to improve the reliability and autonomy of their AI-assisted workflows.
3. Use Cases: Onboarding New Team Members: An AI agent can instantly access the team's curated experience library, avoiding beginner mistakes. Complex Debugging Workflows: The agent retrieves past successful debugging "routes" for similar error signatures. Scheduled System Maintenance: The agent uses validated maintenance procedures (cards) that have evolved from past successful and failed attempts. Skill Standardization: Teams can formally review, version, and distribute useful scripts/tools alongside the context for their use.

Unique Advantages

1. Differentiation: Unlike cloud-based memory SaaS or simple note-taking plugins, Khaos Brain is local-first, Git-native, and file-based. This contrasts with competitors by offering complete data ownership, offline functionality, and integration with existing developer workflows (code review via PRs, rollback via Git history). It treats memory as a maintainable codebase, not a magic black box.
2. Key Innovation: The core innovation is the conceptualization and automation of a brain-like cognitive maintenance cycle (Awake/Sleep/Dream/Architect) for an AI agent's knowledge base. This biomimetic approach to knowledge curation—where experience is continuously consolidated, explored, and audited—moves beyond static retrieval to create a living, learning system that improves autonomously.

Frequently Asked Questions (FAQ)

1. What is Khaos Brain and how does it work with AI agents? Khaos Brain is a predictive memory system that works by having an AI agent retrieve relevant experience "cards" before a task and write new observations back after a task. These cards are then automatically organized and refined by background maintenance processes (Sleep, Dream, Architect), creating a continuously improving knowledge base for the agent.
2. Is Khaos Brain only for GitHub's Codex AI agent? While the current release is optimized and integrated for Codex, the product is conceptually an AI-agent experience layer. It can be adapted to any AI agent platform capable of pre-task retrieval, post-task write-back, local script execution, and Git repository interaction.
3. How does Khaos Brain handle privacy and local data? Khaos Brain is designed as a local-first system. Your personal task history, preferences, and private lessons are stored in a local knowledge base on your machine. The optional organization mode syncs shared cards to a local cache but does not overwrite your private data.
4. Can I use Khaos Brain for team collaboration without a dedicated server? Yes, team collaboration uses a GitHub repository (including private repos) as the shared "organization KB." This eliminates the need for a separate memory server, leveraging GitHub's existing infrastructure for permissions, branching, code review, and history tracking for your team's shared experience models.
5. How does skill sharing in Khaos Brain differ from just copying script files? Khaos Brain shares skills contextually. A skill (e.g., a deployment script) is bundled with an experience card that documents why it was created, what task types it applies to, its expected outcomes, and known limitations. This ensures skills are shared with the necessary operational knowledge, not just as isolated code.