OpenKai

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

---

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 1.2+ (JavaScript runtime)
• Docker Desktop (for PostgreSQL)
• Claude Desktop or any MCP-compatible client

Installation

# 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

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

{
  "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 for the full template.

Required Settings

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

Optional Settings

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 for the complete schema.

---

Troubleshooting

PostgreSQL won't start

# 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

bun run health

---

Contributing

See CONTRIBUTING.md for guidelines on how to contribute.

---

License

MIT

---

OpenKai v1.0.0 | Powered by Model Context Protocol | PostgreSQL | Bun