@susu-eng/gralkor 27.2.15 → 27.3.0

package/README.md

@@ -65,6 +65,23 @@ Gralkor is _good_ memory, not cheap memory. You can push the llm choice and perh
 - Hooks: auto-capture (stores full multi-turn conversations after each agent run), auto-recall (injects relevant facts before the agent responds)
 - Set up: `plugins.slots.memory = "gralkor"` in `openclaw.json`
 
+## Using Gralkor from Elixir / Jido
+
+Gralkor is primarily an OpenClaw plugin, but the Python server exposes a harness-agnostic HTTP API. The Elixir package in `ex/` — published as [`:gralkor` on Hex](https://hex.pm/packages/gralkor) — wraps it: supervises the Python server, exposes a `Gralkor.Client` port with HTTP and in-memory adapters, ships a boot-readiness gate, and auto-recovers from orphaned uvicorn processes on dev reboot.
+
+**For Jido agents**, use [`:jido_gralkor`](https://hex.pm/packages/jido_gralkor) — it pulls `:gralkor` transitively and adds three modules (a plugin + two ReAct tools) that turn the Client port into transparent long-term memory on your agent. That package's README is the Jido-dev entry point; it covers the full wiring recipe.
+
+**For any Elixir app** (non-Jido), see [`ex/README.md`](./ex/README.md) — how to supervise the server, gate your boot on readiness, and call `Gralkor.Client.impl/0` from your own code.
+
+**HTTP endpoints** (unauthenticated — loopback-only; consumer supervises the server):
+
+- `POST /recall` — before-prompt auto-recall
+- `POST /capture` — fire-and-forget turn capture (server buffers, distils, ingests on idle)
+- `POST /session_end` — flush the session's buffer now (fire-and-forget; 204 before the graph write); for consumers that know when a session is over
+- `POST /tools/memory_search`, `POST /tools/memory_add` — consumer-facing tools
+- `POST /distill` — standalone distillation (for clients that want raw distill access)
+- Existing: `POST /episodes`, `POST /search`, `GET /health`
+
 ## Quick Start
 
 ### 1. Prerequisites

package/openclaw.plugin.json

@@ -153,5 +153,5 @@
       "label": "Groq API key"
     }
   },
-  "version": "27.2.15"
+  "version": "27.3.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@susu-eng/gralkor",
   "displayName": "Gralkor",
-  "version": "27.2.15",
+  "version": "27.3.0",
   "description": "OpenClaw memory plugin powered by Graphiti knowledge graphs and FalkorDB",
   "type": "module",
   "main": "./dist/index.js",
@@ -85,6 +85,7 @@
     "pack": "bash scripts/pack.sh",
     "publish:npm": "bash scripts/publish-npm.sh",
     "publish:clawhub": "bash scripts/publish-clawhub.sh",
+    "publish:hex": "bash scripts/publish-hex.sh",
     "publish:all": "bash scripts/publish-all.sh"
   }
 }

package/server/main.py

@@ -11,11 +11,19 @@ from copy import deepcopy
 from datetime import datetime, timezone
 from typing import Any, Literal
 
+import uuid
+
 import yaml
-from fastapi import FastAPI
+from fastapi import APIRouter, FastAPI, HTTPException, Response, status
 from fastapi.responses import JSONResponse
 from pydantic import BaseModel, Field, create_model
 
+from pipelines.capture_buffer import CaptureBuffer, CaptureClientError, turns_to_conversation
+from pipelines.distill import Turn, format_transcript
+from pipelines.formatting import format_fact, format_node
+from pipelines.interpret import interpret_facts
+from pipelines.message_clean import ConversationMessage
+
 
 
 from graphiti_core import Graphiti
@@ -37,9 +45,17 @@ def _load_config() -> dict:
     return {}
 
 
+DEFAULT_LLM_PROVIDER = "gemini"
+DEFAULT_LLM_MODEL = "gemini-3.1-flash-lite-preview"
+DEFAULT_EMBEDDER_PROVIDER = "gemini"
+DEFAULT_EMBEDDER_MODEL = "gemini-embedding-2-preview"
+
+
 def _build_llm_client(cfg: dict):
-    provider = cfg.get("llm", {}).get("provider", "gemini")
-    model = cfg.get("llm", {}).get("model")
+    provider = cfg.get("llm", {}).get("provider") or DEFAULT_LLM_PROVIDER
+    model = cfg.get("llm", {}).get("model") or (
+        DEFAULT_LLM_MODEL if provider == DEFAULT_LLM_PROVIDER else None
+    )
     llm_cfg = LLMConfig(model=model) if model else None
 
     if provider == "anthropic":
@@ -62,8 +78,10 @@ def _build_llm_client(cfg: dict):
 
 
 def _build_embedder(cfg: dict):
-    provider = cfg.get("embedder", {}).get("provider", "gemini")
-    model = cfg.get("embedder", {}).get("model")
+    provider = cfg.get("embedder", {}).get("provider") or DEFAULT_EMBEDDER_PROVIDER
+    model = cfg.get("embedder", {}).get("model") or (
+        DEFAULT_EMBEDDER_MODEL if provider == DEFAULT_EMBEDDER_PROVIDER else None
+    )
 
     if provider == "gemini":
         from graphiti_core.embedder.gemini import GeminiEmbedder, GeminiEmbedderConfig
@@ -259,7 +277,13 @@ async def lifespan(_app: FastAPI):
         edge_names = list(ontology_edge_types or {})
         print(f"[gralkor] ontology: entities={entity_names} edges={edge_names}", flush=True)
 
+    global capture_buffer
+    idle_seconds = float(cfg.get("capture", {}).get("idle_seconds", CAPTURE_IDLE_SECONDS_DEFAULT))
+    capture_buffer = CaptureBuffer(idle_seconds=idle_seconds, flush_callback=_capture_flush)
+
     yield
+
+    await capture_buffer.flush_all()
     await graphiti.close()
 
 
@@ -345,6 +369,40 @@ async def rate_limit_middleware(request, call_next):
         raise
 
 
+# ── Auth ─────────────────────────────────────────────────────
+
+
+# ── Capture buffer ───────────────────────────────────────────
+
+CAPTURE_IDLE_SECONDS_DEFAULT = 300.0
+capture_buffer: CaptureBuffer | None = None
+
+
+async def _capture_flush(group_id: str, turns: list[Turn]) -> None:
+    if graphiti is None:
+        return
+    t0 = time.monotonic()
+    episode_body = await format_transcript(turns, graphiti.llm_client)
+    if not episode_body.strip():
+        return
+    logger.debug("[gralkor] [test] capture flush body: %s", episode_body)
+    async with _driver_lock:
+        result = await graphiti.add_episode(
+            name=f"conversation-{int(time.time() * 1000)}",
+            episode_body=episode_body,
+            source_description="auto-capture",
+            group_id=_sanitize_group_id(group_id),
+            reference_time=datetime.now(timezone.utc),
+            source=EpisodeType.message,
+            entity_types=ontology_entity_types,
+            edge_types=ontology_edge_types,
+            edge_type_map=ontology_edge_type_map,
+        )
+    duration_ms = (time.monotonic() - t0) * 1000
+    logger.info("[gralkor] capture flushed — group:%s uuid:%s bodyChars:%d %.0fms",
+                group_id, result.episode.uuid, len(episode_body), duration_ms)
+
+
 # ── Idempotency store ────────────────────────────────────────
 
 # In-memory store: idempotency_key -> serialized_episode
@@ -385,6 +443,63 @@ class GroupIdRequest(BaseModel):
     group_id: str
 
 
+class RecallRequest(BaseModel):
+    session_id: str
+    group_id: str
+    query: str
+    max_results: int = 10
+
+
+class RecallResponse(BaseModel):
+    memory_block: str
+
+
+class TurnBody(BaseModel):
+    user_query: str
+    events: list[Any] = Field(default_factory=list)
+    assistant_answer: str
+
+
+class DistillRequest(BaseModel):
+    turns: list[TurnBody]
+
+
+class DistillResponse(BaseModel):
+    episode_body: str
+
+
+class CaptureRequest(BaseModel):
+    session_id: str
+    group_id: str
+    turn: TurnBody
+
+
+class SessionEndRequest(BaseModel):
+    session_id: str = Field(min_length=1)
+
+
+class MemorySearchRequest(BaseModel):
+    session_id: str
+    group_id: str
+    query: str
+    max_results: int = 20
+    max_entity_results: int = 10
+
+
+class MemorySearchResponse(BaseModel):
+    text: str
+
+
+class MemoryAddRequest(BaseModel):
+    group_id: str
+    content: str
+    source_description: str = "manual"
+
+
+class MemoryAddResponse(BaseModel):
+    status: Literal["stored"]
+
+
 # ── Serializers ───────────────────────────────────────────────
 
 
@@ -431,7 +546,37 @@ def _serialize_episode(ep: EpisodicNode) -> dict[str, Any]:
 logger = logging.getLogger(__name__)
 
 
-@app.get("/health")
+router = APIRouter()
+
+
+def _turn_body_to_turn(body: TurnBody) -> Turn:
+    return Turn(
+        user_query=body.user_query,
+        events=list(body.events),
+        assistant_answer=body.assistant_answer,
+    )
+
+
+def _elide_tokens(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {k: "[...]" if k == "token" else _elide_tokens(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_elide_tokens(v) for v in value]
+    return value
+
+
+def _conversation_for_session(session_id: str) -> list[ConversationMessage]:
+    if capture_buffer is None:
+        return []
+    return turns_to_conversation(capture_buffer.turns_for(session_id))
+
+
+FURTHER_QUERYING_INSTRUCTION = (
+    "Search memory (up to 3 times, diverse queries) if you need more detail."
+)
+
+
+@router.get("/health")
 async def health():
     result: dict = {"status": "ok"}
 
@@ -460,23 +605,18 @@ async def health():
     return result
 
 
-@app.post("/episodes")
+@router.post("/episodes")
 async def add_episode(req: AddEpisodeRequest):
     cached = _idempotency_check(req.idempotency_key)
     if cached is not None:
-        logger.info("[gralkor] add-episode idempotent hit — key:%s uuid:%s",
-                    req.idempotency_key, cached.get("uuid"))
         return cached
 
-    logger.info("[gralkor] add-episode — group:%s name:%s bodyChars:%d source:%s",
-                req.group_id, req.name, len(req.episode_body), req.source or "message")
     ref_time = (
         datetime.fromisoformat(req.reference_time)
         if req.reference_time
         else datetime.now(timezone.utc)
     )
     episode_type = EpisodeType(req.source) if req.source else EpisodeType.message
-    t0 = time.monotonic()
     async with _driver_lock:
         result = await graphiti.add_episode(
             name=req.name,
@@ -490,10 +630,7 @@ async def add_episode(req: AddEpisodeRequest):
             edge_type_map=ontology_edge_type_map,
             excluded_entity_types=None,
         )
-    duration_ms = (time.monotonic() - t0) * 1000
     episode = result.episode
-    logger.info("[gralkor] episode added — uuid:%s duration:%.0fms", episode.uuid, duration_ms)
-    logger.debug("[gralkor] episode result: %s", _serialize_episode(episode))
     serialized = _serialize_episode(episode)
     _idempotency_store_result(req.idempotency_key, serialized)
     return serialized
@@ -535,7 +672,6 @@ def _ensure_driver_graph(group_ids: list[str] | None) -> None:
         try:
             graphiti.driver = graphiti.driver.clone(database=target)
             graphiti.clients.driver = graphiti.driver
-            print(f"[gralkor] driver graph routed: {target}", flush=True)
         except Exception as e:
             # Invalid group_id (e.g. hyphens rejected by FalkorDB).  Skip routing
             # so the search runs against the current graph and returns empty results
@@ -543,12 +679,10 @@ def _ensure_driver_graph(group_ids: list[str] | None) -> None:
             logger.warning("[gralkor] driver graph routing failed for %s: %s", target, e)
 
 
-@app.post("/search")
+@router.post("/search")
 async def search(req: SearchRequest):
     # Sanitize group IDs: hyphens cause RediSearch syntax errors in graphiti-core.
     sanitized = [_sanitize_group_id(g) for g in req.group_ids]
-    logger.info("[gralkor] search — mode:%s query:%d chars group_ids:%s num_results:%d",
-                req.mode, len(req.query), sanitized, req.num_results)
     # graphiti.add_episode() clones the driver to target the correct FalkorDB
     # named graph (database=group_id), but graphiti.search() does not — it just
     # uses whatever graph the driver currently points at. Before the first
@@ -582,23 +716,19 @@ async def search(req: SearchRequest):
         duration_ms = (time.monotonic() - t0) * 1000
         logger.error("[gralkor] search failed — mode:%s %.0fms: %s", req.mode, duration_ms, e)
         raise
-    duration_ms = (time.monotonic() - t0) * 1000
     result = [_serialize_fact(e) for e in edges]
     serialized_nodes = [_serialize_node(n) for n in nodes]
-    logger.info("[gralkor] search result — mode:%s %d facts %d nodes %.0fms",
-                req.mode, len(result), len(serialized_nodes), duration_ms)
-    logger.debug("[gralkor] search facts: %s", result)
     return {"facts": result, "nodes": serialized_nodes}
 
 
 
-@app.post("/build-indices")
+@router.post("/build-indices")
 async def build_indices():
     await graphiti.build_indices_and_constraints()
     return {"status": "ok"}
 
 
-@app.post("/build-communities")
+@router.post("/build-communities")
 async def build_communities(req: GroupIdRequest):
     gid = _sanitize_group_id(req.group_id)
     async with _driver_lock:
@@ -607,3 +737,137 @@ async def build_communities(req: GroupIdRequest):
             group_ids=[gid],
         )
     return {"communities": len(communities), "edges": len(edges)}
+
+
+# ── New endpoints ────────────────────────────────────────────
+
+
+@router.post("/recall", response_model=RecallResponse)
+async def recall(req: RecallRequest) -> RecallResponse:
+    sanitized = _sanitize_group_id(req.group_id)
+    conversation = _conversation_for_session(req.session_id)
+    logger.info("[gralkor] recall — session:%s group:%s queryChars:%d max:%d",
+                req.session_id, sanitized, len(req.query), req.max_results)
+    logger.debug("[gralkor] [test] recall query: %s", req.query)
+    t0 = time.monotonic()
+
+    async with _driver_lock:
+        _ensure_driver_graph([sanitized])
+        edges = await graphiti.search(
+            query=_sanitize_query(req.query),
+            group_ids=[sanitized],
+            num_results=req.max_results,
+        )
+
+    facts = [_serialize_fact(e) for e in edges]
+    if not facts:
+        logger.info("[gralkor] recall result — 0 facts %.0fms",
+                    (time.monotonic() - t0) * 1000)
+        return RecallResponse(memory_block="")
+
+    facts_text = "\n".join(format_fact(f) for f in facts)
+    interpretation = await interpret_facts(conversation, facts_text, graphiti.llm_client)
+
+    block = (
+        '<gralkor-memory trust="untrusted">\n'
+        f"Facts:\n{facts_text}\n\n"
+        f"Interpretation:\n{interpretation}\n\n"
+        f"{FURTHER_QUERYING_INSTRUCTION}\n"
+        "</gralkor-memory>"
+    )
+    duration_ms = (time.monotonic() - t0) * 1000
+    logger.info("[gralkor] recall result — %d facts blockChars:%d %.0fms",
+                len(facts), len(block), duration_ms)
+    logger.debug("[gralkor] [test] recall block: %s", block)
+    return RecallResponse(memory_block=block)
+
+
+@router.post("/distill", response_model=DistillResponse)
+async def distill(req: DistillRequest) -> DistillResponse:
+    turns = [_turn_body_to_turn(t) for t in req.turns]
+    episode_body = await format_transcript(turns, graphiti.llm_client if graphiti else None)
+    return DistillResponse(episode_body=episode_body)
+
+
+@router.post("/capture", status_code=status.HTTP_204_NO_CONTENT)
+async def capture(req: CaptureRequest) -> Response:
+    if capture_buffer is None:
+        raise HTTPException(status.HTTP_503_SERVICE_UNAVAILABLE, "capture buffer not initialized")
+    sanitized = _sanitize_group_id(req.group_id)
+    turn = _turn_body_to_turn(req.turn)
+    capture_buffer.append(req.session_id, sanitized, turn)
+    logger.debug("[gralkor] [test] capture turn: user_query=%s events=%s assistant_answer=%s",
+                 turn.user_query, _elide_tokens(turn.events), turn.assistant_answer)
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+@router.post("/session_end", status_code=status.HTTP_204_NO_CONTENT)
+async def session_end(req: SessionEndRequest) -> Response:
+    if capture_buffer is None:
+        raise HTTPException(status.HTTP_503_SERVICE_UNAVAILABLE, "capture buffer not initialized")
+    turns = len(capture_buffer.turns_for(req.session_id))
+    capture_buffer.flush(req.session_id)
+    logger.info("[gralkor] session_end session:%s turns:%d", req.session_id, turns)
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+@router.post("/tools/memory_search", response_model=MemorySearchResponse)
+async def tools_memory_search(req: MemorySearchRequest) -> MemorySearchResponse:
+    sanitized = _sanitize_group_id(req.group_id)
+    conversation = _conversation_for_session(req.session_id)
+    logger.info("[gralkor] tools.memory_search — session:%s group:%s queryChars:%d max:%d/%d",
+                req.session_id, sanitized, len(req.query), req.max_results, req.max_entity_results)
+    logger.debug("[gralkor] [test] tools.memory_search query: %s", req.query)
+    t0 = time.monotonic()
+
+    async with _driver_lock:
+        _ensure_driver_graph([sanitized])
+        config = deepcopy(COMBINED_HYBRID_SEARCH_CROSS_ENCODER)
+        config.limit = req.max_results
+        search_result = await graphiti.search_(
+            query=_sanitize_query(req.query),
+            group_ids=[sanitized],
+            config=config,
+        )
+
+    facts = [_serialize_fact(e) for e in search_result.edges]
+    nodes = [_serialize_node(n) for n in search_result.nodes[: req.max_entity_results]]
+
+    if not facts and not nodes:
+        logger.info("[gralkor] tools.memory_search result — 0 facts 0 entities %.0fms",
+                    (time.monotonic() - t0) * 1000)
+        return MemorySearchResponse(text="Facts: (none)\nEntities: (none)")
+
+    facts_section = "Facts:\n" + ("\n".join(format_fact(f) for f in facts) if facts else "(none)")
+    entities_section = "Entities:\n" + (
+        "\n".join(format_node(n) for n in nodes) if nodes else "(none)"
+    )
+    facts_text = facts_section + "\n\n" + entities_section
+    interpretation = await interpret_facts(conversation, facts_text, graphiti.llm_client)
+    text = f"{facts_text}\n\nInterpretation:\n{interpretation}"
+    duration_ms = (time.monotonic() - t0) * 1000
+    logger.info("[gralkor] tools.memory_search result — %d facts %d entities textChars:%d %.0fms",
+                len(facts), len(nodes), len(text), duration_ms)
+    logger.debug("[gralkor] [test] tools.memory_search text: %s", text)
+    return MemorySearchResponse(text=text)
+
+
+@router.post("/tools/memory_add", response_model=MemoryAddResponse)
+async def tools_memory_add(req: MemoryAddRequest) -> MemoryAddResponse:
+    sanitized = _sanitize_group_id(req.group_id)
+    async with _driver_lock:
+        await graphiti.add_episode(
+            name=f"manual-add-{int(time.time() * 1000)}",
+            episode_body=req.content,
+            source_description=req.source_description,
+            group_id=sanitized,
+            reference_time=datetime.now(timezone.utc),
+            source=EpisodeType.text,
+            entity_types=ontology_entity_types,
+            edge_types=ontology_edge_types,
+            edge_type_map=ontology_edge_type_map,
+        )
+    return MemoryAddResponse(status="stored")
+
+
+app.include_router(router)