README.md

metadata

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:

# 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

# 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:

                         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/ directory:

• 01. Architecture Overview — Core thesis, 3-tier model, design invariants, and scope boundaries.
• 02. API Specification & Implementation — Endpoint contracts, GitHub ingestion engine, case-insensitive resolver, 60s tree cache, and search engine.
• 03. Developer Guide & Testing — Workspace scripts, test suite execution, live GitHub validation benchmarks, and troubleshooting.
• 04. MCP Specification & Agent Adapter — Dual transport specs, dual capability declaration, resources & tools mapping, and error ergonomics.
• 05. CLI Specification & Workflows — Pure filesystem cache (.evb/), agent meta-skill bootstrapping, dirty diffing, and GitHub-native RBAC (push / propose).
• 06. Roadmap & Next Steps — 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:

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:

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:

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:

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	node -v
pnpm	>= 9.0.0	npm install -g pnpm (or corepack enable && corepack prepare pnpm@latest --activate)	pnpm -v
Git	>= 2.30.0	Download Git	git --version
GitHub Token (Optional)	Classic / Fine-grained PAT	Generate Token (increases API limit from 60 to 5,000 req/hr)	—

🧪 Workspace Commands & Tests

# 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

# 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