kongbrain 0.3.3 → 0.3.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/.clawhubignore +24 -0
  2. package/README.md +31 -13
  3. package/SKILL.md +110 -0
  4. package/package.json +9 -1
  5. package/src/deferred-cleanup.ts +5 -0
  6. package/src/handoff-file.ts +15 -3
package/.clawhubignore ADDED
@@ -0,0 +1,24 @@
1
+ # Binary assets (not text-based, rejected by clawhub)
2
+ *.png
3
+ *.jpg
4
+ *.jpeg
5
+ *.gif
6
+
7
+ # Dev tooling
8
+ .claude/
9
+ test/
10
+ vitest.config.ts
11
+ *.test.ts
12
+
13
+ # Build/deps
14
+ node_modules/
15
+ dist/
16
+ package-lock.json
17
+
18
+ # Secrets/runtime
19
+ .env
20
+ .env.*
21
+ .kongbrain-handoff.json
22
+
23
+ # Internal docs
24
+ UPSTREAM-PROPOSALS.md
package/README.md CHANGED
@@ -5,6 +5,7 @@
5
5
  ![KongBrain](KongClaw.png)
6
6
 
7
7
  [![npm](https://img.shields.io/npm/v/kongbrain?style=for-the-badge&logo=npm&color=cb3837)](https://www.npmjs.com/package/kongbrain)
8
+ [![ClawHub](https://img.shields.io/badge/ClawHub-kongbrain-ff6b35?style=for-the-badge)](https://clawhub.ai/packages/kongbrain)
8
9
  [![GitHub Stars](https://img.shields.io/github/stars/42U/kongbrain?style=for-the-badge&logo=github&color=gold)](https://github.com/42U/kongbrain)
9
10
  [![License: MIT](https://img.shields.io/github/license/42U/kongbrain?style=for-the-badge&logo=opensourceinitiative&color=blue)](https://opensource.org/licenses/MIT)
10
11
  [![Node.js](https://img.shields.io/badge/Node.js-20+-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org)
@@ -47,29 +48,46 @@ npm install -g openclaw
47
48
 
48
49
  ### 2. Start SurrealDB
49
50
 
50
- Pick one:
51
+ Install SurrealDB via your platform's package manager (see [surrealdb.com/install](https://surrealdb.com/docs/surrealdb/installation)):
51
52
 
52
53
  ```bash
53
- # Native install
54
+ # macOS
55
+ brew install surrealdb/tap/surreal
56
+
57
+ # Linux (Debian/Ubuntu)
54
58
  curl -sSf https://install.surrealdb.com | sh
55
59
  export PATH="$HOME/.surrealdb:$PATH"
56
- surreal start --user root --pass root --bind 0.0.0.0:8042 surrealkv:~/.kongbrain/surreal.db
57
60
  ```
58
61
 
62
+ Then start it locally — **change the credentials before use**:
63
+
59
64
  ```bash
60
- # Docker
61
- docker run -d --name surrealdb -p 8042:8000 \
65
+ surreal start --user youruser --pass yourpass --bind 127.0.0.1:8042 surrealkv:~/.kongbrain/surreal.db
66
+ ```
67
+
68
+ Or with Docker:
69
+
70
+ ```bash
71
+ docker run -d --name surrealdb -p 127.0.0.1:8042:8000 \
62
72
  -v ~/.kongbrain/surreal-data:/data \
63
73
  surrealdb/surrealdb:latest start \
64
- --user root --pass root surrealkv:/data/surreal.db
74
+ --user youruser --pass yourpass surrealkv:/data/surreal.db
65
75
  ```
66
76
 
77
+ > **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.
78
+
67
79
  ### 3. Install KongBrain
68
80
 
69
81
  ```bash
82
+ # From ClawHub (recommended)
83
+ openclaw plugins install clawhub:kongbrain
84
+
85
+ # From npm (fallback)
70
86
  openclaw plugins install kongbrain
71
87
  ```
72
88
 
89
+ > **Note:** Bare `openclaw plugins install kongbrain` checks ClawHub first, then falls back to npm. Use the `clawhub:` prefix to install from ClawHub explicitly.
90
+
73
91
  ### 4. Activate
74
92
 
75
93
  Add to your OpenClaw config (`~/.openclaw/openclaw.json`):
@@ -93,7 +111,7 @@ openclaw tui
93
111
 
94
112
  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.
95
113
 
96
- 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.
114
+ The BGE-M3 embedding model (~420MB) downloads automatically on first startup from [Hugging Face](https://huggingface.co/BAAI/bge-m3). All database tables and indexes are created automatically on first run. No manual setup required.
97
115
 
98
116
  <details>
99
117
  <summary><strong>Configuration Options</strong></summary>
@@ -102,9 +120,9 @@ All options have sensible defaults. Override via plugin config or environment va
102
120
 
103
121
  | Option | Env Var | Default |
104
122
  |--------|---------|---------|
105
- | `surreal.url` | `SURREAL_URL` | `ws://localhost:8042/rpc` |
106
- | `surreal.user` | `SURREAL_USER` | `root` |
107
- | `surreal.pass` | `SURREAL_PASS` | `root` |
123
+ | `surreal.url` | `SURREAL_URL` | `ws://127.0.0.1:8042/rpc` |
124
+ | `surreal.user` | `SURREAL_USER` | (required) |
125
+ | `surreal.pass` | `SURREAL_PASS` | (required) |
108
126
  | `surreal.ns` | `SURREAL_NS` | `kong` |
109
127
  | `surreal.db` | `SURREAL_DB` | `memory` |
110
128
  | `embedding.modelPath` | `KONGBRAIN_EMBEDDING_MODEL` | Auto-downloaded BGE-M3 Q4_K_M |
@@ -123,9 +141,9 @@ Full config example:
123
141
  "kongbrain": {
124
142
  "config": {
125
143
  "surreal": {
126
- "url": "ws://localhost:8042/rpc",
127
- "user": "root",
128
- "pass": "root",
144
+ "url": "ws://127.0.0.1:8042/rpc",
145
+ "user": "youruser",
146
+ "pass": "yourpass",
129
147
  "ns": "kong",
130
148
  "db": "memory"
131
149
  }
package/SKILL.md ADDED
@@ -0,0 +1,110 @@
1
+ ---
2
+ name: kongbrain
3
+ description: Graph-backed persistent memory engine for OpenClaw. Replaces the default context window with SurrealDB + vector embeddings that learn across sessions.
4
+ version: 0.3.5
5
+ homepage: https://github.com/42U/kongbrain
6
+ metadata:
7
+ openclaw:
8
+ requires:
9
+ bins:
10
+ - surreal
11
+ env:
12
+ - SURREAL_URL
13
+ - SURREAL_USER
14
+ - SURREAL_PASS
15
+ - SURREAL_NS
16
+ - SURREAL_DB
17
+ primaryEnv: SURREAL_URL
18
+ install:
19
+ - kind: node
20
+ package: kongbrain
21
+ bins: []
22
+ ---
23
+
24
+ # KongBrain
25
+
26
+ Graph-backed persistent memory engine for OpenClaw. Replaces the default context window with SurrealDB + vector embeddings that learn across sessions.
27
+
28
+ ## What it does
29
+
30
+ KongBrain gives your OpenClaw agent persistent, structured memory:
31
+
32
+ - **Session tracking** - records conversations and extracts knowledge automatically
33
+ - **9 memory categories** - knowledge, goals, reflections, handoffs, corrections, preferences, decisions, skills, and causal chains
34
+ - **Vector search** - BGE-M3 embeddings for semantic recall
35
+ - **Graph relationships** - memories linked via SurrealDB graph edges for traversal
36
+ - **Tiered memory** - core memories always loaded, session memories pinned, rest searched on demand
37
+ - **Mid-session extraction** - extracts knowledge during conversation, not just at exit
38
+ - **Crash resilience** - deferred cleanup processes orphaned sessions on next startup
39
+
40
+ ## Requirements
41
+
42
+ - **SurrealDB** - running instance (local or remote)
43
+ - **Node.js** >= 18
44
+
45
+ ## Setup
46
+
47
+ ### Install SurrealDB
48
+
49
+ See the official install guide: https://surrealdb.com/docs/surrealdb/installation
50
+
51
+ Platform packages:
52
+
53
+ ```bash
54
+ # macOS
55
+ brew install surrealdb/tap/surreal
56
+
57
+ # Linux (Debian/Ubuntu)
58
+ curl -sSf https://install.surrealdb.com | sh
59
+
60
+ # Docker
61
+ docker pull surrealdb/surrealdb:latest
62
+ ```
63
+
64
+ ### Start SurrealDB
65
+
66
+ ```bash
67
+ # Local only (recommended) - use strong credentials in production
68
+ surreal start --user youruser --pass yourpass --bind 127.0.0.1:8000 surrealkv:~/.kongbrain/surreal.db
69
+ ```
70
+
71
+ > **Security note:** Always bind to `127.0.0.1` (not `0.0.0.0`) unless you specifically need remote access. Change the default credentials before use.
72
+
73
+ For Docker:
74
+
75
+ ```bash
76
+ docker run -d --name surrealdb -p 127.0.0.1:8000:8000 \
77
+ -v ~/.kongbrain/surreal-data:/data \
78
+ surrealdb/surrealdb:latest start \
79
+ --user youruser --pass yourpass surrealkv:/data/surreal.db
80
+ ```
81
+
82
+ ## Configuration
83
+
84
+ Set environment variables or provide a `.env` file:
85
+
86
+ ```
87
+ SURREAL_URL=ws://127.0.0.1:8000/rpc
88
+ SURREAL_USER=youruser
89
+ SURREAL_PASS=yourpass
90
+ SURREAL_NS=kongbrain
91
+ SURREAL_DB=kongbrain
92
+ ```
93
+
94
+ ## Usage
95
+
96
+ Install as an OpenClaw plugin:
97
+
98
+ ```bash
99
+ openclaw plugins install clawhub:kongbrain
100
+ ```
101
+
102
+ Or via npm:
103
+
104
+ ```bash
105
+ npm install kongbrain
106
+ ```
107
+
108
+ The BGE-M3 embedding model (~420MB) downloads automatically on first startup from Hugging Face (https://huggingface.co/BAAI/bge-m3). All database tables and indexes are created automatically on first run.
109
+
110
+ KongBrain hooks into OpenClaw's plugin lifecycle automatically. Memory extraction runs in the background via a daemon worker thread.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "kongbrain",
3
- "version": "0.3.3",
3
+ "version": "0.3.5",
4
4
  "description": "Graph-backed persistent memory engine for OpenClaw. Replaces the default context window with SurrealDB + vector embeddings that learn across sessions.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -30,6 +30,14 @@
30
30
  ],
31
31
  "install": {
32
32
  "minHostVersion": ">=2026.3.23"
33
+ },
34
+ "compat": {
35
+ "pluginApi": ">=2026.3.23",
36
+ "minGatewayVersion": "2026.3.23"
37
+ },
38
+ "build": {
39
+ "openclawVersion": "2026.3.23",
40
+ "pluginSdkVersion": "2026.3.23"
33
41
  }
34
42
  },
35
43
  "scripts": {
package/src/deferred-cleanup.ts CHANGED
@@ -129,6 +129,11 @@ async function processOrphanedSession(
129
129
  result = JSON.parse(jsonMatch[0].replace(/,\s*([}\]])/g, "$1"));
130
130
  } catch { result = {}; }
131
131
  }
132
+ // Strip prototype pollution keys from LLM-generated JSON
133
+ const BANNED_KEYS = new Set(["__proto__", "constructor", "prototype"]);
134
+ for (const key of Object.keys(result)) {
135
+ if (BANNED_KEYS.has(key)) delete (result as any)[key];
136
+ }
132
137
 
133
138
  const keys = Object.keys(result);
134
139
  console.warn(`[deferred] parsed ${keys.length} keys: ${keys.join(", ")}`);
package/src/handoff-file.ts CHANGED
@@ -6,7 +6,7 @@
6
6
  * so the next session's wakeup has context even before deferred
7
7
  * extraction runs.
8
8
  */
9
- import { readFileSync, writeFileSync, unlinkSync, existsSync } from "node:fs";
9
+ import { readFileSync, writeFileSync, unlinkSync, existsSync, chmodSync } from "node:fs";
10
10
  import { join } from "node:path";
11
11
 
12
12
  const HANDOFF_FILENAME = ".kongbrain-handoff.json";
@@ -29,7 +29,7 @@ export function writeHandoffFileSync(
29
29
  ): void {
30
30
  try {
31
31
  const path = join(workspaceDir, HANDOFF_FILENAME);
32
- writeFileSync(path, JSON.stringify(data, null, 2), "utf-8");
32
+ writeFileSync(path, JSON.stringify(data, null, 2), { encoding: "utf-8", mode: 0o600 });
33
33
  } catch {
34
34
  // Best-effort — sync exit handler, can't log async
35
35
  }
@@ -46,7 +46,19 @@ export function readAndDeleteHandoffFile(
46
46
  try {
47
47
  const raw = readFileSync(path, "utf-8");
48
48
  unlinkSync(path);
49
- return JSON.parse(raw) as HandoffFileData;
49
+ const parsed = JSON.parse(raw);
50
+ // Runtime validation — reject prototype pollution and malformed data
51
+ if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
52
+ if ("__proto__" in parsed || "constructor" in parsed) return null;
53
+ const data: HandoffFileData = {
54
+ sessionId: typeof parsed.sessionId === "string" ? parsed.sessionId.slice(0, 200) : "",
55
+ timestamp: typeof parsed.timestamp === "string" ? parsed.timestamp.slice(0, 50) : "",
56
+ userTurnCount: typeof parsed.userTurnCount === "number" ? parsed.userTurnCount : 0,
57
+ lastUserText: typeof parsed.lastUserText === "string" ? parsed.lastUserText.slice(0, 500) : "",
58
+ lastAssistantText: typeof parsed.lastAssistantText === "string" ? parsed.lastAssistantText.slice(0, 500) : "",
59
+ unextractedTokens: typeof parsed.unextractedTokens === "number" ? parsed.unextractedTokens : 0,
60
+ };
61
+ return data;
50
62
  } catch {
51
63
  // Corrupted or deleted between check and read
52
64
  try { unlinkSync(path); } catch { /* ignore */ }