What Is the MiniDB Package in MoonshotAI/kimi-code? Embedded KV Database Explained

The @moonshot-ai/minidb package is the embedded key-value database that provides persistent, in-memory storage with WAL durability, snapshots, and full-text search for the Kimi Code platform.

All higher-level Kimi Code services—including session management, search indexing, backups, and the optional RESP server—rely on minidb as their foundational persistence engine. This article explains its architecture, core APIs, and how it integrates with the broader codebase.

What MiniDB Provides: Core Features

minidb delivers a production-ready storage layer without external dependencies. According to the MoonshotAI/kimi-code source, it combines several specialized subsystems under a unified MiniDb class.

In-Memory Store with Durable Writes

The Store class maintains a fast in-memory map of keys to values (with optional TTL). Durability comes through:

• Write-ahead logging (WAL) – All mutations append to src/wal.ts before applying to memory
• Snapshotting – Periodic checkpoints in src/snapshot.ts bound WAL replay time
• Compaction – Background merging in src/compaction.ts reclaims space and controls file growth

On MiniDb.open(), the database loads the latest snapshot then replays the WAL, automatically truncating any torn tail from a crash.

Indexing and Query Capabilities

Beyond basic KV operations, minidb supports rich queries via:

Index Type	Source File	Purpose
Secondary indexes	src/index-manager.ts, src/dt-index.ts	Exact-match lookups on object fields
Full-text indexes	src/text-index/	Tokenized search over text fields

The search service in Kimi Code uses MiniDb.createTextIndex and MiniDb.search for fast content retrieval.

Multi-Process Sharding with ClusterDb

For deployments with multiple writer processes, src/cluster/ClusterDb shards the database across multiple directories. This layer provides atomic cross-shard operations while avoiding lock contention.

Opening and Using MiniDB: Code Examples

The MiniDb class exposes a promise-based API defined in packages/minidb/src/mini-db.ts.

Basic Database Lifecycle

import { MiniDb } from '@moonshot-ai/minidb';

// Open with JSON values and balanced durability
const db = await MiniDb.open({
  dir: './data',
  valueCodec: 'json',
  fsyncPolicy: 'everysec',  // fsync every second; alternatives: 'always', 'none'
});

Key-Value Operations with TTL

// Store session data (used by kap-server)
await db.set('session:123', {
  user: 'alice',
  tokens: [],
  lastActive: Date.now()
});

// Retrieve
const session = db.get('session:123');

// Temporary keys with automatic expiration
await db.set('cache:result', expensiveComputation(), { ttl: 60_000 });
console.log(db.ttl('cache:result'));  // remaining milliseconds

Secondary Indexes for Field Lookups

// Create index on 'user' field for fast filtering
await db.createIndex('byUser', { field: 'user' });

// Exact-match query
const aliceSessions = db.findEq('byUser', 'alice');

Full-Text Search Integration

// Index message content for search service
await db.createTextIndex('body', { fields: ['messages'] });

// Search with ranking and limits
const hits = await db.search('body', 'error handling', {
  limit: 10,
  offset: 0
});

Backup and Restore Operations

// Point-in-time snapshot for backup system
await db.backup('./backups/snapshot-$(Date.now()).db');

// Restore from backup
const restoredDb = await MiniDb.restore({
  dir: './data',
  backupPath: './backups/snapshot-123456.db'
});

How Kimi Code Services Use MiniDB

The minidb package serves as the single persistence backend across multiple Kimi Code components:

• kap-server – Opens a MiniDb instance for session storage (key → JSON session objects)
• Search service – Builds full-text indexes on conversation content via createTextIndex and search
• Backup system – Uses MiniDb.backup and MiniDb.restore for user data snapshots
• RESP server – Optional TCP server in src/server.ts exposes the database via Redis protocol for external tooling

MiniDB Source File Reference

File	Responsibility
packages/minidb/package.json	Package metadata and export map
packages/minidb/src/index.ts	Public barrel—exports MiniDb class and types
packages/minidb/src/mini-db.ts	Core implementation: lifecycle, WAL, compaction, indexing
packages/minidb/src/wal.ts	Crash-safe append-only write log
packages/minidb/src/snapshot.ts	Point-in-time state serialization
packages/minidb/src/compaction.ts	Background WAL merge and cleanup
packages/minidb/src/cluster/	ClusterDb sharding for multi-process deployments
packages/minidb/src/server.ts	Optional RESP/TCP protocol server

Configuration Options for Production Use

When initializing MiniDb for Kimi Code deployments, consider these parameters from the source:

• fsyncPolicy – 'everysec' (default) balances safety and performance; use 'always' for strict durability, 'none' for maximum throughput
• valueCodec – 'json' for object storage, 'string' or 'buffer' for raw data
• Cluster configuration – Set cluster: { shards: 4 } when running multiple writer processes

Summary

• @moonshot-ai/minidb is the embedded KV database powering all persistence in Kimi Code
• Combines in-memory speed with WAL durability, snapshots, and automatic compaction
• Supports secondary indexes and full-text search for rich query patterns
• Used by session storage, search service, backups, and the optional RESP server
• Implements multi-process sharding via ClusterDb for scaled deployments

Frequently Asked Questions

What is the MiniDB package used for in MoonshotAI/kimi-code?

The @moonshot-ai/minidb package provides the embedded key-value database that stores session data, search indexes, and backups for the Kimi Code platform. It offers fast in-memory operations with durable persistence through write-ahead logging and snapshots.

Does MiniDB require external dependencies like Redis or PostgreSQL?

No. MiniDB has no native dependencies and runs entirely within the Node.js process. The optional RESP server in src/server.ts can expose MiniDB via the Redis protocol, but this is for external interoperability—not a requirement.

How does MiniDB ensure data durability during crashes?

MiniDB uses a write-ahead log (src/wal.ts) where every mutation appends before applying to memory. On restart, it loads the latest snapshot from src/snapshot.ts and replays the WAL, automatically truncating incomplete entries at the tail.

Can MiniDB handle multiple writer processes?

Yes. The ClusterDb implementation in src/cluster/ shards the database across directories, allowing multiple processes to write concurrently while maintaining atomic cross-shard operations when needed.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}