KongBrain

A graph-backed cognitive engine for OpenClaw.

Quick Start | Architecture | How It Works | Tools | Development

OpenClaw ships with a lobster brain. It works. Lobsters have survived 350 million years, but they also solve problems by walking backwards and occasionally eating each other.

When a conversation gets too long, the lobster brain does what lobsters do best: it panics, truncates everything before message 47, and carries on like nothing happened. Your carefully explained architecture? Gone. That bug you described in detail twenty minutes ago? Never heard of it.

KongBrain is a brain transplant. You're replacing that crustacean context window with a primate cortex backed by a graph database, vector embeddings, and the kind of persistent memory that lets your AI remember what you said last Tuesday. And judge you for it.

Apes remember. Apes use tools. Apes hold grudges about your code style and learn from them. Lobsters eat garbage off the ocean floor and forget about it immediately.

The surgery takes about 2 minutes. No anesthesia required.

Persistent memory graph. Vector-embedded, self-scoring, wired to learn across sessions. It extracts skills from what worked, traces causal chains through what broke, reflects on its own failures, and earns an identity through real experience. Every session compounds on the last.

Your assistant stops forgetting. Then it starts getting smarter.

What Changes

Quick Start

From zero to ape brain in under 5 minutes.

1. Install OpenClaw (if you haven't already)

npm install -g openclaw

2. Start SurrealDB

Install SurrealDB via your platform's package manager (see surrealdb.com/install):

macOS:

brew install surrealdb/tap/surreal

Linux — see https://surrealdb.com/docs/surrealdb/installation for your distro.

Then start it locally, change the credentials before use:

surreal start --user youruser --pass yourpass --bind 127.0.0.1:8042 surrealkv:~/.kongbrain/surreal.db

Or with Docker:

docker run -d --name surrealdb -p 127.0.0.1:8042:8000 \
  -v ~/.kongbrain/surreal-data:/data \
  surrealdb/surrealdb:latest start \
  --user youruser --pass yourpass surrealkv:/data/surreal.db

Security note: Always bind to 127.0.0.1 (not 0.0.0.0) unless you need remote access. Never use default credentials in production.

3. Install KongBrain

From ClawHub (recommended):

openclaw plugins install clawhub:kongbrain

From npm:

openclaw plugins install kongbrain

Note: Bare openclaw plugins install kongbrain checks ClawHub first, then falls back to npm. Use the clawhub: prefix to install from ClawHub explicitly.

4. Activate

Add to your OpenClaw config (~/.openclaw/openclaw.json):

{
  "plugins": {
    "allow": ["kongbrain"],
    "slots": {
      "contextEngine": "kongbrain"
    }
  }
}

5. Talk to your ape

openclaw tui

That's it. KongBrain uses whatever LLM provider and model you already have configured in OpenClaw (Anthropic, OpenAI, Google, Ollama, whatever). No separate API keys needed for the brain itself.

The BGE-M3 embedding model (~420MB) downloads automatically on first startup from Hugging Face. All database tables and indexes are created automatically on first run. No manual setup required.

All options have sensible defaults. Override via plugin config or environment variables:

Full config example:

{
  "plugins": {
    "allow": ["kongbrain"],
    "slots": {
      "contextEngine": "kongbrain"
    },
    "entries": {
      "kongbrain": {
        "config": {
          "surreal": {
            "url": "ws://127.0.0.1:8042/rpc",
            "user": "youruser",
            "pass": "yourpass",
            "ns": "kong",
            "db": "memory"
          }
        }
      }
    }
  }
}

Architecture

The IKONG Pillars

KongBrain's cognitive architecture follows five functional pillars:

A 6th pillar, Persona, is unlocked at soul graduation: "You have a Soul, an identity grounded in real experience. Be unique, be genuine, be yourself."

Structural Pillars

The graph entity model in SurrealDB:

On startup, the agent bootstraps the full chain: Agent → owns → Project, Agent → performed → Task, Task → task_part_of → Project, Session → session_task → Task. Graph expansion traverses these edges during retrieval.

The Knowledge Graph

SurrealDB with HNSW vector indexes (1024-dim cosine). Everything is embedded and queryable.

Every turn gets classified by intent and assigned an adaptive config:

Fast path: Short inputs (<20 chars, no ?) skip classification entirely. Confidence gate: Below 0.40 confidence, falls back to conservative config.

1. Embed user input via BGE-M3 (or hit prefetch cache at 0.85 cosine threshold)
2. Vector search across 6 tables (turn, identity_chunk, concept, memory, artifact, monologue)
3. Graph expand: fetch neighbors via structural + semantic edges, compute cosine similarity
4. Score all candidates with WMR (Working Memory Ranker):

   score = W * [similarity, recency, importance, access, neighbor_bonus, utility, reflection_boost]
   

5. Budget trim: inject Tier 0/1 core memory first (15% of context), then ranked results up to 21% retrieval budget
6. Stage retrieval snapshot for post-hoc quality evaluation

A ~130K-parameter cross-attention network that replaces the fixed WMR weights once enough data accumulates.

• Activation: 5,000+ labeled retrieval outcomes
• Training: Pure TypeScript SGD with manual backprop, 80 epochs
• Staleness: Retrains when data grows 50%+ or weights age > 7 days

The agent earns an identity document through accumulated experience. Graduation requires all 7 thresholds met AND a quality score >= 0.6:

Quality scoring from 4 real performance signals: retrieval utilization (30%), skill success rate (25%), critical reflection rate (25%), tool failure rate (20%).

Maturity stages: nascent (0-3/7) → developing (4/7) → emerging (5/7) → maturing (6/7) → ready (7/7 + quality gate). The agent and user are notified at each stage transition.

Soul evolution: Every 10 sessions after graduation, the soul is re-evaluated against new experience and revised if the agent has meaningfully changed.

Soul document structure: Working style, self-observations, earned values (grounded in specific evidence), revision history. Seeded as Tier 0 core memory, loaded every single turn.

Triggers at session end when metrics indicate problems:

The LLM generates a 2-4 sentence reflection: root cause, error pattern, what to do differently. Stored with importance 7.0, deduped at 0.85 cosine similarity.

How It Works

Every Turn

User Input
    |
    v
Preflight ──────── Intent classification (25ms, zero-shot BGE-M3 cosine)
    |                  10 categories: simple-question, code-read, code-write,
    |                  code-debug, deep-explore, reference-prior, meta-session,
    |                  multi-step, continuation, unknown
    v
Prefetch ────────── Predictive background vector searches (LRU cache, 5-min TTL)
    |
    v
Context Injection ─ Vector search -> graph expand -> 6-signal scoring -> budget trim
    |                  Searches: turns, concepts, memories, artifacts, identity, monologues
    |                  Scores: similarity, recency, importance, access, neighbor, utility
    |                  Budget: 21% of context window reserved for retrieval
    v
Agent Loop ──────── LLM + tool execution
    |                  Planning gate: announces plan before touching tools
    |                  Smart truncation: preserves tail of large tool outputs
    v
Turn Storage ────── Every message embedded + stored + linked via graph edges
    |                  responds_to, part_of, mentions, produced
    v
Quality Eval ────── Measures retrieval utilization (text overlap, trigrams, unigrams)
    |                  Tracks tool success, context waste, feeds ACAN training
    v
Memory Daemon ───── Worker thread extracts 9 knowledge types via LLM:
    |                  causal chains, monologues, concepts, corrections,
    |                  preferences, artifacts, decisions, skills, resolved memories
    v
Postflight ──────── Records orchestrator metrics (non-blocking)

Between Sessions

At session end, KongBrain runs a combined extraction pass: skill graduation, metacognitive reflection, causal chain consolidation, soul graduation check, and soul evolution. A handoff note is written so the next session wakes up knowing what happened.

At session start, a wake-up briefing is synthesized from the handoff, recent monologues, soul content (if graduated), and identity state, then injected as inner speech so the agent knows who it is and what it was doing.

A worker thread running throughout the session. Batches turns every ~12K tokens, calls the configured LLM to extract:

• Causal chains: trigger/outcome sequences with success/confidence
• Monologue traces: thinking blocks that reveal problem-solving approach
• Concepts: semantic nodes (architecture patterns, domain terms)
• Corrections: user-provided fixes (importance: 9)
• Preferences: behavioral rules learned from feedback
• Artifacts: file paths created or modified
• Decisions: important conclusions reached
• Skills: multi-step procedures (if 5+ tool calls in session)
• Resolved memories: completed tasks and confirmed facts

Tools

Three tools are registered for the LLM:

• recall Search graph memory by query
• core_memory Read/write persistent core directives (tiered: always-loaded vs session-pinned)
• introspect Inspect database state, verify memory counts, run diagnostics, check graduation status, migrate workspace files

Performance

KongBrain is aggressively optimized for token efficiency and latency, informed by analysis of the Claude Code source.

DB Query Batching

All graph operations use batched multi-statement queries (queryBatch). A single assemble() call sends ~5 round-trips to SurrealDB instead of ~337 individual queries:

Token Estimation

Token counting is aligned with the Anthropic API's actual tokenizer characteristics:

• 4 bytes/token for prose/code (not the common 3.2-3.5 underestimate)
• 2 bytes/token for JSON content (denser single-char tokens)
• 33% safety margin on aggregate estimates
• 2000 tokens for images/documents (matching API billing)

Context Window Efficiency

Every turn, old messages are surgically stripped to save tokens while preserving recent context:

• Thinking blocks replaced with [thinking] marker (saves 1-5k tokens each)
• Old tool results content-cleared to stubs (saves 20-80k tokens/session)
• Old assistant filler collapsed to first line (saves 5-15k/session)
• Images in old messages replaced with [image] marker (saves 2k tokens each)
• System prompt additions capped at 8% of context window with priority trimming

Structured Output

All internal LLM calls (memory extraction, cognitive checks, soul generation, skill extraction) use json_schema structured output when the provider supports it. This eliminates markdown fencing, preamble text, and parsing failures.

Embedding Reuse

User message embeddings computed at ingest time are stashed in session state and reused during context retrieval, eliminating 1-4 redundant BGE-M3 inference calls per turn.

Development

git clone https://github.com/42U/kongbrain.git
cd kongbrain
pnpm install
pnpm build
pnpm test

Link your local build to OpenClaw:

openclaw plugins install . --link

Then set plugins.slots.contextEngine to "kongbrain" in ~/.openclaw/openclaw.json and run openclaw.

Contributing

1. Clone the repo and install dependencies (pnpm install)
2. Make your changes
3. Build (pnpm build) and run tests (pnpm test)
4. Open a PR against master

The lobster doesn't accept contributions. The ape does.

MIT License | Built by 42U