Spaces:
Sleeping
Sleeping
| 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 · Portable · Markdown-Native · 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. | |