# 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](#the-executable-circuit-substrate)).
- **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`](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`](docs/DECISIONS.md) ADR-040/041.

## Quickstart

Requires **Python 3.11+** and **Neo4j 5**.

```bash
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`](config/default.toml). See [`CLAUDE.md`](CLAUDE.md) for the full module map and
[`docs/DECISIONS.md`](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.

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

## License

[MIT](LICENSE) © 2026 Rick (github.com/xz0831).