8000 GitHub - Jiminyang1/minibot: Local CLI AI agent with tool calling, MCP support, session persistence, and long-term user memory. · GitHub
[go: up one dir, main page]

Skip to content
Jiminyang1Public

About

Local CLI AI agent with tool calling, MCP support, session persistence, and long-term user memory.

Resources

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

131 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

MiniBot

MiniBot has been rewritten in TypeScript: Jiminyang1/minibot-ts. This repository holds the original Python version.

中文

A local command-line AI agent runtime built on OpenAI-compatible chat.completions. A single-owner synchronous turn loop with tool calling, unifying local tools, MCP, Skills, and cross-session long-term memory; every runtime fact flows through one event stream to the CLI, the Web/SSE UI, and the run log.

Capabilities

  • Token-level streaming: CLI typewriter and Web streaming bubbles (message.delta events; message.completed stays authoritative)
  • Local + MCP tools behind one Tool interface (declarative concurrency/approval properties)
  • Append-only session persistence with automatic compaction (safe-cut-point summaries, read-only tool-block fallback)
  • Structured RuntimeEvent as the sole output channel: CLI rendering, SSE Web UI, and runs.jsonl are all subscribers
  • Progressive skill disclosure (L1 metadata resident in the system prompt, L2 body on demand via read_skill)
  • Cross-session user memory (remember / forget) plus episodic memory (search_history searches raw messages and compaction summaries across all past sessions)
  • Scheduled tasks and reminders: created in natural language (cron routines / one-shots), fired unattended by minibot-daemon, delivered via macOS notifications and stored as searchable sessions
  • Sensitive-tool approval (ask / always; CLI prompt or Web approval endpoint). Once web pages, search results or MCP output are in a session, remember and fetch_url to a URL that no user message or untrusted tool result showed also ask, so injected text cannot quietly persist or send data out
  • Quality loop: golden evals scored per stage (pytest, Langfuse dataset replay, LLM-as-judge) and an experimental lessons loop that mines failures, drafts fixes for human review and retrieves approved ones
  • Reliability: exponential-backoff retries for transient LLM errors (never after the first delta), summariser failures degrade to truncation, tool args pre-validated against their JSON Schema
  • MCP over stdio / streamable_http; bundled SQLite demo and macOS system servers, draw.io MCP in the default config

Quick start

Uses uv (Python 3.12):

cp .env.example .env   # set OPENAI_API_KEY
uv sync
uv run minibot

uv sync --extra data also installs pandas, matplotlib, openpyxl and tabulate, for scripts that the exec tool runs on artifacts. MiniBot itself does not import them, and a plain uv sync removes them again.

Web UI:

uv run minibot-server --host 127.0.0.1 --port 8765
# open http://127.0.0.1:8765/

The server has no authentication. It accepts only loopback Host headers (localhost, 127.0.0.1, [::1]), which blocks DNS rebinding, and rejects writes that carry a foreign Origin. Binding a non-loopback --host prints a warning; add the names remote clients use with --allowed-host.

minibot opens a full-screen TUI (Textual) by default: scrollable conversation, Markdown-rendered replies, streaming, reasoning and tool calls collapsed into clickable one-liners, a bottom-pinned input, and an approval modal (y/n); Esc cancels the run, Ctrl+N starts a session. Slash commands work as usual.

The line REPL remains as minibot --plain (auto-fallback when piped): --verbose, --no-color, spinner status bar, typewriter streaming, and the collapsing reasoning preview all behave as before.

Architecture

flowchart TB
    subgraph entry [Entry]
        CLI[CLI]
        Web[Web / SSE]
    end

    subgraph core [Core]
        AS[AgentSession]
        AL[AgentLoop]
    end

    subgraph services [Services]
        CB[ContextBuilder]
        TB[TokenBudget]
        CP[Compactor]
        GATE[ToolApprovalGate]
    end

    subgraph infra [Infrastructure]
        SM[SessionManager]
        TRG[ToolRegistry]
        MCP[MCPHost]
        LLM[LLMClient]
    end

    subgraph subscribers [Event subscribers]
        EV[(Event stream)]
        FOLD[RunLogFold → runs.jsonl]
    end

    CLI --> AS
    Web --> AS
    AS --> AL
    AL --> CB & TB & CP & GATE
    AL --> LLM
    AL --> TRG
    AL --> SM
    AL -. emit .-> EV
    EV --> FOLD
    EV --> CLI
    EV --> Web
    TRG --> Local[Local Tools]
    TRG --> Proxy[MCPToolProxy]
    Proxy --> MCP
Loading

Per-turn flow — AgentLoop.run_turn is the single owner; each iteration runs in order:

  1. Budget check (TokenBudget); if over budget, Compactor.reduce (compact + persist + emit)
  2. ContextBuilder.build assembles the request as a pure function (system prompt / memory / time / skills catalog + projected history)
  3. Streamed LLM call (deltas publish as message.delta events; the terminal LLMResponse drives everything downstream)
  4. Tool execution (approval via the injected ToolApprovalGate; consecutive read-only tools run as a parallel batch)
  5. Message append (session persistence + event); large outputs become artifact references via ToolOutputMaterializer

Design constraints

Principle Detail
Single owner run_turn reads top-to-bottom as one turn's full lifecycle; turn state lives only in loop locals
Orchestration vs mechanics The loop only decides and delegates; mechanics live in named, independently testable components
One output channel RuntimeEvent is the sole exit; runs.jsonl is RunLogFold's fold over the stream
Append-only session messages.jsonl is the source of truth; compaction appends an entry and persists immediately
Projected view SessionContextProjector derives model-visible messages (incl. interrupted results for cut-off tool calls)
Sync turn loop Main loop is synchronous; MCP asyncio lives in background threads

Deep dives: docs/architecture.md — layering rules, per-turn sequence diagram, the full event catalog, the compaction decision tree, error/cancellation/concurrency semantics; docs/core-philosophy.md — the judgment criteria behind this shape (both in Chinese).

Modules

Path Role
bootstrap.py Composition root; wires the runtime
runtime/agent_session.py Run lifecycle: session lock, cancellation, run.* events, event fan-out
runtime/agent_loop.py The core loop (single owner)
runtime/context_builder.py Pure request assembly
runtime/budget.py Token budget and incremental estimation
runtime/compactor.py Compaction mechanics + immediate persistence (cut-point rules in compaction.py)
runtime/approval.py Approval policy and the injected approval gate
runtime/run_log_fold.py runs.jsonl as a fold over the event stream
session/ Append-only persistence + projection
tools/ Local Tool implementations and ToolRegistry
mcp_host/ MCP client, transports, MCPToolProxy
mcp_servers/ Bundled SQLite / macOS MCP servers
skills/ Skill metadata and Markdown bodies
user_memory.py Global long-term memory
evals/ Golden evals: sandbox, per-stage scoring, Langfuse dataset, pytest suite, trace promotion
lessons/ Lessons loop: mining, clustering, drafting, review, retrieval
cli.py / server.py CLI and Web entry points

Configuration

Agent (.env)

Variable Default Description
OPENAI_API_KEY — required
OPENAI_BASE_URL official OpenAI-compatible endpoint
MINIBOT_MODEL gpt-5.4-mini model name
MINIBOT_CONTEXT_WINDOW_TOKENS model catalog hard context-window override for unknown/compatible models
MINIBOT_MODEL_MAX_INPUT_TOKENS model catalog hard input-limit override when the provider has a separate cap
MINIBOT_MODEL_MAX_OUTPUT_TOKENS model catalog hard output-limit override for unknown/compatible models
MINIBOT_MAX_OUTPUT_TOKENS 4096 output ceiling actually sent to the provider on every request
MINIBOT_APPROVAL_MODE ask ask / always
MINIBOT_MAX_ITERATIONS 20 max LLM↔tool rounds per turn
MINIBOT_MAX_PARALLEL_TOOLS 4 parallel tool cap per response
MINIBOT_COMPACT_TOKEN_THRESHOLD model hard input limit compaction policy threshold, not the model window
MINIBOT_COMPACT_KEEP_RECENT_TOKENS 16000 recent context kept after compaction
MINIBOT_RESERVED_COMPLETION_TOKENS — legacy alias for MINIBOT_MAX_OUTPUT_TOKENS
MINIBOT_INCLUDE_REASONING_CONTENT auto reasoning-field passthrough (DeepSeek etc.)
MINIBOT_STREAMING auto set 0/off to disable streaming (for endpoints with broken SSE)
MINIBOT_LLM_MAX_RETRIES 3 max retries for transient LLM errors (429/5xx/connection)
MINIBOT_LESSONS auto auto (on when fastembed is installed and a lesson is approved) / on / off
MINIBOT_LESSONS_TOP_K / MINIBOT_LESSONS_MIN_SCORE 3 / 0.55 most lessons per request / cosine floor
MINIBOT_EVAL_JUDGE_MODEL the tested model model that grades the eval answer stage; pin it when comparing models
MINIBOT_FETCH_VIA_JINA 0 1 lets fetch_url try the Jina reader (r.jina.ai) first; better text extraction, but every fetched URL goes to that third party
LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY — setting both enables Langfuse tracing (one trace per turn: full requests, tools, approvals, compaction)
LANGFUSE_BASE_URL EU cloud Langfuse endpoint: your signup region, or a self-hosted URL
MINIBOT_LANGFUSE 1 0 keeps keys configured but disables tracing
MINIBOT_LANGFUSE_MAX_INPUT_MESSAGES 50 history messages uploaded per model call, after the system prompt (0 = all)
MINIBOT_HOME ~/.minibot global state home (sessions / run log / memory / mcp.json)

Persistence — state is centralized globally (default ~/.minibot, override with MINIBOT_HOME). Conversations belong to the user, not to the launch directory; the workspace only roots the fs/exec tools and is recorded as session metadata:

  • ~/.minibot/sessions/<id>/messages.jsonl — all sessions (append-only; meta records workspace provenance)
  • ~/.minibot/runs.jsonl — run summaries (fold of the event stream)
  • ~/.minibot/sessions/<id>/artifacts/ — large tool outputs
  • ~/.minibot/user_memory.json — long-term memory

Legacy per-workspace .minibot directories migrate with one command (id collisions renamed, run logs merged):

uv run minibot --migrate <dir1> <dir2> ...

MCP (mcp.json, global)

Lookup order: MINIBOT_MCP_CONFIG_PATH → ~/.minibot/mcp.json → bundled mcp.json.

  • Servers with enabled: true connect and discover tools at startup; one failing server never blocks startup
  • trusted: true skips approval; MCP output still counts as untrusted content for the approval rules above
  • Transports support ${ENV_VAR}, ${MINIBOT_PYTHON}, ${MINIBOT_PACKAGE_DIR}
  • The bundled config includes sqlite, macos_system, and an external draw.io MCP server launched via npx -y @drawio/mcp

Scheduled tasks

Say "generate my daily brief at 8 every morning" or "remind me to submit the report tomorrow at 9" in conversation — MiniBot calls schedule_task (approval-gated) and writes ~/.minibot/schedule.json. Firing needs the resident daemon:

uv run minibot-daemon    # resident process; single-instance lock
  • Routines use five-field cron (local time); one-shot reminders use ISO timestamps
  • Each firing creates a fresh [定时] session (searchable via search_history) and posts a macOS notification
  • Missed firings catch up within a one-hour grace window (laptop lid, daemon downtime); older misses are recorded and skipped
  • Unattended runs deny sensitive tools by default; set MINIBOT_APPROVAL_MODE=always for the daemon at your own risk
  • Manage with /tasks, /tasks cancel <id>, or plain natural language

Heartbeat: cron executes a fixed instruction on time; heartbeat wakes up and decides for itself. Say "patrol every 30 minutes" to create one (schedule_task with heartbeat mode): on each beat it reviews the ~/.minibot/HEARTBEAT.md checklist (inlined into the prompt) inside one persistent session, does what needs doing, and replies HEARTBEAT_OK to stay silent when nothing needs you — notifications fire only when something does. The checklist is plain Markdown (# lines are comments); the ever-growing session is kept in check by automatic compaction.

Quality loop: evals and lessons

Evals measure the agent. The lessons loop (experimental) turns past failures into rules that a human approves. run --lessons compare is how to check whether approved lessons help. With ten cases run once each, one flip is ten points of noise, so add --repeat N: each case then has a pass count per mode, and the report separates cases that always pass, always fail, or pass only sometimes.

Golden evals (evals/). Cases live in evals/cases.json, mirrored to the Langfuse dataset minibot-golden. Each case runs one sandboxed turn and is scored per stage: skill selection → tool selection → tool arguments → answer (LLM-as-judge) → outcome.

uv run python -m minibot.evals run                    # every case; prints the first failing stage per case + trace URL
uv run python -m minibot.evals pytest -k tool_args    # pytest, one test per (case, stage); replays the Langfuse dataset
uv run python -m minibot.evals traces --failed        # recent real runs that went wrong
uv run python -m minibot.evals promote <trace_id>     # turn a real run into a case: recorded tool outputs replay in the sandbox
uv run python -m minibot.evals run --lessons compare  # same cases with lessons off and on: pass rates, flips, calls/tokens/latency
uv run python -m minibot.evals run --repeat 3         # the same cases three times: pass / flaky / fail per case, pass-rate range
uv run python -m minibot.evals run --repeat 3 --baseline <run>  # also compare with a saved run: stage rates, cost, cases that got worse + trace
uv run python -m minibot.evals compare <base> <new>   # the same comparison between two saved runs

Every run saves its scored rows (repeats pooled) as $MINIBOT_HOME/evals/<run>.json; that run name is what --baseline and compare take. Only cases present in both runs, with the same definition, are compared; a case whose input or expectations changed in between is listed instead, and a change in the scoring code is flagged. Each run also records a hash of every prompt, skill and tool definition the model is shown, so the report lists the parts whose text changed and, for each case that got worse, the changed parts it used (the place to look first). A change of judge is flagged too: the answer stage is graded by MINIBOT_EVAL_JUDGE_MODEL (default: the tested model), so pin it before comparing two models. Each row of runs.jsonl also records the lessons its requests carried and, with Langfuse on, its trace id.

The pytest suite calls the real model, so it only runs with -m golden (the pytest subcommand adds it); plain pytest collects unit tests only.

Lessons (lessons/, needs uv sync --extra lessons) — experimental. A lesson is a human-approved rule: when , do . It has not run on real failures yet, and its thresholds come from a small hand-written set; uv run python -m minibot.lessons.benchmark re-measures them.

uv run python -m minibot.lessons mine --dry-run   # failures found in sessions and runs.jsonl, clustered
uv run python -m minibot.lessons mine             # the LLM drafts one lesson per cluster
uv run python -m minibot.lessons review           # approve / edit / reject each draft
uv run python -m minibot.lessons list --status approved

Mining reads failed tool calls, failed or exhausted turns, denied approvals and user corrections ("不对", "wrong"). Incidents are clustered with a local embedding model (BAAI/bge-small-zh-v1.5, about 90 MB, cached under ~/.minibot/models); no data leaves the machine and there is no vector database. At request time, each user message gets the approved lessons whose trigger or evidence requests match it, appended to that message. Never the system prompt, and never only the latest message: a message must read the same in every request, or the prompt cache loses the turn that follows it. model.request.started names the lessons in the request. Only approved lessons are ever injected: drafts are mined from tool output and web text, so the review step is also the prompt-injection gate.

CLI commands

/sessions · /new · /resume <id> · /delete <id|current> · /compact · /mcp · /mcp tools [server] · /memory [clear|forget <id>] · /skills · /tasks [cancel <id>] · /permission [ask|always] · /config · /help

Web API

Method Path Description
POST /runs create a run, returns run_id
GET /runs/{run_id}/events SSE with Last-Event-ID replay
POST /runs/{run_id}/cancel cancel a run
POST /runs/{run_id}/approvals/{approval_id} resolve a tool approval
GET /sessions list sessions
GET /sessions/current current session
POST /sessions create and switch the current session
GET/PATCH/DELETE /sessions/{id} read, retitle, delete a session
GET /sessions/{id}/messages conversation history

Disconnecting from SSE only cancels the subscription, not the background run.

Tests

uv run python -m unittest discover -s tests
uv run ruff check .

Event names and payloads are the stable contract shared by the CLI, SSE, and the run log; consult the event catalog in docs/architecture.md before changing them.

About

Local CLI AI agent with tool calling, MCP support, session persistence, and long-term user memory.

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0