Mini-Agent

Personal AI Agent with Memory + Proactivity. A lightweight agent that maintains long-term memory, schedules proactive tasks, and supports multi-instance deployment.

Features

• Long-term Memory: File-based memory using Markdown (MEMORY.md)
• Daily Notes: Automatic logging of conversations (daily/YYYY-MM-DD.md)
• Task Management: HEARTBEAT.md for active and scheduled tasks
• Proactive Mode: Cron-based task checking and execution
• Multi-Instance: Run multiple isolated instances with different configurations
• HTTP API: RESTful API for integration
• Claude Integration: Uses Claude Code CLI for AI processing

Quick Start

# Install via script (recommended)
curl -fsSL https://raw.githubusercontent.com/miles990/mini-agent/main/install.sh | bash

# Or manually
git clone https://github.com/miles990/mini-agent.git ~/.mini-agent
cd ~/.mini-agent && pnpm install && pnpm build && npm link

Usage

Interactive Chat

mini-agent

Commands in chat:

• /help - Show available commands
• /search <query> - Search memory
• /remember <text> - Save to memory
• /heartbeat - Show active tasks
• /trigger - Execute pending tasks
• /proactive on|off - Toggle proactive mode
• /quit - Exit

Process Files

mini-agent readme.md "summarize this"
mini-agent src/app.ts "review this code"
mini-agent a.txt b.txt "compare these files"

Pipe Mode

echo "Hello" | mini-agent "translate to Chinese"
git diff | mini-agent "write commit message"

HTTP Server

mini-agent server --port 3001

API endpoints:

• POST /chat - Send a message
• GET /memory - Read memory
• GET /memory/search?q= - Search memory
• POST /memory - Add to memory
• GET /tasks - List tasks
• POST /tasks - Add a task
• POST /heartbeat/trigger - Trigger tasks

Multi-Instance Support

Create Instances

mini-agent instance create --name "Research" --port 3002
mini-agent instance create --name "Coding" --port 3003 --role worker

List Instances

mini-agent instance list

Use Specific Instance

mini-agent --instance abc12345 "hello"
mini-agent --instance abc12345 server

Start Instance Server

mini-agent instance start abc12345

Data Structure

~/.mini-agent/
├── config.yaml                 # Global configuration
├── instances/
│   ├── default/                # Default instance
│   │   ├── instance.yaml       # Instance config
│   │   ├── MEMORY.md           # Long-term memory
│   │   ├── HEARTBEAT.md        # Tasks
│   │   ├── SKILLS.md           # Available skills
│   │   └── daily/              # Daily notes
│   └── {uuid}/                 # Custom instances
└── shared/
    └── GLOBAL_MEMORY.md        # Shared memory (optional)

Configuration

Global Config (~/.mini-agent/config.yaml)

defaults:
  port: 3001
  proactiveSchedule: "*/30 * * * *"
  claudeTimeout: 120000
  maxSearchResults: 5

instances:
  - id: default
    role: standalone

Instance Config (instance.yaml)

id: "abc12345"
name: "Research Assistant"
role: standalone
port: 3002

persona:
  description: "A technical research assistant"
  systemPrompt: |
    You are a helpful research assistant...

proactive:
  enabled: true
  schedule: "0 9,12,18 * * *"

memory:
  maxSize: "50MB"
  syncToGlobal: false

Memory Tags

The agent uses special tags in responses:

• [REMEMBER]...[/REMEMBER] - Content to save to memory
• [TASK schedule="..."]...[/TASK] - Task to add to heartbeat

Example:

User: Remember that I prefer TypeScript
Assistant: [REMEMBER]User prefers TypeScript over JavaScript[/REMEMBER]
I'll remember that you prefer TypeScript!

Integration

As Claude Code Skill

Copy this SKILL.md to your project's .claude/skills/mini-agent/ directory.

As API Service

// Chat with agent
const response = await fetch('http://localhost:3001/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ message: 'Hello!' })
});
const data = await response.json();
console.log(data.content);

// Add to memory
await fetch('http://localhost:3001/memory', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ content: 'Important fact', section: 'Facts' })
});

Requirements

• Node.js >= 20
• Claude Code CLI (claude command available)

License

MIT