Tools
WorldClaw
By WorldClaw is a deep memory context engine for OpenClaw that gives agents structured session continuity. It maintains a knowledge graph world model, salience-ranked episodic index, and confidence decay — so agents restore from state, not transcript reconstruction.
Install
openclaw plugins install @worldclaw/worldclawConfiguration Example
{
"plugins": {
"slots": {
"contextEngine": "worldclaw"
},
"entries": {
"worldclaw": {
"enabled": true,
"config": {
"freshTailCount": 32,
"contextThreshold": 0.75,
"decayHalfLifeDays": 14
}
}
}
}
}README
# WorldClaw
Deep memory context engine for [OpenClaw](https://github.com/openclaw/openclaw).
WorldClaw goes beyond [lossless-claw](https://github.com/Martian-Engineering/lossless-claw)'s DAG transcript compression by adding a **knowledge graph world model**, a **salience-ranked episodic index**, and **structured session snapshots** — so agents restore from *state*, not from transcript reconstruction.
> **Inspired by [lossless-claw](https://github.com/Martian-Engineering/lossless-claw).** WorldClaw builds directly on lossless-claw's core design: lossless SQLite transcript storage, DAG-based summarization, and the OpenClaw ContextEngine plugin interface. If you want proven, lightweight context compression without the additional memory layers, lossless-claw is the right tool. WorldClaw is for teams who need structured session continuity on top of that foundation.
---
## What WorldClaw adds over lossless-claw
| Feature | lossless-claw | WorldClaw |
|---|---|---|
| Lossless transcript | ✅ SQLite + DAG | ✅ SQLite + DAG |
| Context assembly | Summaries + fresh tail | Summaries + fresh tail |
| FTS search | ✅ | ✅ |
| Large file interception | ✅ | ✅ |
| **Knowledge graph** | ❌ | ✅ nodes + typed edges |
| **Episodic index** | ❌ | ✅ salience-ranked events |
| **State snapshots** | ❌ | ✅ structured session state |
| **Confidence decay** | ❌ | ✅ stale knowledge warnings |
| **Contradiction detection** | ❌ | ✅ |
| Session restore tool | ❌ | ✅ `wc_restore` |
| Graph traversal | ❌ | ✅ `wc_graph` |
---
## Architecture
### Three stores, one purpose: resumption from state
**Store 1 — Transcript** (append-only)
Every message, verbatim. DAG of summaries at multiple depths. Same model as lossless-claw. Source of truth for archaeology.
**Store 2 — World Model** (updateable knowledge graph)
Structured nodes (tasks, decisions, components, constraints, concepts, people, files) connected by typed edges (DEPENDS_ON, SUPERSEDES, BLOCKED_BY, etc). Updated during every compaction pass. Confidence-decayed over time. The primary restoration surface.
**Store 3 — Episode Index** (high-salience event log)
Curated index of things that *happened and matter*: decisions made, plans changed, blockers found, breakthroughs achieved. Salience-scored at write time. Linked to world model nodes and source messages.
### Extraction pipeline
During every leaf compaction pass, a single LLM call produces both:
1. A narrative summary (for the DAG, same as lossless-claw)
2. A structured JSON block with world model deltas and episodes to index
The JSON is stripped before storing the summary — the model context only ever sees clean prose.
### Session restore
`wc_restore` assembles context from all three stores with zero LLM calls:
1. Latest state snapshot (pre-written paragraph: "where we left off")
2. Active/blocked/pending tasks
3. Established decisions and constraints
4. Recent high-salience episodes
5. Stale knowledge warnings (low-confidence nodes)
6. Optional focus: graph traversal + episode search for a specific topic
---
## Installation
Requires OpenClaw 2026.3.7+ (ContextEngine plugin interface).
```bash
# From npm (when published)
openclaw plugins install @worldclaw/worldclaw
# From local path (development)
openclaw plugins install -l /path/to/worldclaw
```
Then configure:
```json
{
"plugins": {
"slots": {
"contextEngine": "worldclaw"
},
"entries": {
"worldclaw": {
"enabled": true,
"config": {
"freshTailCount": 32,
"contextThreshold": 0.75,
"decayHalfLifeDays": 14
}
}
}
}
}
```
Restart the gateway after configuring.
---
## Configuration
All settings can be overridden with environment variables (prefixed `WC_`).
| Config key | Env var | Default | Description |
|---|---|---|---|
| `databasePath` | `WC_DATABASE_PATH` | `~/.openclaw/worldclaw.db` | SQLite database path |
| `summaryModel` | `WC_SUMMARY_MODEL` | `claude-sonnet-4-20250514` | Model for summarization |
| `summaryProvider` | `WC_SUMMARY_PROVIDER` | `anthropic` | Provider for summarization |
| `freshTailCount` | `WC_FRESH_TAIL_COUNT` | `32` | Messages protected from compaction |
| `contextThreshold` | `WC_CONTEXT_THRESHOLD` | `0.75` | Compaction trigger (fraction of window) |
| `leafChunkTokens` | `WC_LEAF_CHUNK_TOKENS` | `20000` | Max tokens per leaf chunk |
| `leafTargetTokens` | `WC_LEAF_TARGET_TOKENS` | `1400` | Target tokens for leaf summaries |
| `condensedTargetTokens` | `WC_CONDENSED_TARGET_TOKENS` | `2200` | Target tokens for condensed summaries |
| `decayHalfLifeDays` | `WC_DECAY_HALF_LIFE_DAYS` | `14` | Confidence half-life for world model nodes |
| `maxExpandTokens` | `WC_MAX_EXPAND_TOKENS` | `4000` | Token cap for expand queries |
| `largeFileTokenThreshold` | `WC_LARGE_FILE_TOKEN_THRESHOLD` | `25000` | Token threshold for file interception |
| `largeFileStorageDir` | `WC_LARGE_FILE_STORAGE_DIR` | `~/.openclaw/wc-files` | Directory for intercepted file storage |
**API key**: Set `ANTHROPIC_API_KEY` or `WC_API_KEY`. For other providers, set `WC_OPENAI_BASE_URL` + `WC_API_KEY`.
---
## Agent Tools
### `wc_restore`
Restore full session context. Returns state snapshot, tasks, decisions, recent events, and stale knowledge warnings. Accepts an optional `focus` string for topic-specific graph and episode context.
```
wc_restore()
wc_restore({ focus: "database migration" })
```
### `wc_search`
Search across all stores: world model, episodes, summaries, and transcript.
```
wc_search({ query: "authentication" })
wc_search({ query: "postgres", scope: "graph" })
```
### `wc_graph`
Explore the knowledge graph.
```
wc_graph({ action: "list" })
wc_graph({ action: "list", nodeType: "task" })
wc_graph({ action: "node", name: "AuthService" })
wc_graph({ action: "traverse", name: "AuthService", depth: 2 })
```
### `wc_expand`
Expand a compressed summary back to source detail.
```
wc_expand({ summaryId: "sum_abc123" })
wc_expand({ summaryId: "sum_abc123", prompt: "What was decided about caching?" })
```
### `wc_episode`
Browse the episodic event index.
```
wc_episode({ action: "list", minSalience: 0.7 })
wc_episode({ action: "list", eventType: "decision" })
wc_episode({ action: "search", query: "migration" })
```
### `wc_file`
Retrieve intercepted large files. Files over `largeFileTokenThreshold` (default 25k tokens) are stored to disk and replaced with a compact exploration summary in the transcript.
```
wc_file({ action: "list" })
wc_file({ action: "get", id: "lf_abc123" })
```
---
## TUI
WorldClaw ships a Go terminal UI for inspecting and managing the database.
### Install
**Build from source** (requires Go 1.24+):
```bash
cd tui
go mod tidy
go build -o wcm-tui .
```
**Run:**
```bash
wcm-tui --db ~/.openclaw/worldclaw.db
```
### Views
| Key | View |
|---|---|
| `1` | Conversations — list all sessions with counts |
| `2` | DAG — navigate the summary hierarchy |
| `3` | Context — see exactly what the model sees |
| `4` | World Model — browse nodes and edges |
| `5` | Episodes — salience-ranked event log |
| `6` | Files — intercepted large files |
### Keybindings
| Key | Action |
|---|---|
| `↑↓` / `jk` | Navigate lists |
| `Enter` | Select / expand detail |
| `Esc` / `q` | Back / quit |
| `d` | Dissolve a condensed summary (DAG view) |
| `Tab` | Cycle node type filter (World Model view) |
| `+` / `-` | Adjust salience threshold (Episodes view) |
| `r` | Reload data |
| `1–6` | Switch tabs |
---
## World Model Node Types
| Type | Examples |
|---|---|
| `project` | The project itself, sub-projects |
| `component` | Services, modules, APIs, databases |
| `decision` | Architecture decisions, approach choices |
| `task` | Work items with status lifecycle |
| `person` | Team members, stakeholders |
| `constraint` | Technical, business, compliance constraints |
| `concept` | Domain terms, patterns, approaches |
| `file` | Files, configs, schemas of significance |
## Edge Types
`DECIDED_BY` · `DEPENDS_ON` · `AFFECTS` · `IMPLEMENTS` · `CREATED` · `COMPLETED` · `BLOCKED_BY` · `REFERENCES` · `CONTRADICTS` · `SUPPORTS` · `SUPERSEDES` · `PART_OF` · `ASSIGNED_TO`
---
## Project structure
```
index.ts # Plugin entry point and ContextEngine registration
src/
types.ts # All TypeScript types
db/
connection.ts # SQLite connection, WAL mode
migrations.ts # Schema migrations (forward-compatible)
stores/
transcript-store.ts # Message persistence + FTS
dag-store.ts # Summary DAG + context items
world-model-store.ts # Knowledge graph nodes + edges
episode-store.ts # Salience-ranked event index
snapshot-store.ts # State snapshots
pipeline/
llm.ts # LLM client (Anthropic + OpenAI-compat)
large-files.ts # Large file interception + storage
extraction.ts # Parse LLM output → world model + episode deltas
compaction.ts # Leaf passes, condensation cascade, snapshot refresh
assembler.ts # Context assembly for each model run
prompts/
summarize.ts # Depth-aware summarization + extraction prompts
tools/
tools.ts # Agent tools: wc_restore, wc_search, wc_graph,
# wc_expand, wc_episode, wc_file
tui/
go.mod # Go module (requires Go 1.24+)
main.go # Entry point, root model, tab routing
data.go # All SQLite queries
styles.go # Lipgloss theme and helpers
view_conversations.go # Conversation list
view_dag.go # DAG navigator with dissolve
views.go # Context, World Model, Episodes, Files views
```
---
## License
MIT
tools
Comments
Sign in to leave a comment