cilow 0.1.0__py3-none-any.whl

cilow/__init__.py

@@ -0,0 +1,116 @@
+"""cilow — Python client for Cilow, the verifiable context layer for AI agents.
+
+Point it at a running ``cilow-serve`` and call the FOUR core verbs (the MCP core profile):
+``ingest`` (the one write door: facts | text | bytes | url), ``context_pack`` (the product read:
+injectible pack + citations with ``is_current`` + ``abstained`` / ``grounding`` / ``trace_id``),
+``forget`` (withdraw), and ``explain`` (why a read surfaced what it surfaced, via ``trace_id``).
+``remember`` / ``recall`` / ``answer`` / ``timeline`` / ``track_entity`` remain as full-profile /
+legacy aliases. The headline feature is CALIBRATED ABSTENTION: reads return ``abstained=True``
+when the engine does not know, instead of fabricating. Gate your agent on that flag.
+
+    from cilow import CilowClient
+
+    cilow = CilowClient(base_url="http://localhost:8080", token="demo")
+    cilow.ingest(facts=[{"subject": "Maya", "predicate": "employer", "object": "Acme"}])
+    r = cilow.context_pack("where does Maya work", anchor="Maya", attribute="employer")
+    print(r.reason if r.abstained else r.pack)
+    why = cilow.explain(r.trace_id)  # cited claims + grounding vs the tenant threshold
+"""
+
+from .client import CilowClient, ingest_source_id, now_micros
+from .errors import CilowError
+from .types import (
+    AnswerResponse,
+    Branch,
+    Citation,
+    CitationPart,
+    Claim,
+    ConsolidateResponse,
+    Fact,
+    FeedbackResponse,
+    ContextPackResponse,
+    ExplainCited,
+    ExplainReport,
+    ExplainResponse,
+    ForgetResponse,
+    ForkResponse,
+    IngestAnyResponse,
+    IngestResponse,
+    IngestAudioResponse,
+    IngestImageResponse,
+    IngestPdfResponse,
+    IngestStructuredResponse,
+    Outcome,
+    ReaderUsage,
+    ReasonCode,
+    TerminalLayer,
+    TERMINAL_LAYERS,
+    Evidence,
+    EvidenceStructure,
+    EvidenceProvenance,
+    Receipt,
+    RecallResponse,
+    RememberResponse,
+    RememberTextResponse,
+    Scope,
+    Source,
+    TimelineEntry,
+    TrackEntityResponse,
+    Workspace,
+    EvidenceRevision,
+    ContextProgram,
+    ContextProgramV2,
+    ContextTrace,
+    MemoryProposal,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CilowClient",
+    "CilowError",
+    "now_micros",
+    "ingest_source_id",
+    "Scope",
+    "Fact",
+    "Source",
+    "RememberResponse",
+    "Claim",
+    "Receipt",
+    "RecallResponse",
+    "Citation",
+    "CitationPart",
+    "AnswerResponse",
+    "ReaderUsage",
+    "ReasonCode",
+    "TerminalLayer",
+    "TERMINAL_LAYERS",
+    "Evidence",
+    "EvidenceStructure",
+    "EvidenceProvenance",
+    "TimelineEntry",
+    "TrackEntityResponse",
+    "Outcome",
+    "FeedbackResponse",
+    "ConsolidateResponse",
+    "RememberTextResponse",
+    "IngestImageResponse",
+    "IngestAudioResponse",
+    "IngestPdfResponse",
+    "IngestStructuredResponse",
+    "IngestAnyResponse",
+    "ForgetResponse",
+    "ContextPackResponse",
+    "IngestResponse",
+    "ExplainResponse",
+    "ExplainReport",
+    "ExplainCited",
+    "Branch",
+    "ForkResponse",
+    "Workspace",
+    "EvidenceRevision",
+    "ContextProgram",
+    "ContextProgramV2",
+    "ContextTrace",
+    "MemoryProposal",
+]

cilow/adapters/__init__.py

@@ -0,0 +1,37 @@
+"""``cilow.adapters`` — framework bindings over the ONE :class:`CilowMemory` contract.
+
+Every binding is a thin shim that maps a framework's memory/retriever/tool interface onto the five
+contract verbs (``ingest`` / ``recall`` / ``answer`` / ``reset`` / ``health``) and re-exposes the
+differentiator unchanged: ``abstained`` + ``reason_code`` + the ``grounded`` signal.
+
+    from cilow.adapters import CilowMemoryClient
+    from cilow.adapters import openai, anthropic, langchain
+
+Branch on an adapter result's ``.is_calibrated_abstain`` / ``.is_infrastructure_abstain`` properties.
+"""
+
+from . import anthropic, langchain, openai
+from .memory import (
+    AnswerResult,
+    CilowMemory,
+    CilowMemoryClient,
+    IngestResult,
+    MemoryHit,
+    RecallResult,
+)
+from .remaining import REMAINING_ADAPTERS, make_autogen_memory, make_llamaindex_retriever
+
+__all__ = [
+    "CilowMemory",
+    "CilowMemoryClient",
+    "MemoryHit",
+    "RecallResult",
+    "AnswerResult",
+    "IngestResult",
+    "openai",
+    "anthropic",
+    "langchain",
+    "REMAINING_ADAPTERS",
+    "make_llamaindex_retriever",
+    "make_autogen_memory",
+]

cilow/adapters/anthropic.py

@@ -0,0 +1,64 @@
+"""Anthropic SDK binding over :class:`CilowMemory`, no ``anthropic`` dependency required.
+
+Anthropic has no OpenAI-compatible endpoint, so the base_url swap does NOT apply (design doc R2.2).
+This binding uses the explicit Messages tool-use path: register :data:`CILOW_RECALL_TOOL`, execute
+calls with :func:`run_recall_tool` into a ``tool_result`` block, and/or pre-inject grounded context
+with :func:`inject_memory`. Both surface the abstained/grounded branch.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Tuple
+
+from .memory import CilowMemory, RecallResult
+
+CILOW_RECALL_TOOL: Dict[str, Any] = {
+    "name": "cilow_recall",
+    "description": (
+        "Recall grounded facts from verifiable long-term memory. Returns memory-grounded results, "
+        "or a calibrated abstain when memory genuinely does not know — then DO NOT fabricate."
+    ),
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "query": {"type": "string", "description": "What to look up in memory."},
+            "anchor": {"type": "string", "description": "Optional exact entity hint."},
+            "attribute": {"type": "string", "description": "Optional exact predicate hint."},
+        },
+        "required": ["query"],
+    },
+}
+
+
+def run_recall_tool(memory: CilowMemory, tool_use_id: str, tool_input: Dict[str, Any]) -> Tuple[Dict[str, Any], RecallResult]:
+    """Execute one ``cilow_recall`` tool_use. Returns ``(tool_result_block, result)``. An INFRASTRUCTURE
+    abstain is marked ``is_error=True`` (retryable); a calibrated abstain is a normal result whose
+    content instructs the model not to fabricate."""
+    result = memory.recall(tool_input["query"], anchor=tool_input.get("anchor"), attribute=tool_input.get("attribute"))
+    block: Dict[str, Any] = {"type": "tool_result", "tool_use_id": tool_use_id}
+    if result.reason_code == "provider_unavailable":
+        block["is_error"] = True
+        block["content"] = f"MEMORY TEMPORARILY UNAVAILABLE: {result.reason or 'provider error'} — retry."
+        return block, result
+    if result.abstained or not result.grounded:
+        block["content"] = (
+            f"MEMORY ABSTAINED: {result.reason or 'memory does not know'}. "
+            "Do not fabricate; ask the user or say you don't know."
+        )
+        return block, result
+    lines = "\n".join(f"- {h.text}" for h in result.results)
+    block["content"] = f"MEMORY-GROUNDED FACTS:\n{lines}"
+    return block, result
+
+
+def inject_memory(memory: CilowMemory, query: str, *, anchor: Optional[str] = None, attribute: Optional[str] = None) -> Tuple[str, bool, RecallResult]:
+    """Pre-inject grounded memory ahead of ``messages.create``: recall, and if grounded return a
+    ``system`` string block to prepend plus the branch signal. On an abstain the system block is empty
+    and ``grounded`` is False — the caller decides whether to proceed or stop. Returns
+    ``(system, grounded, result)``."""
+    result = memory.recall(query, anchor=anchor, attribute=attribute)
+    if not result.grounded:
+        return "", False, result
+    lines = "\n".join(f"- {h.text}" for h in result.results)
+    system = f"Answer using ONLY these memory-grounded facts. If they are insufficient, say so.\n{lines}"
+    return system, True, result

cilow/adapters/langchain.py

@@ -0,0 +1,96 @@
+"""LangChain binding over :class:`CilowMemory`, no ``langchain`` dependency required.
+
+Two duck-typed classes that satisfy LangChain's structural contracts so they drop into any chain:
+ - :class:`CilowRetriever` mirrors ``BaseRetriever`` (``get_relevant_documents(query) -> list[Document]``).
+ - :class:`CilowChatMemory` mirrors ``BaseMemory`` (``memory_variables`` / ``load_memory_variables`` /
+   ``save_context`` / ``clear``).
+The abstention contract is preserved: an abstain yields ZERO documents (never a fabricated one), and
+the grounded/abstain branch is readable via :meth:`CilowRetriever.recall_with_signal`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from .memory import CilowMemory, RecallResult
+
+
+@dataclass
+class Document:
+    """Structural ``Document`` (LangChain ``langchain_core.documents``)."""
+
+    page_content: str
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+class CilowRetriever:
+    """A LangChain-compatible retriever backed by Cilow recall."""
+
+    def __init__(self, memory: CilowMemory, *, k: Optional[int] = None, anchor: Optional[str] = None,
+                 attribute: Optional[str] = None) -> None:
+        self._m = memory
+        self._k = k
+        self._anchor = anchor
+        self._attribute = attribute
+
+    def get_relevant_documents(self, query: str) -> List[Document]:
+        """BaseRetriever entry point. Returns memory-grounded docs, or ``[]`` on an abstain."""
+        r = self._m.recall(query, k=self._k, anchor=self._anchor, attribute=self._attribute)
+        if not r.grounded:
+            return []
+        return [
+            Document(page_content=h.text, metadata={"id": h.id, "entity": h.entity, "score": h.score, "grounded": True})
+            for h in r.results
+        ]
+
+    # LangChain 0.2+ internal hook.
+    def _get_relevant_documents(self, query: str) -> List[Document]:
+        return self.get_relevant_documents(query)
+
+    def recall_with_signal(self, query: str) -> RecallResult:
+        """Escape hatch: the full :class:`RecallResult` to branch on ``abstained`` / ``reason_code``."""
+        return self._m.recall(query, k=self._k, anchor=self._anchor, attribute=self._attribute)
+
+
+class CilowChatMemory:
+    """A LangChain-compatible ``BaseMemory``: recall on load, persist turns on save."""
+
+    def __init__(self, memory: CilowMemory, *, memory_key: str = "history", input_key: Optional[str] = None,
+                 output_key: Optional[str] = None, subject_hint: Optional[str] = None,
+                 anchor: Optional[str] = None, attribute: Optional[str] = None) -> None:
+        self._m = memory
+        self._memory_key = memory_key
+        self._input_key = input_key
+        self._output_key = output_key
+        self._subject_hint = subject_hint
+        self._anchor = anchor
+        self._attribute = attribute
+
+    @property
+    def memory_variables(self) -> List[str]:
+        return [self._memory_key]
+
+    def load_memory_variables(self, inputs: Dict[str, Any]) -> Dict[str, Any]:
+        """Load grounded history. On an abstain the variable is an empty string (honest, no fabrication)."""
+        query = self._pick(inputs, self._input_key)
+        if not query:
+            return {self._memory_key: ""}
+        r = self._m.recall(query, anchor=self._anchor, attribute=self._attribute)
+        return {self._memory_key: "\n".join(h.text for h in r.results) if r.grounded else ""}
+
+    def save_context(self, inputs: Dict[str, Any], outputs: Dict[str, Any]) -> None:
+        """Persist the turn into memory so future recalls can ground on it."""
+        text = "\n".join(t for t in (self._pick(inputs, self._input_key), self._pick(outputs, self._output_key)) if t)
+        if text:
+            self._m.ingest(text, subject_hint=self._subject_hint)
+
+    def clear(self) -> None:
+        self._m.reset()
+
+    @staticmethod
+    def _pick(bag: Dict[str, Any], key: Optional[str]) -> str:
+        if key:
+            return str(bag.get(key, ""))
+        vals = list(bag.values())
+        return str(vals[0]) if vals else ""

cilow/adapters/memory.py

@@ -0,0 +1,157 @@
+"""``CilowMemory`` — the ONE adapter contract every framework binding maps onto (Python mirror).
+
+A tiny, framework-neutral surface over the shipped REST endpoints (``/v1/memories/*`` + the
+``/v1/chat/completions`` proxy). Each framework adapter (OpenAI, Anthropic, LangChain, …) is a thin
+shim onto these five verbs that re-exposes the differentiator unchanged: ``abstained`` +
+``reason_code`` + the ``grounded`` signal. Transport is the existing :class:`~cilow.CilowClient` — the
+bindings call the SDK, never raw HTTP.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional, Protocol, Union
+
+from ..client import CilowClient
+from ..types import ReasonCode
+
+_CALIBRATED = ("below_threshold", "no_candidates")
+
+
+@dataclass
+class MemoryHit:
+    """One recalled memory line — ``text`` is ready to inject; structured fields kept alongside."""
+
+    id: str
+    text: str
+    entity: str
+    value: str
+    score: float
+
+
+@dataclass
+class _Abstainable:
+    abstained: bool = False
+    reason: Optional[str] = None
+    reason_code: Optional[ReasonCode] = None
+
+    @property
+    def is_infrastructure_abstain(self) -> bool:
+        """Retryable INFRA abstain (the embedding provider failed) — memory may hold the answer."""
+        return self.abstained and self.reason_code == "provider_unavailable"
+
+    @property
+    def is_calibrated_abstain(self) -> bool:
+        """Memory genuinely lacks grounded context. Do NOT fabricate past it."""
+        return self.abstained and self.reason_code in _CALIBRATED
+
+    @property
+    def should_retry(self) -> bool:
+        return self.is_infrastructure_abstain
+
+
+@dataclass
+class RecallResult(_Abstainable):
+    """Result of :meth:`CilowMemory.recall`. ``grounded`` is the universal drop-in signal."""
+
+    results: List[MemoryHit] = field(default_factory=list)
+    grounded: bool = False
+    margin: Optional[float] = None
+    packed_tokens: Optional[int] = None
+
+
+@dataclass
+class AnswerResult(_Abstainable):
+    """Result of :meth:`CilowMemory.answer` — a synthesized answer + the grounded/abstain signal."""
+
+    text: str = ""
+    grounded: bool = False
+
+
+@dataclass
+class IngestResult:
+    count: int
+    ids: List[str]
+
+
+class CilowMemory(Protocol):
+    """The single contract. Five verbs; every framework binding targets exactly these.
+
+    ``ingest`` → ``/v1/memories/add`` · ``recall`` → ``/search`` · ``answer`` → ``/search``
+    (mode ``"answer"``) · ``reset`` → ``/list`` + ``/delete`` · ``health`` → ``GET /health``.
+    ``proxy_base_url()`` is the drop-in OpenAI-compatible base URL that emits the grounded header.
+    """
+
+    def ingest(self, items: Union[str, List[str]], *, subject_hint: Optional[str] = None) -> IngestResult: ...
+    def recall(self, query: str, *, k: Optional[int] = None, anchor: Optional[str] = None, attribute: Optional[str] = None) -> RecallResult: ...
+    def answer(self, query: str, *, anchor: Optional[str] = None, attribute: Optional[str] = None) -> AnswerResult: ...
+    def reset(self) -> int: ...
+    def health(self) -> bool: ...
+    def proxy_base_url(self) -> str: ...
+
+
+class CilowMemoryClient:
+    """The concrete :class:`CilowMemory` over a :class:`~cilow.CilowClient`."""
+
+    def __init__(self, client: CilowClient) -> None:
+        self._c = client
+
+    @classmethod
+    def create(cls, base_url: str, token: str) -> "CilowMemoryClient":
+        return cls(CilowClient(base_url=base_url, token=token))
+
+    def ingest(self, items: Union[str, List[str]], *, subject_hint: Optional[str] = None) -> IngestResult:
+        the_list = [items] if isinstance(items, str) else list(items)
+        if len(the_list) == 1:
+            r = self._c.memories.add(the_list[0], subject_hint=subject_hint)
+            ids = [m["id"] for m in r.get("memories", [])]
+            return IngestResult(count=r.get("count", len(ids)), ids=ids)
+        r = self._c.memories.batch_add([{"content": c, "subject_hint": subject_hint} for c in the_list])
+        ids = [m["id"] for res in r.get("results", []) for m in res.get("memories", [])]
+        return IngestResult(count=len(ids), ids=ids)
+
+    def recall(self, query: str, *, k: Optional[int] = None, anchor: Optional[str] = None, attribute: Optional[str] = None) -> RecallResult:
+        r = self._c.memories.search(query, anchor=anchor, attribute=attribute)
+        raw = r.get("results", []) or []
+        if k is not None:
+            raw = raw[:k]
+        hits = [
+            MemoryHit(id=h.get("id", ""), text=h.get("text", ""), entity=h.get("entity", ""),
+                      value=h.get("value", h.get("text", "")), score=h.get("score", 0.0))
+            for h in raw
+        ]
+        abstained = bool(r.get("abstained", False))
+        return RecallResult(
+            abstained=abstained, reason=r.get("reason"), reason_code=r.get("reason_code"),
+            results=hits, grounded=(not abstained and len(hits) > 0),
+            margin=r.get("margin"), packed_tokens=r.get("packed_tokens"),
+        )
+
+    def answer(self, query: str, *, anchor: Optional[str] = None, attribute: Optional[str] = None) -> AnswerResult:
+        r = self._c.memories.search(query, anchor=anchor, attribute=attribute, mode="answer")
+        abstained = bool(r.get("abstained", False))
+        text = r.get("context_text", "") or ""
+        return AnswerResult(
+            abstained=abstained, reason=r.get("reason"), reason_code=r.get("reason_code"),
+            text=text, grounded=(not abstained and bool(text)),
+        )
+
+    def reset(self) -> int:
+        deleted = 0
+        while True:
+            page = self._c.memories.list(active_only=True, limit=200)
+            mems = page.get("memories", [])
+            if not mems:
+                break
+            for m in mems:
+                res = self._c.memories.delete(m["id"])
+                deleted += res.get("deleted", 0)
+            if len(mems) < 200:
+                break
+        return deleted
+
+    def health(self) -> bool:
+        return self._c.health()
+
+    def proxy_base_url(self) -> str:
+        return f"{self._c.base_url}/v1"

cilow/adapters/openai.py

@@ -0,0 +1,74 @@
+"""OpenAI SDK binding over :class:`CilowMemory`, no ``openai`` dependency required.
+
+Two thin surfaces:
+ 1. ``base_url`` swap — :func:`cilow_proxy_config` returns kwargs for ``OpenAI(...)`` pointing at the
+    Cilow proxy; recall→inject→forward is automatic and every response carries
+    ``x-cilow-memory-grounded`` (read it with :func:`grounded_from_headers`).
+ 2. memory tool-use — hand :data:`CILOW_RECALL_TOOL` to ``tools=[...]`` and execute calls with
+    :func:`run_recall_tool`; the tool result carries the abstained/grounded branch so the model never
+    fabricates past a calibrated abstain.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Optional, Tuple, Union
+
+from .memory import CilowMemory, RecallResult
+
+GROUNDED_HEADER = "x-cilow-memory-grounded"
+
+CILOW_RECALL_TOOL: Dict[str, Any] = {
+    "type": "function",
+    "function": {
+        "name": "cilow_recall",
+        "description": (
+            "Recall grounded facts from verifiable long-term memory. Returns memory-grounded results, "
+            "or a calibrated abstain when memory genuinely does not know — then DO NOT fabricate."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string", "description": "What to look up in memory."},
+                "anchor": {"type": "string", "description": "Optional exact entity hint."},
+                "attribute": {"type": "string", "description": "Optional exact predicate hint."},
+            },
+            "required": ["query"],
+        },
+    },
+}
+
+
+def cilow_proxy_config(memory: CilowMemory, token: str) -> Dict[str, str]:
+    """Kwargs to spread into ``OpenAI(**cilow_proxy_config(memory, token))``."""
+    return {"base_url": memory.proxy_base_url(), "api_key": token}
+
+
+def grounded_from_headers(headers: Any) -> Optional[bool]:
+    """Read the grounded signal off an OpenAI raw response's headers (``.with_raw_response``), a mapping,
+    or anything with ``.get``. Returns ``None`` when the header is absent (non-proxy)."""
+    raw = None
+    if hasattr(headers, "get"):
+        raw = headers.get(GROUNDED_HEADER)
+    if raw is None and isinstance(headers, dict):
+        raw = headers.get(GROUNDED_HEADER.upper())
+    if raw is None:
+        return None
+    return str(raw).strip().lower() == "true"
+
+
+def run_recall_tool(memory: CilowMemory, raw_args: Union[str, Dict[str, Any]]) -> Tuple[str, RecallResult]:
+    """Execute one ``cilow_recall`` tool call. Returns ``(content, result)``: the ``content`` string to
+    feed back as the tool result, plus the raw :class:`RecallResult` so the caller can branch. On an
+    abstain the content is an explicit "memory does not know" so the model does not fabricate."""
+    args = json.loads(raw_args) if isinstance(raw_args, str) else raw_args
+    result = memory.recall(args["query"], anchor=args.get("anchor"), attribute=args.get("attribute"))
+    if result.abstained or not result.grounded:
+        kind = "temporarily unavailable" if result.reason_code == "provider_unavailable" else "no grounded facts"
+        content = (
+            f"MEMORY ABSTAINED ({kind}): {result.reason or 'memory does not know'}. "
+            "Do not fabricate; ask the user or say you don't know."
+        )
+        return content, result
+    lines = "\n".join(f"- {h.text}" for h in result.results)
+    return f"MEMORY-GROUNDED FACTS:\n{lines}", result

cilow/adapters/remaining.py

@@ -0,0 +1,65 @@
+"""The remaining six framework bindings — same :class:`CilowMemory` contract, same thin-shim pattern as
+``openai.py`` / ``anthropic.py`` / ``langchain.py``. Each row documents the framework's integration
+point and the exact mapping onto the five verbs. Where the framework interface is a plain
+function/protocol we ship a working stub; where it requires extending a framework base class we leave a
+typed TODO so the shim lands the moment the dep is added.
+
+THE INVARIANT (all nine): map the framework's memory/retriever/tool onto
+``ingest`` / ``recall`` / ``answer`` / ``reset`` / ``health`` (+ ``proxy_base_url()`` for base_url swaps)
+and re-expose ``abstained`` + ``reason_code`` + ``grounded`` unchanged. An abstain is always surfaced
+so the caller can apply its fallback policy.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from .memory import CilowMemory
+
+# framework -> (integration point, mapping, status)
+REMAINING_ADAPTERS: List[Dict[str, str]] = [
+    {"framework": "LlamaIndex", "integration_point": "BaseRetriever._retrieve(QueryBundle) -> list[NodeWithScore]",
+     "mapping": "recall -> NodeWithScore list; abstain => []. Near-identical to CilowRetriever.", "status": "stub"},
+    {"framework": "Vercel AI SDK", "integration_point": "wrapLanguageModel middleware",
+     "mapping": "proxy_base_url() as the provider base URL; surface grounded in stream metadata (R2.1 streaming).", "status": "todo"},
+    {"framework": "CrewAI", "integration_point": "Storage / memory backend",
+     "mapping": "save->ingest, search->recall; branch on abstained before use.", "status": "todo"},
+    {"framework": "AutoGen", "integration_point": "Memory protocol (add / query)",
+     "mapping": "add->ingest, query->recall; abstain => empty MemoryQueryResult.", "status": "stub"},
+    {"framework": "Composio", "integration_point": "connector / tool bundle",
+     "mapping": "the five CilowMemory verbs as Composio actions.", "status": "todo"},
+    {"framework": "MCP", "integration_point": "native /mcp recall/answer/remember (already shipped)",
+     "mapping": "no shim needed — add cilow-mcp to .mcp.json.", "status": "stub"},
+]
+
+
+def make_llamaindex_retriever(memory: CilowMemory, *, k: Optional[int] = None, anchor: Optional[str] = None):
+    """LlamaIndex stub — an object whose ``retrieve`` returns NodeWithScore-shaped dicts (abstain => []).
+    When ``llama-index`` is added, extend ``BaseRetriever`` and delegate to this."""
+
+    class _Retriever:
+        def retrieve(self, query: str) -> List[Dict[str, Any]]:
+            r = memory.recall(query, k=k, anchor=anchor)
+            if not r.grounded:
+                return []
+            return [
+                {"node": {"text": h.text, "metadata": {"id": h.id, "entity": h.entity, "grounded": True}}, "score": h.score}
+                for h in r.results
+            ]
+
+    return _Retriever()
+
+
+def make_autogen_memory(memory: CilowMemory, *, subject_hint: Optional[str] = None):
+    """AutoGen stub — the ``Memory`` protocol (``add`` / ``query``). ``query`` returns grounded content
+    strings; an abstain yields an empty list (never a fabricated memory)."""
+
+    class _Memory:
+        def add(self, content: str) -> None:
+            memory.ingest(content, subject_hint=subject_hint)
+
+        def query(self, query: str) -> Dict[str, Any]:
+            r = memory.recall(query)
+            return {"results": [h.text for h in r.results] if r.grounded else [], "grounded": r.grounded}
+
+    return _Memory()