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

bash

# 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

bash

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

bash

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

bash

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

HTTP Server

bash

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

bash

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

List Instances

bash

mini-agent instance list

Use Specific Instance

bash

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

Start Instance Server

bash

mini-agent instance start abc12345

Data Structure

code

~/.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)

yaml

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

instances:
  - id: default
    role: standalone

Instance Config (instance.yaml)

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:

code

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

javascript

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