@susu-eng/gralkor 27.2.9 → 27.2.11

package/README.md

@@ -8,74 +8,55 @@ Gralkor automatically remembers and recalls everything your agent says, _thinks_
 
 ## Why Gralkor
 
-Here's the honest field report on every OpenClaw memory plugin:
-
-| Plugin | Storage | Captures thinking | Episode scope | Temporal facts | Local |
-|---|---|---|---|---|---|
-| **memory-core** *(built-in)* | Markdown files | no | full (LLM-written at compaction) | no | ✓ |
-| **lancedb-pro** | LanceDB (flat vector) | no | new messages per run | partial | ✓ |
-| **MemOS Local** | SQLite + vector | no | turn delta | recency decay only | ✓ |
-| **Cognee** | Cognee graph API | no | Q&A pairs | partial | optional |
-| **Supermemory** | Cloud (opaque) | no | last turn only | server-side flag | ✗ |
-| **MemOS Cloud** | Cloud (opaque) | no | last turn *(default)* | none | ✗ |
-| **Awareness** | Cloud + MD mirror | no | first message + last reply | none | ✗ |
-| **Gralkor** | Graphiti knowledge graph | **yes** | full session | `valid_at`/`invalid_at`/`expired_at` | ✓ |
-
 Let's look in detail about the decisions made for Gralkor and why they make it the best memory plugin for OpenClaw.
 
-**Graphs, not Markdown or pure vector.** The AI ecosystem's fixation on Markdown-based memory is baffling. Graphs are the right data structure for representing knowledge. Your code is a graph (syntax trees), your filesystem is a graph, the web is a graph. The world is a deeply interrelated graph, and trying to flatten it into Markdown files or pure vector embeddings is fighting reality.
-
-Yet: the most popular memory plugin — memory-core, the one that ships inside OpenClaw — writes your agent's memory to `MEMORY.md` and `memory/YYYY-MM-DD.md`. The second most popular, lancedb-pro, stores extracted facts as flat rows in LanceDB. [Graphiti](https://github.com/getzep/graphiti) combines a knowledge graph with vector embeddings — you get structured relationships *and* semantic retrieval. Facts carry temporal validity: when they became true, when they stopped being true, when they were superseded.
-
-This is not another chunking strategy or embedding experiment. Graphiti has solved this layer of the problem and Gralkor deploys and leverages it optimally for this use case.
+**Graphs, not Markdown or pure vector.** Graphs are the right data structure for representing knowledge. Your code is a graph - the _world_ is a deeply interrelated graph and trying to flatten it into Markdown files or pure vector embeddings is fighting reality. Gralkor doesn't use MD files (other than indexing yours), and this is not another chunking strategy or embedding experiment. Graphiti has already solved this layer and Gralkor leverages it optimally for this use case.
 
 [HippoRAG](https://arxiv.org/abs/2405.14831) (NeurIPS 2024) found graph-based retrieval reaches 89.1% recall@5 on 2WikiMultiHopQA versus 68.2% for flat vector retrieval — a 20.9-point gap. [AriGraph](https://arxiv.org/abs/2407.04363) (IJCAI 2025) independently found KG-augmented agents markedly outperform RAG, summarization, and full-conversation-history baselines across interactive environments.
 
-**Remembering behaviour, not just dialog.** Agents make mistakes options, weight options, reject approaches - they _learn_ as they complete tasks. Gralkor distills the agent's thinking blocks - it's learning - into first-person behavioural summaries and weaves them into the episode transcript before ingestion. The graph doesn't just know what was said; it knows how the agent arrived there.
+**Remembering behaviour, not just dialog.** Agents make mistakes, weigh options, reject approaches - they _learn_ as they complete tasks. Gralkor distills the agent's behaviour - not just its dialog - into first-person behavioural reports weaved into episode transcripts before ingestion.
 
-Yet: Every other OpenClaw memory plugin only remembers what was spoken, totally ignoring what your agent thinks and does — lancedb-pro filters for `type === "text"` only, MemOS strips `<think>` tags, Supermemory never looks at them. Even if you have a sophisticated memory system, your agent is inherently dishonest with you, frequently claiming to remember what it has done when it only really remembers what it claimed to have done, or to have thought what it is only now imagining.
+For almost all other memory plugins, your agent is inherently dishonest with you, frequently claiming to remember what it has done when it only really remembers what it _already claimed_ to have done, or to have thought _what it is only now imagining_.
 
-Gralkor actually remembers what your agent thought and did — it is the only OpenClaw memory plugin with this capability.
+With Gralkor your agent actually remembers it's thoughts and actions.
 
 [Reflexion](https://arxiv.org/abs/2303.11366) (NeurIPS 2023) showed agents storing self-reflective reasoning traces outperform GPT-4 output-only baselines by 11 points on HumanEval. [ExpeL](https://arxiv.org/abs/2308.10144) (AAAI 2024) directly ablated reasoning-trace storage versus output-only: +11–19 points across benchmarks from storing the reasoning process alone.
 
 **Maximum context at ingestion.** Gralkor captures all messages in each session of work, distills behaviour, and feeds results to Graphiti *as whole episodes*. Extraction works _way_ better when Graphiti has full context.
 
-Yet: Most memory plugins save isolated question-answer pairs or summarized snippets: "Awareness" stores the first user message and the last assistant reply — a 30-turn debugging session becomes two sentences. Some default to the last turn only. Others capture single turns of dialog.
+Most memory plugins save isolated question-answer pairs or summarized snippets: Some store only the first user message and the last assistant reply, others store to the last turn only.
 
-Gralkor captures _the whole episode_ — the entire series of questions, thoughts, actions, and responses that _solved the problem_. Richer semantics, better understanding, better recall.
+Gralkor captures the entire series of questions, thoughts, actions, and responses that _solved the problem_ together, with all their interrelationships. Richer semantics, better understanding, better recall.
 
 [SeCom](https://arxiv.org/abs/2502.05589) (ICLR 2025) found coherent multi-turn episode storage scores 5.99 GPT4Score points higher than isolated turn-level storage on LOCOMO. [LongMemEval](https://arxiv.org/abs/2410.10813) (ICLR 2025) confirms: fact-level QA-pair extraction drops accuracy from 0.692 to 0.615 versus full-round episode storage.
 
-**Built for the long term.** Graphiti — on which Gralkor is based — is _temporally aware_. On every ingestion, it doesn't just append; it resolves new information against the existing graph, amending, expiring, and invalidating so that your agent knows _what happened over time_.
+**Built for the long term.** Graphiti (and therefore Gralkor) is deeply temporal. On every ingestion, it doesn't just append; it resolves new information against the existing graph, amending, expiring, and invalidating so that your agent knows _what happened over time_.
 
-Graphiti does the heavy temporal lifting on ingestion and supports point-in-time queries across a traversable structure. This is expensive, bad for throughput, and useless for short-lived agents, so serving a single, long-lived user agent is _the perfect use case_. Graphiti was destined for Gralkor and OpenClaw.
+Graphiti does the heavy temporal lifting on ingestion. It's bad for throughput, and useless for short-lived agents, which means serving a single, long-lived user agent is _the perfect use case_.
 
 [LongMemEval](https://arxiv.org/abs/2410.10813) (ICLR 2025) established that temporal reasoning is the hardest memory sub-task for commercial LLMs; time-aware indexing recovers 7–11% of that loss. [MemoTime](https://arxiv.org/abs/2510.13614) (WWW 2026) found temporal knowledge graphs enable a 4B model to match GPT-4-Turbo on temporal reasoning, with up to 24% improvement over static memory baselines.
 
-**Recursion through reflection.** A knowledge graph is a living structure. Point your agent back at its own memory — let it reflect on what it knows, identify contradictions, synthesize higher-order insights, and do with them whatever you believe to be _good cognitive architecture_ :shrug:. Gralkor doesn't prescribe how you do this.
+**Recursion through reflection.** Point your agent back at its own memory — let it reflect on what it knows, identify contradictions, synthesize higher-order insights, and do with them whatever you believe to be _good cognitive architecture_. Gralkor doesn't limit you to one approach, but the research is quite clear - you should do _something_.
 
-My way is to use cron and [Thinker CLI](https://github.com/elimydlarz/thinker-cli) together, directing the agent to use the search and add memory tools. Share yours, and ask to see mine.
+My way is to use cron and [Thinker CLI](https://github.com/elimydlarz/thinker-cli) together, directing the agent to use the search and add memory tools in a sequential reflective process. Share yours, and ask to see mine.
 
 [Reflexion](https://arxiv.org/abs/2303.11366) (NeurIPS 2023) demonstrated that agents storing verbal reflections in an episodic buffer gain 11 points with no weight updates. [Generative Agents](https://arxiv.org/abs/2304.03442) (UIST 2023) showed empirically that a reflection layer synthesizing raw memories into higher-order insights is essential for coherent long-term behavior.
 
-**Custom ontology: model your agent's world _your way_.** Define your own entity types, attributes, and relationships so that information is parsed into entities and relationships you define. You could use a domain model codified by experts, be the expert, or try to encode _your_ model of the world.
+**Custom ontology: model your agent's world _your way_.** Gralkor lets you define your own entity types, attributes, and relationships so that information is parsed into entities and relationships you define. Your graph doesn't have to be a black box - you can keep track of what matters to you.
 
-Agent memory doesn't have to be so fuzzy that you lose what matters.
+You can use a domain model codified by experts in your field, or encode _your_ model of the world so that your agent shares it.
 
 [Apple's ODKE+](https://arxiv.org/abs/2509.04696) (2025) showed ontology-guided extraction hits 98.8% precision vs 91% raw LLM; [GoLLIE](https://arxiv.org/abs/2310.03668) (ICLR 2024) directly ablated schema-constrained versus unconstrained generation on the same model, finding +13 F1 points average across NER, relation, and event extraction in zero-shot settings.
 
-**On cost.** Gralkor costs more to run than a Markdown file. It's better context management, not overhead. Instead of paying to pollute your context window with junk every read, you pay more on ingestion in exchange for cheap, high-relevance reads. Extract and structure what matters, then pull only the right stuff at read time.
+**Interpretation** Gralkor interprets information in memory for relevance to the task at hand. This step radically improves output with minimal impact on cost and latency.
 
-It's worth it: A single recalled fact — "we chose postgres over mysql because of the jsonb column support we need for X" — prevents re-litigating that decision in a new session. An agent that remembers your architectural decisions, your preferences, your debugging history, and your reasoning across sessions changes the character of your work.
+**On cost.** Gralkor costs more to run than a Markdown file in the short term. In the longer term, Gralkor provides more efficient context management, reducing token burn. Instead of paying to pollute your context window with junk every read, you pay more on ingestion in exchange for cheap, high-relevance reads forever.
 
-You stop spending turns re-establishing context and focus more on what you care about. Paying $20 to Google every month to make your agent _meaningfully_ more effective is a no-brainer. The agents that cost you _real_ money are the ones that forget everything and make you start over, or burn tokens overloading context with noise.
+An agent that remembers behaviour, decisions, your preferences, and reasoning across sessions changes the _character_ of your work. You stop spending turns re-establishing context and focus more on what you care about. A single recalled behavioural fact — "we rejected mysql because it lacked jsonb column support needed for X" — prevents re-litigating that decision in a new session - it might save 10 subagents repeating a parallel investigation of database options.
 
-Gralkor is _good_ memory, not cheap memory. You can push the llm choice and perhaps get better extraction, but otherwise I've just made it as good as possible, other than being reasonable about latency.
+Gralkor is _good_ memory, not cheap memory. You can push the llm choice and perhaps get better extraction, but otherwise I've just made it as good as possible while being reasonable about latency.
 
-## What it does
-
-Gralkor replaces the native memory plugin entirely, taking the memory slot.
+## Tools
 
 - **`memory_search`** — searches the knowledge graph and returns relevant facts and entity summaries
 - **`memory_add`** — stores information in the knowledge graph; Graphiti extracts entities and relationships
@@ -134,12 +115,22 @@ openclaw plugins install ./susu-eng-gralkor-memory-26.0.14.tgz --dangerously-for
 
 ### 4. Enable and assign the memory slot
 
+OpenClaw has a single `memory` slot that determines which plugin provides memory to your agents. You must explicitly assign Gralkor to the `memory` slot, otherwise installing the plugin does nothing — auto-capture and auto-recall hooks will never fire.
+
 ```bash
-# Allowlist (if you use one)
+# If you use an allowlist, add gralkor to it
 openclaw config set --json plugins.allow '["gralkor"]'
 
-# Assign the memory slot — replaces the built-in memory-core
+# Enable the plugin entry
+openclaw config set plugins.entries.gralkor.enabled true
+
+# Assign Gralkor to the memory slot (replaces the built-in memory-core)
 openclaw config set plugins.slots.memory gralkor
+
+# Expose Gralkor's tools to the agent. Auto-capture and auto-recall work without
+# this, but the agent won't see memory_add / memory_build_indices / memory_build_communities
+# unless you add them to the active tool profile's allowlist.
+openclaw config set --json tools.alsoAllow '["gralkor"]'
 ```
 
 ### 5. Restart and go
@@ -167,20 +158,6 @@ Start chatting with your agent. Gralkor works in the background:
 openclaw plugins update gralkor --dangerously-force-unsafe-install
 ```
 
-### Reinstalling
-
-The plugin dir (`~/.openclaw/extensions/gralkor`) is ephemeral — it can be deleted and reinstalled freely. The `dataDir` is persistent — the venv and FalkorDB database survive across reinstalls.
-
-```bash
-openclaw plugins uninstall gralkor
-openclaw plugins install @susu-eng/gralkor --dangerously-force-unsafe-install
-openclaw config set plugins.slots.memory gralkor
-```
-
-`uninstall` removes the plugin files and resets the memory slot automatically.
-
-The second boot is fast (~4s) because the venv in `dataDir` is reused.
-
 ### LLM providers
 
 Graphiti needs an LLM to extract entities and relationships from conversations.
@@ -192,24 +169,12 @@ Graphiti needs an LLM to extract entities and relationships from conversations.
 | **Anthropic** | `anthropicApiKey` | LLM only — still needs `openaiApiKey` for embeddings |
 | **Groq** | `groqApiKey` | LLM only — still needs `openaiApiKey` for embeddings |
 
-To switch away from Gemini, set `llm` and `embedder` in the plugin config. For example, with OpenAI:
+To switch away from Gemini, set `llm` and `embedder`. For example, with OpenAI:
 
-```json
-{
-  "plugins": {
-    "entries": {
-      "gralkor": {
-        "enabled": true,
-        "config": {
-          "dataDir": "/path/to/gralkor-data",
-          "openaiApiKey": { "$ref": "env:OPENAI_API_KEY" },
-          "llm": { "provider": "openai", "model": "gpt-4.1-mini" },
-          "embedder": { "provider": "openai", "model": "text-embedding-3-small" }
-        }
-      }
-    }
-  }
-}
+```bash
+openclaw config set plugins.entries.gralkor.config.openaiApiKey "$OPENAI_API_KEY"
+openclaw config set --json plugins.entries.gralkor.config.llm '{"provider":"openai","model":"gpt-4.1-mini"}'
+openclaw config set --json plugins.entries.gralkor.config.embedder '{"provider":"openai","model":"text-embedding-3-small"}'
 ```
 
 ## CLI
@@ -219,26 +184,15 @@ openclaw gralkor status              # Server state, config, graph stats, data d
 openclaw gralkor search <group_id> <query>  # Search the knowledge graph
 ```
 
+See [Graph partitioning](#graph-partitioning) for what `<group_id>` should be.
+
 ## Configuration
 
-Configure in your OpenClaw plugin settings (`~/.openclaw/openclaw.json`):
+Configure with `openclaw config set`. For example:
 
-```json
-{
-  "plugins": {
-    "entries": {
-      "gralkor": {
-        "enabled": true,
-        "config": {
-          "autoCapture": { "enabled": true },
-          "autoRecall": { "enabled": true, "maxResults": 10 },
-          "idleTimeoutMs": 300000,
-          "dataDir": "/path/to/data"
-        }
-      }
-    }
-  }
-}
+```bash
+openclaw config set --json plugins.entries.gralkor.config.autoRecall.maxResults 20
+openclaw config set --json plugins.entries.gralkor.config.idleTimeoutMs 600000
 ```
 
 | Setting | Default | Description |
@@ -254,38 +208,33 @@ Configure in your OpenClaw plugin settings (`~/.openclaw/openclaw.json`):
 
 ### Complete config reference
 
+The full plugin config shape (as it appears under `plugins.entries.gralkor.config` in `~/.openclaw/openclaw.json`):
+
 ```json
 {
-  "plugins": {
-    "entries": {
-      "gralkor": {
-        "enabled": true,
-        "config": {
-          "dataDir": "/path/to/gralkor-data",
-          "workspaceDir": "~/.openclaw/workspace",
-          "googleApiKey": "your-gemini-key",
-          "llm": { "provider": "gemini", "model": "gemini-3.1-flash-lite-preview" },
-          "embedder": { "provider": "gemini", "model": "gemini-embedding-2-preview" },
-          "autoCapture": { "enabled": true },
-          "autoRecall": { "enabled": true, "maxResults": 10 },
-          "search": { "maxResults": 20, "maxEntityResults": 10 },
-          "idleTimeoutMs": 300000,
-          "ontology": {
-            "entities": {},
-            "edges": {},
-            "edgeMap": {}
-          },
-          "test": false
-        }
-      }
-    }
-  }
+  "dataDir": "/path/to/gralkor-data",
+  "workspaceDir": "~/.openclaw/workspace",
+  "googleApiKey": "your-gemini-key",
+  "llm": { "provider": "gemini", "model": "gemini-3.1-flash-lite-preview" },
+  "embedder": { "provider": "gemini", "model": "gemini-embedding-2-preview" },
+  "autoCapture": { "enabled": true },
+  "autoRecall": { "enabled": true, "maxResults": 10 },
+  "search": { "maxResults": 20, "maxEntityResults": 10 },
+  "idleTimeoutMs": 300000,
+  "ontology": {
+    "entities": {},
+    "edges": {},
+    "edgeMap": {}
+  },
+  "test": false
 }
 ```
 
 ### Graph partitioning
 
-Each agent gets its own graph partition automatically (based on `agentId`). No configuration needed — different agents won't see each other's knowledge.
+Each agent gets its own graph partition automatically — different agents won't see each other's knowledge, and no configuration is needed.
+
+The partition key (`group_id`) is the agent's ID with hyphens replaced by underscores (FalkorDB's RediSearch syntax doesn't accept hyphens). So an agent named `my-coding-agent` stores its memory under group `my_coding_agent`. Agents running without an explicit ID use the partition `default`. You'll need this `group_id` whenever you query the graph directly — e.g. `openclaw gralkor search <group_id> <query>`.
 
 ## Custom entity and relationship types
 
@@ -293,81 +242,70 @@ By default, Graphiti extracts generic entities and connects them with generic `R
 
 If you want more structured extraction, you can define custom entity and relationship types. Graphiti will classify entities into your types, extract structured attributes, and create typed relationships between them.
 
-### Entities only (start here)
+### Entities
 
-The simplest useful ontology defines just entity types. Relationships will still be created, using Graphiti's default `RELATES_TO` type.
+The simplest useful ontology defines just entity types. Relationships will still be created, using Graphiti's default `RELATES_TO` type. Set the whole ontology in one go:
 
-```json
-{
-  "plugins": {
-    "entries": {
-      "gralkor": {
-        "enabled": true,
-        "config": {
-          "ontology": {
-            "entities": {
-              "Project": {
-                "description": "A software project or initiative being actively developed. Look for mentions of repositories, codebases, applications, services, or named systems that are built and maintained by a team.",
-                "attributes": {
-                  "status": ["active", "completed", "paused"],
-                  "language": "Primary programming language used in the project"
-                }
-              },
-              "Technology": {
-                "description": "A programming language, framework, library, database, or infrastructure tool. Identify by mentions of specific named technologies used in or considered for projects.",
-                "attributes": {
-                  "category": ["language", "framework", "database", "infrastructure", "tool"]
-                }
-              }
-            }
-          }
-        }
+```bash
+openclaw config set --json plugins.entries.gralkor.config.ontology '{
+  "entities": {
+    "Project": {
+      "description": "A software project or initiative being actively developed. Look for mentions of repositories, codebases, applications, services, or named systems that are built and maintained by a team.",
+      "attributes": {
+        "status": ["active", "completed", "paused"],
+        "language": "Primary programming language used in the project"
+      }
+    },
+    "Technology": {
+      "description": "A programming language, framework, library, database, or infrastructure tool. Identify by mentions of specific named technologies used in or considered for projects.",
+      "attributes": {
+        "category": ["language", "framework", "database", "infrastructure", "tool"]
       }
     }
   }
-}
+}'
 ```
 
-### Adding relationships
+### Relationships
 
 To control how entities are connected, add `edges` (relationship types) and `edgeMap` (which entity pairs they apply to):
 
 ```json
 {
-  "ontology": {
-    "entities": {
-      "Project": {
-        "description": "A software project or initiative being actively developed. Look for mentions of repositories, codebases, applications, services, or named systems that are built and maintained by a team.",
-        "attributes": {
-          "status": ["active", "completed", "paused"],
-          "language": "Primary programming language used in the project"
-        }
-      },
-      "Technology": {
-        "description": "A programming language, framework, library, database, or infrastructure tool. Identify by mentions of specific named technologies used in or considered for projects.",
-        "attributes": {
-          "category": ["language", "framework", "database", "infrastructure", "tool"]
-        }
+  "entities": {
+    "Project": {
+      "description": "A software project or initiative being actively developed. Look for mentions of repositories, codebases, applications, services, or named systems that are built and maintained by a team.",
+      "attributes": {
+        "status": ["active", "completed", "paused"],
+        "language": "Primary programming language used in the project"
       }
     },
-    "edges": {
-      "Uses": {
-        "description": "A project actively using a technology in its stack. Look for statements about tech choices, dependencies, or implementation details that indicate a project relies on a specific technology.",
-        "attributes": {
-          "version": "Version of the technology in use, if mentioned"
-        }
+    "Technology": {
+      "description": "A programming language, framework, library, database, or infrastructure tool. Identify by mentions of specific named technologies used in or considered for projects.",
+      "attributes": {
+        "category": ["language", "framework", "database", "infrastructure", "tool"]
+      }
+    }
+  },
+  "edges": {
+    "Uses": {
+      "description": "A project actively using a technology in its stack. Look for statements about tech choices, dependencies, or implementation details that indicate a project relies on a specific technology.",
+      "attributes": {
+        "version": "Version of the technology in use, if mentioned"
       }
-    },
-    "edgeMap": {
-      "Project,Technology": ["Uses"]
     }
+  },
+  "edgeMap": {
+    "Project,Technology": ["Uses"]
   }
 }
 ```
 
+Apply with `openclaw config set --json plugins.entries.gralkor.config.ontology '<above>'`.
+
 Without `edgeMap`, all edge types can connect any entity pair. With `edgeMap`, relationships are constrained to specific pairs — entity pairs not listed fall back to `RELATES_TO`.
 
-### Attribute format
+### Attributes
 
 Attributes control what Graphiti extracts for each entity or relationship. They are **required fields** — if the LLM can't populate them from the text, it won't extract that entity type at all. This makes attributes the primary mechanism for gating extraction quality.
 
@@ -380,7 +318,7 @@ Attributes control what Graphiti extracts for each entity or relationship. They
 
 Supported types for the object form: `string`, `int`, `float`, `bool`, `datetime`.
 
-### Writing good descriptions
+### Descriptions
 
 Descriptions are the most important part of your ontology — they tell the LLM what to look for. Write them like extraction instructions, not dictionary definitions.
 
@@ -416,21 +354,21 @@ openclaw config set plugins.entries.gralkor.config.dataDir /data/gralkor
 
 ```
 User sends message
-       │
-       ▼
- ┌─────────────┐     search     ┌──────────┐     query     ┌──────────┐
- │  auto-recall │ ──────────▶   │ Graphiti  │ ──────────▶   │ FalkorDB │
- │    hook      │ ◀──────────   │   API     │ ◀──────────   │          │
- └─────────────┘    facts       └──────────┘   subgraph     └──────────┘
-       │
-       ▼
+        │
+        ▼
+ ┌──────────────┐    search    ┌──────────────┐    query     ┌──────────────┐
+ │ auto-recall  │ ───────────▶ │   Graphiti   │ ───────────▶ │   FalkorDB   │
+ │    hook      │ ◀─────────── │     API      │ ◀─────────── │              │
+ └──────────────┘    facts     └──────────────┘   subgraph   └──────────────┘
+        │
+        ▼
  Agent runs (with recalled facts as context)
-       │
-       ▼
- ┌──────────────┐    ingest     ┌──────────┐    extract     ┌──────────┐
- │ auto-capture  │ ──────────▶  │ Graphiti  │ ──────────▶   │ FalkorDB │
- │    hook       │              │   API     │   entities    │          │
- └──────────────┘              └──────────┘   & facts      └──────────┘
+        │
+        ▼
+ ┌──────────────┐    ingest    ┌──────────────┐   extract    ┌──────────────┐
+ │ auto-capture │ ───────────▶ │   Graphiti   │ ───────────▶ │   FalkorDB   │
+ │    hook      │              │     API      │  entities    │              │
+ └──────────────┘              └──────────────┘   & facts    └──────────────┘
 ```
 
 Graphiti handles the heavy lifting: entity extraction, relationship mapping, temporal tracking, and embedding-based search. Gralkor wires it into the OpenClaw plugin lifecycle. The Graphiti server and embedded FalkorDB run as a managed subprocess — started and stopped automatically by the plugin.
@@ -438,7 +376,18 @@ Graphiti handles the heavy lifting: entity extraction, relationship mapping, tem
 ## Troubleshooting
 
 **`openclaw gralkor status` says "Server process: stopped"**
-Python 3.12+ is not found on the system PATH. Install Python 3.12+ and restart OpenClaw.
+Many things can cause this. Use the available diagnostics to narrow it down:
+
+- **`openclaw gralkor status`** — shows process state, config summary, `dataDir`, venv state, and (if unreachable) the connection error
+- **Gateway logs** — grep for `[gralkor] boot:` markers. You should see `boot: plugin loaded`, `boot: starting`, then `boot: ready`. A `boot: ... failed:` line tells you which stage broke
+- **`openclaw gralkor search <group_id> <query>`** — quick end-to-end check that the server is reachable and the graph has data (group ID is required; it's the agent ID with hyphens replaced by underscores)
+
+Common causes:
+- `uv` not on PATH (Python itself is managed by `uv` — it fetches 3.12+ on demand and produces its own errors)
+- `uv sync` failed (network/registry issue, or on first boot ~1–2 min is normal — wait it out)
+- Missing or invalid LLM API key — the server starts but every operation fails
+- Stale `server.pid` in `dataDir` holding port 8001 (the manager tries to clean this up, but a SIGKILL'd predecessor can leave the port wedged)
+- On `linux/arm64`: bundled falkordblite wheel couldn't be resolved (not in `server/wheels/`, not cached in `dataDir/wheels/`, and the GitHub Release download failed)
 
 **First startup takes a long time**
 Normal — Gralkor is creating a Python virtual environment and installing dependencies via pip. This takes ~1-2 minutes. Subsequent starts reuse the venv and skip pip.
@@ -448,7 +397,7 @@ Most likely: missing or invalid LLM API key. Check your provider API key configu
 
 **No memories being recalled**
 - Check that `autoRecall.enabled` is `true` (it is by default)
-- Verify the graph has data: run `openclaw gralkor search <term>`
+- Verify the graph has data: run `openclaw gralkor search <group_id> <term>` (group ID = agent ID with hyphens replaced by underscores)
 - Auto-recall extracts keywords from the user's message — very short messages may not match
 
 **Agent doesn't store conversations**
@@ -457,31 +406,3 @@ Most likely: missing or invalid LLM API key. Check your provider API key configu
 - Conversations where the first user message starts with `/` are skipped by design
 - Empty conversations (no extractable text) are skipped
 
-**Agent doesn't have plugin tools (`memory_add`, `memory_build_indices`, etc.)**
-OpenClaw's tool profiles (`coding`, `minimal`, etc.) only allowlist core tools by default. Plugin tools are filtered out when a profile is active. To enable them, add them to `alsoAllow` in your `openclaw.json`:
-
-```json
-{
-  "tools": {
-    "alsoAllow": ["memory_add", "memory_build_indices", "memory_build_communities"]
-  }
-}
-```
-
-You can also allow all Gralkor tools with `"alsoAllow": ["gralkor"]` or all plugin tools with `"alsoAllow": ["group:plugins"]`. Note that `memory_add` is not required for Gralkor to work — auto-capture already stores everything your agent hears, says, thinks, and does. `memory_add` is only needed if you want the agent to selectively store specific insights or conclusions on its own.
-
-## Legacy Docker mode
-
-If you prefer to run FalkorDB as a separate Docker container (e.g. for production deployments with specific resource constraints), you can set `FALKORDB_URI` to bypass the embedded mode:
-
-```bash
-cd ~/.openclaw/plugins/gralkor
-docker build -t gralkor-server:latest server/
-FALKORDB_URI=redis://falkordb:6379 docker compose up -d
-```
-
-This starts FalkorDB on port 6379 and the Graphiti API on port 8001. If your OpenClaw gateway runs in Docker, connect it to the `gralkor` network:
-
-```bash
-docker network connect gralkor <your-openclaw-container-name>
-```

package/dist/server-env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-env.d.ts","sourceRoot":"","sources":["../src/server-env.ts"],"names":[],"mappings":"AAQA,KAAK,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAMrC,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,MAAM,CAWT"}
+{"version":3,"file":"server-env.d.ts","sourceRoot":"","sources":["../src/server-env.ts"],"names":[],"mappings":"AAQA,KAAK,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAMrC,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,MAAM,CAQT"}

package/dist/server-env.js

@@ -15,15 +15,12 @@ export function buildPipEnv(venvDir) {
     return { ...baseEnv(), VIRTUAL_ENV: venvDir };
 }
 export function buildSpawnEnv(opts) {
-    const env = {
+    return {
         ...baseEnv(),
         ...opts.extra,
         ...opts.secretEnv,
         FALKORDB_DATA_DIR: opts.falkordbDataDir,
         CONFIG_PATH: opts.configPath,
     };
-    // Absence of FALKORDB_URI triggers embedded FalkorDBLite mode.
-    delete env.FALKORDB_URI;
-    return env;
 }
 //# sourceMappingURL=server-env.js.map

package/dist/server-env.js.map

@@ -1 +1 @@
-{"version":3,"file":"server-env.js","sourceRoot":"","sources":["../src/server-env.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,EAAE;AACF,8EAA8E;AAC9E,6EAA6E;AAC7E,8EAA8E;AAC9E,yEAAyE;AACzE,yDAAyD;AAIzD,SAAS,OAAO;IACd,OAAO,EAAE,GAAI,OAAO,CAAC,GAAc,EAAE,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,EAAE,GAAG,OAAO,EAAE,EAAE,sBAAsB,EAAE,OAAO,EAAE,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO,EAAE,GAAG,OAAO,EAAE,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAK7B;IACC,MAAM,GAAG,GAAW;QAClB,GAAG,OAAO,EAAE;QACZ,GAAG,IAAI,CAAC,KAAK;QACb,GAAG,IAAI,CAAC,SAAS;QACjB,iBAAiB,EAAE,IAAI,CAAC,eAAe;QACvC,WAAW,EAAE,IAAI,CAAC,UAAU;KAC7B,CAAC;IACF,+DAA+D;IAC/D,OAAO,GAAG,CAAC,YAAY,CAAC;IACxB,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"server-env.js","sourceRoot":"","sources":["../src/server-env.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,EAAE;AACF,8EAA8E;AAC9E,6EAA6E;AAC7E,8EAA8E;AAC9E,yEAAyE;AACzE,yDAAyD;AAIzD,SAAS,OAAO;IACd,OAAO,EAAE,GAAI,OAAO,CAAC,GAAc,EAAE,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,EAAE,GAAG,OAAO,EAAE,EAAE,sBAAsB,EAAE,OAAO,EAAE,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO,EAAE,GAAG,OAAO,EAAE,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAK7B;IACC,OAAO;QACL,GAAG,OAAO,EAAE;QACZ,GAAG,IAAI,CAAC,KAAK;QACb,GAAG,IAAI,CAAC,SAAS;QACjB,iBAAiB,EAAE,IAAI,CAAC,eAAe;QACvC,WAAW,EAAE,IAAI,CAAC,UAAU;KAC7B,CAAC;AACJ,CAAC"}

package/openclaw.plugin.json

@@ -153,5 +153,5 @@
       "label": "Groq API key"
     }
   },
-  "version": "27.2.9"
+  "version": "27.2.11"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@susu-eng/gralkor",
   "displayName": "Gralkor",
-  "version": "27.2.9",
+  "version": "27.2.11",
   "description": "OpenClaw memory plugin powered by Graphiti knowledge graphs and FalkorDB",
   "type": "module",
   "main": "./dist/index.js",

package/server/main.py

@@ -204,32 +204,20 @@ async def lifespan(_app: FastAPI):
     global graphiti, ontology_entity_types, ontology_edge_types, ontology_edge_type_map
     cfg = _load_config()
 
-    falkordb_uri = os.getenv("FALKORDB_URI")
-
-    if falkordb_uri:
-        # Legacy Docker mode: external FalkorDB via TCP
-        stripped = falkordb_uri.split("://", 1)[-1]
-        if ":" in stripped:
-            host, port_str = stripped.rsplit(":", 1)
-            port = int(port_str)
-        else:
-            host, port = stripped, 6379
-        driver = FalkorDriver(host=host, port=port)
-    else:
-        # Default: embedded FalkorDBLite (no Docker needed)
-        logging.getLogger("redislite").setLevel(logging.DEBUG)
+    # Embedded FalkorDBLite (no Docker needed)
+    logging.getLogger("redislite").setLevel(logging.DEBUG)
 
-        from redislite.async_falkordb_client import AsyncFalkorDB
+    from redislite.async_falkordb_client import AsyncFalkorDB
 
-        data_dir = os.getenv("FALKORDB_DATA_DIR", "./data/falkordb")
-        os.makedirs(data_dir, exist_ok=True)
-        db_path = os.path.join(data_dir, "gralkor.db")
-        try:
-            db = AsyncFalkorDB(db_path)
-        except Exception as e:
-            _log_falkordblite_diagnostics(e)
-            raise
-        driver = FalkorDriver(falkor_db=db)
+    data_dir = os.getenv("FALKORDB_DATA_DIR", "./data/falkordb")
+    os.makedirs(data_dir, exist_ok=True)
+    db_path = os.path.join(data_dir, "gralkor.db")
+    try:
+        db = AsyncFalkorDB(db_path)
+    except Exception as e:
+        _log_falkordblite_diagnostics(e)
+        raise
+    driver = FalkorDriver(falkor_db=db)
 
     graphiti = Graphiti(
         graph_driver=driver,

package/docker-compose.yml

@@ -1,34 +0,0 @@
-services:
-  falkordb:
-    image: falkordb/falkordb:latest
-    restart: unless-stopped
-    ports:
-      - "6379:6379"
-      - "3000:3000"
-    volumes:
-      - ${FALKORDB_DATA_DIR:-falkordb_data}:/var/lib/falkordb/data
-    networks:
-      - gralkor
-
-  graphiti:
-    image: gralkor-server:latest
-    restart: unless-stopped
-    ports:
-      - "8001:8001"
-    env_file:
-      - .env
-    environment:
-      FALKORDB_URI: redis://falkordb:6379
-    volumes:
-      - ./config.yaml:/app/config.yaml:ro
-    depends_on:
-      - falkordb
-    networks:
-      - gralkor
-
-networks:
-  gralkor:
-    name: gralkor
-
-volumes:
-  falkordb_data:

package/server/Dockerfile

@@ -1,7 +0,0 @@
-FROM python:3.12-slim
-WORKDIR /app
-COPY requirements.txt .
-RUN pip install --no-cache-dir -r requirements.txt
-COPY main.py .
-EXPOSE 8001
-CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8001"]