@shrimp-kit/core

Shared types, Zod schemas, logger, and utilities for the shrimp-kit ecosystem.

This is the foundation package — all other shrimp-kit packages depend on it.

Install

bun add @shrimp-kit/core

What's Inside

Types

Complete TypeScript type definitions for the entire ecosystem:

• Schedule types — ScheduleType, ScheduleConfig, TaskDefinition, TaskState
• Memory types — MemoryEntry, MemoryIndex, MemoryType, Importance
• Bridge types — BridgeConfig, TelegramMessage, NotifyQueueItem
• Monitor types — HealthStatus, HealthCheckResult, InspectionReport
• Companion types — CompanionPersona, EmotionTrigger, VoiceConfig, ImageGenConfig
• Pipeline types — TTSRequest, TTSResult, ImageGenRequest, ImageGenResult

Zod Schemas

Runtime validation for all major config structures:

import {
  scheduleFileSchema,
  memoryEntrySchema,
  companionPersonaSchema,
  bridgeConfigSchema,
} from "@shrimp-kit/core";

// Validate schedule file
const result = scheduleFileSchema.safeParse(rawData);
if (result.success) {
  const schedule = result.data; // Fully typed!
}

Logger

Structured logger with child logger support:

import { Logger } from "@shrimp-kit/core";

const logger = new Logger({ name: "my-app", level: "info" });
logger.info("Server started", { port: 3000 });

// Child loggers inherit parent config
const dbLogger = logger.child("database");
dbLogger.warn("Connection slow", { latencyMs: 500 });
// → [my-app:database] WARN Connection slow { latencyMs: 500 }

Utilities

File, time, and text utilities used throughout the ecosystem:

import {
  readJson,
  writeJson,
  fileExists,
  isNightTime,
  isoNow,
  tokenize,
  jaccardSimilarity,
  generateId,
  expandHome,
  parseTimeString,
} from "@shrimp-kit/core";

// File operations
const data = await readJson<MyType>("./config.json");
await writeJson("./state.json", myState);

// Time operations
const night = isNightTime(new Date(), ["00:00", "08:00"]); // true/false
const now = isoNow(); // "2026-03-08T12:00:00.000Z"

// Text similarity (used by memory dedup)
const tokens1 = tokenize("the quick brown fox");
const tokens2 = tokenize("the fast brown fox");
const similarity = jaccardSimilarity(tokens1, tokens2); // 0.6

Constants

import { MEMORY_TTL, IMPORTANCE_MULTIPLIER } from "@shrimp-kit/core";

// Default TTL per memory type (days)
MEMORY_TTL.context;    // 14
MEMORY_TTL.preference; // 30
MEMORY_TTL.progress;   // 7

// Importance multiplier for TTL
IMPORTANCE_MULTIPLIER[5]; // 2.0 (high importance = 2x TTL)
IMPORTANCE_MULTIPLIER[1]; // 0.5 (low importance = 0.5x TTL)

API Reference

See the exported types and functions in src/index.ts.