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

Pick one:

# Native install
curl -sSf https://install.surrealdb.com | sh
export PATH="$HOME/.surrealdb:$PATH"
surreal start --user root --pass root --bind 0.0.0.0:8042 surrealkv:~/.kongbrain/surreal.db

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

3. Install KongBrain

openclaw plugins install kongbrain

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. All database tables and indexes are created automatically on first run. No manual setup required.

{
  "plugins": {
    "allow": ["kongbrain"],
    "slots": {
      "contextEngine": "kongbrain"
    },
    "entries": {
      "kongbrain": {
        "config": {
          "surreal": {
            "url": "ws://localhost:8042/rpc",
            "user": "root",
            "pass": "root",
            "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.

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.

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

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.