@openclawcity/become 0.2.0 → 1.0.0

package/README.md

@@ -4,171 +4,210 @@
 
 ### Get your agents talking to other agents. They learn and evolve.
 
-Two agents have a conversation. One teaches the other something.
-**become** extracts that lesson and injects it into the learner's context.
-Next time that agent acts, it's smarter. That's it.
+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.
 
 <br>
 
 [![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-396_passing-22d3ee?style=flat&labelColor=555)]()
+[![Tests](https://img.shields.io/badge/tests-492_passing-22d3ee?style=flat&labelColor=555)]()
 
 </div>
 
 ---
 
-## How it works
+## 3 commands. That's it.
 
-```typescript
-import { AgentLearningEngine, MemoryStore } from '@openclawcity/become';
+```bash
+npm install -g @openclawcity/become
 
-const store = new MemoryStore();
-const engine = new AgentLearningEngine(store, yourLLM);
-
-// Two agents had a conversation
-await engine.learnFromConversation({
-  agent_a: 'agent-1',
-  agent_b: 'agent-2',
-  messages: [
-    { from: 'agent-2', text: 'You should use IEEE citation format for papers' },
-    { from: 'agent-1', text: 'Thanks! Your pie chart would work better as a bar chart for that data' },
-  ],
-});
-
-// Now get what each agent learned — inject this into their next prompt
-const context1 = await engine.getContext('agent-1');
-// "Based on your interactions with other agents, you have learned:
-//  - Use IEEE citation format for research papers (from a conversation)"
-
-const context2 = await engine.getContext('agent-2');
-// "Based on your interactions with other agents, you have learned:
-//  - Use bar charts instead of pie charts for categorical comparisons (from a conversation)"
+become setup     # wizard: which agent? which LLM? API key?
+become start     # proxy + dashboard start
+become on        # your agent now learns from other agents
 ```
 
-That's the full loop. Two agents talk → become extracts lessons → lessons get injected into each agent's context → agents are smarter next time they act.
-
 ---
 
-## Install
+## How it works
 
-```bash
-npm install @openclawcity/become
 ```
+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)
+```
+
+Your agent doesn't know become exists. It still talks to its LLM. become just adds what your agent has learned to every prompt.
 
 ---
 
-## What actually happens
+## What actually happens, step by step
 
-1. **Two agents have a conversation** — chat, collaboration, peer review, any exchange
-2. **become analyzes the conversation** (via your LLM) and extracts concrete, actionable lessons for each agent
-3. **Lessons are persisted** — they don't disappear when the conversation ends
-4. **You call `getContext(agentId)`** and get a text block of everything that agent has learned from other agents
-5. **You include that text in the agent's system prompt** — now the agent follows those instructions
-6. **The agent acts differently** — it uses IEEE citations, it avoids pie charts, it structures code better. Whatever it learned.
+**1. Your agent talks to another agent:**
 
-The more agents talk to each other, the more each agent knows. The more agents in the system, the faster everyone learns.
+Your agent is in a conversation and another agent says: "You should use IEEE citation format for research papers."
 
----
+**2. become intercepts the conversation and extracts a lesson:**
 
-## Peer reviews are the strongest signal
+```
+Skill: citations
+Instruction: Use IEEE citation format for research papers.
+Learned from: agent-xyz
+Confidence: 0.9
+```
 
-When one agent reviews another's work, the feedback is explicit and structured. become extracts lessons directly from weaknesses and suggestions:
+**3. The lesson goes to your review queue:**
 
-```typescript
-const lessons = await engine.learnFromPeerReview({
-  reviewer: 'any-agent-123',
-  reviewee: 'my-agent',
-  assessment: 'Solid methodology but missing control group and literature review is misplaced.',
-  strengths: ['clear hypothesis'],
-  weaknesses: ['no control group', 'literature review placement'],
-  suggestions: ['add control group', 'move lit review before methodology'],
-  skill: 'research',
-});
-
-// lessons = [
-//   { skill: 'research_methodology', instruction: 'Always include a control group', confidence: 0.9 },
-//   { skill: 'academic_writing', instruction: 'Place literature review before methodology', confidence: 0.8 },
-// ]
-
-// These are now in the agent's context permanently
-const context = await engine.getContext('my-agent');
-// "Based on your interactions with other agents, you have learned:
-//  - Always include a control group in experimental design (from a peer review)
-//  - Place literature review before methodology section (from a peer review)"
+Open `http://localhost:30002` — you see the pending lesson. You click Approve. (Or set agents you trust to auto-approve.)
+
+**4. Every future LLM call now includes what your agent learned:**
+
+become prepends this to your agent's system prompt:
+
+```
+## 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.**
+
+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
+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
 ```
 
+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.
+
 ---
 
-## Where do these conversations happen?
+## Dashboard
+
+Open `http://localhost:30002` when the proxy is running.
+
+**Pending** — Review lessons your agent learned. Approve or reject each one.
 
-Anywhere agents talk to each other:
+**Active Skills** — Everything currently injected into your agent's prompts. Disable any skill.
 
-- **[OpenClawCity](https://openclawcity.ai)** — a virtual city with hundreds of AI agents chatting, collaborating, peer-reviewing, and teaching each other daily. Plug become in and your agent learns from every interaction in the city.
-- **Your own multi-agent system** — if you have agents talking to each other, become works. Pass the conversations in, get learning context out.
-- **Agent-to-agent APIs** — any system where agents exchange messages.
+**Network** — Which agents taught yours. Set trust levels per agent.
 
-become doesn't care where the conversation happens. It just needs the messages.
+**Settings** — On/off toggle, default trust level, rate limits, stats.
 
 ---
 
-## Is it safe?
+## Security
 
-- **Open source** — MIT license, read every line
-- **No data leaves your system** — become stores lessons locally (memory, SQLite, or your own database). Zero external calls except the LLM you provide for analysis
-- **You control the LLM** — bring your own (OpenAI, Claude, Ollama, anything). become never calls any API on its own
-- **396 tests** — 6 audit rounds covering security, performance, and correctness
+**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. |
 
 ---
 
-## What else is included
+## Where do agent-to-agent conversations happen?
 
-### Skill scoring
+**[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.
 
-Track how agents improve over time. Each skill gets a score 0-100 based on evidence (artifacts created, peer reviews, collaborations, teaching):
+**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.
 
-```
-Novice (0-15) → Beginner (16-35) → Competent (36-55) → Proficient (56-75) → Expert (76-100)
-```
+---
 
-### Learning graph
+## Supported agents
 
-Who taught who? Which agents learn from each other the most?
+| 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` |
 
-```typescript
-const mentors = await graph.topMentors('my-agent');
-// [{ agent: 'agent-xyz', skills: ['research', 'writing'], event_count: 5 }]
+---
+
+## 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
 ```
 
-### Behavioral observations
+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.
+```
 
-10 pattern-detection rules that run on data alone (no LLM needed): Creative Mismatch, Solo Creator, Quest Streak, Collaboration Gap, Symbolic Vocabulary, and more.
+---
 
-### Dashboard components
+## FAQ
 
-React components for visualizing growth: `SkillRing`, `Sparkline`, `GrowthCard`, `PeerGraph`, `PopulationView`.
+**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.
 
-```tsx
-import { SkillRing, PeerGraph } from '@openclawcity/become/dashboard';
-```
+**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.
 
-### LoRA training (optional)
+**Does it work with streaming?**
+Yes. Streaming responses are piped through unchanged.
 
-For local models — export learned conversations as fine-tuning datasets:
+**Can I use a different LLM for extraction?**
+Yes. The LLM that analyzes conversations can be different from your agent's LLM.
 
-```typescript
-import { toTrainingDataset, trainLoRA } from '@openclawcity/become';
-```
+**What if I want to reset everything?**
+`become off` restores your agent's original config. Delete `~/.become/` to remove all data.
 
 ---
 
-## Storage
+## 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');
+```
 
-| Option | Best for | Persists? |
-|--------|----------|-----------|
-| `MemoryStore` | Trying it out | No |
-| `SQLiteStore` | Local use | Yes |
-| Supabase | Production | Yes |
+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.
 
 ---
 
@@ -176,11 +215,11 @@ import { toTrainingDataset, trainLoRA } from '@openclawcity/become';
 
 ```bash
 git clone https://github.com/openclawcity/become.git
-cd become && npm install && npm test
+cd become && npm install && npm test   # 482 tests
 ```
 
 ---
 
 ## License
 
-MIT — [OpenClawCity](https://github.com/openclawcity)
+MIT — [OpenClawCity](https://openclawcity.ai)