README.md

metadata

title: Ever Brain
emoji: 🧠
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860

Ever Brain

A Cognition Operating System for AI Coding Agents

Persistent · Portable · Markdown-Native · Open Source

---

AI agents lose operational continuity across sessions, tools, projects, and models. Ever Brain fixes this.

Every time you start a new AI session, switch from Claude to Cursor, change tools, resume an old project, or hit usage limits — the new AI instance loses everything: project understanding, architecture decisions, workflow continuity, coding preferences, active tasks, and operational memory.

Brain creates persistent, portable cognition layers shared between you and your AI agents through a markdown-based filesystem protocol. The agents remain the intelligence. Brain preserves continuity.

---

What Brain Is (and Isn't)

Brain is not a chatbot, note-taking app, memory SaaS, or AI coding assistant.

Brain is a filesystem-based continuity infrastructure layer for AI-assisted development.

What you get	What you avoid
Persistent memory across sessions	No databases or vector stores
Portable across AI tools & models	No cloud infrastructure
Fully local, user-owned data	No vendor lock-in
Markdown — human & AI readable	No proprietary formats
Git-compatible versioning	No background daemons

---

Quick Start

Prerequisites

• Python 3.11+
• pip

Install

# Clone the repository
git clone https://huggingface.co/spaces/projectsorg/ever-brain
cd ever-brain

# Install globally (editable mode)
pip install -e .

First Brain in 60 Seconds

# 1. Create a Brain Instance
brain create my-brain

# 2. Activate it
brain use my-brain

# 3. Navigate to any project
cd ~/projects/my-app

# 4. Attach the project to your Brain
brain attach

# 5. Start working with any AI agent — they'll discover Brain automatically

# 6. When done, sync your Brain state
brain sync

# 7. Optionally, disconnect the workspace
brain detach

Run brain with no arguments to see system status at any time:

Brain Status

> Active Brain:      my-brain
> Brain Path:        C:\Users\you\brains\my-brain
> Attached Project:  my-app
> Brain Version:     v2
> Workspace Runtime: Connected

---

Architecture

Brain consists of three distinct layers:

┌─────────────────────────────────────────────┐
│              Brain System (CLI)              │  ← Management, lifecycle, protocol
├─────────────────────────────────────────────┤
│           Brain Instance (~/brains/)         │  ← Persistent cognition storage
├─────────────────────────────────────────────┤
│        Workspace Runtime (.brain/)           │  ← Local project bridge
└─────────────────────────────────────────────┘

Brain Instance — Your Persistent Memory

Lives at ~/brains/<name>/. This is the source of truth for all cognition.

my-brain/
├── user/                    # Your persistent identity
│   ├── personality.md       #   Communication style & tone
│   ├── preferences.md       #   Coding, architecture, tooling
│   └── workflows.md         #   Development habits & processes
│
├── projects/                # Per-project memory
│   └── my-app/
│       ├── context.md       #   Project overview & tech stack
│       ├── architecture.md  #   System design & structure
│       ├── decisions.md     #   Architecture decision records
│       ├── tasks.md         #   Active, pending, completed tasks
│       ├── handoff.md       #   Session continuity state
│       ├── docs/            #   Additional documentation
│       ├── logs/            #   Operational logs
│       └── agents/          #   Per-agent project logs
│
├── agent-configs/           # Agent discovery protocols
│   ├── .cursorrules         #   Cursor auto-discovery
│   └── CLAUDE.md            #   Claude auto-discovery
│
├── agents/                  # Per-agent operational history
│   ├── claude/
│   ├── cursor/
│   └── codex/
│
├── skills/                  # Reusable workflow conventions
│   ├── coding-style.md
│   └── debugging.md
│
├── raw/                     # Imported unstructured context
├── versions/                # Sync snapshots (v1, v2, ...)
│   └── snapshot-1/
└── AGENT.md                 # Brain protocol definition

Workspace Runtime — The Bridge

The .brain/ directory injected into your project is a lightweight, disposable bridge — not storage. It links agents to your Brain Instance.

project/.brain/
├── AGENT.md           # Generated workspace-specific protocol
├── BRAIN.json         # Machine-readable metadata
├── linked_brain       # Path to active Brain Instance
└── current_project    # Attached project identity

---

CLI Reference

Command	Description
brain	Show system status (default)
brain create <name>	Create a new Brain Instance at ~/brains/<name>/
brain use <name>	Set the active Brain Instance globally
brain import	Inject .brain/ runtime into the current workspace
brain attach	Register the workspace as a project in the active Brain (auto-imports if needed)
brain sync	Create a versioned snapshot of the current Brain state
brain detach	Remove the .brain/ runtime from the workspace
brain delete <name>	Permanently delete a Brain Instance (--force to skip confirmation)
brain status	Display active brain, project, version, and runtime state
brain connect	(Placeholder) Future Supabase cloud sync integration

Examples

# Create and switch between multiple brains
brain create work-brain
brain create personal-brain
brain use work-brain

# Delete a brain you no longer need
brain delete personal-brain

# Check what's active
brain status

# Full workflow: attach, work, sync, detach
brain attach
# ... do your work with AI agents ...
brain sync
brain detach

---

How It Works With AI Agents

Brain operates on a simple contract: agents maintain Brain, Brain maintains continuity.

Agent Protocol

When an AI agent discovers .brain/AGENT.md in a workspace, it:

1. Reads user context from user/ to understand your preferences
2. Reads project memory from projects/<project>/ to resume continuity
3. Follows the handoff protocol: read handoff → work → update handoff
4. Records architecture decisions in decisions.md
5. Updates tasks.md as work progresses
6. Writes session logs to agents/<agent-name>/

Auto-Discovery

Agents discover Brain automatically through standard configuration files:

• Cursor → reads .cursorrules → finds .brain/
• Claude → reads CLAUDE.md → finds .brain/
• Others → discovers .brain/AGENT.md in workspace root

No manual prompting required. Agents self-identify and operate within their own directories by convention.

---

Core Design Principles

Principle	Implementation
Persistent Continuity	Brain persists independently of projects, sessions, and tools
Agents Maintain Brain	AI agents read/write cognition; users just work normally
Markdown Is The Protocol	Everything is markdown, filesystem-based, git-compatible
Local-First Ownership	Fully local, user-owned, inspectable, and portable
Convention Over Configuration	Agents self-identify; no runtime enforcement needed

---

Tech Stack

Component	Technology
Language	Python 3.11+
CLI Framework	Typer
Terminal Rendering	Rich
Storage	Markdown (filesystem)
Versioning	Local snapshots (shutil.copytree)
Config	JSON (~/.brainconfig)
Packaging	pyproject.toml + pip install -e .

---

Project Structure

brain-base/
├── pyproject.toml                # Package config & dependencies
├── README.md
├── brain/
│   ├── __init__.py
│   ├── cli.py                    # Typer app + command registration
│   ├── config.py                 # Global config (~/.brainconfig)
│   ├── paths.py                  # Cross-platform path resolution
│   ├── commands/
│   │   ├── create.py             # brain create <name>
│   │   ├── use.py                # brain use <name>
│   │   ├── status.py             # brain status
│   │   ├── import_brain.py       # brain import
│   │   ├── attach.py             # brain attach
│   │   ├── sync.py               # brain sync
│   │   ├── detach.py             # brain detach
│   │   ├── delete.py             # brain delete <name>
│   │   └── connect.py            # brain connect (placeholder)
│   ├── templates/
│   │   ├── brain_instance.py     # Brain Instance scaffolding
│   │   ├── project_memory.py     # Project memory templates
│   │   ├── workspace_runtime.py  # .brain/ runtime generation
│   │   └── agent_protocol.py     # AGENT.md generation
│   └── utils/
│       ├── git.py                # Git remote/identity detection
│       └── display.py            # Rich console helpers
└── creationdoc/                  # Design documents & specifications

---

Roadmap

• Core CLI (create, use, status, import, attach, sync, detach)
• Brain Instance scaffolding with templates
• Workspace runtime bridge
• Project memory with auto-detection (git remote → folder name → cwd)
• Local version snapshots
• brain delete with confirmation
• Supabase cloud sync (brain connect — placeholder exists)
• Cross-device synchronization
• Team collaboration & shared brains
• Brain export/import between machines
• Plugin system for custom agent protocols

---

Philosophy

The intelligence comes from the agents. The continuity comes from Brain.

Brain doesn't replace your AI tools. It makes them coherent. Every agent you use — Claude, Cursor, Copilot, Codex — reads from the same persistent memory and writes back to it. Context is never lost. Decisions are never forgotten. Handoffs happen automatically.

Your Brain is yours. It's markdown files on your filesystem. No vendor owns it. No cloud stores it. No subscription gates it. You can read it, edit it, version it with git, and carry it anywhere.

---

License

Open Source. See LICENSE for details.