picoagents

<div align="center">
  <img src="assets/logo.png" alt="picoagent logo" width="150" style="border-radius: 20%; margin-bottom: 20px;" />
  <h1>picoagent: Ultra-Lightweight & Mathematically Routed AI</h1>
  <p>
    <a href="https://github.com/borhen68/picoagents"><img src="https://img.shields.io/badge/github-repo-blue" alt="GitHub"></a>
    <img src="https://img.shields.io/badge/python-≥3.11-blue" alt="Python">
    <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
  </p>
</div>

**picoagent** is an ultra-lightweight personal AI assistant focused on mathematical tool-routing and safety.

It delivers advanced agent functionality (vector memory, sandboxing, dual-layer memory, tool chains, plugin hooks) in a compact codebase.

## News

- **2026-03-01** **Market Query Improvements:** Crypto price queries such as "BTC price today" now resolve through a dedicated CoinGecko lookup path in `search`.
- **2026-03-01** **Cron Reliability Fixes:** Gateway cron execution now respects configured `cron_file`, and cron args are normalized (`everyseconds`, `prompt`, etc.).
- **2026-03-01** **Memory Response Hardening:** "Where is memory stored?" style questions return deterministic local file paths and memory preview snippets.
- **2026-02-28**  **Multi-Turn Tool Chains:** Agent can now chain up to 3 tool executions automatically without requiring new user messages. Each tool result is fed back into entropy scoring for the next tool.
- **2026-02-28**  **Tool Timeout Protection:** Every tool execution is now wrapped with a 30-second timeout (configurable). Prevents hanging tools from blocking the agent forever.
- **2026-02-28**  **Tool Result Caching:** Successful tool results are cached for 60 seconds, avoiding redundant API calls for repeated queries.
- **2026-02-28**  **Plugin Hook System:** New `picoagent/hooks.py` module exposes `on_turn_start`, `on_tool_result`, and `on_turn_end` events for extensibility.
- **2026-02-28**  **Skill Install Command:** New `picoagent install-skill <user/repo>` command installs skills directly from GitHub.
- **2026-02-28**  **Skill Hot-Reload:** Skills can now be reloaded on-the-fly by sending SIGHUP to the running agent.
- **2026-02-28**  **Skill Usage Telemetry:** Tracks which skills are used and how often in `~/.picoagent/skill_usage.jsonl`.
- **2026-02-28**  **Skill Dependencies:** Skills can now declare `requires: [other-skill]` to auto-load dependencies.
- **2026-02-27**  **Workspace Sandboxing & Dual-Layer Memory:** Built-in `FileTool` and `ShellTool` are now safely sandboxed to your workspace. The LLM now continuously consolidates your long conversations into a searchable `HISTORY.md` and semantic `MEMORY.md` file in the background!
- **2026-02-27**  **Entropy-Gating Engine:** Agent workflow now calculates Shannon Entropy and TF-IDF scores locally before executing tools to prevent hallucinations.
- **2026-02-26**  **Template Support:** Full compatibility with nanobot-style Markdown templates (`SOUL.md`, `USER.md`).

## Key Features

**Multi-Turn Tool Chains**: The agent can automatically execute up to 3 tool calls in sequence, feeding each result back into entropy scoring for the next decision.

**Tool Timeout Protection**: Every tool execution has a configurable timeout (default 30s) to prevent hanging.

**Tool Result Caching**: Successful tool results are cached for 60 seconds to avoid redundant API calls.

**Plugin Hook System**: Extend picoagent with custom plugins via `on_turn_start`, `on_tool_result`, and `on_turn_end` hooks.

**Skill Install from GitHub**: Install skills directly with `picoagent install-skill user/repo` without manual downloads.

**Dual-Layer Memory**: Combines vector recall with durable markdown memory files (`MEMORY.md` and `HISTORY.md`).

**Mathematically Routed**: Uses Shannon Entropy to gate tool execution. If uncertainty is high, the agent asks for clarification instead of guessing.

**Strict Safety Sandboxing**: Regex barriers block destructive shell commands, and file traversal is locked to the workspace root.

**Maintenance Commands**: Includes `doctor`, `prune-memory`, and `threshold-stats` CLI commands for runtime diagnostics.

## Architecture Stack

- **Core Routing:** `LocalHeuristicClient` + `EntropyScheduler`
- **Memory Engine:** `VectorMemory` + `DualMemoryStore`
- **Session Layer:** `SessionManager` + `AgentLoop` (Asyncio)

## Use Cases

<table align="center">
  <tr align="center">
    <th><p align="center">Secure Local Automation</p></th>
    <th><p align="center">Full-Stack Software Engineer</p></th>
    <th><p align="center">Smart Daily Routine Manager</p></th>
    <th><p align="center">Personal Knowledge Assistant</p></th>
  </tr>
  <tr>
    <td align="center">Sandboxed • Monitored • Auditable</td>
    <td align="center">Develop • Deploy • Scale</td>
    <td align="center">Cron Jobs • Heartbeats • Automate</td>
    <td align="center">Vector Recall • Decay • Reasoning</td>
  </tr>
</table>

## Install

**Install from source** (latest features, recommended for development)

```bash
git clone https://github.com/borhen68/picoagents.git
cd picoagents
pip install -e .
```

## Quick Start

> [!TIP]
> Set your API key in `~/.picoagent/config.json`.

**1. Initialize**

```bash
picoagent onboard
```

**2. Configure (`~/.picoagent/config.json`)**

Add your preferred provider and API keys (example using Groq):
```json
{
  "providers": {
    "groq": {
      "apiKey": "YOUR_GROQ_KEY"
    }
  },
  "agents": {
    "provider": "groq",
    "model": "llama-3.3-70b-versatile"
  }
}
```

**3. Chat**

```bash
picoagent agent
```

That's it! You have a working AI assistant in 2 minutes.

## Chat Apps (Gateway)

Connect picoagent to your favorite chat platform. It supports persistent sessions across all of them!

| Channel | What you need |
|---------|---------------|
| **Telegram** | Bot token from @BotFather |
| **Discord** | Bot token + Message Content intent |
| **WhatsApp** | Inbox/Outbox config via Webhook bridge |
| **Slack** | Bot token + Channel ID |
| **Email** | IMAP/SMTP credentials |

<details>
<summary><b>Telegram</b> (Recommended)</summary>

**1. Create a bot**
- Open Telegram, search `@BotFather`
- Send `/newbot`, follow prompts
- Copy the token

**2. Configure** (`~/.picoagent/config.json`)

```json
{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_CHAT_ID"],
      "replyToMessage": true,
      "pollSeconds": 3
    }
  }
}
```

**3. Run**

```bash
picoagent gateway
```

</details>

<details>
<summary><b>Discord</b></summary>

**1. Configure** (`~/.picoagent/config.json`)

```json
{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "channelId": "YOUR_CHANNEL_ID",
      "replyAsReply": true,
      "pollSeconds": 3
    }
  }
}
```

**2. Run**

```bash
picoagent gateway
```

</details>

<details>
<summary><b>Slack</b></summary>

**1. Configure** (`~/.picoagent/config.json`)

```json
{
  "channels": {
    "slack": {
      "enabled": true,
      "token": "xoxb-YOUR_BOT_TOKEN",
      "channelId": "YOUR_CHANNEL_ID",
      "pollSeconds": 3
    }
  }
}
```

**2. Run**

```bash
picoagent gateway
```

</details>

<details>
<summary><b>Email</b></summary>

**1. Configure** (`~/.picoagent/config.json`)

```json
{
  "channels": {
    "email": {
      "enabled": true,
      "username": "bot@example.com",
      "password": "app-password",
      "imapHost": "imap.example.com",
      "smtpHost": "smtp.example.com",
      "imapPort": 993,
      "smtpPort": 587,
      "useTls": true
    }
  }
}
```

**2. Run**

```bash
picoagent gateway
```

</details>

## Configuration

Config file: `~/.picoagent/config.json`

### Providers

picoagent separates out its fast embedding providers from its chat providers. This allows you to mix and match (e.g., fast Groq Chat with high-dimension OpenAI Embeddings).

| Provider | Purpose | Get API Key |
|----------|---------|-------------|
| `custo

[truncated…]