Spaces:

projectsorg
/

ever-brain

Sleeping

App Files Files Community

ever-brain / README.md

AlexKurian

feat: complete Ever-Brain engine, MCP server, CLI evb mcp command, Dockerfile and release workflow

61b1da1 3 months ago

preview code

Raw History Blame Contribute Delete

7.77 kB

---
title: Ever-Brain MCP & Intelligence Gateway
emoji: 🧠
colorFrom: purple
colorTo: indigo
sdk: docker
app_port: 7860
---
# Ever-Brain — Shared Project Intelligence Layer

> **"Git stores what the project IS; Ever-Brain stores what the project KNOWS."**

Ever-Brain is a portable, agent-agnostic project intelligence layer that makes repository knowledge, skills, and context discoverable, persistent, and consumable across AI agents and developers.

---

## ⚡ Quick Start (Run in 60 Seconds)

Clone and host both the **Ever-Brain API** and **Ever-Brain MCP Server** concurrently with a single command:

```bash
# 1. Clone & Enter
git clone https://github.com/abrez-rizvi/ever-brain.git
cd ever-brain
# 2. Install Dependencies
pnpm install
# 3. Start Local Servers (API + MCP Concurrently)
pnpm dev
```

That's it! Both servers are now live:
* 🟢 **Ever-Brain API**: `http://localhost:3000` *(Health check: `http://localhost:3000/health`)*
* 🟣 **Ever-Brain MCP Server**: `http://localhost:3002` *(SSE endpoint: `http://localhost:3002/sse`)*

### 🎮 Using the CLI Immediately
```bash
# Run CLI directly inside the repo:
pnpm evb --help
# Or link it globally to use 'evb' anywhere on your PC:
pnpm cli:link
```

---

## 🏛️ System Architecture

Ever-Brain decouples project intelligence from individual AI agents into three modular tiers:

```text
                         GitHub / Raw CDN (Storage & Persistence)
                                           │
                                           ▼
                                 Ever-Brain API (Source Layer)
                                  ↙                    ↘
                   Ever-Brain MCP (Agent Layer)       Ever-Brain CLI (Developer & Agent Plane)
                              ↓                                 ↓
                          AI Agents                   Local Environment / IDE
```

1. **Ever-Brain API (`packages/api`)** *(Delivered)*: Stateless, read-oriented HTTP source layer. Resolves repositories, discovers text/Markdown files via recursive Git Trees, streams raw content with zero REST API quota overhead, provides in-memory tree caching, and supports plain substring search.
2. **Ever-Brain MCP (`packages/mcp`)** *(Delivered)*: Agent consumption layer exposing resources (`ever-brain://repo/...`) and ReAct tools (`list_files`, `read_file`, `search_files`) over Streamable HTTP (MCP 2025-03-26) and Legacy SSE (MCP 2024-11-05).
3. **Ever-Brain CLI (`packages/cli`)** *(Delivered)*: Developer and AI agent control plane for local caching, status inspection, skill materialization, auto-bootstrapping agent meta-skills, and GitHub-native Read/Write collaboration (`evb push` for maintainers, `evb propose` for contributors).

---

## 📚 Project Wiki

Comprehensive documentation is available in the [`docs/wiki/`](./docs/wiki/) directory:

- [**01. Architecture Overview**](./docs/wiki/01-architecture-overview.md) — Core thesis, 3-tier model, design invariants, and scope boundaries.
- [**02. API Specification & Implementation**](./docs/wiki/02-api-specification-and-implementation.md) — Endpoint contracts, GitHub ingestion engine, case-insensitive resolver, 60s tree cache, and search engine.
- [**03. Developer Guide & Testing**](./docs/wiki/03-developer-guide-and-testing.md) — Workspace scripts, test suite execution, live GitHub validation benchmarks, and troubleshooting.
- [**04. MCP Specification & Agent Adapter**](./docs/wiki/04-mcp-specification-and-adapter.md) — Dual transport specs, dual capability declaration, resources & tools mapping, and error ergonomics.
- [**05. CLI Specification & Workflows**](./docs/wiki/05-cli-specification-and-workflows.md) — Pure filesystem cache (`.evb/`), agent meta-skill bootstrapping, dirty diffing, and GitHub-native RBAC (`push` / `propose`).
- [**06. Roadmap & Next Steps**](./docs/wiki/06-roadmap-and-next-steps.md) — Supabase cloud deployment, production hardening, and continuous learning roadmap.

---

## 💡 Trying Ever-Brain on Any Project on Your PC

You can use Ever-Brain on **any project or workspace on your computer** without modifying your project's codebase. Here is how to test it end-to-end in 5 minutes:

### 1. Link the CLI globally
From your `ever-brain` root folder, run:
```bash
pnpm cli:link
```
*(Runs `pnpm --dir packages/cli link --global`. If you haven't used global pnpm tools before, run `pnpm setup` once).*

### 2. Keep the local servers running
In a terminal in `ever-brain`, start the servers:
```bash
pnpm dev
```
*(Hosts API on `:3000` and MCP on `:3002`)*

### 3. Navigate to any project folder
In a separate terminal, navigate to any repository or codebase on your machine:
```bash
cd C:\path\to\your-other-project
# or: cd ~/projects/my-app
```

### 4. Initialize Ever-Brain
Connect your project to any GitHub repository containing intelligence, runbooks, or skills:
```bash
evb init https://github.com/spencerpauly/skills-repo
```

### 5. What Happens Next
1. **Auto-Bootstrapped Meta-Skill**: Ever-Brain detects your environment and installs the `ever-brain` meta-skill into:
   - **Google Antigravity / Gemini**: `.gemini/skills/ever-brain/`
   - **Cursor**: `.cursor/rules/ever-brain.mdc`
   - **Claude Code**: `.claude/skills/ever-brain/`
2. **Instant Agent Context**: Your AI agent can now autonomously query, read, and search project rules and skills!
3. **Inspect & Materialize**:
   - `evb status` — View connected intelligence repository and cache state.
   - `evb skills list` — List all available runbooks.
   - `evb skills install <skill-name>` — Materialize a skill directly into your agent's skills directory.
4. **Collaborate & Propose Changes**:
   - Edit files in `.evb/cache/`
   - `evb diff` — Inspect uncommitted local changes.
   - `evb push` / `evb propose` — Commit directly or open a GitHub Pull Request.

---

## 🛠️ Advanced Development & Verification

### 📋 Prerequisites & Downloads

| Software | Required Version | Download / Installation | Verify Command |
| :--- | :--- | :--- | :--- |
| **Node.js** | `>= 20.0.0` (LTS recommended) | [Download Node.js](https://nodejs.org/) | `node -v` |
| **pnpm** | `>= 9.0.0` | `npm install -g pnpm`<br>*(or `corepack enable && corepack prepare pnpm@latest --activate`)* | `pnpm -v` |
| **Git** | `>= 2.30.0` | [Download Git](https://git-scm.com/downloads) | `git --version` |
| **GitHub Token** *(Optional)* | Classic / Fine-grained PAT | [Generate Token](https://github.com/settings/tokens)<br>*(increases API limit from 60 to 5,000 req/hr)* | — |

### 🧪 Workspace Commands & Tests

```bash
# Start both API and MCP servers concurrently
pnpm dev
# Start individual services in development mode
pnpm dev:api                     # API on port 3000
pnpm dev:mcp                     # MCP server on port 3002
# Run all automated tests across all 3 packages
pnpm test
# Run TypeScript type check across all packages
pnpm typecheck
# Build all packages for production
pnpm build
```

---

## 💻 CLI Quickstart

```bash
# Connect current workspace to an Ever-Brain intelligence repository & bootstrap agent meta-skill
evb init https://github.com/acme/project-intelligence
# Inspect connection, cached volume, and uncommitted modifications
evb status
# Inspect knowledge documents
evb knowledge list
evb knowledge show architecture.md
# Inspect and materialize skills for local agents
evb skills list
evb skills show testing
evb skills install testing --target gemini # or cursor, claude
# Check diffs and publish changes
evb diff
evb push -m "feat(skills): add database migration runbook" # Direct commit for maintainers
evb propose --title "feat: Add Webhook runbook"           # Opens GitHub PR for contributors
```

## 📄 License
MIT

	---
	title: Ever-Brain MCP & Intelligence Gateway
	emoji: 🧠
	colorFrom: purple
	colorTo: indigo
	sdk: docker
	app_port: 7860
	---

	# Ever-Brain — Shared Project Intelligence Layer

	> "Git stores what the project IS; Ever-Brain stores what the project KNOWS."

	Ever-Brain is a portable, agent-agnostic project intelligence layer that makes repository knowledge, skills, and context discoverable, persistent, and consumable across AI agents and developers.

	---

	## ⚡ Quick Start (Run in 60 Seconds)

	Clone and host both the Ever-Brain API and Ever-Brain MCP Server concurrently with a single command:

	```bash
	# 1. Clone & Enter
	git clone https://github.com/abrez-rizvi/ever-brain.git
	cd ever-brain

	# 2. Install Dependencies
	pnpm install

	# 3. Start Local Servers (API + MCP Concurrently)
	pnpm dev
	```

	That's it! Both servers are now live:
	* 🟢 Ever-Brain API: `http://localhost:3000` (Health check: `http://localhost:3000/health`)
	* 🟣 Ever-Brain MCP Server: `http://localhost:3002` (SSE endpoint: `http://localhost:3002/sse`)

	### 🎮 Using the CLI Immediately
	```bash
	# Run CLI directly inside the repo:
	pnpm evb --help

	# Or link it globally to use 'evb' anywhere on your PC:
	pnpm cli:link
	```

	---

	## 🏛️ System Architecture

	Ever-Brain decouples project intelligence from individual AI agents into three modular tiers:

	```text
	GitHub / Raw CDN (Storage & Persistence)
	│
	▼
	Ever-Brain API (Source Layer)
	↙ ↘
	Ever-Brain MCP (Agent Layer) Ever-Brain CLI (Developer & Agent Plane)
	↓ ↓
	AI Agents Local Environment / IDE
	```

	1. Ever-Brain API (`packages/api`) (Delivered): Stateless, read-oriented HTTP source layer. Resolves repositories, discovers text/Markdown files via recursive Git Trees, streams raw content with zero REST API quota overhead, provides in-memory tree caching, and supports plain substring search.
	2. Ever-Brain MCP (`packages/mcp`) (Delivered): Agent consumption layer exposing resources (`ever-brain://repo/...`) and ReAct tools (`list_files`, `read_file`, `search_files`) over Streamable HTTP (MCP 2025-03-26) and Legacy SSE (MCP 2024-11-05).
	3. Ever-Brain CLI (`packages/cli`) (Delivered): Developer and AI agent control plane for local caching, status inspection, skill materialization, auto-bootstrapping agent meta-skills, and GitHub-native Read/Write collaboration (`evb push` for maintainers, `evb propose` for contributors).

	---

	## 📚 Project Wiki

	Comprehensive documentation is available in the [`docs/wiki/`](./docs/wiki/) directory:

	- [01. Architecture Overview](./docs/wiki/01-architecture-overview.md) — Core thesis, 3-tier model, design invariants, and scope boundaries.
	- [02. API Specification & Implementation](./docs/wiki/02-api-specification-and-implementation.md) — Endpoint contracts, GitHub ingestion engine, case-insensitive resolver, 60s tree cache, and search engine.
	- [03. Developer Guide & Testing](./docs/wiki/03-developer-guide-and-testing.md) — Workspace scripts, test suite execution, live GitHub validation benchmarks, and troubleshooting.
	- [04. MCP Specification & Agent Adapter](./docs/wiki/04-mcp-specification-and-adapter.md) — Dual transport specs, dual capability declaration, resources & tools mapping, and error ergonomics.
	- [05. CLI Specification & Workflows](./docs/wiki/05-cli-specification-and-workflows.md) — Pure filesystem cache (`.evb/`), agent meta-skill bootstrapping, dirty diffing, and GitHub-native RBAC (`push` / `propose`).
	- [06. Roadmap & Next Steps](./docs/wiki/06-roadmap-and-next-steps.md) — Supabase cloud deployment, production hardening, and continuous learning roadmap.

	---

	## 💡 Trying Ever-Brain on Any Project on Your PC

	You can use Ever-Brain on any project or workspace on your computer without modifying your project's codebase. Here is how to test it end-to-end in 5 minutes:

	### 1. Link the CLI globally
	From your `ever-brain` root folder, run:
	```bash
	pnpm cli:link
	```
	(Runs `pnpm --dir packages/cli link --global`. If you haven't used global pnpm tools before, run `pnpm setup` once).

	### 2. Keep the local servers running
	In a terminal in `ever-brain`, start the servers:
	```bash
	pnpm dev
	```
	(Hosts API on `:3000` and MCP on `:3002`)

	### 3. Navigate to any project folder
	In a separate terminal, navigate to any repository or codebase on your machine:
	```bash
	cd C:\path\to\your-other-project
	# or: cd ~/projects/my-app
	```

	### 4. Initialize Ever-Brain
	Connect your project to any GitHub repository containing intelligence, runbooks, or skills:
	```bash
	evb init https://github.com/spencerpauly/skills-repo
	```

	### 5. What Happens Next
	1. Auto-Bootstrapped Meta-Skill: Ever-Brain detects your environment and installs the `ever-brain` meta-skill into:
	- Google Antigravity / Gemini: `.gemini/skills/ever-brain/`
	- Cursor: `.cursor/rules/ever-brain.mdc`
	- Claude Code: `.claude/skills/ever-brain/`
	2. Instant Agent Context: Your AI agent can now autonomously query, read, and search project rules and skills!
	3. Inspect & Materialize:
	- `evb status` — View connected intelligence repository and cache state.
	- `evb skills list` — List all available runbooks.
	- `evb skills install <skill-name>` — Materialize a skill directly into your agent's skills directory.
	4. Collaborate & Propose Changes:
	- Edit files in `.evb/cache/`
	- `evb diff` — Inspect uncommitted local changes.
	- `evb push` / `evb propose` — Commit directly or open a GitHub Pull Request.

	---

	## 🛠️ Advanced Development & Verification

	### 📋 Prerequisites & Downloads

	\| Software \| Required Version \| Download / Installation \| Verify Command \|
	\| :--- \| :--- \| :--- \| :--- \|
	\| Node.js \| `>= 20.0.0` (LTS recommended) \| [Download Node.js](https://nodejs.org/) \| `node -v` \|
	\| pnpm \| `>= 9.0.0` \| `npm install -g pnpm`<br>(or `corepack enable && corepack prepare pnpm@latest --activate`) \| `pnpm -v` \|
	\| Git \| `>= 2.30.0` \| [Download Git](https://git-scm.com/downloads) \| `git --version` \|
	\| GitHub Token (Optional) \| Classic / Fine-grained PAT \| [Generate Token](https://github.com/settings/tokens)<br>(increases API limit from 60 to 5,000 req/hr) \| — \|

	### 🧪 Workspace Commands & Tests

	```bash
	# Start both API and MCP servers concurrently
	pnpm dev

	# Start individual services in development mode
	pnpm dev:api # API on port 3000
	pnpm dev:mcp # MCP server on port 3002

	# Run all automated tests across all 3 packages
	pnpm test

	# Run TypeScript type check across all packages
	pnpm typecheck

	# Build all packages for production
	pnpm build
	```

	---

	## 💻 CLI Quickstart

	```bash
	# Connect current workspace to an Ever-Brain intelligence repository & bootstrap agent meta-skill
	evb init https://github.com/acme/project-intelligence

	# Inspect connection, cached volume, and uncommitted modifications
	evb status

	# Inspect knowledge documents
	evb knowledge list
	evb knowledge show architecture.md

	# Inspect and materialize skills for local agents
	evb skills list
	evb skills show testing
	evb skills install testing --target gemini # or cursor, claude

	# Check diffs and publish changes
	evb diff
	evb push -m "feat(skills): add database migration runbook" # Direct commit for maintainers
	evb propose --title "feat: Add Webhook runbook" # Opens GitHub PR for contributors
	```

	## 📄 License
	MIT