Skip to main content
Architecture

​
Package Structure

Cohaku is a TypeScript ESM monorepo (Turborepo + pnpm) with multiple packages: 
packages/
├── shared/     # Type definitions, interfaces, constants (tsc)
├── core/       # Memory engine, SQLite driver, embedding, scoring (tsc)
├── mcp-server/ # MCP tool registration, stdio transport (tsc, private)
├── api/        # Hono HTTP API (tsc)
├── cli/        # CLI binary — the only published package (tsup bundle)
└── docs/       # Mintlify documentation
The dependency flow is strictly one-directional: 
shared → core → mcp-server / api → cli
The cli package uses tsup (esbuild) to bundle all workspace dependencies into a single distributable binary (@cohaku/cli on npm). The mcp-server package is private and not published separately — it is bundled into the CLI.

​
Components

​
Storage Layer

The SqliteDriver manages all persistence using better-sqlite3 with two extensions:
  • sqlite-vec — Virtual tables for vector similarity search (cosine distance)
  • FTS5 — Built-in full-text search with BM25 ranking and Porter stemming
All data lives in a single SQLite file (default: ~/.config/cohaku/memory.db).

​
Embedding

Uses @xenova/transformers to run all-MiniLM-L6-v2 locally. Produces 384-dimensional embeddings for:
  • Memory content → vec_memories
  • Entity names → vec_nodes
  • Edge facts → vec_edges
No API keys or network calls required.

​
Memory Engine

The MemoryEngine class orchestrates all operations:
  • Generates embeddings on write
  • Runs hybrid search (semantic + BM25) on query
  • Computes 4-component scoring (semantic, BM25, recency, salience)
  • Manages sessions, episodes, and the knowledge graph

​
MCP Server

Exposes 24 tools via the Model Context Protocol over stdio transport. Each tool maps to a MemoryEngine method with Zod validation on parameters. Tools are organized into 6 categories:
CategoryCountDescription
Context1get_context — prioritized memory loading
Memory6CRUD, search, deduplication, consolidation
Knowledge Graph5Entities, edges, graph traversal search
Episodes3Chronological event logging
Sessions4Work session lifecycle with checkpoints
Config Generation9Export to Claude Code, Cursor, Copilot, Windsurf, etc.
The server also provides MCP instructions that guide connected agents on how to use the tools effectively (session workflow, memory layer selection, etc.).

​
Data Model

memories          -- 3-layer memory with soft-delete
memories_fts      -- FTS5 index for BM25 search
vec_memories      -- sqlite-vec for semantic search

nodes             -- Knowledge graph entities
vec_nodes         -- Entity name embeddings
edges             -- Bi-temporal relationships
vec_edges         -- Edge fact embeddings

episodes          -- Conversation episodes
episode_refs      -- Episode-to-entity references

sessions          -- Session lifecycle tracking
config            -- Key-value configuration