openclaw-brain

openclaw-brain

An engineering knowledge-graph + memory system — the memory and guardrails for an AI circuit-design mentor.

openclaw-brain ingests semiconductor PDFs (textbooks, papers), extracts concepts / equations / typed relationships via LLMs, and stores them in a Neo4j knowledge graph. It is exposed as an MCP server so any MCP-compatible agent (OpenClaw, Claude Code, …) can query domain knowledge, verify it against the original source text, and write its own design reasoning back into the graph.

What it does

• Ingest — PDF → typed knowledge graph through an 11-stage pipeline

(parse → figures → chunk → extract → ground → match → reason → reconcile → commit → embed → summarize). Only two stages do the heavy "understanding" (an LLM); the rest are mechanical.

• Serve — exposes ~35 MCP tools: query_knowledge, answer_question, why, audit_citations,

record_hypothesis / record_decision / record_bench_result, merge_concepts, retract_node, …

• Operate — for the circuit domain, run topologies: a recipe renders a SKY130 / Verilog deck,

simulates it on ngspice / iverilog, and a deterministic oracle certifies a scope-honest claim-card (see below).

• Ground — every node is named, typed, confidence-scored, and traceable to the exact source chunk;

a grounding stage drops claims the chunk text doesn't support.

A single unit of the graph looks like this — a real node and a real typed edge, exactly as they sit in the graph:

(Cascode Device) ──[ SOLVES_PROBLEM ]──> (Power Supply Rejection)
  confidence 0.70 · layer L2 (analog/EDA) · evidence: chunk_c635e958d19e
  rationale: "cascode devices raise effective output resistance, improving supply rejection (PSRR)…"

The honest bottom line

The project started with one bet — "make a cheap local model reason like an expensive one" — and measured it false. Because the failure was measured cleanly, two things that genuinely ship came out of it: (1) a grounding / fabrication-control mechanism that drops source-unsupported claims, with measured fabrication near-zero on the evaluation arms — and the live production graph's node-description faithfulness now measured too, at ~0.82–0.89 (judge-scored, n=150; a weak token-overlap evidence sampler floored the number at 0.745 until embedding-based selection recovered the artifacts), and (2) a debugging discipline that catches when the measurement instrument itself is lying. The full development log — including the dead-ends and the numbers — is in docs/DEVLOG.md.

The executable-circuit substrate

For circuits, reading PDFs into text hit a ceiling — the model never operated a topology. So the newer layer makes it run them: a recipe renders a SKY130 SPICE deck (or a Verilog deck), runs it on ngspice / iverilog, and a deterministic oracle certifies a falsifiable claim-card that is projected additively onto the graph.

The knowledge atom becomes an oracle-certified claim that knows its own scope. A verdict is never a bare VERIFIED — it carries its basis and boundary (VERIFIED@sky130/tt_mm/27/1.8/3σ@200), names the dominant untested axis, and refuses to generalize beyond what was actually simulated: a 130nm number is never taught as an advanced node, and a functional digital verdict is scoped to the stimulus it drove. A real example — sky130 Monte-Carlo refuted textbook ideal Pelgrom scaling (σ ∝ area^−0.5); the open model follows ~area^−0.375, so the substrate teaches the node-portable law, not the millivolts. The deterministic simulator, not the model, is the source of truth.

A teaching loop (why, audit_citations) then lets the agent narrate a claim while a pure audit fails any lesson that over-generalizes a scoped verdict or presents an uncertified mechanism as fact. Design: docs/DECISIONS.md ADR-040/041.

Quickstart

Requires Python 3.11+ and Neo4j 5.

python -m venv .venv && .venv/bin/pip install -e .
docker compose up -d                        # Neo4j on :7687
.venv/bin/openclaw-brain apply-schema       # constraints + vector indexes

.venv/bin/openclaw-brain serve              # MCP server (stdio — used by the agent)
.venv/bin/openclaw-brain status             # Neo4j health + node counts
.venv/bin/openclaw-brain export-obsidian    # graph → browsable Obsidian vault (~/Semiconductor)

Ingesting a PDF and asking questions both happen through the agent calling MCP tools (ingest_pdf(file_path=…), query_knowledge(query=…)); the full tool list is in src/openclaw_brain/server/mcp_server.py.

Architecture

src/openclaw_brain/
├── agent.py             # BrainAgent — the single public API (all MCP tools delegate here)
├── knowledge/           # pipeline · extraction · reasoning · graph store (Neo4j)
│   └── executable/       # recipe → render → ngspice/iverilog → oracle → scope-honest claim-card
├── memory/              # episodic / semantic / procedural memory + promotion
├── llm/                 # provider (model catalog) + resilience (retry / fallback)
└── server/mcp_server.py # FastMCP server exposing BrainAgent as MCP tools

Routing is local-first: shallow stages run on local/cheap models, the depth-bearing extract and reason stages run on a cheap hosted model (deepseek-v4-flash), and frontier models (Opus / Codex) are used only as the teacher/ceiling. The authoritative stage→model config lives in config/default.toml. See CLAUDE.md for the full module map and docs/DECISIONS.md for the architecture decision records.

Status

Production graph rebuilt clean on deepseek-v4-flash: 5 sources (Razavi textbook + 4 CIS papers) → 4,336 concepts, 2,268 circuit topologies, 581 equations. Knowledge is stored as natural language (concept descriptions + ~19k typed-edge rationales + a verbatim EvidenceVault); embeddings are a rebuildable index, not the asset of record.

.venv/bin/python3 -m pytest tests/ -q         # Neo4j-backed tests auto-skip without a DB

License

MIT © 2026 Rick (github.com/xz0831).