Content
# Brain-Framework
> Give your AI Agent a structured memory system — Based on Obsidian + MCP protocol.
## What is Brain-Framework?
Brain-Framework is an **Agent memory architecture specification**, which uses Obsidian Vault as an external memory carrier, and cooperates with MCP (Model Context Protocol) to achieve the AI Agent's persistent memory, context retrieval, and knowledge evolution.
**Core Concept**: Agents should not "forget", and each conversation should not start from scratch.
## Architecture Diagram
```mermaid
graph LR
A[Agent<br/>Claude / Codex / etc] -->|MCP Protocol| B[obsidian-mcp-server]
B -->|REST API| C[Obsidian Vault<br/>Brain]
C --> D[_brain/<br/>Memory System]
C --> E[_wiki/<br/>Knowledge Base]
C --> F[_sources/<br/>Original Notes]
```
## Quick Start in 5 Minutes
### Step 1: Clone + Import Vault
```bash
git clone https://github.com/{your-username}/brain-framework.git
```
Open `Agent brain/` folder as Vault in Obsidian:
- Open Obsidian → "Open folder as vault"
- Select `brain-framework/Agent brain/`
### Step 2: Configure Obsidian Plugin
Read `1-Obsidian Configuration.md`, complete:
1. Install **Local REST API** plugin (Community Plugins)
2. Enable service, copy **API Token**
3. Record **Base URL** (default `http://127.0.0.1:27123`)
### Step 3: Connect Agent MCP Service
Read `2-Agent Automatic Configuration.md`:
1. **Replace placeholders**: Replace `{OBSIDIAN_API_KEY}` and `{OBSIDIAN_BASE_URL}` with values obtained in Step 2
2. **Send to Agent**: Send the replaced content as Prompt to your Agent
3. Agent will automatically:
- Install `obsidian-mcp-server`
- Configure MCP service
- Execute Brain self-test verification
### Step 4: Initialize Personalized Configuration
Run initialization script (Windows use PowerShell, Mac/Linux use Bash):
```powershell
# Windows
.\scripts\init.ps1
```
```bash
# Mac / Linux
bash scripts/init.sh
```
Input:
- Agent name (e.g., `Claude`, `Nerve`, `MyAssistant`)
- Agent identity description (one sentence)
- Core role (one sentence)
- Vault port (default 27123)
Generated files:
- `AGENTS.md` — Personalized Agent protocol file
- `personalized/identity.md` — Agent identity definition
- `personalized/vault.yaml` — Vault connection configuration
#### Placement Description
| Generated File | Placement Location |
|-----------|--------------------|
| `AGENTS.md` (root directory) | **Copy to Agent configuration directory**:<br/>• Claude Code: `~/.claude/CLAUDE.md`<br/>• OpenCode: `~/.opencode/opencode.json` same level directory<br/>• Other Agent: Refer to its documentation for "project instructions" or "system prompt" location |
| `personalized/identity.md` | **Manually copy to Obsidian Vault**:<br/>`Agent brain/_brain/_identity/self.md` (overwrite original template) |
| `personalized/vault.yaml` | For reference, currently not automatically used |
## Directory Structure
```
brain-framework/
├── 1-Obsidian Configuration.md ← Obsidian plugin installation guide
├── 2-Agent Automatic Configuration.md ← Agent MCP configuration Prompt template
├── README.md ← This file
├── AGENTS_TEMPLATE.md ← Agent protocol template (with placeholders)
├── _schema/ ← Protocol definition layer
│ ├── BRAIN.md ← Brain interaction protocol
│ ├── CLAUDE.md ← Agent general rules
│ └── INSTRUCTIONS.md ← Agent workflow
├── scripts/ ← Initialization tools
│ ├── init.sh ← Linux/Mac initialization script
│ ├── init.ps1 ← Windows initialization script
│ └── AGENTS.md ← Example generated AGENTS.md
├── Agent brain/ ← Obsidian Vault template
│ ├── .obsidian/ ← Obsidian configuration (plugins, themes)
│ ├── _brain/ ← Memory system (cleaned, with .gitkeep)
│ │ ├── _cache/ ← Session cache
│ │ ├── _identity/ ← Agent identity definition
│ │ ├── _episodic/ ← Episodic memory
│ │ ├── _procedural/ ← Procedural memory (preferences/patterns)
│ │ └── _semantic/ ← Semantic memory (insights/knowledge)
│ ├── _wiki/ ← Structured knowledge base
│ ├── _sources/ ← Original notes
│ └── _schema/ ← Vault internal protocol copy
└── personalized/ ← User personalized configuration (generated by init script)
├── identity.md ← Agent identity (need to manually put into _brain/_identity/self.md)
└── vault.yaml ← Vault connection configuration
```
## Memory Architecture
Brain-Framework adopts **three-layer memory architecture**:
| Layer | Location | Function |
|-----|------|------|
| **Sources** | `_sources/learning/` | Original input, read-only |
| **Wiki** | `_wiki/concepts/` | Agent refined structured knowledge |
| **Brain** | `_brain/` | Fused memory (episodic/procedural/semantic) |
**Knowledge Flow**:
```
User Input → Sources (original) → Wiki (refined) → Brain (fused)
```
## Technology Stack
- **Obsidian**: Vault as memory storage carrier
- **Local REST API**: Obsidian plugin, providing HTTP API
- **obsidian-mcp-server**: MCP service, bridging Agent and Obsidian
- **Agent**: Claude Code / OpenCode / Any Agent supporting MCP
## License
MIT
## Contribution
Welcome to submit Issues and Pull Requests!
*Brain-Framework — Give your Agent a memory that lasts.*
