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

> Discover the @moonshot-ai/minidb package, an embedded KV database for Kimi Code. Learn about its in-memory storage, WAL durability, snapshots, and full-text search capabilities.

- Repository: [Moonshot AI/kimi-code](https://github.com/MoonshotAI/kimi-code)
- Tags: deep-dive
- Published: 2026-08-14

---

**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`](https://github.com/MoonshotAI/kimi-code/blob/main/src/wal.ts) before applying to memory
- **Snapshotting** – Periodic checkpoints in [`src/snapshot.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/snapshot.ts) bound WAL replay time
- **Compaction** – Background merging in [`src/compaction.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/src/index-manager.ts), [`src/dt-index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/minidb/src/mini-db.ts).

### Basic Database Lifecycle

```typescript
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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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`](https://github.com/MoonshotAI/kimi-code/blob/main/src/server.ts) exposes the database via Redis protocol for external tooling

## MiniDB Source File Reference

| File | Responsibility |
|------|----------------|
| [`packages/minidb/package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/minidb/package.json) | Package metadata and export map |
| [`packages/minidb/src/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/minidb/src/index.ts) | Public barrel—exports `MiniDb` class and types |
| [`packages/minidb/src/mini-db.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/minidb/src/mini-db.ts) | Core implementation: lifecycle, WAL, compaction, indexing |
| [`packages/minidb/src/wal.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/minidb/src/wal.ts) | Crash-safe append-only write log |
| [`packages/minidb/src/snapshot.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/minidb/src/snapshot.ts) | Point-in-time state serialization |
| [`packages/minidb/src/compaction.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/src/wal.ts)) where every mutation appends before applying to memory. On restart, it loads the latest snapshot from [`src/snapshot.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/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.