Content
<!-- 한국어: 이 파일 · English: README.en.md · 상세 가이드: GUIDE.md · (이 문서와 README.pdf 내용 동일) -->
# Tool List
> **A complete local memory tool that automatically saves important decisions and promises from conversations with AI and visualizes them as a knowledge graph.**
**Analogy:** AI is a genius, but it forgets everything once the conversation is over. O-Brain is an **automatic memo note** that you can put next to that AI. It automatically records important information and provides it whenever you need it.
---
## Key Features
| Feature | Description |
|------|------|
| **100% Local** | All memories are stored only on your PC. No external server or cloud transmission. |
| **Hybrid Search** | Uses both keyword (FTS5) and semantic similarity (vector search) |
| **Knowledge Graph** | Visualizes memories as 2D/3D points and lines |
| **Time Travel** | Queries memories that were alive on a specific date |
| **Trust Decay** | Automatically decreases the reliability of AI-extracted memories with a 30-day half-life |
| **Security Filter** | Automatically removes and stores API keys and passwords (`[REDACTED]`) |
| **Automatic Backup** | Automatically generates snapshots when the server starts or before batch deletion |
| **MCP Integration** | Stores, searches, and manages relationships with 7 tools in Claude Code |
| **Orphan Node Visualization** | Displays unrelated memories with a dotted border |
---
## Prerequisites
| Item | Requirements |
|------|-----------|
| Operating System | Windows 10 / 11 (64-bit) |
| Node.js | 20.x LTS or higher (free installation from [nodejs.org](https://nodejs.org)) |
| Storage Space | 500 MB or more (including ~90 MB embedding model) |
| RAM | 4 GB or more (8 GB or more recommended) |
| Browser | Chrome, Edge, Firefox, etc. |
> Claude Code is only required when integrating with MCP tools. The web dashboard can be used without Claude Code.
---
## Installation (2 steps)
**Step 1: Install dependencies (in terminal)**
```bash
cd D:\AI_Dev_Work\2026y\26y_06m_21d_SoDam_O-Brain\app
npm install
```
**Step 2: Start the server**
```bash
npm start
```
→ If you see the message `O-Brain local server ▶ http://127.0.0.1:7740`, it's successful.
**Open in browser:**
```
http://127.0.0.1:7740
```
> **First run**: Automatically downloads the AI embedding model (~90 MB). Takes 1~3 minutes. Subsequent runs start immediately.
---
## Claude Code Plugin Method (optional)
If you're using Claude Code, you can also install it as a plugin:
```
/plugin marketplace add D:\AI_Dev_Work\2026y\26y_06m_21d_SoDam_O-Brain\plugin
/plugin install o-brain@o-brain-local
```
After installation and restarting Claude Code, you can use slash commands:
| Command | Action |
|------|---------|
| `/o-brain:status` | Query current memory count and status |
| `/o-brain:selftest` | Batch check for storage, search, and security (✅✅✅ for normal) |
| `/o-brain:remember` | Extract and store decisions from current conversation |
| `/o-brain:link` | Connect relationships between memories |
| `/o-brain:backup` | Create manual backup |
| `/o-brain:open` | Open dashboard in browser |
---
## MCP Tool Integration (Claude Code)
If you register with Claude Code's `settings.json`, you can store and search memories during conversations:
```json
{
"mcpServers": {
"o-brain": {
"command": "node",
"args": ["C:/absolute/path/app/src/mcp-server.mjs"]
}
}
}
```
Available MCP tools: `save_memory`, `search_memory`, `get_memory`, `get_related`, `get_timeline`, `add_relation`, `list_categories`
---
## Main Commands
```bash
# Run in app/ folder
npm start # Start server (port 7740)
npm run selftest # Self-diagnosis
npm run backup # Manual backup
npm run status # DB status query
npm run seed # Input example data (for testing)
```
---
## File and Data Locations
| Item | Location |
|------|------|
| Memory Database | `app/data/obrain.db` |
| Automatic Backup | `app/data/backups/` (stores latest 10) |
| API Token File | `app/data/.api-token` (updated every run) |
| Personal Settings | `app/.env.local` (uses default if not present) |
### Environment Variables (`app/.env.local`)
| Variable | Default Value | Description |
|------|--------|------|
| `OBRAIN_PORT` | `7740` | Server port number |
| `OBRAIN_DATA_DIR` | `./data` | Data storage folder |
---
## Security Overview
- Server binds **only to 127.0.0.1 (your PC)** - inaccessible from external devices
- **Automatically removes API keys and passwords** before storing memories (processed by redact.mjs)
- A new **local API token** is automatically generated every time the server runs (crypto.randomBytes)
- `data/`, `.env.local`, and `*.sqlite` are included in `.gitignore` - never uploaded to Git
- No external cloud communication. Embedding models run completely locally
---
## Architecture Summary
```
[Claude Code / Browser]
↓
[Express Server 127.0.0.1:7740]
↓
[Security Filter] → [Embedding (local AI)] → [SQLite DB]
├── FTS5 (keyword search)
└── sqlite-vec (vector search)
```
Tech stack: Node.js ES Modules · Express.js v5 · SQLite (better-sqlite3) · sqlite-vec · @huggingface/transformers (all-MiniLM-L6-v2) · force-graph / 3d-force-graph · @modelcontextprotocol/sdk
---
## Quick Troubleshooting Reference
| Symptom | Solution |
|------|------|
| `'node' is not a command` | Install LTS from [nodejs.org](https://nodejs.org) → **open a new terminal** |
| `EADDRINUSE :::7740` | Add `OBRAIN_PORT=7741` to `.env.local` and restart |
| Graph is empty | Add example data with `npm run seed` |
| Browser cannot connect | Check if `npm start` is running → verify address is `http://127.0.0.1:7740` |
| Embedding download fails | Check internet connection · allow Node.js in firewall |
| Memory loss | Restore latest `.db` file from `app/data/backups/` |
Detailed guide: **[GUIDE.en.md](./GUIDE.en.md)**
---
## License · Copyright · Commercial Use
**Apache License 2.0 © SoDam AI Studio, 2026**
| Item | Content |
|------|------|
| Personal Use | Free to use |
| Modification · Reproduction | Allowed (preserve copyright notice) |
| Commercial Use | Allowed under Apache-2.0 conditions |
| Warranty | **None (AS-IS)** - user responsible for usage results |
| External Services | Terms and conditions of external services like Claude / Anthropic apply |
- Built-in open-source libraries (better-sqlite3, sqlite-vec, @huggingface/transformers, force-graph, etc.) follow **their respective licenses** (MIT/Apache-2.0)
- "Claude", "Anthropic" are trademarks of their respective companies. O-Brain has no official affiliation with them
- Full license text: `LICENSE` file
---
*This document and README.pdf have the same content.*
*Detailed guide: [GUIDE.md](./GUIDE.md) (Korean) · [GUIDE.en.md](./GUIDE.en.md) (English)*
