atomicmemory-langflow 0.1.17__py3-none-any.whl

atomicmemory_langflow/__init__.py

@@ -0,0 +1,30 @@
+"""AtomicMemory custom components for Langflow.
+
+Importing this package does NOT import Langflow (`lfx`). Component classes are
+resolved lazily via ``__getattr__`` so the lfx-free helper modules
+(``_scope``/``_messages``/``_sdk``/``_chat_history``) stay unit-testable without
+the Langflow host installed.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+__version__ = "0.1.0"
+
+_EXPORTS = {
+    "AtomicMemoryChatMemoryComponent": "chat_memory",
+    "AtomicMemorySearchContextComponent": "search_context",
+    "AtomicMemoryStoreMessageComponent": "store_message",
+    "AtomicMemoryDeleteComponent": "delete",
+}
+
+__all__ = list(_EXPORTS)
+
+
+def __getattr__(name: str) -> Any:
+    module = _EXPORTS.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    return getattr(import_module(f".{module}", __name__), name)

atomicmemory_langflow/_chat_history.py

@@ -0,0 +1,60 @@
+"""Read-only LangChain chat history backed by AtomicMemory (lfx-free)."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from langchain_core.chat_history import BaseChatMessageHistory
+from langchain_core.messages import BaseMessage
+
+from ._messages import memory_to_lc_message
+
+logger = logging.getLogger(__name__)
+
+
+class AtomicMemoryChatMessageHistory(BaseChatMessageHistory):
+    """Surfaces a scope's memories as chat history. Writes are no-ops here —
+    use the Store Message component. LangChain provides the async surface
+    (aget_messages/aadd_messages) by delegating to these sync methods.
+    """
+
+    def __init__(self, *, bridge: Any, scope: dict, limit: int, fail_open: bool = False) -> None:
+        self._bridge = bridge
+        self._scope = scope
+        self._limit = limit
+        self._fail_open = fail_open
+        self._warned = False
+
+    @property
+    def messages(self) -> list[BaseMessage]:
+        try:
+            page = self._bridge.list_memories(scope=self._scope, limit=self._limit)
+        except Exception as exc:
+            # Fail closed by default: surface "memory unavailable" rather than
+            # silently pretending the user has no memory. Opt into soft failure
+            # (empty history) with fail_open=True.
+            if self._fail_open:
+                logger.warning(
+                    "AtomicMemory history read failed; returning empty history (fail_open): %s", exc
+                )
+                return []
+            raise RuntimeError(f"AtomicMemory history read failed: {exc}") from exc
+        memories = list(getattr(page, "memories", []))
+        memories.reverse()  # newest-first -> chronological
+        return [memory_to_lc_message(m) for m in memories]
+
+    def add_messages(self, messages: list[BaseMessage]) -> None:
+        if not self._warned:
+            logger.warning(
+                "AtomicMemory Chat Memory is read-only; writes here are ignored. "
+                "Use the 'AtomicMemory Store Message' component to persist memory."
+            )
+            self._warned = True
+
+    def add_message(self, message: BaseMessage) -> None:
+        self.add_messages([message])
+
+    def clear(self) -> None:
+        # Read-only; erasure is via the AtomicMemory Delete component.
+        return None

atomicmemory_langflow/_component_base.py

@@ -0,0 +1,51 @@
+"""Mixin shared by the AtomicMemory components (lfx-free; only reads attrs).
+
+Inputs are named ``memory_user_id``/``memory_session_id`` (NOT ``user_id``) to
+avoid colliding with Langflow's base ``Component.user_id`` property, which holds
+the authenticated run user we fall back to.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._scope import build_scope
+from ._sdk import AtomicMemoryBridge
+
+
+class AtomicMemoryComponentMixin:
+    def _resolve_user_id(self) -> str:
+        explicit = (getattr(self, "memory_user_id", "") or "")
+        explicit = str(explicit).strip()
+        if explicit:
+            return explicit
+        ctx = getattr(self, "user_id", None)  # base Component.user_id (run context)
+        return str(ctx).strip() if ctx else ""
+
+    def _resolve_session_id(self) -> str | None:
+        explicit = (getattr(self, "memory_session_id", "") or "")
+        explicit = str(explicit).strip()
+        if explicit:
+            return explicit
+        graph = getattr(self, "graph", None)
+        sid = getattr(graph, "session_id", None) if graph is not None else None
+        return str(sid).strip() if sid else None
+
+    def _build_scope(self, *, include_session: bool = True) -> dict:
+        # namespace is intentionally not plumbed in Phase 1 (provider honors it
+        # only on search/package, not ingest/list/delete). See _inputs.scope_inputs.
+        # include_session=False yields a user-only scope for cross-session recall:
+        # Core hard-filters search/list by session, so retrieval meant to span
+        # sessions must omit the thread.
+        return build_scope(
+            self._resolve_user_id(),
+            session_id=self._resolve_session_id() if include_session else None,
+        )
+
+    def _build_bridge(self) -> AtomicMemoryBridge:
+        return AtomicMemoryBridge(
+            provider=getattr(self, "provider", "atomicmemory"),
+            api_url=getattr(self, "api_url", None),
+            api_key=getattr(self, "api_key", None),
+            provider_config=dict(getattr(self, "provider_config", {}) or {}),
+        )

atomicmemory_langflow/_inputs.py

@@ -0,0 +1,72 @@
+"""Shared Langflow input builders (imports lfx). Each call returns fresh Input
+instances so components do not share mutable input objects."""
+
+from __future__ import annotations
+
+from lfx.inputs.inputs import (
+    DictInput,
+    DropdownInput,
+    MessageTextInput,
+    SecretStrInput,
+)
+
+from ._sdk import DEFAULT_API_URL
+
+
+def connection_inputs() -> list:
+    return [
+        DropdownInput(
+            name="provider",
+            display_name="Provider",
+            options=["atomicmemory"],
+            value="atomicmemory",
+            advanced=True,
+            info="Memory provider. Phase 1 supports atomicmemory.",
+        ),
+        MessageTextInput(
+            name="api_url",
+            display_name="API URL",
+            value=DEFAULT_API_URL,
+            advanced=True,
+            info="AtomicMemory Core base URL.",
+        ),
+        SecretStrInput(
+            name="api_key",
+            display_name="API Key",
+            value="",
+            required=False,
+            advanced=True,
+            info="API key (optional for local Core). Never put secrets in Provider Config.",
+        ),
+        DictInput(
+            name="provider_config",
+            display_name="Provider Config",
+            value={},
+            advanced=True,
+            info="Advanced SDK provider config. Must not contain secrets.",
+        ),
+    ]
+
+
+def scope_inputs(*, include_session: bool = True) -> list:
+    # NOTE: `namespace` is intentionally NOT exposed in Phase 1. The AtomicMemory
+    # Python provider only applies namespace on search/package — ingest/list/delete
+    # ignore it — so exposing it would silently break scoping (store/delete would
+    # not be namespace-isolated). Re-add only after end-to-end namespace support.
+    items = [
+        MessageTextInput(
+            name="memory_user_id",
+            display_name="User ID",
+            info="Memory scope. Defaults to the Langflow run user when left blank.",
+        ),
+    ]
+    if include_session:
+        items.append(
+            MessageTextInput(
+                name="memory_session_id",
+                display_name="Session ID",
+                advanced=True,
+                info="Session/thread scope. Defaults to the flow session when blank.",
+            )
+        )
+    return items

atomicmemory_langflow/_messages.py

@@ -0,0 +1,68 @@
+"""Convert between Langflow/LangChain senders and SDK roles, and map stored
+memories to LangChain messages (lfx-free)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def coerce_text(value: Any) -> str:
+    """Extract plain text from an input that may be a Langflow/LangChain Message.
+
+    A MessageTextInput fed from another component's Message output can arrive as
+    a Message object, whose ``str()`` is its JSON serialization (``{"text": ...}``),
+    not the text. Stringifying that as a search query or ingest content corrupts
+    it. Prefer ``.text`` when present; otherwise fall back to ``str()``.
+    """
+    if value is None:
+        return ""
+    text = getattr(value, "text", None)
+    if isinstance(text, str):
+        return text
+    return str(value)
+
+
+# Langflow sender constants ("User"/"Machine"/"System"/"Tool") + LangChain
+# message types ("human"/"ai"/"system"/"tool") -> SDK role.
+_SENDER_TO_ROLE = {
+    "user": "user",
+    "human": "user",
+    "assistant": "assistant",
+    "ai": "assistant",
+    "machine": "assistant",
+    "system": "system",
+    "tool": "tool",
+}
+
+
+def sender_to_role(sender: Any) -> str:
+    """Total map to an SDK role (`user|assistant|system|tool`); unknown -> `user`."""
+    if sender is None:
+        return "user"
+    return _SENDER_TO_ROLE.get(str(sender).strip().lower(), "user")
+
+
+def memory_to_lc_message(memory: Any):
+    """Map a stored Memory to a LangChain message.
+
+    Role is NOT generally preserved: the AtomicMemory provider flattens
+    messages-mode ingest into a transcript and extracts semantic memories, so
+    most recalled memories have no ``role`` metadata and come back as a
+    ``[memory] …`` HumanMessage. The ``role == "assistant"`` check below is
+    best-effort for the rare case a provider surfaces role metadata.
+
+    SECURITY: retrieved memory is user-influenced; never return a SystemMessage
+    (which would grant system authority — a prompt-injection vector). Everything
+    that isn't an explicit assistant memory is a HumanMessage tagged ``[memory]``
+    so downstream prompts can see it is recalled context.
+    """
+    from langchain_core.messages import AIMessage, HumanMessage
+
+    content = getattr(memory, "content", "") or ""
+    role = None
+    meta = getattr(memory, "metadata", None)
+    if isinstance(meta, dict):
+        role = meta.get("role")
+    if role == "assistant":
+        return AIMessage(content=content)
+    return HumanMessage(content=f"[memory] {content}")

atomicmemory_langflow/_scope.py

@@ -0,0 +1,40 @@
+"""Map Langflow inputs to an AtomicMemory SDK scope dict (lfx-free, SDK-free)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def _clean(value: Any) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def build_scope(
+    user_id: Any,
+    *,
+    session_id: Any = None,
+    namespace: Any = None,
+    agent_id: Any = None,
+) -> dict[str, str]:
+    """Build an SDK scope dict. ``user`` is required (Core enforces it).
+
+    Langflow session -> ``thread``; namespace -> ``namespace``; agent -> ``agent``.
+    Optional fields are omitted when blank.
+    """
+    user = _clean(user_id)
+    if not user:
+        raise ValueError("AtomicMemory requires a non-empty user_id.")
+    scope: dict[str, str] = {"user": user}
+    thread = _clean(session_id)
+    if thread:
+        scope["thread"] = thread
+    ns = _clean(namespace)
+    if ns:
+        scope["namespace"] = ns
+    agent = _clean(agent_id)
+    if agent:
+        scope["agent"] = agent
+    return scope

atomicmemory_langflow/_sdk.py

@@ -0,0 +1,234 @@
+"""SDK boundary: the single place that touches the `atomicmemory` SDK.
+
+lfx-free. Components call this bridge; the bridge passes plain dicts to the SDK
+client (the client coerces them into validated Pydantic requests). A
+``client_factory`` hook lets tests inject a fake client.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from contextlib import contextmanager
+from typing import Any, Callable, Iterator
+from urllib.parse import urlparse
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_API_URL = "http://localhost:17350"
+_LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1"}
+
+# Sensitivity class for extraction-mode ingests is never inferred. `mode="messages"`
+# runs core-side LLM extraction, which persists the *raw* transcript in the audit
+# episode (not a derived summary), so the bridge omits content_class by default: a
+# core running the default RAW_CONTENT_POLICY=reject then redacts that raw transcript
+# while still extracting searchable memories. Callers stamp "summary"/"redacted"
+# explicitly only when the content is genuinely distilled or has sensitive spans removed.
+
+# Phase 1 supports only the atomicmemory provider end-to-end.
+SUPPORTED_PROVIDERS = frozenset({"atomicmemory"})
+
+# provider_config is ALLOWLIST-only: just harmless SDK tuning keys. Anything else —
+# including any secret/connection-shaped key (accessToken, clientSecret, headers,
+# authorization, …) — is rejected. Secrets and the URL belong in the dedicated
+# 'API Key' / 'API URL' fields, never in the plaintext-persisted provider_config.
+_ALLOWED_CONFIG_KEYS = frozenset(
+    {"timeoutseconds", "timeout_seconds", "apiversion", "api_version"}
+)
+
+# Operator-controlled (env, NOT flow-author) allowance for a non-local api_url.
+_ALLOW_REMOTE_ENV = "ATOMICMEMORY_LANGFLOW_ALLOW_REMOTE"
+_ALLOWED_HOSTS_ENV = "ATOMICMEMORY_LANGFLOW_ALLOWED_HOSTS"
+
+
+def sdk_is_available() -> bool:
+    try:
+        import atomicmemory  # noqa: F401
+    except Exception:  # pragma: no cover - import guard
+        return False
+    return True
+
+
+def _require_sdk():
+    try:
+        import atomicmemory
+    except ImportError as exc:  # pragma: no cover - exercised via monkeypatch
+        raise RuntimeError(
+            "The 'atomicmemory' SDK is required for AtomicMemory components. "
+            "Install it with: pip install atomicmemory"
+        ) from exc
+    return atomicmemory
+
+
+def _env_truthy(value: Any) -> bool:
+    return str(value).strip().lower() in {"1", "true", "yes", "on"} if value else False
+
+
+def _remote_host_allowed(host: str) -> bool:
+    if _env_truthy(os.environ.get(_ALLOW_REMOTE_ENV)):
+        return True
+    allowed = os.environ.get(_ALLOWED_HOSTS_ENV, "")
+    return host in {h.strip().lower() for h in allowed.split(",") if h.strip()}
+
+
+def validate_api_url(api_url: Any) -> str:
+    url = (str(api_url).strip() if api_url else "") or DEFAULT_API_URL
+    parsed = urlparse(url)
+    if parsed.scheme not in ("http", "https"):
+        raise ValueError(f"api_url must be http or https, got: {url!r}")
+    host = (parsed.hostname or "").lower()
+    if host not in _LOCAL_HOSTS and not _remote_host_allowed(host):
+        # Restrict non-local hosts unless the operator opts in via env. NOTE: this is
+        # not full SSRF protection — loopback (localhost ports) is always allowed; see
+        # the README security section for the shared/cloud caveat.
+        raise ValueError(
+            f"api_url host {host!r} is not local and not allowed. To use a remote "
+            f"AtomicMemory Core, the operator must set {_ALLOW_REMOTE_ENV}=1 or list "
+            f"the host in {_ALLOWED_HOSTS_ENV} (comma-separated)."
+        )
+    return url
+
+
+def _normalize_key(key: Any) -> str:
+    return str(key).strip().lower().replace("-", "_").replace(" ", "_")
+
+
+def validate_provider(provider: Any) -> str:
+    name = (str(provider).strip() if provider else "") or "atomicmemory"
+    if name not in SUPPORTED_PROVIDERS:
+        raise ValueError(
+            f"Unsupported provider {name!r}. Phase 1 supports only: "
+            f"{', '.join(sorted(SUPPORTED_PROVIDERS))}."
+        )
+    return name
+
+
+def validate_provider_config(provider_config: Any) -> dict[str, Any]:
+    """Allowlist-only: accept just known tuning keys; reject everything else
+    (URLs, keys, and any secret-shaped key like accessToken/clientSecret)."""
+    cfg = dict(provider_config or {})
+    for key in cfg:
+        if _normalize_key(key) not in _ALLOWED_CONFIG_KEYS:
+            raise ValueError(
+                f"provider_config key {key!r} is not allowed. Phase 1 accepts only "
+                "tuning keys (timeoutSeconds, apiVersion); set the API URL/Key via the "
+                "component's 'API URL' and 'API Key' (secret) fields, not provider_config."
+            )
+    return cfg
+
+
+class AtomicMemoryBridge:
+    """Thin, sync boundary over the AtomicMemory SDK MemoryClient.
+
+    A client is constructed + initialized + closed per operation (cheap at
+    canvas latencies; avoids connection leaks and cross-run state). Requests are
+    plain dicts; the SDK coerces/validates them.
+    """
+
+    def __init__(
+        self,
+        *,
+        provider: str = "atomicmemory",
+        api_url: Any = None,
+        api_key: Any = None,
+        provider_config: Any = None,
+        client_factory: Callable[[dict, str], Any] | None = None,
+    ) -> None:
+        self._provider = validate_provider(provider)
+        self._api_url = validate_api_url(api_url)
+        self._api_key = (str(api_key).strip() or None) if api_key else None
+        self._provider_config = validate_provider_config(provider_config)
+        self._client_factory = client_factory
+
+    def _provider_settings(self) -> dict[str, Any]:
+        # provider_config first, then the validated connection fields LAST so they
+        # can never be overridden (defense in depth alongside validate_provider_config).
+        settings: dict[str, Any] = {**self._provider_config, "apiUrl": self._api_url}
+        if self._api_key:
+            settings["apiKey"] = self._api_key
+        return settings
+
+    @contextmanager
+    def _client(self) -> Iterator[Any]:
+        if self._client_factory is not None:
+            client = self._client_factory({self._provider: self._provider_settings()}, self._provider)
+        else:
+            am = _require_sdk()
+            client = am.MemoryClient(
+                providers={self._provider: self._provider_settings()},
+                default_provider=self._provider,
+            )
+        try:
+            client.initialize()
+            yield client
+        finally:
+            client.close()
+
+    def capabilities(self):
+        with self._client() as client:
+            return client.capabilities()
+
+    def ingest_messages(
+        self,
+        *,
+        scope: dict,
+        messages: list[dict],
+        metadata: dict | None = None,
+        content_class: str | None = None,
+    ):
+        # Never infer a class: when unset, omit it so a core running
+        # RAW_CONTENT_POLICY=reject redacts the raw transcript from the audit
+        # episode (extraction still runs) instead of the plugin mislabeling it.
+        body = {
+            "mode": "messages",
+            "scope": scope,
+            "messages": messages,
+            "provenance": {"source": "langflow"},
+            "metadata": metadata or {},
+        }
+        if content_class:
+            body["content_class"] = content_class
+        with self._client() as client:
+            return client.ingest(body)
+
+    def list_memories(self, *, scope: dict, limit: int):
+        with self._client() as client:
+            return client.list({"scope": scope, "limit": limit})
+
+    def search(self, *, scope: dict, query: str, limit: int):
+        with self._client() as client:
+            return client.search({"scope": scope, "query": query, "limit": limit})
+
+    def package(self, *, scope: dict, query: str, limit: int, token_budget: int | None = None):
+        with self._client() as client:
+            req: dict[str, Any] = {"scope": scope, "query": query, "limit": limit}
+            if token_budget is not None:
+                req["token_budget"] = token_budget
+            return client.package(req)
+
+    def delete_scope(self, *, scope: dict, page_size: int = 100) -> dict[str, int]:
+        """Best-effort scope erasure: page list() then delete() each id.
+
+        The SDK has no native scope-wipe; this is best-effort over SDK-visible
+        memories. Ids are collected first (no mutate-while-paginating).
+        """
+        with self._client() as client:
+            ids: list[str] = []
+            cursor: str | None = None
+            while True:
+                req: dict[str, Any] = {"scope": scope, "limit": page_size}
+                if cursor:
+                    req["cursor"] = cursor
+                page = client.list(req)
+                ids.extend(m.id for m in page.memories)
+                cursor = getattr(page, "cursor", None)
+                if not cursor or not page.memories:
+                    break
+            deleted = failed = 0
+            for mid in ids:
+                try:
+                    client.delete({"id": mid, "scope": scope})
+                    deleted += 1
+                except Exception:  # noqa: BLE001 - best-effort; count failures
+                    failed += 1
+            return {"deleted": deleted, "failed": failed, "found": len(ids)}

atomicmemory_langflow/chat_memory.py

@@ -0,0 +1,55 @@
+"""AtomicMemory Chat Memory — read-only Langflow Message History backend."""
+
+from __future__ import annotations
+
+from lfx.base.memory.model import LCChatMemoryComponent
+from lfx.field_typing.constants import Memory
+from lfx.inputs.inputs import BoolInput, IntInput
+
+from ._chat_history import AtomicMemoryChatMessageHistory
+from ._component_base import AtomicMemoryComponentMixin
+from ._inputs import connection_inputs, scope_inputs
+
+MAX_HISTORY_LIMIT = 100
+
+
+class AtomicMemoryChatMemoryComponent(AtomicMemoryComponentMixin, LCChatMemoryComponent):
+    display_name = "Chat Memory (AtomicMemory)"
+    description = (
+        "Read-only chat history backed by AtomicMemory (semantic memory for the "
+        "user/session). Persist memory with the AtomicMemory Store Message component."
+    )
+    name = "AtomicMemoryChatMemory"
+    icon = "messages-square"
+
+    inputs = [
+        *connection_inputs(),
+        *scope_inputs(),
+        IntInput(
+            name="limit",
+            display_name="Max memories",
+            value=10,
+            info=f"Maximum memories to surface as history (capped at {MAX_HISTORY_LIMIT}).",
+        ),
+        BoolInput(
+            name="fail_open",
+            display_name="Fail open on error",
+            value=False,
+            advanced=True,
+            info="If the memory backend is unreachable: when false (default), raise a "
+            "clear error; when true, return empty history instead.",
+        ),
+    ]
+
+    def build_message_history(self) -> Memory:
+        scope = self._build_scope()
+        bridge = self._build_bridge()
+        try:
+            raw = int(self.limit)
+        except (TypeError, ValueError):
+            raw = 10
+        limit = max(1, min(raw, MAX_HISTORY_LIMIT))
+        self.status = f"AtomicMemory history · user={scope['user']} · limit={limit}"
+        return AtomicMemoryChatMessageHistory(
+            bridge=bridge, scope=scope, limit=limit, fail_open=bool(self.fail_open),
+        )

atomicmemory_langflow/delete.py

@@ -0,0 +1,56 @@
+"""AtomicMemory Delete Memories in Scope — best-effort erasure (right-to-erasure).
+
+Deletes the SDK-visible memories in a scope (paged list -> delete each). Not a
+native atomic Core scope-wipe. Confirmation-gated.
+"""
+
+from __future__ import annotations
+
+from lfx.custom.custom_component.component import Component
+from lfx.inputs.inputs import BoolInput
+from lfx.schema.message import Message
+from lfx.template.field.base import Output
+
+from ._component_base import AtomicMemoryComponentMixin
+from ._inputs import connection_inputs, scope_inputs
+
+
+class AtomicMemoryDeleteComponent(AtomicMemoryComponentMixin, Component):
+    display_name = "Delete Memories in Scope (AtomicMemory)"
+    description = (
+        "Delete the SDK-visible memories in a scope (best-effort, not an atomic "
+        "Core wipe). Requires explicit confirmation."
+    )
+    name = "AtomicMemoryDelete"
+    icon = "trash"
+
+    inputs = [
+        *connection_inputs(),
+        *scope_inputs(),
+        BoolInput(
+            name="confirm",
+            display_name="Confirm",
+            value=False,
+            info="Must be true to delete. Guards against accidental erasure.",
+        ),
+    ]
+
+    outputs = [Output(name="result", display_name="Result", method="delete")]
+
+    def delete(self) -> Message:
+        scope = self._build_scope()
+        if not self.confirm:
+            text = "Delete skipped: set 'Confirm' to true to erase memories in this scope."
+            self.status = "skipped (confirm=false)"
+            return Message(text=text, sender="Machine", sender_name="AtomicMemory")
+        bridge = self._build_bridge()
+        summary = bridge.delete_scope(scope=scope)
+        text = (
+            f"Deleted {summary['deleted']} of {summary['found']} memories "
+            f"(failed {summary['failed']}) for scope {scope}."
+        )
+        self.status = text
+        return Message(
+            text=text, sender="Machine", sender_name="AtomicMemory",
+            session_metadata={"atomicmemory": summary},
+        )

atomicmemory_langflow/search_context.py

@@ -0,0 +1,100 @@
+"""AtomicMemory Search Context — query-driven, prompt-ready memory context."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from lfx.custom.custom_component.component import Component
+from lfx.inputs.inputs import BoolInput, IntInput, MessageTextInput
+from lfx.schema.message import Message
+from lfx.template.field.base import Output
+
+from ._component_base import AtomicMemoryComponentMixin
+from ._inputs import connection_inputs, scope_inputs
+from ._messages import coerce_text
+
+DEFAULT_SEARCH_LIMIT = 5
+MAX_SEARCH_LIMIT = 100
+
+
+def _clamp_limit(value: Any) -> int:
+    try:
+        limit = int(value)
+    except (TypeError, ValueError):
+        return DEFAULT_SEARCH_LIMIT
+    return max(1, min(limit, MAX_SEARCH_LIMIT))
+
+
+def _format_results(page: Any) -> str:
+    lines = []
+    for result in getattr(page, "results", []) or []:
+        memory = getattr(result, "memory", None)
+        content = getattr(memory, "content", None) or getattr(result, "content", "")
+        if content:
+            lines.append(f"- {content}")
+    return "\n".join(lines) if lines else "(no relevant memories found)"
+
+
+class AtomicMemorySearchContextComponent(AtomicMemoryComponentMixin, Component):
+    display_name = "Search Context (AtomicMemory)"
+    description = "Retrieve relevant long-term memory for a query as prompt-ready context."
+    name = "AtomicMemorySearchContext"
+    icon = "search"
+
+    inputs = [
+        MessageTextInput(name="query", display_name="Query", required=True),
+        *connection_inputs(),
+        *scope_inputs(),
+        IntInput(
+            name="limit",
+            display_name="Limit",
+            value=DEFAULT_SEARCH_LIMIT,
+            info=f"Max memories to retrieve (clamped to 1..{MAX_SEARCH_LIMIT}).",
+        ),
+        BoolInput(
+            name="use_packaged_context",
+            display_name="Use packaged context",
+            value=True,
+            info="Use the provider's packaged context. Requires provider support; "
+            "turn off for search-only mode.",
+        ),
+        BoolInput(
+            name="scope_to_session",
+            display_name="Scope to session",
+            value=False,
+            advanced=True,
+            info="When off (default), recall spans the user's whole memory across "
+            "sessions — the point of long-term memory. When on, restrict retrieval to "
+            "the current session/thread (Core hard-filters by session).",
+        ),
+    ]
+
+    outputs = [Output(name="context", display_name="Context", method="build_context")]
+
+    def build_context(self) -> Message:
+        query = coerce_text(self.query).strip()
+        if not query:
+            raise ValueError("Search Context requires a non-empty query.")
+        # Long-term recall is user-scoped by default (cross-session); opt into
+        # session-only retrieval with scope_to_session.
+        scope = self._build_scope(include_session=bool(self.scope_to_session))
+        bridge = self._build_bridge()
+        limit = _clamp_limit(self.limit)
+
+        if self.use_packaged_context:
+            caps = bridge.capabilities()
+            if not getattr(getattr(caps, "extensions", None), "package", False):
+                raise ValueError(
+                    "Provider does not support packaged context "
+                    "(capabilities().extensions.package is false). "
+                    "Set 'Use packaged context' to false for search-only mode."
+                )
+            package = bridge.package(scope=scope, query=query, limit=limit)
+            text = package.text
+        else:
+            page = bridge.search(scope=scope, query=query, limit=limit)
+            text = _format_results(page)
+
+        self.status = f"AtomicMemory context · {len(text)} chars"
+        # sender is required for Langflow message persistence (MessageResponse.from_message).
+        return Message(text=text, sender="Machine", sender_name="AtomicMemory Search Context")

atomicmemory_langflow/store_message.py

@@ -0,0 +1,81 @@
+"""AtomicMemory Store Message — explicitly persist one message into memory."""
+
+from __future__ import annotations
+
+from lfx.custom.custom_component.component import Component
+from lfx.inputs.inputs import DropdownInput, MessageTextInput
+from lfx.schema.message import Message
+from lfx.template.field.base import Output
+
+from ._component_base import AtomicMemoryComponentMixin
+from ._inputs import connection_inputs, scope_inputs
+from ._messages import coerce_text, sender_to_role
+
+MAX_CONTENT_CHARS = 100_000  # Core rejects conversations beyond this.
+
+
+class AtomicMemoryStoreMessageComponent(AtomicMemoryComponentMixin, Component):
+    display_name = "Store Message (AtomicMemory)"
+    description = "Store a message/turn into AtomicMemory (explicit, visible write)."
+    name = "AtomicMemoryStoreMessage"
+    icon = "save"
+
+    inputs = [
+        MessageTextInput(name="message", display_name="Message", required=True),
+        DropdownInput(
+            name="sender",
+            display_name="Sender",
+            options=["User", "Machine", "System", "Tool"],
+            value="User",
+        ),
+        DropdownInput(
+            name="content_class",
+            display_name="Content Class",
+            options=["raw", "summary", "redacted"],
+            value="raw",
+            info=(
+                "How the core treats the stored transcript under "
+                "RAW_CONTENT_POLICY=reject. 'raw' (default): the message is extracted "
+                "into searchable memories but the raw transcript is omitted from the "
+                "audit episode. Choose 'summary' or 'redacted' only when the message is "
+                "genuinely distilled or has had sensitive spans removed."
+            ),
+        ),
+        *connection_inputs(),
+        *scope_inputs(),
+    ]
+
+    outputs = [Output(name="stored_message", display_name="Stored Message", method="store_message")]
+
+    def store_message(self) -> Message:
+        text = coerce_text(self.message).strip()
+        if not text:
+            # Fail closed even on API/tweak paths (the UI marks the field required).
+            raise ValueError("Store Message requires non-empty message content.")
+        if len(text) > MAX_CONTENT_CHARS:
+            raise ValueError(
+                f"message is {len(text)} chars; AtomicMemory Core limit is {MAX_CONTENT_CHARS}."
+            )
+        scope = self._build_scope()
+        bridge = self._build_bridge()
+        role = sender_to_role(self.sender)
+        result = bridge.ingest_messages(
+            scope=scope,
+            messages=[{"role": role, "content": text}],
+            metadata={"kind": "turn"},
+            content_class=self.content_class or None,
+        )
+        outcome = {
+            "created": len(getattr(result, "created", []) or []),
+            "updated": len(getattr(result, "updated", []) or []),
+            "unchanged": len(getattr(result, "unchanged", []) or []),
+        }
+        self.status = (
+            f"stored · +{outcome['created']} ~{outcome['updated']} ={outcome['unchanged']}"
+        )
+        return Message(
+            text=text,
+            sender=self.sender,
+            sender_name="AtomicMemory",
+            session_metadata={"atomicmemory": outcome},
+        )

atomicmemory_langflow-0.1.17.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: atomicmemory-langflow
+Version: 0.1.17
+Summary: AtomicMemory custom components for Langflow.
+Author: Atomic Strata
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/atomicstrata/atomicmemory
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: atomicmemory<2.0.0,>=1.1.0
+Requires-Dist: langchain-core<2.0,>=0.3
+Provides-Extra: langflow
+Requires-Dist: langflow<2.0,>=1.6; extra == "langflow"
+
+# AtomicMemory components for Langflow
+
+Four Langflow custom components backed by the Python `atomicmemory` SDK:
+
+They appear in the Langflow component sidebar under the **atomicmemory** category:
+
+| Component | Purpose |
+|-----------|---------|
+| **Chat Memory (AtomicMemory)** | Read-only chat history (Message History backend) from a user/session scope. |
+| **Search Context (AtomicMemory)** | Query-driven, prompt-ready memory context, **user-scoped across sessions** by default (packaged or search-only). |
+| **Store Message (AtomicMemory)** | Explicitly persist a message/turn into memory. |
+| **Delete Memories in Scope (AtomicMemory)** | Best-effort erasure of a scope's memories (confirm-gated). |
+
+## Requirements & compatibility
+
+- Python ≥ 3.10, `atomicmemory >= 1.0.1`, `langchain-core`.
+- **Langflow is the host** and must be installed in the same environment.
+  Tested with Langflow `>=1.6,<2.0` (the components import a few `lfx` internals;
+  see the loader smoke test). Newer Langflow majors may move these symbols.
+- A running **AtomicMemory Core** (default `http://localhost:17350`). Core needs
+  an LLM/embeddings key for ingest extraction.
+
+> **Heads up:** ingest runs synchronous LLM extraction + embedding, so storing a
+> memory can take **seconds (sometimes ~20s)**. Writes are explicit (Store Message)
+> so this latency is visible, not hidden. Chat Memory is **read-only** — it never
+> auto-writes on every turn. If the backend is unreachable, Chat Memory **fails
+> closed** (raises a clear error) by default; set its `Fail open on error` toggle
+> to return empty history instead.
+
+## Install
+
+```bash
+pip install atomicmemory-langflow            # into Langflow's environment
+# copy the component entry files into your Langflow components root:
+npx @atomicmemory/langflow-plugin --target ~/.langflow/components --python <langflow-python>
+# or set the components root via env instead of --target:
+LANGFLOW_COMPONENTS_PATH=~/.langflow/components npx @atomicmemory/langflow-plugin --python <langflow-python>
+```
+Restart Langflow; the components appear under the **atomicmemory** category.
+
+## Scope, identity & multi-tenant safety
+
+Memory is scoped by `user` (required) and optional `session` (thread).
+`User ID` defaults to the **Langflow run user** when blank; an explicit value
+overrides it. Note this is run context, not strong auth — in CLI/anonymous paths
+Langflow may auto-generate an opaque user id.
+
+**Search Context recalls user-scoped (across sessions) by default** — long-term
+memory should persist beyond a single conversation, and Core hard-filters
+search/list by session. Set its advanced `Scope to session` toggle to restrict
+retrieval to the current session. Chat Memory (this-conversation history) and
+Store Message remain session-aware.
+
+(`namespace` is not exposed in Phase 1: the AtomicMemory Python provider only
+applies it on search/package, not ingest/list/delete, so exposing it would
+silently break store/delete scoping. It returns once the SDK honors it end-to-end.)
+
+**Trust boundary:** scope is the only memory boundary, and Langflow lets `user_id`/
+`session_id` be set via flow inputs/tweaks. In shared / multi-tenant / Cloud
+deployments, control who can edit and run flows — a flow author who sets `user_id`
+can read/write that user's memories.
+
+## Security
+
+- Put API keys only in the **API Key** (secret) field — never in **Provider Config**
+  (it is stored in plaintext in the flow). **Provider Config is allowlist-only**:
+  only known tuning keys (`timeoutSeconds`, `apiVersion`) are accepted; everything
+  else — URLs, keys, and any secret-shaped key (`accessToken`, `clientSecret`, …) —
+  is rejected.
+- **`provider` is validated**: Phase 1 accepts only `atomicmemory`, even via API/tweaks
+  (the UI dropdown is not the only guard).
+- **`API URL` is fail-closed for remote hosts.** It must be `http(s)` and resolve to a
+  local host by default; pointing memory at a non-local endpoint requires the
+  **operator** (not the flow author) to opt in via `ATOMICMEMORY_LANGFLOW_ALLOW_REMOTE=1`
+  or `ATOMICMEMORY_LANGFLOW_ALLOWED_HOSTS=host1,host2`. **This is not full SSRF
+  protection:** it does not sandbox the loopback interface, so a flow author can still
+  reach services bound to the Langflow host's `localhost`/`127.0.0.1` (any port). Treat
+  flow authors as trusted, or add network-egress controls, on shared/multi-tenant/cloud
+  deployments.
+- Retrieved memory is emitted as ordinary context, never as a system message.
+
+## Provider neutrality
+
+`provider` defaults to `atomicmemory` (the only Phase 1 tested provider). The
+architecture is provider-neutral — provider name + `provider_config` flow to the
+SDK — but other providers are not yet listed in the dropdown.
+
+## Testing & known follow-ups
+
+Unit tests run without a live backend (`cd plugins/langflow && python -m unittest
+discover -s tests`); the SDK-contract and Langflow-loader tests exercise the real
+`atomicmemory` SDK models and `lfx` template builder when those packages are
+installed.
+
+Follow-ups (tracked, not yet in this PR):
+- **End-to-end lane against a real AtomicMemory Core** (Docker + Core + an LLM key):
+  Store Message → Search Context → Delete with synthetic data, with the package
+  installed into a Langflow-compatible venv. Unit tests use fakes/model coercion;
+  this lane would catch integration drift the fakes can't.
+- **Namespace scoping** once the Python SDK honors it on ingest/list/delete (today
+  only search/package), at which point the `namespace` input returns.
+- **Branded AtomicMemory icon** (vendor logo, like the model providers') — **deferred**.
+  Each component currently uses a distinct Lucide icon (`save` / `search` /
+  `messages-square` / `trash`). A real brand mark is a Langflow *vendor icon*, which
+  per Langflow's docs requires frontend changes (an `@/icons/AtomicMemory` SVG +
+  forwardRef wrapper + a `lazyIconImports` entry) and so cannot ship from a Python
+  component bundle — it needs an upstream Langflow PR. Logo SVGs exist under
+  `supermem-internal-web/static/img/`.

atomicmemory_langflow-0.1.17.dist-info/RECORD

@@ -0,0 +1,16 @@
+atomicmemory_langflow/__init__.py,sha256=6Wmwc7_WALEKWoB81f8GtQuoZsPulQ3r8ThkPHXjmLQ,922
+atomicmemory_langflow/_chat_history.py,sha256=TM0mAwEeo2262jmVssnJ38mG0Bn9RiV4NfKlkQBMHx8,2309
+atomicmemory_langflow/_component_base.py,sha256=uIi0XyhSzSNIzAmVhgjYcZyPrN0UoEHKLiWIDAwtV0k,2092
+atomicmemory_langflow/_inputs.py,sha256=bA4MpD1RoqaSY7H__2SiDwL1XEK7nk1my27uyYWOMbE,2288
+atomicmemory_langflow/_messages.py,sha256=m9e30U5u5-FLLtHlF2wA2s02Iq2gKNiLx2VnNDUZuMA,2488
+atomicmemory_langflow/_scope.py,sha256=OhhyBRWn9cQL8FQnHflCSsH8_7xwsDl8PE9d-P5QVDQ,1033
+atomicmemory_langflow/_sdk.py,sha256=Xl2X01blvy-VVueepvHgvI4I_W-zzyUmLIk-iNwMFdc,9379
+atomicmemory_langflow/chat_memory.py,sha256=j4-MwH_aETGbDaAZGbKPzPY9C1el41TfUQw0ka7FHyI,1976
+atomicmemory_langflow/delete.py,sha256=iML1ckmhOOyY-hauQuAbesBCh0qXJ--zUGIVkwefzOs,2021
+atomicmemory_langflow/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+atomicmemory_langflow/search_context.py,sha256=k9m1XNfoYUhXrKTelbDloSn1FNA-3iuhEjsoMuxWbCM,3942
+atomicmemory_langflow/store_message.py,sha256=HtQpjpRGGl-TSQ8_lg38k7EbnxZoKYehsd62qf6vwLU,3244
+atomicmemory_langflow-0.1.17.dist-info/METADATA,sha256=rnhVgWOwDPBEBvZHZ_RkG5ht1XsQM0kCvY2TtDhef1s,6546
+atomicmemory_langflow-0.1.17.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+atomicmemory_langflow-0.1.17.dist-info/top_level.txt,sha256=UbvY-0cwzAFYyiRSMHXHxVV59K0tohp7dYXlmqplrXU,22
+atomicmemory_langflow-0.1.17.dist-info/RECORD,,

atomicmemory_langflow-0.1.17.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

atomicmemory_langflow-0.1.17.dist-info/top_level.txt

@@ -0,0 +1 @@
+atomicmemory_langflow