OpenAkari (Human Readme)

Open source implementation for Autonomous Knowledge Acquisition and Research Intelligence (Akari)

LLM agents can now operate as persistent researchers — selecting tasks, running experiments, recording findings, and building institutional knowledge across thousands of stateless sessions. This repo shows how.

What this is

OpenAkari is extracted from a production autonomous research system where LLM agents have been running real research — evaluating artifacts, building infrastructure, and operating an autonomous research workflow — for thousands of agent sessions and multiple projects.

This is not a framework to install. It's a reference architecture and scaffold for your AI agent to read and further operate on. See docs/repo-as-interface.md.

Want evidence that this system runs autonomously at scale? Start with docs/fleet-research.md.

Important note:

• The architectural decision records (ADRs) and many patterns in this repo are extracted from the actual operational history of Akari running on real research projects. They preserve lessons from that history, but they do not describe the open-source repo's current runnable state one-to-one.
• Openakari is a reference architecture, not a capability guarantee. The repo does not automatically reproduce Akari's autonomy or output quality in the production system.
• In practice, an Akari-like system has to be "trained" through real project work: conventions must be adapted, skills must be exercised, failures must be diagnosed, and the repo must accumulate its own operational memory.

How to use it

OpenAkari does not ship with any library, API, CLI (command line interface), or GUI (graphical user interface). The primary user of Akari is Akari itself powered by LLM agents. The repo is the interface.

Intended usage to use OpenAkari as a "dependency library" for your agent system

1. Point your LLM agent (Claude Code, Cursor, Copilot, etc.) at this repo
2. Tell it what kind of autonomous system you want to build
3. It reads the patterns, conventions, skills, and reference implementations
4. It adapts what's relevant to your project

Intended usage to use OpenAkari to carry out research projects

1. Run your LLM agent (Claude Code, Cursor, Copilot, etc.) in this repo
2. Tell it what projects you would like to do
3. It reads the patterns, conventions, skills, and reference implementations
4. It adapts what's relevant to your project

OpenAkari also ships two reference capability implementations:

1. a slack bot to report akari's operations and for human interactions
2. an example fleet system to run fast LLM models for simple work in large scale

In the Akari production system, the slack bot is the main interface of human use. However since you might not be using Slack as your favorite IM, the slack bot is only included in the OpenAkari repo as a reference.

To add your own human messaging interface to OpenAkari:

1. Clone OpenClaw.
2. Run your LLM Agent in this repo.
3. Point it to the OpenClaw folder you cloned.
4. Tell it that you would like to support a messaging interface of {your favorite IM} using openakari and openclaw code as reference.

What's inside

| Component | Description | Files | |-----------|-------------|-------| | CLAUDE.md | Agent operating manual — conventions, schemas, session discipline | 1 | | .claude/skills/ | 26 encoded judgment skills (orient, diagnose, design, critique, compound, etc.) | 25 dirs | | infra/scheduler/ | Session orchestrator — cron scheduling, local control API, safety gates, push coordination | TypeScript | | infra/scheduler/reference-implementations/ | Slack + fleet code as references for agents (not intended to work out of the box) | TypeScript | | decisions/ | 66 architectural decision records documenting every significant infrastructure choice | 66 files | | projects/akari/patterns/ | 7 evidence-backed design patterns for autonomous research | 7 files | | docs/ | Design rationale, SOPs, conventions | 15+ files | | infra/experiment-runner/ | Fire-and-forget experiment submission with progress tracking | Python | | infra/budget-verify/ | Resource tracking and budget enforcement | Python | | examples/ | Example project scaffold | 1 dir |

Key ideas

The repo is the brain. Agents have no memory between sessions. The repository encodes everything they know — findings, decisions, tasks, open questions, experimental results. If it's not committed, it doesn't exist. See docs/design.md.

Skills encode judgment. Agent capabilities decompose into four layers: code, schema, convention, skill. Skills capture the reasoning that can't be reduced to rules — how to orient at session start, how to design an experiment, how to diagnose unexpected results. See projects/akari/patterns/skills-architecture.md.

Conventions prevent drift. Stateless agents will contradict each other without anchoring. Decision records, provenance requirements, and session discipline create consistency across thousands of sessions. See decisions/.

Autonomous execution needs safety gates. Agents can run freely on routine work. Expensive or irreversible decisions go through an approval queue for human review. See projects/akari/patterns/autonomous-execution.md.

Knowledge output is the metric. Every session is evaluated by the knowledge it produces — findings, decisions, hypotheses tested. The fundamental efficiency metric is findings per dollar, not tasks completed. See CLAUDE.md.

How it compares

openakari occupies a different point in the design space from both general coding agents and general personal assistant agents:

| Dimension | General coding agents | General personal assistant agents | openakari | |-----------|------------------------|-----------------------------------|-----------| | Primary unit of work | One coding task or PR | One request, thread, or workflow | Ongoing research program across projects | | Memory | Mostly session-local or tool-local | Mostly conversation-local | Persistent institutional knowledge via repo | | Output | Code changes, fixes, refactors | Messages, coordination, reminders, actions | Findings, decisions, experiments, code, and structured records | | Governance | Usually light or human-driven | Usually human-in-the-loop | Budget enforcement, approval gates, decision records | | Autonomy horizon | Short task horizon | Short request horizon | Multi-session, long-horizon autonomous operation | | Self-improvement | Usually external to the system | Usually external to the system | The system can study and improve its own operation through the akari meta-project | | Scale | Usually one active agent | Usually one assistant per user | Scheduler supports autonomous sessions; fleet execution is provided as a reference implementation | | Human bridge | IDE/editor interaction | Chat, email, calendar, app actions | Slack/coordinator patterns are provided as reference implementations | | Skills | Prompt habits or tool use | Prompt habits or tool use | 26 explicit encoded judgment procedures |

General coding agents answer: "Can an AI help with this code task?"

General personal assistant agents answer: "Can an AI help me coordinate and execute everyday work?"

openakari answers: "Can AI agents operate as a persistent research group that studies both the world and itself?"

The design patterns

Seven evidence-backed patterns extracted from operating the system:

1. Repo as Cognitive State — The repository is the sole persistent memory. File-based state artifacts, orient-read-write cycle, archival conventions.

2. Autonomous Execution — Five-step SOP (orient/select/classify/execute/commit), scope-based approval gates, scheduled cron sessions.

3. Skills Architecture — Four-layer capability model (code/schema/convention/skill), 26 encoded judgment procedures.

4. Inline Logging — Record as you go, not at the end. Five-rule checklist, findings provenance requirement.

5. Layered Budget Enforcement — Four enforcement layers from convention to hard gate.

6. Structured Work Records — YAML frontmatter, type-specific sections, automated validation.

7. Gravity-Driven Migration — Capabilities migrate from manual to code when patterns recur 3+ times.

Reading guide

| I want to... | Start here | |---|---| | Understand how to use this repo | docs/repo-as-interface.md | | See operational evidence for autonomy at scale | docs/fleet-research.md | | Understand the core philosophy | docs/design.md | | See the agent operating manual | CLAUDE.md | | Learn the design patterns | projects/akari/patterns/ | | Read the encoded skills | .claude/skills/ | | See the end-to-end work cycle | docs/sops/autonomous-work-cycle.md | | Understand why decisions were made | decisions/ | | Create a project structure | examples/ | | See the meta-project that studies the