# OpenKai

**An open-source personal memory system for AI agents via MCP**

[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](#)
[![Runtime](https://img.shields.io/badge/runtime-Bun-orange.svg)](https://bun.sh)
[![MCP](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.io)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

---

## What is OpenKai?

OpenKai is a PostgreSQL + SQLite hybrid MCP (Model Context Protocol) server that gives AI agents persistent memory across conversations. It remembers who you are, what you've talked about, your goals, emotions, and more.

Built as an MCP server, it integrates directly with Claude Desktop and any MCP-compatible client.

### Key Features

- **51 MCP tools** for comprehensive memory management
- **5 memory types**: Core, Long-term, Short-term, Episodic, Working
- **Goals & Projects** tracking with milestones and progress
- **Emotional Intelligence** - tag and query memories by emotion
- **Temporal Queries** - "what did we discuss last week?"
- **Memory Consolidation** - automatically promotes important short-term memories
- **Reflection Engine** - finds contradictions and consolidation opportunities
- **Memory Reinforcement** - tracks access patterns and strengthens connections
- **PostgreSQL** for persistent storage, **SQLite** for fast in-memory caching
- **Bun runtime** for 20x faster startup than Node.js

---

## Quick Start

### Prerequisites

- **[Bun](https://bun.sh) 1.2+** (JavaScript runtime)
- **Docker Desktop** (for PostgreSQL)
- **Claude Desktop** or any MCP-compatible client

### Installation

```bash
# 1. Clone the repository
git clone https://github.com/yourusername/openkai.git
cd openkai

# 2. Install dependencies
bun install

# 3. Copy environment template and set your password
cp .env.example .env
# Edit .env and set POSTGRES_PASSWORD to a secure value

# 4. Start PostgreSQL
cd docker && POSTGRES_PASSWORD=yourpassword POSTGRES_PORT=5433 docker compose up -d postgres
cd ..

# 5. Start the MCP server
bun start
```

### Development Commands

```bash
bun start              # Start MCP server
bun run dev            # Start with hot reload
bun run health         # Health check
bun test               # Run tests
bun run docker:up      # Start Docker containers
bun run docker:down    # Stop Docker containers
```

---

## Claude Desktop Configuration

Add to your Claude Desktop config file:

- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "openkai": {
      "command": "bun",
      "args": ["/path/to/openkai/src/server/index.js"],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5433",
        "POSTGRES_DB": "kai",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "your-password-here",
        "CACHE_BACKEND": "sqlite",
        "REDIS_OPTIONAL": "true",
        "NODE_ENV": "development",
        "LOG_LEVEL": "info"
      }
    }
  }
}
```

Replace `/path/to/openkai/` with your actual installation path.

---

## Memory Types

| Type | Description | Persistence |
|------|-------------|-------------|
| **Core** | Permanent memories (name, identity, key facts) | Never expires |
| **Long-term** | Categorized memories with importance & strength | Never expires |
| **Short-term** | Temporary memories with configurable expiration | TTL-based |
| **Episodic** | Conversation summaries with key points & decisions | Never expires |
| **Working** | Session scratchpad for active work | Session-based |

---

## MCP Tools (51 total)

### Core Memory (3)
`save_core_memory`, `update_core_memory`, `delete_core_memory`

### Long-term Memory (3)
`save_long_term_memory`, `update_long_term_memory`, `delete_long_term_memory`

### Short-term Memory (2)
`save_short_term_memory`, `delete_short_term_memory`

### Utility (5)
`load_complete_memory`, `search_memories`, `get_memory_statistics`, `cleanup_expired_memories`, `apply_importance_decay`

### Episodic Memory (3)
`save_episodic_memory`, `get_episodic_memories`, `search_episodes`

### Working Memory / Scratchpad (4)
`save_to_scratchpad`, `get_from_scratchpad`, `get_full_scratchpad`, `clear_scratchpad`

### Reflection Engine (3)
`reflect_on_memories`, `get_unresolved_findings`, `resolve_finding`

### Memory Reinforcement (3)
`reinforce_memory`, `get_memory_health`, `apply_memory_maintenance`

### Goals & Projects (10)
`create_goal`, `update_goal`, `update_goal_progress`, `get_active_goals`, `get_goal_details`, `add_goal_milestone`, `complete_milestone`, `log_goal_activity`, `get_neglected_goals`, `get_goal_stats`

### Temporal Queries (4)
`get_memories_by_time`, `get_date_summary`, `get_weekly_summary`, `get_activity_timeline`

### Emotional Intelligence (5)
`tag_memory_emotion`, `get_memories_by_emotion`, `get_emotional_distribution`, `get_emotional_trend`, `auto_tag_emotions`

### Memory Consolidation (5)
`run_memory_consolidation`, `get_promotion_candidates`, `promote_memory`, `get_consolidation_stats`, `strengthen_connections`

---

## Architecture

```
┌─────────────────────────────────────────────┐
│           MCP Client (Claude Desktop)       │
└──────────────────┬──────────────────────────┘
                   │ stdio
                   v
┌─────────────────────────────────────────────┐
│         OpenKai MCP Server (Bun)            │
│  ┌────────────┐  ┌────────────────────────┐ │
│  │ MCP Tools  │  │  Memory Modules        │ │
│  │ (51 tools) │  │  core, longterm, short  │ │
│  │            │  │  episodic, working      │ │
│  │            │  │  goals, emotions        │ │
│  │            │  │  temporal, consolidation│ │
│  │            │  │  reflection, reinforce  │ │
│  └────────────┘  └────────────────────────┘ │
└──────────┬──────────────────┬───────────────┘
           │                  │
           v                  v
┌──────────────────┐  ┌──────────────────┐
│  PostgreSQL 15   │  │  SQLite Cache    │
│  (Persistent)    │  │  (In-memory)     │
│  Port 5433       │  │  Fast reads      │
└──────────────────┘  └──────────────────┘
```

### Project Structure

```
openkai/
├── src/server/
│   ├── index.js              # MCP server entry point
│   ├── config.js             # Environment configuration
│   ├── database/
│   │   ├── postgres.js       # PostgreSQL connection & queries
│   │   └── sqlite-cache.js   # SQLite in-memory cache
│   ├── memory/
│   │   ├── core.js           # Core memory CRUD
│   │   ├── longterm.js       # Long-term memory CRUD
│   │   ├── shortterm.js      # Short-term memory CRUD
│   │   ├── episodic.js       # Conversation summaries
│   │   ├── working.js        # Working memory scratchpad
│   │   ├── goals.js          # Goals & projects tracking
│   │   ├── emotions.js       # Emotional intelligence
│   │   ├── temporal.js       # Temporal queries
│   │   ├── consolidation.js  # Memory consolidation
│   │   ├── reflection.js     # Reflection engine
│   │   └── reinforcement.js  # Memory reinforcement
│   ├── tools/
│   │   ├── index.js          # Base tool registry
│   │   └── v5-tools.js       # Extended tool definitions
│   └── utils/
│       ├── logger.js         # Logging
│       ├── errors.js         # Custom errors
│       └── validation.js     # Input validation
├── docker/
│   ├── docker-compose.yml    # PostgreSQL container
│   └── postgres/init.sql     # Database schema
├── scripts/                  # Operational scripts
├── config/                   # Configuration templates
├── .env.example              # Environment template
└── package.json              # Bun dependencies
```

---

## Configuration

All configuration is via environment variables (`.env` file). See [`.env.example`](.env.example) for the full template.

### Required Settings

```bash
POSTGRES_HOST=localhost
POSTGRES_PORT=5433
POSTGRES_DB=kai
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your-secure-password
```

### Optional Settings

```bash
CACHE_BACKEND=sqlite         # SQLite in-memory cache (default)
REDIS_OPTIONAL=true          # Redis is optional/legacy
NODE_ENV=development
LOG_LEVEL=info
```

---

## Database Schema

PostgreSQL tables:
- `kai_core_memories` - Permanent memories
- `kai_long_term_memories` - Categorized memories with strength ratings
- `kai_short_term_memories` - Temporary memories with expiration
- `kai_episodic_memories` - Conversation summaries
- `kai_working_memory` - Session scratchpad
- `kai_goals` - Goals and projects
- `kai_goal_milestones` - Goal checkpoints
- `kai_goal_activities` - Goal activity log
- `kai_reflection_log` - Reflection findings
- `kai_memory_access_log` - Access analytics
- `kai_memory_connections` - Memory relationship graph
- `kai_emergent_patterns` - Pattern discovery
- `kai_consolidation_log` - Consolidation history
- `kai_temporal_context` - Daily context summaries
- `kai_system_metadata` - Schema version and system state

See [`docker/postgres/init.sql`](docker/postgres/init.sql) for the complete schema.

---

## Troubleshooting

### PostgreSQL won't start
```bash
# Check if port 5433 is in use
docker ps | grep 5433

# Start postgres only
cd docker && POSTGRES_PASSWORD=yourpassword POSTGRES_PORT=5433 docker compose up -d postgres
```

### MCP client can't connect
1. Make sure `kai-postgres` is running: `docker ps --filter "name=kai-postgres"`
2. Verify `bun` is installed: `bun --version`
3. Check the path in your MCP client config points to `src/server/index.js`
4. Restart your MCP client after config changes

### Health check
```bash
bun run health
```

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute.

---

## License

[MIT](LICENSE)

---

**OpenKai v1.0.0** | Powered by [Model Context Protocol](https://modelcontextprotocol.io) | [PostgreSQL](https://www.postgresql.org) | [Bun](https://bun.sh)