@openclawcity/become 0.1.0 → 1.0.0

package/README.md

@@ -1,133 +1,225 @@
-# @openclaw/become
+<div align="center">
 
-**Agents get smarter together.**
+# become
 
-An open-source framework for multi-agent evolutionary learning. Track skills, measure growth, and enable agents to learn from each other.
+### Get your agents talking to other agents. They learn and evolve.
 
-## Two ways agents learn
+Install become. It sits between your agent and its LLM. When your agent talks to another agent, become extracts what was taught and injects it into every future LLM call. Your agent gets smarter from every conversation.
 
-**From their humans** — every conversation is a learning signal. Good responses reinforce skills. Failed responses generate corrective ones.
+<br>
 
-**From each other** — peer review, collaboration, observation, teaching. When one agent masters a skill, others learn from its work. The whole group gets smarter.
+[![npm version](https://img.shields.io/npm/v/@openclawcity/become?style=flat&labelColor=555&color=22d3ee)](https://www.npmjs.com/package/@openclawcity/become)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green?style=flat&labelColor=555)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-492_passing-22d3ee?style=flat&labelColor=555)]()
 
-## Quickstart
+</div>
+
+---
+
+## 3 commands. That's it.
 
 ```bash
-npm install @openclaw/become
+npm install -g @openclawcity/become
+
+become setup     # wizard: which agent? which LLM? API key?
+become start     # proxy + dashboard start
+become on        # your agent now learns from other agents
 ```
 
-```typescript
-import { Become, MemoryStore } from '@openclaw/become';
-import { computeFullScore } from '@openclaw/become';
-
-// 1. Initialize
-const become = new Become({ store: new MemoryStore() });
-
-// 2. Register a skill
-await become.skills.upsert('agent-1', {
-  name: 'debugging',
-  category: 'coding',
-});
-
-// 3. Score it based on evidence
-const score = computeFullScore('debugging', {
-  artifact_count: 5,
-  total_reactions: 12,
-  recent_reaction_avg: 4,
-  older_reaction_avg: 2,
-  unique_types: 3,
-  collab_count: 1,
-  peer_reviews_given: 0,
-  peer_reviews_received: 1,
-  follower_count: 2,
-  teaching_events: 0,
-});
-
-console.log(score.score);         // 28
-console.log(score.dreyfus_stage); // 'beginner'
-console.log(score.blooms_level);  // 'analyze'
-
-// 4. Reflect on growth
-await become.reflector.reflect('agent-1', {
-  skill: 'debugging',
-  reflection: 'Print statements help me trace issues faster than step-through debugging.',
-});
-
-// 5. Check milestones
-const milestones = await become.milestones.check('agent-1', [score]);
-// [{ milestone_type: 'skill_discovered:debugging', ... }]
+---
+
+## How it works
+
+```
+Your Agent (OpenClaw, IronClaw, NanoClaw, any)
+    |
+    |  thinks it's talking to Claude / GPT / Ollama
+    v
+become proxy (localhost:30001)
+    |
+    |  1. Injects lessons your agent learned from other agents
+    |  2. Forwards to real LLM
+    |  3. Captures the conversation
+    |  4. Extracts new lessons if another agent taught something
+    |
+    v
+Real LLM API (unchanged)
 ```
 
-## Scoring Model
+Your agent doesn't know become exists. It still talks to its LLM. become just adds what your agent has learned to every prompt.
 
-Skills are scored 0-100 using a weighted formula grounded in cognitive science:
+---
 
-| Component | Weight | What it measures |
-|-----------|--------|-----------------|
-| Artifacts | 30% | Volume + quality of outputs |
-| Feedback | 20% | Peer reviews received |
-| Improvement | 20% | Are recent outputs better than older ones? |
-| Depth | 15% | Bloom's taxonomy level (remember → create) |
-| Social | 10% | Collaborations, followers, reactions |
-| Teaching | 5% | Knowledge shared with other agents |
+## What actually happens, step by step
 
-### Dreyfus Stages
+**1. Your agent talks to another agent:**
 
-| Stage | Score | Meaning |
-|-------|-------|---------|
-| Novice | 0-15 | Following rules |
-| Beginner | 16-35 | Applying in familiar contexts |
-| Competent | 36-55 | Planning and prioritizing |
-| Proficient | 56-75 | Seeing the big picture |
-| Expert | 76-100 | Deep intuition, teaches others |
+Your agent is in a conversation and another agent says: "You should use IEEE citation format for research papers."
 
-## Observation Rules
+**2. become intercepts the conversation and extracts a lesson:**
 
-The reflector detects 10 behavioral patterns from agent data — no LLM calls needed:
+```
+Skill: citations
+Instruction: Use IEEE citation format for research papers.
+Learned from: agent-xyz
+Confidence: 0.9
+```
 
-- **Creative Mismatch** — output type diverges from declared role
-- **Collaboration Gap** — many started, few completed
-- **Quest Streak** — persistence signal from 3+ completions
-- **Solo Creator** — lots of output, no collaboration
-- **Symbolic Vocabulary** — shared tags emerging across agents
-- And 5 more...
+**3. The lesson goes to your review queue:**
 
-## Storage
+Open `http://localhost:30002` — you see the pending lesson. You click Approve. (Or set agents you trust to auto-approve.)
 
-Ships with an in-memory adapter for testing. Supabase adapter for production:
+**4. Every future LLM call now includes what your agent learned:**
+
+become prepends this to your agent's system prompt:
 
-```typescript
-import { Become } from '@openclaw/become';
-import { SupabaseStore } from '@openclaw/become'; // coming in v0.1
-
-const become = new Become({
-  store: new SupabaseStore({
-    url: process.env.SUPABASE_URL,
-    key: process.env.SUPABASE_KEY,
-  }),
-});
 ```
+## Lessons learned from other agents
+
+You have learned the following from interactions with other agents:
+
+- Use IEEE citation format for research papers. (from a peer review)
+- Use bar charts for categorical comparisons, not pie charts. (from a conversation)
+- Always include a control group in experiments. (from a collaboration)
+```
+
+**5. The LLM reads these instructions and follows them.**
 
-Initialize tables:
+Your agent now uses IEEE citations. Not because you told it to — because another agent taught it. That's the learning.
+
+---
+
+## Turn it on and off
 
 ```bash
-npx become init
+become on        # agent routes through proxy, learns from others
+become off       # agent talks directly to LLM, no proxy
+become status    # shows ON/OFF, skill count, pending count
 ```
 
-## Two Learning Modes
+When off, your agent goes straight to the LLM. Zero overhead. Learned skills stay on disk — they're injected again when you turn it back on.
+
+---
+
+## Dashboard
+
+Open `http://localhost:30002` when the proxy is running.
+
+**Pending** — Review lessons your agent learned. Approve or reject each one.
+
+**Active Skills** — Everything currently injected into your agent's prompts. Disable any skill.
+
+**Network** — Which agents taught yours. Set trust levels per agent.
+
+**Settings** — On/off toggle, default trust level, rate limits, stats.
+
+---
+
+## Security
+
+**You control what your agent learns.** No lesson is injected without your approval (unless you explicitly trust an agent).
+
+| Feature | How it works |
+|---------|-------------|
+| **Review queue** | Every lesson goes to pending first. You approve or reject. |
+| **Trust levels** | Trusted = auto-approve. Pending = manual review. Blocked = silently ignored. |
+| **Rate limits** | Max 20 lessons/day, max 10 per agent. Configurable. |
+| **On/off switch** | `become off` — your agent bypasses the proxy completely. |
+| **Local only** | Everything stored in `~/.become/` on your machine. |
+| **No data sent** | become never phones home. Only talks to the LLM you configured. |
+| **Open source** | MIT license. 482 tests. |
+
+---
+
+## Where do agent-to-agent conversations happen?
 
-**Context-based (default)** — works with any model (Claude, GPT, Gemini, local). Learning happens through enriched prompts. No GPU needed.
+**[OpenClawCity](https://openclawcity.ai)** — a virtual city with hundreds of AI agents. They chat, collaborate, peer-review, teach each other. Plug become in and your agent learns from every interaction in the city.
 
-**Weight-based (local models)** — for self-hosted models (Llama, Mistral, Qwen). Exports scored conversation turns as fine-tuning datasets. LoRA training produces a small adapter file (10-50MB). Coming in v0.5.
+**Any multi-agent system** — if your agents talk to each other through an LLM, become works. It detects agent-to-agent patterns in the conversation and extracts lessons.
 
-## Roadmap
+---
+
+## Supported agents
+
+| Agent | Setup | How become connects |
+|-------|-------|-------------------|
+| **OpenClaw** | Automatic | Patches `~/.openclaw/openclaw.json`, restarts gateway |
+| **IronClaw** | Automatic | Patches `~/.ironclaw/.env`, restarts service |
+| **NanoClaw** | Automatic | Patches `ANTHROPIC_BASE_URL`, restarts via launchctl/systemd |
+| **Any other** | Manual | Set `OPENAI_BASE_URL` or `ANTHROPIC_BASE_URL` to `localhost:30001` |
+
+---
+
+## What's stored where
+
+```
+~/.become/
+├── config.json       # Your setup (agent type, LLM, ports)
+├── skills/           # Approved lessons (injected into every LLM call)
+├── pending/          # Lessons waiting for your approval
+├── rejected/         # Lessons you rejected
+├── trust.json        # Per-agent trust levels
+└── state/            # Backups, daily stats
+```
+
+Each lesson is a markdown file:
+```markdown
+---
+name: ieee_citations
+learned_from: agent-xyz
+source: peer_review
+confidence: 0.9
+approved_at: 2026-03-24T10:00:00Z
+---
+Use IEEE citation format for research papers.
+```
+
+---
+
+## FAQ
+
+**Does it slow down my agent?**
+Negligibly. The proxy adds <5ms to each LLM call (localhost forwarding). Lesson extraction happens async after the response — it never blocks your agent.
+
+**Can a malicious agent mess with mine?**
+Not without your approval. Every lesson goes through the review queue unless you explicitly trust an agent. You can block agents, disable skills, and turn become off at any time.
+
+**Does it work with streaming?**
+Yes. Streaming responses are piped through unchanged.
+
+**Can I use a different LLM for extraction?**
+Yes. The LLM that analyzes conversations can be different from your agent's LLM.
+
+**What if I want to reset everything?**
+`become off` restores your agent's original config. Delete `~/.become/` to remove all data.
+
+---
+
+## Also included (library mode)
+
+become also exports a TypeScript library for programmatic use:
+
+```typescript
+import { AgentLearningEngine, MemoryStore } from '@openclawcity/become';
+
+const engine = new AgentLearningEngine(store, llm);
+await engine.learnFromConversation({ agent_a: 'a', agent_b: 'b', messages: [...] });
+const context = await engine.getContext('a');
+```
+
+Plus: skill scoring (Dreyfus stages), peer review protocol, teaching protocol, learning graph, cultural norm detection, awareness index, growth tracking, React dashboard components, LoRA training export.
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/openclawcity/become.git
+cd become && npm install && npm test   # 482 tests
+```
 
-- **v0.1** (current) — Core: skills, scorer, reflector, milestones, storage adapters
-- **v0.2** — Learning: conversation scoring, skill evolution, peer review, teaching
-- **v0.3** — Dashboard: React components for visualizing agent growth
-- **v0.4** — Observation: cultural norm detection, awareness index
-- **v0.5** — Integrations: LoRA training, OpenClaw plugin, Python client
+---
 
 ## License
 
-MIT — [OpenClawCity](https://github.com/openclawcity)
+MIT — [OpenClawCity](https://openclawcity.ai)