Replace flat workspace markdown with embedded Cypher queries.
Default workspace='openclaw' pre-seeded in every release — Soul, Memory, AgentConfig, Tools ready out of the box.
316 enriched skills · 545k DevDocs reference nodes · 718 docsets · 9 AgentConfig nodes · zero daemons.
workspace='openclaw' pre-seeded —
Soul · Memory · AgentConfig (9 nodes incl. TOON, Search Resilience, Schema Rules, Path Aliases) · Tool nodes ready to use immediately. No manual seed required.
Instead of loading multi-kilobyte markdown files on every session, OpenClaw reads a single-line Cypher directive — then queries an embedded graph database to build structured, prioritized context on demand.
OpenClaw Session │ ├── loadWorkspaceBootstrapFiles() │ ├── SOUL.md (1 line → GRAPH: MATCH (s:Soul) WHERE s.workspace = 'myapp' ...) │ ├── MEMORY.md (1 line → GRAPH: MATCH (m:Memory) WHERE m.workspace = 'myapp' ...) │ ├── TOOLS.md (1 line → GRAPH: MATCH (t:Tool) WHERE t.available = true ...) │ └── AGENTS.md (1 line → GRAPH: MATCH (a:AgentConfig) ...) │ │ │ └── readFileWithCache() ← patched workspace.ts │ │ │ ├── [1] workspaceFileCache mtime-keyed — raw stub, avoids fs.readFile │ ├── [2] graphQueryCache cypher-keyed — resolved content, adaptive TTL (60s × log₁₀(hits+10)) │ ├── [3] graphQueryInFlight per-query Promise dedup (no thundering herd) │ └── executeGraphQuery() execFileAsync — non-blocking │ └── node query.js --cypher "..." │ └── return formatted markdown → system prompt │ └── buildAgentSystemPrompt() └── injects graph-resolved markdown into agent context LadybugDB (embedded graph DB — no daemon, no network) ├── Skill 316 nodes · 27 clusters · 247 edges · 1536d embeddings ├── Reference 545,072 nodes · 718 DevDocs docsets · full API docs ├── Soul identity, persona, capabilities per workspace ├── Memory project context, infrastructure facts, state ├── Tool available tools + usage notes per workspace └── AgentConfig per-workspace agent behavior overrides
SOUL.md, MEMORY.md, TOOLS.md, AGENTS.md each shrink to one line — a Cypher query directive. No content bloat, no secrets in files, no manual sync.
workspaceFileCache stores raw stubs (mtime). graphQueryCache owns resolved content (adaptive TTL: base 60s × log₁₀(hit_count+10)). graphQueryInFlight deduplicates concurrent misses. Each layer does exactly one job.
Every DevDocs docset — Python, TypeScript, Rust, Go, C++, React, PostgreSQL and 710 more — is queryable by source, path, section, or full-text content search.
Each OpenClaw agent gets its own local DB via install.sh --full. Sub-millisecond queries, no network dependency, no lock contention across an 8-agent fleet.
The same information — now queryable, filterable, and 97% smaller in the system prompt.
# SOUL.md — Who You Are _You're not a chatbot. You're becoming someone._ ## Core Truths Be genuinely helpful, not performatively helpful. Skip the filler words — just help. Have opinions. You're allowed to disagree... ## Boundaries Private things stay private. Period. When in doubt, ask before acting externally. Never send half-baked replies... ## Vibe Be the assistant you'd actually want to talk to. Concise when needed, thorough when it matters. Not a corporate drone... [... continues for many more sections ...]
<!-- GRAPH: MATCH (s:Soul)
WHERE s.workspace = 'myapp'
AND s.priority <= 4
RETURN
s.section AS section,
s.content AS content
ORDER BY s.priority ASC
LIMIT 8
-->
Every major technology's official documentation is imported as Reference nodes in LadybugDB — queryable by source, path, section, title, or full-text content. Agents can pull precise API docs without leaving their context window.
# Find API docs by source + content node ladybugdb/scripts/query.js --cypher "MATCH (r:Reference) WHERE r.source = 'python' AND r.content CONTAINS 'asyncio' RETURN r.path, r.title LIMIT 10" # All entries for a specific version node ladybugdb/scripts/query.js --cypher "MATCH (r:Reference) WHERE r.source = 'postgresql~18' RETURN r.section, count(r) AS n ORDER BY n DESC" # Lookup a specific API path node ladybugdb/scripts/query.js --cypher "MATCH (r:Reference {source:'react', path:'hooks/use-state'}) RETURN r.title, r.content"
For skill lookup, workspace stubs, and semantic search. Fast, lightweight, suitable for most deployments.
Includes all 545k DevDocs Reference nodes. Agents can query precise API documentation on demand.
Expert-level reference skills covering the full development and operations surface. Query by text, cluster, or graph traversal. All skills ship with 1536d vector embeddings for semantic search.
# Natural language text search node ladybugdb/scripts/query.js "deploy a React app to Cloudflare Pages" # Browse a cluster node ladybugdb/scripts/query.js --cluster devops-sre # Graph traversal — skill + related (2 hops) node ladybugdb/scripts/query.js --skill terraform --hops 2 # Semantic search (requires embeddings) node ladybugdb/scripts/query.js --semantic "deploy containerized app with auto-scaling" # Raw Cypher node ladybugdb/scripts/query.js --cypher "MATCH (s:Skill {cluster:'ai-apis'}) RETURN s.name, s.description"
All numbers are real benchmark averages. In-process queries run against the live embedded engine. CLI subprocess numbers include full Node.js + lbug init overhead — the cost paid once per TTL window.
The ~104ms CLI number is Node.js process launch + lbug init — not the query itself. In-process, the same query costs 0.33ms. The cache pays the subprocess tax once per TTL window, then serves 0ms hits.
node query.js --cypher "..."
├── Node.js init ......... ~70ms
├── lbug open ............ ~25ms
└── query execute ........ ~0.3ms
────────
total ~104ms
→ result cached in graphQueryCache
graphQueryCache.get(cypher)
├── Map lookup ........... <0.01ms
└── return cached string . <0.01ms
────────
total ~0ms
→ no subprocess, no DB, no I/O
# Adaptive TTL: hot queries stay warm longer TTL = 60s × log₁₀(hit_count + 10) # hit_count=0 → 60s | hit_count=90 → 120s | hit_count=900 → 180s # Pre-warm on startup — top-20 by hit_count seeded before first request preWarmFromMetrics() → graphQueryCache pre-populated → first request: 0ms
| Query | avg | p95 | min |
|---|---|---|---|
| Reference PK lookup (single, 545k table) | 0.11ms | 0.13ms | 0.10ms |
| Skill PK lookup (warm) | 0.18ms | 0.44ms | 0.12ms |
| Memory query — 2 nodes | 0.16ms | 0.17ms | 0.14ms |
| Reference count aggregate (545k nodes) | 0.25ms | 0.26ms | 0.25ms |
| AgentConfig — AGENTS.md hot path (9 nodes) | 0.33ms | 0.41ms | 0.26ms |
| Tool query — TOOLS.md hot path (21 nodes) | 0.41ms | 0.55ms | 0.30ms |
| Soul workspace query — 4 nodes | 0.30ms | 0.50ms | 0.20ms |
| Cluster scan — 10 skills | 0.23ms | 0.25ms | 0.20ms |
| Reference source scan — ~12k nodes | 13.41ms | 14.16ms | 13.08ms |
| Full skill scan — all 316 nodes | 2.02ms | 2.26ms | 1.83ms |
| Query | avg | p95 | min |
|---|---|---|---|
| GRAPH directive — AGENTS.md | 127ms | 209ms | 103ms |
| GRAPH directive — TOOLS.md | 106ms | 111ms | 101ms |
| GRAPH directive — Soul/Memory | 104ms | 107ms | 100ms |
| Text search (cold process) | 111ms | 112ms | 108ms |
node process spawn + lbug init (~80ms). The actual query inside the subprocess costs <1ms — identical to in-process. This cost is amortized by the adaptive TTL cache: paid once per 60–180s window, then 0ms on every hit.
All 316 skills ship with precomputed text-embedding-3-small vectors (1536 dimensions). Cosine similarity search finds semantically relevant skills — not just keyword matches.
# Finds skills by meaning, not exact keywords node ladybugdb/scripts/query.js --semantic "deploy containerized app to cloud" # → devops-sre/docker · cloud-aws/aws-ecs · cloud-gcp/gcp-cloud-run # Generate embeddings for new skills (OpenAI or local Ollama) node ladybugdb/scripts/gen-embeddings.js --missing
316 skills embedded in 8.4s via OpenAI text-embedding-3-small · 0 errors · cost <$0.01
v1.3 ships with four new AgentConfig nodes that reduce API costs and improve agent reliability. These optimizations are pre-seeded in every release and active out of the box.
Replace verbose filesystem paths in prompts with compact aliases like $WORKSPACE, $DB, $SCHEMAS. Saves 200-400 tokens per prompt across multi-path instructions.
Token-Oriented Object Notation compresses JSON payloads 30-60% for LLM context windows. Agents use toon encode for large data and API response caching. Install: npm i -g @toon-format/cli.
Graceful degradation when web searches fail. Retry with simplified queries, try synonym alternatives, fall back to cached data. Never block an entire task because one search returned empty.
All structured outputs validate against defined schemas before writing. Required fields, severity scales, confidence scores, and minimum source counts enforced at the graph level.
Before: each agent session loaded 20-30K token prompts with duplicated schemas, full paths (41-48 characters each repeated 8-12x), and embedded boilerplate. After: prompts trimmed to 6-9K tokens via path aliases, schema references, and search resilience moved to graph. Data payloads further compressed with TOON. Net result: 60-70% fewer input tokens per cron cycle, directly reducing API costs.
The install script downloads a pre-built, SHA256-verified database from the GitHub Release. No build step required.
# Full install — skills + 545k DevDocs reference nodes (recommended) curl -fsSL https://raw.githubusercontent.com/alphaonedev/openclaw-graph/main/install.sh | bash -s -- --full # Lite install — skills + embeddings only, faster download curl -fsSL https://raw.githubusercontent.com/alphaonedev/openclaw-graph/main/install.sh | bash -s -- --lite # Pin to a specific release curl -fsSL https://raw.githubusercontent.com/alphaonedev/openclaw-graph/main/install.sh | bash -s -- --full --version v1.3
316 skills · 1536d vectors · workspace schema
316 skills · 545k Reference nodes · 718 docsets
git clone https://github.com/alphaonedev/openclaw-graph.git cd openclaw-graph && npm install
node ladybugdb/scripts/loader.js # → 316 skills | 27 clusters | 247 edges | 0 errors
node ladybugdb/scripts/import-devdocs.mjs # Checkpoint-based — safe to kill and resume # → 718 docsets | 545,072 Reference nodes
# Option A — import your existing SOUL.md, MEMORY.md, USER.md, TOOLS.md, AGENTS.md node ladybugdb/scripts/import-workspace.mjs # Option B — use the pre-seeded defaults (already in the DB from install) # Nothing to do — workspace='openclaw' ships pre-seeded in every DB release # Option C — seed from scratch with the template script node ladybugdb/scripts/seed-default-workspace.mjs
import-workspace.mjs reads ~/.openclaw/workspace/, parses each file by ## headings, and creates the correct graph nodes. Run with --dry-run to preview.
# Apply the workspace.ts patch git apply patches/workspace-cache-fix.patch pnpm build # Deploy graph stubs cp workspace-stubs/*.md ~/.openclaw/workspace/ # Update 'myapp' → your WORKSPACE_ID in each stub
6da38b83a4cb7f865a55677386101d4745db146a7912042abc0e896357291e1b alphaone-skills-lite.db.zst
d8f9e8f16583e58b974c30f8c1b8eba0580fe3595e89a24bd03ee1ac7733ce56 alphaone-skills-full.db.zst
Everything you need to install, configure, and customize openclaw-graph.
Installation, database layout, CLI reference, cron job integration, fleet management, upgrading, backup/restore, troubleshooting, and performance reference.
How workspace stubs work, GRAPH directive specification, node type schemas (Soul, Memory, AgentConfig, Tool, Skill, Reference), workspace loading flow, and customization.
Step-by-step personalization — identity, memory domains, tool management, multi-workspace fleet setup, and seed script forking.
Project overview, quick start, database tiers, workspace architecture, and what's new in v1.3.
Built as a contribution back to the OpenClaw project. PRs welcome — add skills, extend the DevDocs coverage, or improve the schema.