@susu-eng/gralkor 27.2.0 → 27.2.3

package/README.md

@@ -1,15 +1,13 @@
 # Gralkor
 
-**Persistent memory for OpenClaw agents, powered by knowledge graphs.**
+**The best memory plugin for OpenClaw agents**
 
-Gralkor is an OpenClaw plugin that gives your agents long-term, temporally-aware memory. It uses [Graphiti](https://github.com/getzep/graphiti) (by Zep) for knowledge graph construction and [FalkorDB](https://www.falkordb.com/) as the graph database backend. Both run automatically as a managed subprocess — no Docker required.
+Gralkor is an OpenClaw plugin that gives your agents long-term, temporally-aware memory. It uses [Graphiti](https://github.com/getzep/graphiti) (by Zep) for knowledge graph construction and [FalkorDB](https://www.falkordb.com/) as the graph database backend. Both run automatically as a managed subprocess - no independent server for you to manage, or SaaS company to connect to.
 
-Gralkor automatically remembers and recalls everything your agents says, _thinks_, and _does_ — no prompt engineering required by the operator, no conscious (haha) effort required by the agent.
+Gralkor automatically remembers and recalls everything your agent says, _thinks_, and _does_ — no prompt engineering required by the operator, no conscious (haha) effort required by the agent.
 
 ## Why Gralkor
 
-After years of building with every AI memory system out there, reading the latest research daily, and doing my own cognitive architecture experiments, I am here to tell you a thing or two about AI memory, and why you should use Gralkor for your OpenClaw agents and forget everything else. I should say up front: I love this space and have enormous respect for everyone shipping in it — what follows is honest craft critique, not shade.
-
 Here's the honest field report on every OpenClaw memory plugin:
 
 | Plugin | Storage | Captures thinking | Episode scope | Temporal facts | Local |
@@ -23,32 +21,19 @@ Here's the honest field report on every OpenClaw memory plugin:
 | **Awareness** | Cloud + MD mirror | no | first message + last reply | none | ✗ |
 | **Gralkor** | Graphiti knowledge graph | **yes** | full session | `valid_at`/`invalid_at`/`expired_at` | ✓ |
 
-**Graphs, not Markdown or pure vector.** The AI ecosystem's fixation on Markdown-based memory is baffling. Graphs have been the right data structure for representing knowledge since long before LLMs existed. Your code is a graph (syntax trees). Your filesystem is a graph. The web is a graph. Relationships between entities are naturally graph-shaped, and trying to flatten them into Markdown files or pure vector embeddings is fighting reality. And 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. Both make recall a lookup problem when it should be a traversal problem. [Graphiti](https://github.com/getzep/graphiti) combines a knowledge graph with vector search — 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 yet another chunking strategy or embedding experiment. Graphiti has solved this layer of the problem and we build on top of it (and not much). [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.** When your agent reasons through a problem — weighing options, rejecting approaches, arriving at a conclusion — that thinking process is as valuable as the final answer. Gralkor distills the agent's thinking blocks 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. *Fighting words*: 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. Gralkor actually remembers what your agent thought and did — it is the only OpenClaw memory plugin with this capability. [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.
-
-**On cost.** Yes, Gralkor costs more to run than a Markdown file. Behaviour distillation adds roughly 20% to ingestion token cost. Auto-recall adds an LLM call before each turn when results need interpretation.
+Let's look in detail about the decisions made for Gralkor and why they make it the best memory plugin for OpenClaw.
 
-Think of it as better context management, not overhead. However you handle long sessions — growing context windows, compaction, summarization — you're paying on every read. Gralkor pays once on write to extract and structure what matters, then pulls only the right stuff at read time.
+**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. [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.
 
-And the leverage is real. 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 doesn't just save time; it changes the character of the work. You stop spending turns re-establishing context and start doing the actual work you opened the terminal for.
+**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. 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. Gralkor actually remembers what your agent thought and did — it is the only OpenClaw memory plugin with this capability. [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.
 
-Paying $15–20/month in API costs to make your agent meaningfully smarter across sessions is not a place to save money. The agents that cost you real money are the ones that forget everything and make you start over.
+**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. It's also 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 doesn't just save time; it changes the character of the work. You stop spending turns re-establishing context and start doing the actual work you opened the terminal for. Paying $15–20/month in API costs to make your agent meaningfully smarter across sessions is a good investment for anybody doing real work. The agents that cost you real money are the ones that forget everything and make you start over.
 
-**Maximum context at ingestion.** 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. Supermemory and MemOS Cloud default to the last turn only. 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 rather fragmented QA pairs. *Fighting words*: Other plugins capture single turns of dialog; we capture _the whole episode_ — the entire series of questions, thoughts, actions, and responses that _solved the problem_. 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.
+**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. Supermemory and MemOS Cloud default to the last turn only. Other plugins capture single turns of dialog; we capture _the whole episode_ — the entire series of questions, thoughts, actions, and responses that _solved the problem_. 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_. lancedb-pro has something in this direction — an `invalidated_at` timestamp on vector rows, genuinely good — but graph edges are not vector rows: Graphiti tracks four timestamps per fact (`created_at`, `valid_at`, `invalid_at`, `expired_at`) 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. [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.
+**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_. lancedb-pro has something in this direction — an `invalidated_at` timestamp on vector rows, but there's no graph. Graphiti tracks four timestamps per fact (`created_at`, `valid_at`, `invalid_at`, `expired_at`) 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. [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. The most powerful thing you can do with it is point the 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. Instead, it provides the platform for cognitive architecture experimentation: a structured, temporally-aware graph that the agent can both read from and write to using OpenClaw crons.
-
-```bash
-# Example: schedule the agent to reflect on its memory every 6 hours
-openclaw cron add --every 6h --prompt "Search your memory for recent facts. \
-Look for contradictions, outdated information, or patterns worth consolidating. \
-Use memory_add to store any new insights."
-```
-
-This is where it gets interesting. The graph gives you a substrate for experimentation — reflection strategies, knowledge consolidation, cross-session reasoning — that flat retrieval systems simply cannot support. [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.
+**Recursion through reflection.** A knowledge graph is a living structure. The most powerful thing you can do with it is point the 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. Instead, it provides the platform for cognitive architecture experimentation: a structured, temporally-aware graph that the agent can both read from and write to using OpenClaw crons. Share yours, and ask to see mine. This is where it gets interesting. The graph gives you a substrate for experimentation — reflection strategies, knowledge consolidation, cross-session reasoning — that flat retrieval systems simply cannot support. [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 the language of your domain — or your life. [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. No other OpenClaw memory plugin offers this. If you want extraction to speak your domain's language: lancedb-pro has six hardcoded categories you can filter but not extend; Supermemory lets you write a free-text hint to guide extraction; the rest offer nothing. Custom ontologies give your agent a model of the world: you could use a domain model codified by experts, be the expert, or try to encode _your_ model of the world. Agent memory doesn't have to be so fuzzy that you lose track of what matters.
 
@@ -56,7 +41,7 @@ This is where it gets interesting. The graph gives you a substrate for experimen
 
 Gralkor replaces the native memory plugin entirely, taking the memory slot.
 
-- **`memory_search`** — searches the knowledge graph and returns relevant facts
+- **`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
 - **`memory_build_indices`** — rebuilds search indices and constraints (maintenance)
 - **`memory_build_communities`** — detects and builds entity communities/clusters to improve search quality (maintenance)
@@ -93,13 +78,7 @@ openclaw config set plugins.entries.gralkor.config.test true
 ### 3. Install the plugin
 
 ```bash
-openclaw plugins install @susu-eng/gralkor
-```
-
-OpenClaw checks ClawHub before npm for bare package specs, so this installs from ClawHub automatically. To be explicit:
-
-```bash
-openclaw plugins install clawhub:@susu-eng/gralkor
+openclaw plugins install npm:@susu-eng/gralkor
 ```
 
 From a tarball (e.g. for air-gapped deploys):
@@ -137,26 +116,24 @@ Start chatting with your agent. Gralkor works in the background:
 - **Auto-capture**: Full multi-turn conversations are stored in the knowledge graph after each agent run
 - **Auto-recall**: Before the agent responds, relevant facts and entities are retrieved and injected as context
 
-### Reinstalling / upgrading
-
-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.
-
-To reinstall:
+### Upgrading
 
 ```bash
-# Clear the memory slot first (otherwise install fails config validation)
-openclaw config set plugins.slots.memory ""
+openclaw plugins update gralkor
+```
 
-# Remove old plugin code
-rm -rf ~/.openclaw/extensions/gralkor
+### Reinstalling
 
-# Reinstall
-openclaw plugins install @susu-eng/gralkor
+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.
 
-# Re-assign slot
+```bash
+openclaw plugins uninstall gralkor
+openclaw plugins install npm:@susu-eng/gralkor
 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

package/openclaw.plugin.json

@@ -153,5 +153,5 @@
       "label": "Groq API key"
     }
   },
-  "version": "27.2.0"
+  "version": "27.2.3"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@susu-eng/gralkor",
-  "version": "27.2.0",
+  "version": "27.2.3",
   "description": "OpenClaw memory plugin powered by Graphiti knowledge graphs and FalkorDB",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,11 +24,11 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/susu-eng/gralkor.git"
+    "url": "git+ssh://git@github.com/elimydlarz/gralkor.git"
   },
-  "homepage": "https://github.com/susu-eng/gralkor#readme",
+  "homepage": "https://github.com/elimydlarz/gralkor#readme",
   "bugs": {
-    "url": "https://github.com/susu-eng/gralkor/issues"
+    "url": "https://github.com/elimydlarz/gralkor/issues"
   },
   "author": "susu-eng",
   "keywords": [
@@ -75,7 +75,8 @@
     "docker:up": "pnpm run docker:build && docker compose up -d",
     "docker:down": "docker compose down",
     "docker:logs": "docker compose logs graphiti",
-    "publish:npm": "bash scripts/publish.sh",
-    "publish:clawhub": "bash scripts/publish-clawhub.sh"
+    "publish:npm": "bash scripts/publish-npm.sh",
+    "publish:clawhub": "bash scripts/publish-clawhub.sh",
+    "publish:all": "bash scripts/publish-all.sh"
   }
 }

package/server/main.py

@@ -287,6 +287,42 @@ def _find_rate_limit_error(exc: Exception) -> Exception | None:
     return None
 
 
+_CREDENTIAL_HINTS = ("api key", "apikey", "credential", "authentication", "expired", "unauthorized")
+
+
+def _downstream_llm_response(exc: Exception) -> JSONResponse:
+    """Map a downstream LLM provider error to an appropriate HTTP response."""
+    http_code = int(getattr(exc, "status_code", None) or getattr(exc, "code", None))
+    msg = str(exc).split("\n")[0][:200]
+
+    if 400 <= http_code < 500:
+        if http_code == 400:
+            status = 503 if any(h in msg.lower() for h in _CREDENTIAL_HINTS) else 500
+        elif http_code in (401, 403):
+            status = 503
+        elif http_code in (404, 422):
+            status = 500
+        else:
+            status = 502
+    else:
+        status = 502
+
+    return JSONResponse(status_code=status, content={"error": "provider error", "detail": msg})
+
+
+def _find_downstream_llm_error(exc: Exception) -> Exception | None:
+    """Walk the exception chain to find a downstream LLM provider error with an HTTP status code."""
+    current: Exception | None = exc
+    seen: set[int] = set()
+    while current is not None and id(current) not in seen:
+        seen.add(id(current))
+        http_code = getattr(current, "status_code", None) or getattr(current, "code", None)
+        if http_code is not None and int(http_code) != 429:
+            return current
+        current = current.__cause__ or current.__context__
+    return None
+
+
 _DEFAULT_RETRY_AFTER = 5  # seconds
 
 
@@ -306,6 +342,9 @@ async def rate_limit_middleware(request, call_next):
                 content={"detail": msg},
                 headers={"retry-after": str(int(retry_after))},
             )
+        llm_err = _find_downstream_llm_error(exc)
+        if llm_err is not None:
+            return _downstream_llm_response(llm_err)
         raise