Sga Mcts Atoms

Name: Sga Mcts Atoms
Rating: 3.5 (1 reviews)
Author: msbel5

By msbel5 👁 8 views ▲ 0 votes

Plan-time atom retrieval for OpenClaw — distill past Inspector-approved runs (arXiv 2604.14712)

Homepage GitHub

Install

pip install lancedb

Configuration Example

{
  "tool": "retrieve_atoms",
  "input": {
    "task_summary": "Add type hint to load_config in trading/config.py",
    "top_k": 3,
    "sim_floor": 0.4
  }
}

README

# @msbel/openclaw-sga-mcts-atoms

> Plan-time atom retrieval for OpenClaw — distill past Inspector-approved
> agent runs into reusable tool-use sequences, retrieve at plan time.

[![npm version](https://img.shields.io/npm/v/@msbel/openclaw-sga-mcts-atoms.svg)](https://www.npmjs.com/package/@msbel/openclaw-sga-mcts-atoms)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Inspired by **SGA-MCTS: Skill-Guided Atom MCTS** ([arXiv 2604.14712](https://arxiv.org/abs/2604.14712)).

## Why

Captain re-derives every plan from scratch. When a similar task ran
successfully last week, today's plan still costs the same Sonnet
tokens. Atom retrieval reuses proven approaches: 30-60% token cost
reduction on tasks with priors.

This is v1 — top-k vector retrieval over an atom store. The full
MCTS tree search from the paper is v2 (when v1 proves useful).

## How it works

```
┌────────────────────┐  Inspector APPROVED   ┌───────────────────┐
│  Agent session     ├──────────────────────▶│  agent_end hook   │
│  (Captain →        │                       │  → atom_extractor │
│   Builder →        │                       └─────────┬─────────┘
│   Inspector)       │                                 │
└────────────────────┘                                 ▼
                                              ┌───────────────────┐
┌────────────────────┐                        │  lancedb/atoms    │
│  New task arrives  │     plan time          │  (1536-dim        │
│                    ├──────────────────────▶│   embeddings)     │
└────────────────────┘    retrieve_atoms      └───────────────────┘
                          tool call
```

Every Inspector-APPROVED session becomes an atom. Captain's next plan
queries the store via the `retrieve_atoms` MCP tool and adapts the
closest match (cosine >= 0.85 = strong match, cite the atom_id).

## Install

This plugin uses `child_process` to call out to Python (lancedb +
openai). OpenClaw's safety guard requires the unsafe-install flag:

```bash
# 1. Install the plugin
openclaw plugins install --dangerously-force-unsafe-install \
    @msbel/openclaw-sga-mcts-atoms

# 2. Install the Python side
mkdir -p ~/.openclaw/sga_mcts
cd ~/.openclaw/sga_mcts
python3 -m venv .venv
.venv/bin/pip install lancedb openai pyarrow

# 3. Drop atom_extractor.py + atom_retriever.py + tests/seed_three.py
#    from this repo's `python/` dir into ~/.openclaw/sga_mcts/
cp -r python/* ~/.openclaw/sga_mcts/

# 4. Set OPENAI_API_KEY (used for embeddings — text-embedding-3-small)
echo "OPENAI_API_KEY=sk-..." >> ~/.openclaw/.env

# 5. Add to plugins.allow + enable + permission
openclaw plugins enable sga-mcts-atoms
# Then edit ~/.openclaw/openclaw.json:
#   plugins.entries["sga-mcts-atoms"].hooks.allowConversationAccess = true

# 6. (Optional) Seed cold-start with 3 handcrafted atoms
~/.openclaw/sga_mcts/.venv/bin/python ~/.openclaw/sga_mcts/tests/seed_three.py

# 7. Restart gateway
systemctl --user restart openclaw-gateway
```

Verify:

```bash
openclaw plugins inspect sga-mcts-atoms
# Expect:
#   Status: loaded
#   Typed hooks: agent_end
#   Tools: retrieve_atoms
#   Policy: allowConversationAccess: true
```

## Captain integration

Add this paragraph to your Captain agent's `AGENT.md`:

> Before decomposing any non-trivial task into steps, ALWAYS call the
> `retrieve_atoms` tool with a one-line task summary. If a returned
> atom has cosine >= 0.85 to the current task, strongly consider
> adapting that proven approach. Cite the atom_id in your plan:
> "Following pattern from atom abc12345 (cosine 0.91): clone, edit,
> test, ship. Deviations from atom: ..."

## Atom schema

| field | type | notes |
|-------|------|-------|
| atom_id | string | UUID |
| created_ts | string | ISO-8601 UTC |
| task_summary | string | <= 200 chars, captured from session |
| task_embedding | float[1536] | text-embedding-3-small |
| agent_chain | string | "liaison,captain,builder,inspector" |
| tool_sequence_json | string | JSON list[{agent,tool,input_summary,target_agent}] |
| approved | bool | Inspector verdict |
| premium_reqs_used | int32 | budget burn |
| wall_time_seconds | int32 | session duration |
| iterations | int32 | how many Inspector rounds |
| git_commit_sha | string | empty if none |
| tags | string | auto-tagged keywords |
| lessons | string | short post-hoc lessons |

## API

### Auto-extract (passive)

When `agent_end` fires with a session whose verdict is `APPROVED`, the
plugin runs `atom_extractor.py <session_id> --approved` automatically.
No Captain involvement needed.

### `retrieve_atoms` (active tool call)

```jsonc
{
  "tool": "retrieve_atoms",
  "input": {
    "task_summary": "Add type hint to load_config in trading/config.py",
    "top_k": 3,
    "sim_floor": 0.4
  }
}
```

Returns rendered text with up to `top_k` matches, each formatted as:

```
ATOM 73325939  cosine=0.75  chain=[liaison,captain,builder,inspector]  premium=3
TASK:    Fix typo in README.md heading of a Python project
TAGS:    python,readme,typo
LESSONS: Inspector wanted the diff in PR description; builder added it on iter 1.
```

If no matches above floor, returns "no atoms above similarity floor 0.40".

## Cold start

The atom store starts empty. Three options:

1. **Wait organically** — atoms accumulate as Inspector-approved
   sessions complete (the agent_end hook auto-extracts).
2. **Seed handcrafted** — `tests/seed_three.py` adds 3 generic atoms
   (typo fix, missing test, dep bump).
3. **Backfill historical** — call `atom_extractor.py <session_id>
   --approved --premium-reqs N --lessons "..."` for past successful
   sessions you know about.

After ~10 atoms, retrieval becomes consistently useful.

## Storage

| | |
|---|---|
| lancedb path | `~/.openclaw/lancedb/atoms.lance/` |
| Disk per atom | ~6 KB (1536 floats + metadata) |
| Disk per year | ~11 MB at 5 atoms/day |
| Search latency | <30 ms on 2K rows |
| Embedding cost | $0.000003 per atom (text-embedding-3-small) |

## Configuration

```jsonc
{
  plugins: {
    entries: {
      "sga-mcts-atoms": {
        enabled: true,
        hooks: { allowConversationAccess: true },
        config: {
          extractorPython: "/home/msbel/.openclaw/sga_mcts/.venv/bin/python",
          extractorScript: "/home/msbel/.openclaw/sga_mcts/atom_extractor.py",
          retrieverScript: "/home/msbel/.openclaw/sga_mcts/atom_retriever.py",
          autoExtractOnAgentEnd: true
        }
      }
    }
  }
}
```

## Compatibility

- OpenClaw `>= 2026.3.24-beta.2`
- Node `>= 20`
- Python `>= 3.10`
- lancedb `>= 0.30`
- openai `>= 1.50`

## Source

- Paper: [arXiv 2604.14712](https://arxiv.org/abs/2604.14712)
- Reference impl: this repo
- Original Alcyone deployment: [github.com/msbel5/alcyone-experiments/tree/agent/sga-mcts-v1](https://github.com/msbel5/alcyone-experiments/tree/agent/sga-mcts-v1)

## License

MIT — see [LICENSE](LICENSE).

## Author

Mami ([@msbel5](https://github.com/msbel5)) with help from Claude.
Personal AI infrastructure project: Alcyone.

tools