Shrimp Kit

AI Agent Infrastructure Framework + Monitoring Dashboard + Companion Framework

Build production-ready AI agent systems with scheduling, memory, monitoring, Telegram bridge, and companion personality — all in TypeScript.

Live Dashboard Demo | Quick Start

Features

• Scheduling — Cron, interval, daily/weekly/monthly with catch-up after sleep, night mode
• Memory — Three-layer system (static / curated / dynamic) with TTL, GC, dedup, promotion
• Monitoring — Health checks, heartbeat detection, disk/process inspectors
• Communication — Telegram bridge with night silence and notification queuing
• Companion — AI personality framework with emotion triggers, heartbeat conversations, TTS/image gen pipeline
• Dashboard — Next.js monitoring UI with real-time status, schedule timeline, memory browser, log viewer

Installation

Option A: Scaffold a New Project (Recommended)

# Create a new agent project
bunx shrimp-kit init my-agent
cd my-agent
bun install

# With AI companion templates
bunx shrimp-kit init my-agent --companion

This generates a ready-to-run project with config files, schedule templates, and boilerplate code.

Option B: Clone the Repo

git clone https://github.com/dead1786/shrimp-kit.git
cd shrimp-kit
bun install

# Run tests (162 tests)
bun run test

# Build all packages
bun run build

# Start dashboard locally
cd apps/dashboard && bun run dev

Prerequisites

• Bun >= 1.3
• TypeScript 5.7+

Packages

Package	Description
@shrimp-kit/core	Shared types, Zod schemas, logger, utilities
@shrimp-kit/scheduler	Schedule engine (cron, interval, daily, weekly, monthly)
@shrimp-kit/memory	Three-layer memory with TTL, GC, dedup, promotion
@shrimp-kit/bridge	Telegram bridge + notification queue + night silence
@shrimp-kit/monitor	Health check framework with pluggable inspectors
@shrimp-kit/companion	AI companion (persona, heartbeat, TTS, image gen)

Quick Example

import { Logger } from "@shrimp-kit/core";
import { MemoryStore } from "@shrimp-kit/memory";
import { Scheduler } from "@shrimp-kit/scheduler";
import { HealthChecker, processInspector } from "@shrimp-kit/monitor";
import { Bridge } from "@shrimp-kit/bridge";

const logger = new Logger({ name: "my-agent", level: "info" });

// Memory — store and query knowledge
const memory = new MemoryStore("./data/memory.json", logger);
await memory.load();
memory.add({ type: "preference", key: "tz", value: "Asia/Taipei", importance: 4 });

// Scheduler — run tasks on schedule
const scheduler = new Scheduler({
  schedulePath: "./data/schedule.json",
  statePath: "./data/state.json",
  queuePath: "./data/queue.json",
  logger,
});
await scheduler.start();

// Monitor — health checks
const checker = new HealthChecker({ logger });
checker.register("my-service", processInspector("svc", "node.*server"));
const report = await checker.runAll();

// Bridge — Telegram messaging with night silence
const bridge = new Bridge({
  config: { botToken: process.env.BOT_TOKEN!, chatId: 123456 },
  logger,
  nightHours: ["00:00", "08:00"],
  notifyQueuePath: "./data/notify-queue.json",
});
await bridge.notify("System started!");

AI Companion

import { Logger } from "@shrimp-kit/core";
import { Companion, TopicManager } from "@shrimp-kit/companion";
import { MemoryStore } from "@shrimp-kit/memory";

const logger = new Logger({ name: "companion", level: "info" });
const memory = new MemoryStore("./data/memory.json", logger);
await memory.load();

const companion = new Companion({
  persona: {
    name: "Luna",
    triggerWord: "LUNA",
    systemPrompt: "You are Luna, a warm and witty companion...",
    greetings: ["Hey~", "What's up?"],
    emotionTriggers: [
      { id: "tired", patterns: ["tired", "exhausted"], responseHint: "Insist they rest", tone: "caring" },
    ],
  },
  memory,
  generateResponse: async (system, user) => {
    // Wire up your LLM here (Claude, GPT, etc.)
    return callYourLLM(system, user);
  },
  logger,
});

const reply = await companion.chat("I'm so tired...", "User");
const heartbeat = await companion.heartbeat(); // proactive conversation

See examples/jellyfish/ for a complete example.

Architecture

shrimp-kit/
├── packages/
│   ├── core/          # Shared types, Zod schemas, logger
│   ├── scheduler/     # Schedule engine
│   ├── memory/        # Three-layer memory system
│   ├── bridge/        # Telegram bridge
│   ├── monitor/       # Health checks
│   └── companion/     # AI companion framework
├── apps/
│   ├── dashboard/     # Next.js monitoring dashboard
│   └── cli/           # Project scaffolder
├── examples/
│   └── jellyfish/     # Example companion config
├── turbo.json
└── package.json

Dependency Graph

core ─────────────────────────────────┐
  ├── scheduler ──── monitor          │
  ├── memory ──────── companion       │
  └── bridge ──────── companion       │
                       └── dashboard ─┘

Tech Stack

Component	Choice	Why
Runtime	Bun	Native TypeScript, fast, built-in test runner
Monorepo	Turborepo	Incremental builds, caching
Frontend	Next.js 15 (App Router)	Vercel deployment, RSC
Validation	Zod	Type inference + runtime validation
Telegram	grammy	Best TypeScript support
UI	Tailwind CSS + Recharts	Professional, customizable

Testing

162 tests across 9 suites:

bun run test

Package	Tests
core	29
scheduler	28
memory	13
bridge	8
monitor	11
companion	11
cli	5
integration	30

Dashboard

The monitoring dashboard provides real-time visibility into your agent system:

• System Status — Health grid with 9 inspectors
• Schedule Timeline — 24h visual timeline of all tasks
• Memory Browser — L1/L2/L3 layer visualization with stats
• Log Viewer — Unified log from 5 sources with filtering
• Agent Overview — Multi-agent status and communication

Try it: shrimp-kit.vercel.app

License

MIT

Author

Built by dead1786.