Skip to content
/
Tier A A8 Cross-runtime harness

OneBrain

onebrain · onebrain-ai/onebrain · ★ 10 · last commit 2026-05-22

Give AI agents persistent memory, 34 skills, and personal calibration via an Obsidian vault so every session picks up exactly where the last one left off — across any harness.

Best whenYour AI should co-evolve with you — every correction sharpens the agent, every link it surfaces sharpens you — using plain Markdown you own forever.
Skip ifCloud sync (local-first only), External databases (Markdown is the memory)
vs seeds
agent-os(behavioral OS layer, markdown-first, harness-agnostic) but differs in four concrete ways: Obsidian as the vault UI laye…
Primitive shape 35 total
Skills 34 Hooks 1
00

Summary

OneBrain — Summary

OneBrain (onebrain-ai/onebrain) is an AI operating system layer built on top of Obsidian that gives AI agents persistent memory, a structured knowledge vault, and 34 pre-built skills — so every session picks up exactly where the last one left off. It is harness-agnostic (Claude Code, Gemini CLI, Codex, Qwen, or any LLM via API key) and uses plain Markdown files in an Obsidian vault as the durable source of truth. The four-tier memory system (Working → Episodic → Semantic → Knowledge) promotes information downward as it earns trust. A companion CLI (onebrain-cli, written in Rust, separate repo) handles vault sync, indexing, and harness routing. A single SessionStart hook checks CLI version compatibility. The 34 skills cover the full knowledge workflow: braindump, capture, bookmark, research, distill, learn, wrapup, recap, memory-review, daily, weekly, scheduling, tasks, and more.

Differs from seeds: closest to agent-os (behavioral OS layer extending AI harnesses, markdown-first) but OneBrain adds a formal four-tier memory promotion system, 34 skills (vs agent-os's 5 commands), Obsidian as the vault/UI layer, harness-agnostic design, and an auto-checkpoint/auto-session-summary system. Also closest to ccmemory (persistent memory, global persistence) but OneBrain uses plain Markdown instead of Neo4j, and does not require any external database.

01

Overview

OneBrain — Origin and Philosophy

Origin

Organization: onebrain-ai. 10 stars (brand new as of May 2026). AGPL-3.0 license. Created March 2026, last push May 2026. Shell primary language. Single contributor (based on star/fork count). Website: onebrain.run.

Philosophy: The Harness OS Architecture

From README:

"Your AI forgets everything when the session ends. Your notes, your AI, and your tools live in separate silos. OneBrain fixes both — giving you a thinking partner that remembers everything."

"Most tools ask you to query an AI. OneBrain co-evolves with you — every preference you teach sharpens the agent, every link it surfaces sharpens you."

The Harness OS Architecture: OneBrain doesn't compete with Claude Code, Gemini CLI, or any other AI harness — it extends them:

Layer 1: OneBrain (plugin + CLI) — 34 skills, hooks, vault sync, memory
Layer 2: Harness — Claude Code, Gemini CLI, Codex, Qwen, ...
Layer 3: LLM — Local (mlx, ollama) or cloud
Layer 4: Obsidian Vault — Plain Markdown, source of truth

The Bidirectional Flow

  • Human → Agent — Every preference, decision, and correction becomes persistent memory. The agent calibrates to you with every interaction.
  • Agent → Human — Captures, classifies, links, and synthesizes the noise of your day — so your attention stays on what only you can do.

Memory Promotion Philosophy

Knowledge moves down the memory stack only as fast as it earns trust:

  • Raw captures → Working (inbox)
  • Session summaries → Episodic (logs)
  • Behavioral patterns → Semantic (memory files, lazy-loaded)
  • Identity/critical behaviors → Semantic always-loaded (MEMORY.md)
  • Synthesized insights → Knowledge (permanent)

Auto-Behaviors Philosophy

From INSTRUCTIONS.md:

"Auto Checkpoint: Every 15 messages, every 30 min, or before context compression" "Auto Session Summary: You say 'bye' → fires silently and saves a session log. If you already ran /wrapup: skips — the log was already written."

02

Architecture

OneBrain — Architecture

Distribution

Clone + plugin install:

git clone https://github.com/onebrain-ai/onebrain.git
# Then install the Claude Code plugin from .claude/plugins/onebrain/

A companion CLI (onebrain-cli, Rust, separate repo: onebrain-ai/onebrain-cli) handles vault sync, indexing, and harness routing.

Required Runtime

  • Claude Code (or Gemini CLI, Codex, Qwen — harness-agnostic)
  • Obsidian (for vault management — optional but recommended for full experience)
  • tmux (for multi-harness terminal management — optional)
  • onebrain-cli >= 3.0.0 (Rust binary — version checked at SessionStart)

Directory Structure (Claude Code plugin)

.claude/plugins/onebrain/
├── .claude-plugin/
│   └── plugin.json          # version 3.0.3; requires cli >= 3.0.0
├── hooks/
│   ├── hooks.json           # SessionStart: check-cli-version.sh
│   └── check-cli-version.sh
├── INSTRUCTIONS.md          # Full agent instructions (loaded via @include)
├── agents/
├── references/
├── skills/                  # 34 skills (each a directory with SKILL.md)
│   ├── _shared/
│   ├── bookmark/
│   ├── braindump/
│   ├── capture/
│   ├── clone/
│   ├── connect/
│   ├── consolidate/
│   ├── daily/
│   ├── distill/
│   ├── doctor/
│   ├── help/
│   ├── import/
│   ├── learn/
│   ├── memory-review/
│   ├── moc/
│   ├── onboarding/
│   ├── pause/
│   ├── qmd/
│   ├── reading-notes/
│   ├── recap/
│   ├── reorganize/
│   ├── research/
│   ├── resume/
│   ├── schedule-add/
│   ├── schedule-list/
│   ├── schedule-once/
│   ├── schedule-remove/
│   ├── search/
│   ├── startup/
│   ├── summarize/
│   ├── tasks/
│   ├── update/
│   ├── weekly/
│   └── wrapup/
└── startup/

Vault Structure (Obsidian)

Obsidian Vault/
├── 00-inbox/          # Raw captures, active conversation
├── 01-projects/       # Active projects
├── 02-areas/          # Ongoing responsibilities
├── 03-knowledge/      # Permanent synthesized notes
├── 04-resources/      # External info, summaries
├── 05-agent/          # AI-specific context
│   ├── MEMORY.md      # Always-loaded: identity + active projects + critical behaviors
│   ├── MEMORY-INDEX.md # Registry for lazy-loaded memory files
│   └── memory/        # Lazy-loaded behavioral patterns + domain facts
├── 06-archive/        # Completed projects
└── 07-logs/           # Logs (session/, checkpoint/, pause/, update/, log/)

Target AI Tools

Claude Code (primary via .claude plugin), Gemini CLI (.gemini plugin), Codex (via harness routing), Qwen. The AGENTS.md and GEMINI.md files confirm multi-harness support.

03

Components

OneBrain — Components

Hooks (.claude/plugins/onebrain/hooks/hooks.json)

Event Handler Purpose
SessionStart check-cli-version.sh Verify onebrain-cli >= 3.0.0; refuse to load if incompatible

Skills (34 total)

Skill Purpose
braindump Capture stream-of-consciousness; classify into inbox
capture Single titled idea → inbox file
bookmark Save URL with annotation
clone Copy/clone a note pattern
connect Link related notes
consolidate Batch-process inbox items
daily Daily note creation/review
distill Expand knowledge; synthesize into knowledge notes
doctor Health check on vault structure
help List available skills
import Import external files into vault
learn Write to memory files; only skill that writes to MEMORY.md Critical Behaviors
memory-review Edit/review memory files
moc Map of Content — link aggregation note
onboarding One-time vault setup; writes MEMORY.md identity section
pause Save mid-task snapshot for multi-session tasks
qmd Query management for vault searches
reading-notes Structured notes from reading material
recap Batch-promote session logs → memory files
reorganize Migrate flat notes into subfolder structure
research Systematic research workflow; output to resources/
resume Resume from pause snapshot
schedule-add Add scheduled item
schedule-list List scheduled items
schedule-once Schedule one-time event
schedule-remove Remove scheduled item
search Search vault (via qmd or Grep)
startup Session startup behavior
summarize Summarize content into knowledge notes
tasks Live task dashboard (TASKS.md)
update Update OneBrain plugin itself
weekly Weekly review workflow
wrapup End-of-session: consolidate logs, write session summary

Companion CLI (onebrain-cli, separate repo)

Rust binary. Handles: vault sync, indexing, harness routing, MCP server integration. Version constraint: >= 3.0.0.

INSTRUCTIONS.md (agent system prompt)

Loaded via @.claude/plugins/onebrain/INSTRUCTIONS.md in CLAUDE.md. Contains:

  • Configuration table (vault folder variables)
  • Role definition
  • Vault structure and file naming conventions
  • Note frontmatter requirements
  • Task syntax (Obsidian Tasks Plugin format)
  • Memory system rules
  • Auto-behavior specifications
05

Prompts

OneBrain — Prompts

Prompt 1: Braindump Skill (skills/braindump/SKILL.md)

Technique: Step-by-step behavioral script with classification table. The skill defines a conversation protocol: invite dump → silently classify → create file immediately without confirmation.

---
name: braindump
description: "Capture a stream of raw thoughts : classify them and file to inbox with action items extracted. Use when the user signals a free-form, stream-of-consciousness dump with multiple unrelated threads — 'let me dump everything on my mind'. Do NOT use for: a single titled idea (use capture), saving a URL (use bookmark), or anything structured and focused."
schedulable: false
---

# Braindump

## Step 1: Invite the Dump

Say:
> Go for it : what's on your mind? Dump everything. I'll sort it out.

Wait for the user to share their thoughts. Don't interrupt.

## Step 2: Classify the Content

Silently analyze and classify each item:

| Type | Description | Destination |
|------|-------------|-------------|
| **Task** | Something to do | Extract as task with date |
| **Idea** | Creative or speculative thought | File to inbox |
| **Note** | Fact, reference, or information | File to inbox |
| **Project** | Something needing a dedicated note | Create/update in [projects_folder]/ |
| **Question** | Open question or uncertainty | File to inbox with `?` tag |
| **Feeling/Reflection** | Personal reflection or emotion | File to inbox |

## Step 3: Create Inbox File

File immediately : do not ask for confirmation first.

Prompt 2: INSTRUCTIONS.md — Agent Identity

Technique: Configuration variable substitution + role assignment + behavioral constraints from the INSTRUCTIONS.md system prompt.

## Your Role

You are a personal chief of staff operating inside an Obsidian vault called OneBrain.
Help the user capture, organize, synthesize, and retrieve knowledge inside this vault.
Be proactive: surface connections, flag stale tasks, suggest next actions based on what you know.

> Session startup (below) handles loading MEMORY.md automatically.

## Personality

Read the `## Identity & Personality` section in `[agent_folder]/MEMORY.md` and follow it.
The agent has a name and personality set during onboarding — use the name and match the personality style.

Prompt 3: Memory Promotion Rules (INSTRUCTIONS.md)

Technique: Strict write-permission rules — each memory tier has exactly one authorized writing skill. Prevents memory pollution.

- `/wrapup` writes session logs only — does not promote to `memory/`
- `/learn` writes to `memory/` immediately; only skill that writes to MEMORY.md Critical Behaviors
- `/recap` batch-promotes from session logs → `memory/` only — does NOT write to MEMORY.md
- Only behaviors applying every session with high-impact failure if missed → MEMORY.md Critical Behaviors
09

Uniqueness

OneBrain — Uniqueness and Positioning

Differs from Seeds

Closest to agent-os (behavioral OS layer for AI agents, markdown-first, cross-harness design) but OneBrain differs in four key ways:

  1. Obsidian as vault layer: agent-os uses plain project files. OneBrain uses an Obsidian vault with its graph view, backlinks, and plugin ecosystem as the knowledge UI. This is the only framework in the corpus that explicitly integrates with a PKM (personal knowledge management) tool.

  2. Four-tier memory promotion system: agent-os has no formal memory hierarchy. OneBrain's Working → Episodic → Semantic → Knowledge stack with strict write-permission rules per skill is the most elaborate memory architecture in the corpus that doesn't require an external database.

  3. 34 skills: agent-os has 5 commands. OneBrain's skill surface covers the entire knowledge lifecycle (braindump, research, distill, learn, wrapup, recap, schedule, tasks, etc.).

  4. Harness-agnostic by design: agent-os targets Claude Code. OneBrain explicitly ships .claude/, .gemini/, and Codex support from day one.

Also related to ccmemory (global persistent memory across sessions, Claude Code plugin) but ccmemory requires Neo4j + vector DB. OneBrain is zero-external-database — Markdown files only.

Positioning

OneBrain targets knowledge workers / personal productivity users who want their AI coding agent to function as a long-term thinking partner, not just a code generator. The Obsidian integration means notes, decisions, and agent memory live in the same system as research notes and project plans. Unlike all other frameworks which target developers solving engineering problems, OneBrain targets users who have a second-brain / PKM practice and want AI to enhance it.

Observable Failure Modes

  1. Obsidian dependency: requires Obsidian installed and a configured vault. Users who don't use Obsidian need to adopt a new tool.
  2. onebrain-cli version gate: SessionStart hook refuses to load if cli < 3.0.0. Missing or outdated CLI silently blocks the plugin.
  3. AGPL-3.0 license: more restrictive than MIT. Commercial use requires AGPL compliance.
  4. Manual memory promotion: unless /recap and /learn are run, important behavioral patterns stay in session logs and don't reach MEMORY.md. Episodic → Semantic promotion requires explicit agent/user action.
  5. Brand-new (March 2026): 10 stars, 1 contributor as of analysis. Immature documentation, possible breaking changes.
04

Workflow

OneBrain — Workflow

Phases

Phase Trigger Artifact
1. Onboarding /onboarding MEMORY.md identity section; vault folder structure
2. Session startup SessionStart hook CLI version check; MEMORY.md + MEMORY-INDEX.md loaded
3. Capture /braindump, /capture, /bookmark Files in 00-inbox/
4. Evolve /research, /distill, /learn Files in 04-resources/, 03-knowledge/, 05-agent/memory/
5. Wrapup /wrapup or natural session end signal Session log in 07-logs/session/YYYY/MM/
6. Memory promotion /recap (batch) or /learn (single) Memory files in 05-agent/memory/
7. Multi-session pause/resume /pause → /resume Pause snapshot in 07-logs/pause/

Auto-Behaviors (runs without explicit invocation)

Behavior Trigger Action
Auto Checkpoint Every 15 messages, every 30 min, or before context compression Writes checkpoint to 07-logs/checkpoint/
Auto Session Summary User says "bye"/"good night"/"I'm done" AND ≥3 exchanges AND /wrapup not yet run Saves silent session log (auto-saved: true)
Phase 2 startup Next session after orphaned checkpoints Synthesizes checkpoints into session log

Memory Promotion Pipeline

session → session log (/wrapup) → memory/ files (/recap) → MEMORY.md Critical Behaviors (/learn)

Rules:

  • /wrapup writes session logs only — does NOT promote to memory/
  • /learn writes to memory/ immediately; only skill that writes to MEMORY.md Critical Behaviors
  • /recap batch-promotes from session logs → memory/ only — does NOT write to MEMORY.md
  • Only behaviors applying every session with high-impact failure if missed → MEMORY.md Critical Behaviors

Approval Gates

None. All skills execute immediately without human confirmation gates.

Co-Evolution Loop

01 CAPTURE (braindump/capture/bookmark) →
02 EVOLVE (research/distill/learn) →
03 WRAPUP (wrapup/recap) →
→ back to CAPTURE
06

Memory Context

OneBrain — Memory and Context

Four-Tier Memory System

Tier Location Content Written by
Working 00-inbox/ + current session Raw captures, active conversation /braindump, /capture, /consolidate
Episodic 07-logs/session/YYYY/MM/ Session summaries, decisions, action items /wrapup, auto-checkpoint
Semantic (always-loaded) 05-agent/MEMORY.md + 05-agent/MEMORY-INDEX.md Identity + Active Projects + Critical Behaviors + memory registry /learn, /onboarding
Semantic (lazy-loaded) 05-agent/memory/ Behavioral patterns, domain facts /learn, /recap, /memory-review
Knowledge 03-knowledge/ Permanent synthesized notes /distill

Memory Loading at Session Start

  1. MEMORY.md loaded always (identity, active projects, critical behaviors)
  2. MEMORY-INDEX.md loaded alongside (registry of lazy-loaded memory files)
  3. Specific memory files in 05-agent/memory/ loaded on demand via MEMORY-INDEX.md

Auto-Checkpoint System

Writes to 07-logs/checkpoint/YYYY-MM-DD-{session_token}-checkpoint-NN.md when:

  • Every 15 messages in session
  • Every 30 minutes
  • Before context compression (PreCompact equivalent)

These serve as recovery mechanism if session ends without /wrapup.

Cross-Session Continuity

  • /pause saves snapshot to 07-logs/pause/YYYY-MM-DD-{slug}-pause-NN.md
  • /resume loads the active pause snapshot → seamless multi-session task continuation
  • Auto Session Summary fires when user says "bye" (natural language end signal)
  • Phase 2 startup synthesizes orphaned checkpoint files into session log

Configuration

Vault folder paths are configurable via vault.yml in the vault root. INSTRUCTIONS.md uses variable substitution: [inbox_folder], [agent_folder], etc.

Memory Storage Type

File-based (plain Markdown). No external database. No vector index. No cloud sync required. The vault is the memory.

07

Orchestration

OneBrain — Orchestration

Multi-Agent

No multi-agent orchestration. OneBrain is a single-agent personal AI OS.

Execution Mode

Continuous — the agent runs with persistent memory across all sessions. Each session is a continuation of the previous one via memory tiers.

Harness Routing

OneBrain is harness-agnostic. The same Obsidian vault can be used with:

  • Claude Code (via .claude/plugins/onebrain/)
  • Gemini CLI (via .gemini/ directory)
  • Codex
  • Qwen
  • Any LLM via API key

Context (MEMORY.md, MEMORY-INDEX.md) is loaded by whichever harness is active. Switching harnesses does not lose memory.

Orchestration Pattern

Sequential within a session. The co-evolution loop (CAPTURE → EVOLVE → WRAPUP → repeat) is documented but not enforced by code — it is a behavioral guideline in INSTRUCTIONS.md.

Isolation

None. All skills write to the same Obsidian vault on disk.

Multi-Model

No multi-model routing. The agent is whatever harness is running. No model-role mapping within OneBrain.

08

Ui Cli Surface

OneBrain — UI and CLI Surface

Obsidian as UI

OneBrain explicitly positions Obsidian as the "command center" for all projects:

"Code in repos, orchestration in vault — agent dispatches from here to wherever the work actually lives." "Markdown replaces Slack / Linear / Notion — version-controlled, AI-readable, yours forever."

Obsidian provides: graph view, search, kanban plugins, calendar, backlinks, the full PKM visual layer. OneBrain does not ship its own UI — it leverages Obsidian.

Companion CLI (onebrain-cli)

Rust binary from separate repo: onebrain-ai/onebrain-cli

  • Vault sync
  • Memory indexing
  • Harness routing
  • MCP server integration
  • Version constraint: >= 3.0.0 (checked at SessionStart)

Latest release: visible via README badge github.com/onebrain-ai/onebrain-cli/releases/latest

Plugin Version

Claude Code plugin version: 3.0.3 (from .claude-plugin/plugin.json)

No Local Web Dashboard

No HTTP server. No browser UI. Obsidian is the native GUI.

IDE Integration

Harness-level — works via whichever IDE hosts Claude Code, Gemini CLI, etc. No dedicated VSCode extension.

Telegram Integration

README mentions Telegram as part of the "full local stack" alongside Claude Code + Obsidian + tmux. Likely via Telegram bot for mobile notifications/captures (not detailed in repo files).

Related frameworks

same archetype · same primary tool · same memory type

claude-mem (thedotmack) ★ 78k
A8 Cross-runtime harness

Background worker service captures every tool call as an observation, AI-compresses sessions, and auto-injects relevant past…

pi (badlogic/earendil) ★ 55k
A8 Cross-runtime harness

A minimal, hackable, multi-provider terminal coding agent that adapts to your workflows via npm-installable TypeScript Extensions…

Agent Skills (Addy Osmani) ★ 46k
A8 Cross-runtime harness

Encodes senior-engineer software development lifecycle as 23 auto-routed skills and 7 slash commands for any AI coding agent.

wshobson/agents Plugin Marketplace ★ 36k
A8 Cross-runtime harness

Single Markdown source for 83 domain-specialized plugins that auto-generates idiomatic artifacts for five AI coding harnesses.

TabbyML/Tabby ★ 34k
A8 Cross-runtime harness

Self-hosted AI coding assistant server (alternative to GitHub Copilot) with admin dashboard, RAG-based completions, and multi-IDE…

Compound Engineering ★ 17k
A8 Cross-runtime harness

Make each unit of engineering work compound into easier future work via brainstorm→plan→execute→review→learn cycles.