|
1 | | -# ewa — Emergent Wisdom Agent |
| 1 | +# Emergent Wisdom Agent (EWA) |
2 | 2 |
|
3 | | -Integration layer for [understanding-graph](https://github.com/emergent-wisdom/understanding-graph) and [sema](https://github.com/emergent-wisdom/sema). |
| 3 | +Integration layer that connects [understanding-graph](https://github.com/emergent-wisdom/understanding-graph) (persistent memory) and [sema](https://github.com/emergent-wisdom/sema) (shared vocabulary) into a unified cognitive system for Claude Code. |
4 | 4 |
|
5 | | -Both ug and sema ship their own Claude Code plugins with skills that teach how to use each tool independently. Ewa is the layer that makes them work **together** — shared vocabulary inside the graph, plus an autonomous harness that runs multi-round loops. |
6 | | - |
7 | | -Two modes: |
8 | | - |
9 | | -- **Plugin mode** — install in Claude Code, get both MCP servers + the integration skill |
10 | | -- **Harness mode** — `npx emergent-wisdom-agent "task"` runs an autonomous multi-round loop using direct Anthropic SDK + MCP client (no CLI wrapper) |
11 | | - |
12 | | -## What each layer provides |
13 | | - |
14 | | -| Layer | What it ships | Install | |
15 | | -|-------|--------------|---------| |
16 | | -| **understanding-graph** | MCP server + 7 skills (orient, graph-workflow, quality-check, reading-mode, creative-work, serendipity, web-ui) | `claude plugin install understanding-graph` | |
17 | | -| **sema** | MCP server + 1 skill (sema-usage) | `claude plugin install sema` | |
18 | | -| **ewa** | Integration skill (sema-in-graph) + 12 agents + autonomous harness + bundled MCP config | `claude plugin install emergent-wisdom-agent` | |
19 | | - |
20 | | -You can use ug or sema standalone. Ewa adds the integration and the harness. |
21 | | - |
22 | | -## Install (plugin mode) |
| 5 | +## Install |
23 | 6 |
|
24 | 7 | ```bash |
25 | | -# One-time: add the Emergent Wisdom marketplace |
26 | | -claude plugin marketplace add emergent-wisdom/marketplace |
27 | | - |
28 | | -# Install all three |
29 | | -claude plugin install understanding-graph |
30 | | -claude plugin install sema |
31 | | -claude plugin install emergent-wisdom-agent |
| 8 | +claude plugin install /path/to/ewa |
32 | 9 | ``` |
33 | 10 |
|
34 | | -- **understanding-graph** provides the ug MCP server + 7 skills (orient, graph-workflow, etc.) |
35 | | -- **sema** provides the sema MCP server + sema-usage skill |
36 | | -- **emergent-wisdom-agent** provides the integration skill (`sema-in-graph`) + 12 agents |
| 11 | +Requires both MCP servers running: |
| 12 | +- **understanding-graph** -- `npx understanding-graph start` |
| 13 | +- **sema** -- `uvx semahash serve` |
37 | 14 |
|
38 | | -Ewa doesn't declare MCP servers — it relies on the ug and sema plugins for that. The `.mcp.json` in this repo is only used by the harness (which connects directly). |
| 15 | +## What each layer provides |
39 | 16 |
|
40 | | -For local development: |
| 17 | +| Layer | What it is | What it gives you | |
| 18 | +|-------|-----------|-------------------| |
| 19 | +| understanding-graph | MCP server + skills | Persistent memory, concept nodes, doc trees, belief revision, project management | |
| 20 | +| sema | MCP server + skill | Shared vocabulary -- 450+ content-addressed patterns with stable invariants | |
| 21 | +| **ewa** | Integration skills + agents | Orientation protocol, sema-in-graph bridge, 12 specialized agent roles | |
41 | 22 |
|
42 | | -```bash |
43 | | -claude --plugin-dir /path/to/understanding-graph \ |
44 | | - --plugin-dir /path/to/sema \ |
45 | | - --plugin-dir /path/to/ewa |
46 | | -``` |
| 23 | +## Skills |
47 | 24 |
|
48 | | -## Install (harness mode) |
| 25 | +### orient |
49 | 26 |
|
50 | | -```bash |
51 | | -npx emergent-wisdom-agent "design a bloom filter" |
52 | | -npx emergent-wisdom-agent --project myproject --rounds 50 --model claude-sonnet-4-20250514 "task" |
53 | | -``` |
| 27 | +Startup protocol for new sessions. Loads understanding-graph orientation, sema usage protocol, and the sema-in-graph bridge. Summarizes graph state and flags maintenance needs. |
54 | 28 |
|
55 | | -The harness connects directly to ug and sema MCP servers via `@modelcontextprotocol/sdk` and runs multi-turn tool loops via `@anthropic-ai/sdk`. No CLI wrapper — MCP sessions are kept alive across rounds for performance. |
| 29 | +### sema-in-graph |
56 | 30 |
|
57 | | -Each round: fresh stateless agent → reads graph → does work → harness checks completion → repeat. The graph is the only memory between rounds. |
| 31 | +How to embed sema handles inside graph nodes as stigmergic signals -- making vocabulary load-bearing rather than decorative. |
58 | 32 |
|
59 | | -## Agents |
| 33 | +## Agents (optional power feature) |
60 | 34 |
|
61 | | -12 specialized agents available for the harness: |
| 35 | +Agents are specialized roles that focus on different aspects of understanding. Use them via Claude Code's agent system when you want a particular cognitive lens. |
62 | 36 |
|
63 | | -| Agent | Role | |
64 | | -|-------|------| |
65 | | -| reader | Controls reading rhythm, stops at thought moments | |
66 | | -| synthesizer | Weaves concepts into coherent thought, applies wisdom protocol | |
67 | | -| connector | Long-range coherence, fights recency bias | |
68 | | -| skeptic | Stress-tests for incoherence and hidden assumptions | |
69 | | -| speculator | Generates hypotheses and branching futures | |
70 | | -| belief-tracker | Documents mind-changes, manages prediction resolution | |
71 | | -| axiologist | Maps optimization functions and value conflicts | |
72 | | -| psychologist | Tracks latent state, analyzes the unsaid | |
73 | | -| critic | Evaluates craft — prose quality, technique, pacing | |
74 | | -| translator | Weaves graph knowledge into fluid narrative | |
75 | | -| architect | Reverse-engineers structure and topology | |
76 | | -| methodologist | Validates evidence, methodology, and epistemic claims | |
| 37 | +| Agent | Role | Lens | |
| 38 | +|-------|------|------| |
| 39 | +| reader | Metabolizes source material | Captures shifts, not summaries | |
| 40 | +| synthesizer | Weaves higher-order understanding | Wisdom protocol, staleness checks | |
| 41 | +| connector | Long-range coherence | Fights recency bias, bridges distant nodes | |
| 42 | +| skeptic | Stress-tester | Hunts incoherence, hidden assumptions | |
| 43 | +| speculator | Engine of possibility | High recall, not precision | |
| 44 | +| belief-tracker | Epistemic historian | Tracks mind-changes, resolves predictions | |
| 45 | +| axiologist | Value mapper | Optimization functions, value conflicts | |
| 46 | +| psychologist | Latent state tracker | What is felt but not said | |
| 47 | +| critic | Craft judge | Prose quality, technique, impact | |
| 48 | +| translator | Voice of the swarm | Expands thought into narrative | |
| 49 | +| architect | Systems thinker | Structure, topology, fragility | |
| 50 | +| methodologist | Epistemic auditor | Evidence quality, scope limitations | |
77 | 51 |
|
78 | 52 | ## Structure |
79 | 53 |
|
80 | 54 | ``` |
81 | 55 | ewa/ |
82 | | -├── .claude-plugin/plugin.json # Plugin manifest |
83 | | -├── .mcp.json # Auto-configures ug + sema |
| 56 | +├── .claude-plugin/ |
| 57 | +│ └── plugin.json |
84 | 58 | ├── skills/ |
85 | | -│ └── sema-in-graph/ # Integration: sema patterns as stigmergic signals in the graph |
86 | | -├── agents/ # 12 agent definitions |
87 | | -├── harness/ # TypeScript autonomous loop |
88 | | -│ ├── cli.ts # npx emergent-wisdom-agent entry point |
89 | | -│ ├── mcp-context.ts # MCP session lifecycle (connect once, reuse) |
90 | | -│ ├── backend.ts # Anthropic SDK multi-turn tool loop |
91 | | -│ ├── loop.ts # Multi-round understanding loop |
92 | | -│ ├── state.ts # Graph state fetching via direct MCP calls |
93 | | -│ ├── sema-discovery.ts # Lightweight pattern discovery pass |
94 | | -│ ├── completion.ts # Task completion checker |
95 | | -│ └── index.ts # Exports |
| 59 | +│ ├── orient/ |
| 60 | +│ │ └── SKILL.md |
| 61 | +│ └── sema-in-graph/ |
| 62 | +│ └── SKILL.md |
| 63 | +├── agents/ |
| 64 | +│ ├── reader.md |
| 65 | +│ ├── synthesizer.md |
| 66 | +│ ├── connector.md |
| 67 | +│ ├── skeptic.md |
| 68 | +│ ├── speculator.md |
| 69 | +│ ├── belief-tracker.md |
| 70 | +│ ├── axiologist.md |
| 71 | +│ ├── psychologist.md |
| 72 | +│ ├── critic.md |
| 73 | +│ ├── translator.md |
| 74 | +│ ├── architect.md |
| 75 | +│ └── methodologist.md |
96 | 76 | ├── package.json |
97 | | -└── tsconfig.json |
| 77 | +├── README.md |
| 78 | +└── LICENSE |
98 | 79 | ``` |
99 | 80 |
|
100 | | -## Dependencies |
| 81 | +## License |
101 | 82 |
|
102 | | -- [@anthropic-ai/sdk](https://www.npmjs.com/package/@anthropic-ai/sdk) — direct Claude API calls |
103 | | -- [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk) — MCP client for kept-alive sessions |
104 | | -- [understanding-graph](https://www.npmjs.com/package/understanding-graph) (npm) — the graph MCP server |
105 | | -- [semahash](https://pypi.org/project/semahash/) (pip/uvx) — the vocabulary MCP server |
106 | | - |
107 | | -## Development |
108 | | - |
109 | | -```bash |
110 | | -npm install |
111 | | -npm run build # tsc |
112 | | -npm run dev # tsc --watch |
113 | | -``` |
| 83 | +MIT |
0 commit comments