README.md

---
title: Ever Brain
emoji: 🧠
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
---
<!-- 
### AGENT DIRECTIVE
This project is powered by Ever Brain Cognition OS. 
To synchronize with the project's persistent memory and architectural state, 
you MUST read AGENT.md in the root directory before starting any task.
-->

<p align="center">
  <h1 align="center">Ever Brain</h1>
  <p align="center"><strong>A Cognition Operating System for AI Coding Agents</strong></p>
  <p align="center">
    Persistent &middot; Portable &middot; Markdown-Native &middot; Open Source
  </p>
</p>

---

> 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

```bash
# 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

```bash
# 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

```bash
# 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](https://typer.tiangolo.com/) |
| Terminal Rendering | [Rich](https://rich.readthedocs.io/) |
| 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

- [x] Core CLI (`create`, `use`, `status`, `import`, `attach`, `sync`, `detach`)
- [x] Brain Instance scaffolding with templates
- [x] Workspace runtime bridge
- [x] Project memory with auto-detection (git remote → folder name → cwd)
- [x] Local version snapshots
- [x] `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](LICENSE) for details.