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.

By default KongBrain runs the BGE-M3 embedding model locally via node-llama-cpp — the GGUF (~420MB) auto-downloads from Hugging Face on first startup. For high-traffic deployments the local model can become a bottleneck on serial embedding calls; in that case switch to any OpenAI-compatible API (real OpenAI, Azure OpenAI, Together, vLLM, LM Studio, Ollama) by changing one config field. See Embedding Providers below.

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://127.0.0.1:8042/rpc",
            "user": "youruser",
            "pass": "yourpass",
            "ns": "kong",
            "db": "memory"
          }
        }
      }
    }
  }
}

Embedding Providers

Switching providers is safe by design. Every embedding written to the database is tagged with the provider that produced it (embedding_provider column). At search time, KongBrain only compares vectors that were produced by the active provider — vectors from a different provider live in a different vector space and would corrupt similarity scores if mixed.

When you switch from local to openai-compat, pre-existing rows stay in the database but become invisible to recall until re-embedded. Run the included migration tool to bring them into the new vector space:

# Estimate cost first (no writes)
npx kongbrain-reembed --from local-bge-m3 --dry-run

# Then run for real (resumable on interruption)
npx kongbrain-reembed --from local-bge-m3

Cost is small: text-embedding-3-small is $0.02 per 1M tokens; a typical 3,400-turn database costs ~$0.04 to re-embed.

Switching to OpenAI

export KONGBRAIN_EMBED_PROVIDER=openai-compat
export OPENAI_API_KEY=sk-...
# Restart the plugin. Migration tool handles existing data.

Switching to a local OpenAI-compatible server (Ollama, vLLM, LM Studio)

# Ollama example — runs entirely locally, no API key needed
ollama pull nomic-embed-text
export OPENAI_BASE_URL=http://localhost:11434/v1
export OPENAI_API_KEY=ollama  # any non-empty string; Ollama doesn't validate
export KONGBRAIN_EMBED_PROVIDER=openai-compat

Set embedding.dimensions to match the server's native output dim. KongBrain verifies the returned vector size on every response and fails loudly if the server ignores the dimensions parameter — preventing silently corrupted indexes.

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

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.