Brain OS — LLM-Managed Memory Vault

A persistent, AI-maintained knowledge base for developers using AI coding assistants (Claude Code, OpenCode, Codex, Cursor).

The idea: The AI reads your sources, extracts key information, and incrementally builds a structured wiki — updating entity pages, revising summaries, noting contradictions, and maintaining cross-references. You read the wiki; the AI writes it.

This is the opposite of RAG. Knowledge is compiled once and kept current, not re-derived on every query.

Quick Start

git clone <this-repo> brain-os
cd brain-os
# Start your AI coding assistant in this directory

Then tell your AI: "This is my memory vault. Read CLAUDE.md and follow Areas/workflows.md to initialize it."

Vault Structure

brain-os/
├── CLAUDE.md           # AI instructions (read by Claude Code, OpenCode, Cursor)
├── AGENTS.md           # Same, for OpenCode/Codex
├── SOUL.md             # AI personality template (customize this)
├── README.md           # This file
├── _MOC.md             # Home hub — links everything
├── context.md          # Active session state
├── index.md            # Page catalog
├── log.md              # Chronological session log
├── RAW/                # Immutable source documents
├── Projects/           # Active work
├── Areas/              # Ongoing responsibilities
│   ├── config.md       # System configuration
│   ├── tools.md        # Tools inventory
│   ├── preferences.md  # User preferences
│   └── workflows.md    # AI maintenance procedures
├── Resources/          # Reference material
│   ├── learned-facts.md    # Cross-session knowledge
│   ├── decisions.md        # Decision journal (with rationale)
│   ├── patterns.md         # Pattern catalog
│   ├── MOC-coding.md       # Coding conventions
│   └── project-setup-template.md  # Project blueprint
├── Archives/           # Inactive items
└── Sessions/           # Daily session notes

How It Works

Three layers:

1. RAW/ — Your source documents (articles, clippings, notes). Immutable. The AI reads from here but never modifies.
2. The Wiki — AI-generated markdown files (areas, resources, sessions). The AI owns this layer entirely — creates, updates, cross-references.
3. The Schema — CLAUDE.md, SOUL.md, Areas/workflows.md tell the AI how to maintain the wiki.

Daily Workflow

1. Start your AI tool in the brain-os/ directory
2. AI reads context.md (~100 tokens) to understand current state
3. Work as normal — the AI writes only when there's genuinely new knowledge
4. Session ends — AI updates context.md and appends to log.md

Customization

SOUL.md

Edit SOUL.md to set your AI assistant's personality — tone, style, communication preferences. This is the identity layer.

CLAUDE.md

Edit CLAUDE.md if you use Claude Code, OpenCode, or Cursor. It tells the AI how to maintain your vault.

Areas/workflows.md

Edit Areas/workflows.md to adjust session procedures, token budgets, safety rules.

Why This Works

The tedious part of maintaining a knowledge base is not the reading or thinking — it's the bookkeeping. Updating cross-references, keeping summaries current, noting contradictions. Humans abandon wikis because maintenance grows faster than value. AI doesn't get bored, doesn't forget to update a cross-reference, and can touch 15 files in one pass.

The human curates sources and asks good questions. The AI does everything else.

Sources & Inspirations

• LLM Wiki — persistent wiki pattern
• Architect's Blueprint — project structure for AI-assisted development
• Loop Engineering — Verifier Principle, iterative refinement
• PARA Method — Projects/Areas/Resources/Archives organization
• Zettelkasten — atomic notes with wiki links
• MOC (Map of Content) — graph hubs for navigation
• Obsidian — markdown-based knowledge graph platform

License

MIT — use freely, share widely.