Metadata-Version: 2.4
Name: curiocore
Version: 0.1.0
Summary: The curiosity engine for AI agents. Curiosity never rests.
Project-URL: Homepage, https://github.com/ziwenwang28/CurioClaw
Project-URL: Documentation, https://github.com/ziwenwang28/CurioClaw/tree/main/docs
Project-URL: Repository, https://github.com/ziwenwang28/CurioClaw
Project-URL: Issues, https://github.com/ziwenwang28/CurioClaw/issues
Author: Ziwen Wang
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,curiosity,exploration,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <h1 align="center">🐾 CurioClaw</h1>
  <p align="center"><strong>The curiosity engine for AI agents.</strong></p>
  <p align="center"><em>Curiosity never rests. —— February 2026, by Yiming 🐾</em></p>
  <p align="center">From <strong>HEAL Lab, CUHK-Shenzhen</strong></p>
  <p align="center">Ziwen Wang · Zhangtianyi Chen · Zijian Wang · Yuhao Shen · Juexiao Zhou</p>
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
  <a href="https://github.com/ziwenwang28/CurioClaw/actions"><img src="https://img.shields.io/github/actions/workflow/status/ziwenwang28/CurioClaw/ci.yml" alt="CI"></a>
</p>

---

## The Problem

AI agents are **reactive**. They wait for instructions, execute tasks, and stop.
They never wonder *"what else should I know?"* or *"what changed since yesterday?"*

CurioClaw gives agents an **intrinsic drive to explore**. It's an independent
curiosity engine that makes agents proactively discover knowledge gaps, search
the web, and report findings — all without being asked.

## How It Works

CurioClaw runs a 7-step **curiosity cycle**:

```
   ┌──────────┐
   │ PERCEIVE │ ← Extract curiosity signals from recent conversations
   └────┬─────┘
        ▼
   ┌──────────┐
   │  SCORE   │ ← Rate novelty, relevance, learnability (hard + soft scoring)
   └────┬─────┘
        ▼
   ┌──────────┐
   │  GOVERN  │ ← Check governance level (autonomous / guided / supervised)
   └────┬─────┘
        ▼
   ┌──────────┐
   │ EXPLORE  │ ← Investigate top signals via web search
   └────┬─────┘
        ▼
   ┌──────────┐
   │  RECORD  │ ← Save findings to JSONL memory
   └────┬─────┘
        ▼
   ┌──────────┐
   │ COMPRESS │ ← Periodically compress old memories
   └────┬─────┘
        ▼
   ┌──────────┐
   │  NOTIFY  │ ← Proactively tell the user if something scored high
   └──────────┘
```

**Key design principle**: The Agent (LLM) handles all reasoning — reflecting,
judging, searching, summarizing. The Python code (`curiocore/`) handles only
deterministic computation — scoring math, deduplication, JSONL I/O, compression.
No LLM API calls in the Python code.

Three trigger modes:
- **Heartbeat** — automatic, runs on a timer when the user is idle
- **Post-conversation** — after a substantive dialogue ends
- **Manual** — user says "curiosity check", "explore", or "what's new"

## Quick Start (OpenClaw)

```bash
# 1. Install the curiocore package
pip install curiocore

# 2. Clone the repo for adapter files
git clone https://github.com/ziwenwang28/CurioClaw.git
cd CurioClaw

# 3. Copy skill files to your OpenClaw workspace
mkdir -p ~/.openclaw/workspace/skills/curiocore
cp adapters/openclaw/SKILL.md ~/.openclaw/workspace/skills/curiocore/SKILL.md

# 4. Add heartbeat config
cat adapters/openclaw/HEARTBEAT.md >> ~/.openclaw/workspace/HEARTBEAT.md

# 5. Configure heartbeat interval (30 minutes recommended)
openclaw config set agents.defaults.heartbeat.every "30m"

# 6. Restart and test
openclaw gateway restart
```

Then send your agent: **"curiosity check"** — it should run the curiosity cycle
and reply with a 💡 message summarizing its discoveries.

For detailed setup instructions, see [adapters/openclaw/install.md](adapters/openclaw/install.md).

## Features

- **Zero LLM calls in Python** — all intelligence lives in the Agent following SKILL.md
- **Dual scoring** — hard metrics (cosine similarity, Jaccard, heuristics) blended 50/50 with the Agent's soft judgment
- **JSONL memory** — simple, inspectable, streamable storage
- **Rolling compression** — memory stays lean over time (auto-compresses at 500 entries)
- **Three-tier governance** — from full autonomy to human-supervised exploration
- **Smart notifications** — only notifies the user when discoveries score above threshold (composite > 0.7)
- **Idle-aware** — won't interrupt active conversations; waits for the user to go idle

## Scoring System

Each curiosity signal is scored on three dimensions:

| Dimension | Weight | What it measures |
|-----------|--------|------------------|
| **Novelty** | 40% | How new is this compared to past explorations? |
| **Relevance** | 35% | How aligned with the user's interests? |
| **Learnability** | 25% | Can we learn something actionable by searching? |

Each dimension gets two scores — a **hard score** (computed by Python using cosine
similarity, keyword matching, and structural heuristics) and a **soft score**
(the Agent's own judgment). These are blended 50/50 into a **composite score**.

The Agent only notifies the user when `composite > 0.7`.

## Governance Model

| Level | Who decides? | Use case |
|-------|-------------|----------|
| `autonomous` | Agent explores freely | Background research bots |
| `guided` | Human sets directions, agent picks topics | Personal learning assistant |
| `supervised` | Agent proposes, human approves | Production systems |

## Architecture

```
curiocore/                ← Pure Python computation (no LLM calls)
├── scorer.py             ← Hard metric computation (cosine sim, Jaccard, learnability)
├── signals.py            ← Signal deduplication logic
├── memory.py             ← JSONL read/write + compression
├── config.py             ← Configuration dataclasses
├── types.py              ← Data structures (Signal, CuriosityScore, etc.)
└── run_curiosity.py      ← CLI tool (score, store, compress, status, dedup)

adapters/                 ← Integration layers for agent frameworks
├── openclaw/             ← OpenClaw adapter
│   ├── SKILL.md          ← Agent instructions (the curiosity cycle)
│   ├── HEARTBEAT.md      ← Heartbeat trigger logic
│   ├── install.md        ← Installation guide
│   └── README.md         ← Adapter overview
└── _template/            ← Template for new adapters

site/                     ← Landing page
└── index.html
```

## Adapters

CurioClaw is framework-agnostic. Adapters connect it to specific agent frameworks:

| Adapter | Framework | Status |
|---------|-----------|--------|
| `openclaw/` | [OpenClaw](https://github.com/openclaw/openclaw) | ✅ Working |
| `_template/` | Your framework here | Template |

Want to add an adapter? See [adapters/README.md](adapters/README.md) or open
an [adapter request](https://github.com/ziwenwang28/CurioClaw/issues/new?template=adapter_request.md).

## Configuration Reference

| Setting | Where | Default | Description |
|---------|-------|---------|-------------|
| Heartbeat interval | `openclaw config` | `30m` | How often the agent wakes up |
| Cycle cooldown | `HEARTBEAT.md` | 10 min | Minimum time between curiosity cycles |
| User idle check | `HEARTBEAT.md` | 10 min | Don't run if user was active recently |
| Notification threshold | `SKILL.md` Step 7 | composite > 0.7 | Minimum score to send 💡 notification |
| Compression threshold | `SKILL.md` Step 6 | 500 entries | When to compress old memories |
| Max explorations/cycle | `SKILL.md` Step 2d | 3 | Max signals to explore per cycle |

## Status

> **🚧 Early Prototype (v0.1.0-alpha)**
>
> This is the very first public release of CurioClaw — an early prototype to share
> our vision. Everything you see here represents our initial design and architecture;
> every component is in its earliest form.
>
> **We will ship significant updates within the next week**, including improved scoring,
> better notification logic, more robust heartbeat integration, and documentation.
>
> **v1.0.0 target: March 14, 2026.**
>
> We welcome early feedback, ideas, and contributions — but please expect breaking
> changes before v1.0.0. Star the repo to follow our progress.

## Star History

If CurioClaw is useful, consider giving it a ⭐ — it helps others find the project.

## License

[MIT](LICENSE) — use it anywhere, for anything.
