Content
# ai-cortex
Your portable AI brain. Wherever you go, I remember.
## What is this?
ai-cortex is a memory server for your AIs. Install it once, connect every AI you use — Claude Code at home, Claude Code at work, Gemini on your phone. All share the same identity, the same memories, the same knowledge.
```
[Home] Claude Code ──MCP──┐
[Work] Claude Code ──MCP──┤ ┌─────────────────────────┐
[Mobile] Gemini ──REST──────┼────→│ ai-cortex (your brain) │
[Server] OpenClaw ──REST────┤ │ identity + memory + knowledge
[Other] Custom AI ──API────┘ └─────────────────────────┘
```
Not an AI agent. Not an assistant. Not a model. Just memory — structured, searchable, persistent.
## Quick Start
### 1. Server: create the brain
```bash
npm install -g ai-cortex
# Interactive wizard (creates DB, config, identity)
ai-cortex init
# Start the server
ai-cortex start
```
### 2. Client: connect Claude Code
```bash
# On any machine where you use Claude Code:
ai-cortex connect http://your-server:7878
```
That's it. `connect` fetches the config from the brain and writes the three files Claude Code needs — MCP server, permissions, and behavioral instructions. Restart Claude Code and it will start using the brain.
### With Docker
```bash
git clone https://github.com/ivncmp/ai-cortex.git
cd ai-cortex
cp .env.example .env # Set token, names, port
docker compose up -d
```
Then from any client machine:
```bash
ai-cortex connect http://your-server:7878
```
## How it works
The brain has 4 layers:
| Layer | What | How |
|-------|------|-----|
| **Identity** | Who is the AI? Who is the user? How should it behave? | `documents` table (identity, user, soul, memory) |
| **Conversations** | Raw chat history from every AI session | `conversations` + `messages` tables |
| **Knowledge** | Structured facts organized by PARA | `entities` + `facts` tables, hot/warm/cold tiers |
| **Recall** | Full-text search over all facts | FTS5 with OR logic for multi-language queries |
### Memory tiers
Memories fade if you don't use them — like a real brain.
| Tier | Rule | Behavior |
|------|------|----------|
| **hot** | accessed <= 7 days ago OR accessCount >= 10 | Always ready |
| **warm** | 8-30 days | Loaded on demand |
| **cold** | > 30 days | Fading, candidate for archival |
Every search bumps accessed facts back to hot. The brain stays sharp on what matters.
## CLI Commands
| Command | Where | Purpose |
|---------|-------|---------|
| `ai-cortex init [path]` | Server | Create a new brain (DB, config, identity) |
| `ai-cortex start [path]` | Server | Start the API server + dashboard |
| `ai-cortex connect [url]` | Client | Connect Claude Code to a running brain |
| `ai-cortex status [path]` | Server | Check brain status |
`init` and `connect` are deliberately separate: **init** runs on the server and knows nothing about clients. **connect** runs on the client and knows nothing about the brain's internals. The brain serves its own client config via `GET /connect`.
## API
All endpoints require `Authorization: Bearer <token>` except `/health` and `/connect`.
```
GET /health Brain pulse
GET /connect Client config (MCP, permissions, CLAUDE.md)
GET /workspace List identity documents
GET /workspace/:key Read one document
PUT /workspace/:key Create or update
DELETE /workspace/:key Remove
GET /entities List entities
GET /entities/:id Entity with all its facts
POST /entities Create entity
DELETE /entities/:id Archive entity
GET /entities/:id/facts Facts for an entity
POST /entities/:id/facts Add a fact
PATCH /facts/:id/access Bump access (keeps memory hot)
GET /conversations List conversations (?source= filter)
GET /conversations/:id Full conversation with messages
POST /conversations Start a new conversation
POST /conversations/:id/messages Send messages (single or batch)
GET /conversations/pending Unprocessed messages overview
POST /search Full-text search over all facts
GET /memory/summary Overview: entities x tiers
```
## MCP Tools
Available to any MCP client (Claude Code, etc.):
| Tool | Purpose |
|------|---------|
| `recall` | Search memory + get identity (primary tool) |
| `remember` | Save a fact to an entity |
| `get_entity` | Read entity with all its facts |
| `list_entities` | List entities by category or type |
| `create_entity` | Create a new entity |
| `bump` | Touch a memory to keep it hot |
| `log` | Send conversation messages for storage |
| `wake_up` | Full identity load (redundant with recall) |
| `overview` | Brain stats |
## Dashboard
Web dashboard on port 7879 (API port + 1). Shows brain stats, entities, facts, conversations, and full-text search. Token auth via localStorage.
## Stack
| Layer | Technology |
|-------|-----------|
| Language | Node.js + TypeScript |
| API | Fastify |
| DB | SQLite + FTS5 (better-sqlite3) |
| MCP | @modelcontextprotocol/sdk (HTTP transport) |
| Validation | Zod |
| CLI | @clack/prompts |
| Dashboard | React 18 (CDN, no build step) |
## Development
```bash
npm install
npm run dev # dev server with watch
npm test # vitest
npm run build # compile TypeScript + copy dashboard
```
## License
MIT
