EasyBrain
by cavizu
README.md
<div align="center">
# π§ EasyBrain
**Per-project persistent memory engine, Official MCP Server & Agent Skill.**
*Install once globally. Keep every project's memory isolated β 100% locally (Zero-API-Key) or in your personal Supabase (`pgvector`).*
[](LICENSE)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](#using-as-an-mcp-server--agent-skill)
---
π **Languages / Idiomas**:
**[ English πΊπΈ ](README.md)** β’ **[ PortuguΓͺs (Brasil) π§π· ](README.pt-BR.md)**
---
</div>
## π What is EasyBrain?
**EasyBrain** gives your AI coding agents (Antigravity, Claude Code, Codex, Cursor, Windsurf, or custom orchestrators) **persistent, isolated memory per project** without bloating your context window.
When you start a new chat in the same repository, your agent calls `easybrain_bootstrap` to load a compact **Project State Snapshot** (objective, stack, decisions, current task, next steps) in ~1,000 tokens instead of re-reading the entire codebase.
---
## β¨ Core Features (v1.2.1)
- **Strict Per-Project Isolation (`projectId`)**: Automatically resolves `.easybrain/project.json` per repository (supporting monorepos). Project A never leaks into Project B.
- **Two Processing Modes**:
- **Basic Mode (Zero API Key / Zero Cost)**: Works out of the box with no `OPENAI_API_KEY`. Provides structured Project Checkpoints, instant `bootstrap`, lexical keyword recall, and verbatim source log tracking.
- **Enriched Mode (AI Librarian + Semantic Vectors)**: Add any OpenAI-compatible key (OpenAI, Groq, DeepSeek, Ollama, OpenRouter) to automatically consolidate raw logs into dense episodic summaries and vector embeddings.
- **Dual Storage Engine**:
- **Local Zero-Config (`STORAGE_PROVIDER=local`)**: Stores memory per project in `<project>/.easybrain/memory.json` with cross-process file locking (`.lock`), corruption-proof schema validation, and atomic write-then-rename durability.
- **Personal Supabase (`STORAGE_PROVIDER=supabase`)**: Connects to your own Supabase (`PostgreSQL + pgvector` HNSW) with `project_id` isolation and strict `lock_token` atomic transactions.
- **Official MCP Server + `SKILL.md`**: Built with `@modelcontextprotocol/sdk` exposing 4 lean tools (`easybrain_bootstrap`, `easybrain_save`, `easybrain_recall`, `easybrain_get_sources`) paired with a standard `skills/easybrain/SKILL.md`.
---
## π Quickstart (Zero-Setup in 60 Seconds)
```bash
git clone https://github.com/cavizu/easybrain.git
cd easybrain
npm install
npm test
npm run demo
```
No database account and no API key are required to run `npm test` or `npm run demo` in Basic Mode.
---
## π» CLI Commands
```bash
# Initialize EasyBrain explicitly for a project (creates .easybrain/project.json)
npx easybrain init [--project <path>]
# Diagnose environment, active storage engine, processing mode, and project scope
npx easybrain doctor [--project <path>]
# Print ready-to-copy MCP server JSON config and Skill paths for your IDE
npx easybrain setup
```
---
## π οΈ Using as an MCP Server + Agent Skill
Run the setup helper to see the exact paths for your machine:
```bash
npm run build
npx easybrain setup
```
1. **Install the Skill (`skills/easybrain/SKILL.md`)** into your IDE's personal skills folder:
- **Antigravity**: `~/.gemini/config/skills/easybrain/SKILL.md`
- **Claude Code**: `~/.claude/skills/easybrain/SKILL.md`
- **Codex**: `~/.agents/skills/easybrain/SKILL.md`
2. **Register the MCP Server** in your IDE config (`claude_desktop_config.json`, `.cursor/mcp.json`, etc.):
```json
{
"mcpServers": {
"easybrain": {
"command": "node",
"args": ["/absolute/path/to/easybrain/dist/mcp/server.js"],
"env": {
"STORAGE_PROVIDER": "auto"
}
}
}
}
```
---
## ποΈ Optional: Connecting Your Personal Supabase
1. Open your Supabase **SQL Editor** and run [`sql/schema.sql`](sql/schema.sql).
2. Configure `.env`:
```ini
STORAGE_PROVIDER=supabase
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
# Optional for Enriched Mode:
OPENAI_API_KEY=sk-...
```
---
## π³ Docker & REST API (Optional)
You can also run EasyBrain as a standalone REST microservice:
```bash
docker compose up -d
curl http://127.0.0.1:3000/health
```
The REST API exposes the same endpoints as the client: `/health`, `/api/memory/bootstrap`, `/api/memory/checkpoint`, `/api/memory/ingest`, `/api/memory/retrieve`, and `/api/memory/logs/decompress`.
---
## π License
MIT License β see [LICENSE](LICENSE).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues