crewai-pastdotdev 0.1.0__py3-none-any.whl

crewai_pastdotdev/__init__.py

@@ -0,0 +1,23 @@
+"""past dev for CrewAI: Ingest and Recall as crew memory and as agent tools."""
+
+from crewai_pastdotdev._version import __version__
+from crewai_pastdotdev.client import DEFAULT_API_HOST, PastDevClient, PastDevError
+from crewai_pastdotdev.memory import PastDevMemory
+from crewai_pastdotdev.tools import (
+    PastDevIngestInput,
+    PastDevIngestTool,
+    PastDevRecallInput,
+    PastDevRecallTool,
+)
+
+__all__ = [
+    "DEFAULT_API_HOST",
+    "PastDevClient",
+    "PastDevError",
+    "PastDevIngestInput",
+    "PastDevIngestTool",
+    "PastDevMemory",
+    "PastDevRecallInput",
+    "PastDevRecallTool",
+    "__version__",
+]

crewai_pastdotdev/_common.py

@@ -0,0 +1,85 @@
+"""Helpers shared by the memory and the tools."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from datetime import datetime, timezone
+from typing import Any
+
+from pydantic import SecretStr
+
+from crewai_pastdotdev.client import PastDevClient
+
+MAX_IDENTITY_LENGTH = 200
+RECALL_LIMIT_MAX = 200
+
+_FRACTION = re.compile(r"(\.\d{6})\d+")
+
+
+def check_identity(identity: str) -> str:
+    """Return the identity, or raise ``ValueError`` if past dev would refuse it."""
+    if not identity or not identity.strip():
+        raise ValueError("past dev needs an identity: the id of the person the memory is about.")
+    if len(identity) > MAX_IDENTITY_LENGTH:
+        raise ValueError(f"A past dev identity is at most {MAX_IDENTITY_LENGTH} characters.")
+    return identity
+
+
+def make_client(
+    client: PastDevClient | None, api_key: SecretStr | None, api_host: str | None
+) -> PastDevClient:
+    if client is not None:
+        return client
+    return PastDevClient(
+        api_key=api_key.get_secret_value() if api_key is not None else None,
+        api_host=api_host,
+    )
+
+
+def source_id_for(identity: str, content: str) -> str:
+    """A stable source id for one piece of content from one identity.
+
+    The same content from the same identity gets the same id, so a repeated
+    ingest is recognized as unchanged and costs nothing. Two identities that
+    send the same words keep two separate data points.
+    """
+    digest = hashlib.sha256(f"{identity}\x00{content}".encode()).hexdigest()
+    return f"crewai-{digest}"
+
+
+def clamp_limit(limit: int) -> int:
+    return max(1, min(int(limit), RECALL_LIMIT_MAX))
+
+
+def parse_datetime(value: str | None) -> datetime | None:
+    """Parse an API date-time (ISO 8601, ``Z`` suffix, up to 7 decimals)."""
+    if not value:
+        return None
+    text = _FRACTION.sub(r"\1", value.replace("Z", "+00:00"))
+    try:
+        parsed = datetime.fromisoformat(text)
+    except ValueError:
+        return None
+    return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
+
+
+def format_recall(response: dict[str, Any]) -> str:
+    """Render a recall response as text for an agent to read."""
+    results = response.get("results") or []
+    if not results:
+        return "past dev found no relevant memories."
+    lines = [f"past dev recalled {len(results)} memories, most relevant first:"]
+    for result in results:
+        date = (result.get("occurredAt") or "")[:10]
+        artifact = result.get("artifact") or {}
+        superseded = artifact.get("supersededAt")
+        head = f"{result.get('rank', '?')}. [{date}] {result.get('content', '').strip()}"
+        if superseded:
+            head += f" (superseded on {superseded[:10]})"
+        lines.append(head)
+        for source in result.get("sources") or []:
+            name = source.get("label") or source.get("sourceId")
+            for excerpt in source.get("excerpts") or []:
+                lines.append(f'   - "{excerpt}" ({name}, {(source.get("occurredAt") or "")[:10]})')
+    return "\n".join(lines)

crewai_pastdotdev/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

crewai_pastdotdev/client.py

@@ -0,0 +1,289 @@
+"""A small HTTP client for the past dev Memory API.
+
+Only the operations this package uses: Ingest, Recall, Delete data point,
+and the two list reads (audiences, identities). See
+https://past.dev/docs/memory-api/api-reference for the full API.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from collections.abc import Iterator
+from datetime import datetime
+from typing import Any, Literal
+from urllib.parse import quote
+
+import httpx
+
+from crewai_pastdotdev._version import __version__
+
+DEFAULT_API_HOST = "https://api.past.dev"
+
+RecallLevel = Literal["low", "medium", "high", "extra-high"]
+RecallSort = Literal["relevance", "chronological"]
+
+# A 429 with one of these codes is a monthly or billing-period cap.
+# Waiting a few seconds does not lift it, so it is not retried.
+_CAP_CODES = frozenset({"project-cap-reached", "spend-cap-reached"})
+
+
+class PastDevError(Exception):
+    """An error response from the past dev API, or a failed request.
+
+    ``code`` is the API's stable kebab-case code (for example
+    ``out-of-credits``), ``status`` the HTTP status (0 when no response came
+    back) and ``request_id`` the ``X-Request-Id`` header, which past dev
+    support can trace.
+    """
+
+    def __init__(
+        self,
+        code: str,
+        status: int,
+        message: str | None = None,
+        request_id: str | None = None,
+        data: Any = None,
+    ) -> None:
+        self.code = code
+        self.status = status
+        self.message = message
+        self.request_id = request_id
+        self.data = data
+        text = f"past dev error {code} (HTTP {status})"
+        if message:
+            text += f": {message}"
+        if request_id:
+            text += f" [request id {request_id}]"
+        super().__init__(text)
+
+
+def _iso(value: datetime | str | None) -> str | None:
+    if value is None or isinstance(value, str):
+        return value
+    return value.isoformat()
+
+
+def _compact(body: dict[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in body.items() if v is not None}
+
+
+class PastDevClient:
+    """Synchronous client for the past dev Memory API.
+
+    Args:
+        api_key: A project API key (``past_sk_...``). Read from the
+            ``PAST_API_KEY`` environment variable when omitted.
+        api_host: The API host. Read from ``PAST_API_HOST`` when omitted,
+            else ``https://api.past.dev``. Set it when past dev runs in your
+            own cloud.
+        timeout: Seconds before a request times out.
+        max_retries: How many times a rate-limited request (HTTP 429) is
+            sent again, after the wait the server asks for. Other errors are
+            never retried.
+        transport: An ``httpx`` transport, for tests.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        api_host: str | None = None,
+        *,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        key = api_key or os.environ.get("PAST_API_KEY")
+        if not key:
+            raise ValueError(
+                "past dev needs a project API key: pass api_key or set PAST_API_KEY."
+            )
+        host = (api_host or os.environ.get("PAST_API_HOST") or DEFAULT_API_HOST).rstrip("/")
+        self.api_host = host
+        self.max_retries = max_retries
+        self._http = httpx.Client(
+            base_url=host,
+            timeout=timeout,
+            transport=transport,
+            headers={
+                "Authorization": f"Bearer {key}",
+                "User-Agent": f"crewai-pastdotdev/{__version__}",
+                "Accept": "application/json",
+            },
+        )
+
+    def __repr__(self) -> str:
+        return f"PastDevClient(api_host={self.api_host!r})"
+
+    def __deepcopy__(self, memo: dict[int, Any]) -> PastDevClient:
+        # CrewAI deep-copies agents and memory. The HTTP pool is thread-safe,
+        # so copies share it instead of opening a second one.
+        return self
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> PastDevClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # -- operations ---------------------------------------------------------
+
+    def ingest(
+        self,
+        content: str,
+        *,
+        identity: str | None = None,
+        id: str | None = None,
+        timestamp: datetime | str | None = None,
+        audience: str | None = None,
+        label: str | None = None,
+        metadata: Any = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        """Ingest one data point. ``POST /api/v1/ingest``.
+
+        Returns the receipt: ``projectId``, ``ingestionId``, ``sourceId``,
+        ``status`` (``queued`` or ``completed``) and ``unchanged``.
+        """
+        body = _compact(
+            {
+                "content": content,
+                "identity": identity,
+                "id": id,
+                "timestamp": _iso(timestamp),
+                "audience": audience,
+                "label": label,
+                "metadata": metadata,
+                "idempotencyKey": idempotency_key,
+            }
+        )
+        return self._request("POST", "/api/v1/ingest", json=body)
+
+    def recall(
+        self,
+        query: str,
+        *,
+        identity: str,
+        limit: int | None = None,
+        level: RecallLevel | None = None,
+        max_tokens: int | None = None,
+        query_timestamp: datetime | str | None = None,
+        occurred_from: datetime | str | None = None,
+        occurred_to: datetime | str | None = None,
+        sort: RecallSort | None = None,
+    ) -> dict[str, Any]:
+        """Recall ranked memory documents. ``POST /api/v1/recall``.
+
+        Returns ``asOf``, ``usedEvidenceTokens`` and ``results``; each result
+        carries ``id``, ``rank``, ``occurredAt``, ``content``, ``artifact``
+        and ``sources``.
+        """
+        if level is not None and max_tokens is not None:
+            raise ValueError("Send level or max_tokens, never both.")
+        body = _compact(
+            {
+                "query": query,
+                "identity": identity,
+                "limit": limit,
+                "level": level,
+                "maxTokens": max_tokens,
+                "queryTimestamp": _iso(query_timestamp),
+                "occurredFrom": _iso(occurred_from),
+                "occurredTo": _iso(occurred_to),
+                "sort": sort,
+            }
+        )
+        return self._request("POST", "/api/v1/recall", json=body)
+
+    def delete_data_point(self, source_id: str) -> dict[str, Any]:
+        """Delete one data point by its source id.
+        ``DELETE /api/v1/data-points/{sourceId}``.
+
+        Returns the deletion receipt (``operationId``, ``ids``). The purge
+        completes in the background.
+        """
+        return self._request("DELETE", f"/api/v1/data-points/{quote(source_id, safe='')}")
+
+    def list_audiences(self) -> list[dict[str, Any]]:
+        """List the project's audiences. ``GET /api/v1/audiences``.
+
+        Costs no credits, so it also serves as a connection test.
+        """
+        return list(self._request("GET", "/api/v1/audiences").get("audiences", []))
+
+    def list_identities(self, *, page_size: int = 100) -> Iterator[dict[str, Any]]:
+        """Iterate over every identity of the project, page by page.
+        ``GET /api/v1/identities``.
+        """
+        after: str | None = None
+        while True:
+            params: dict[str, Any] = {"limit": page_size}
+            if after:
+                params["after"] = after
+            page = self._request("GET", "/api/v1/identities", params=params)
+            yield from page.get("identities", [])
+            after = page.get("endCursor")
+            if not page.get("hasMore") or not after:
+                return
+
+    def check_connection(self) -> None:
+        """Raise :class:`PastDevError` unless the key and host work.
+
+        Calls ``GET /api/v1/audiences``, which costs no credits.
+        """
+        self.list_audiences()
+
+    # -- transport ----------------------------------------------------------
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        attempt = 0
+        while True:
+            try:
+                response = self._http.request(method, path, **kwargs)
+            except httpx.HTTPError as exc:
+                raise PastDevError("network-error", 0, str(exc)) from exc
+            if response.status_code < 400:
+                if not response.content:
+                    return {}
+                return dict(response.json())
+            error = _error_from(response)
+            if (
+                response.status_code == 429
+                and error.code not in _CAP_CODES
+                and attempt < self.max_retries
+            ):
+                attempt += 1
+                time.sleep(_retry_after(response, attempt))
+                continue
+            raise error
+
+
+def _error_from(response: httpx.Response) -> PastDevError:
+    request_id = response.headers.get("X-Request-Id")
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+    if isinstance(body, dict) and "code" in body:
+        return PastDevError(
+            str(body["code"]),
+            int(body.get("status") or response.status_code),
+            body.get("debugMessage"),
+            request_id,
+            body.get("data"),
+        )
+    code = "rate-limited" if response.status_code == 429 else f"http-{response.status_code}"
+    return PastDevError(code, response.status_code, response.text or None, request_id)
+
+
+def _retry_after(response: httpx.Response, attempt: int) -> float:
+    header = response.headers.get("Retry-After")
+    if header:
+        try:
+            return min(max(float(header), 0.0), 60.0)
+        except ValueError:
+            pass
+    return float(min(2 ** (attempt - 1), 8))

crewai_pastdotdev/memory.py

@@ -0,0 +1,366 @@
+"""past dev as CrewAI memory.
+
+CrewAI 1.x has one ``Memory`` class. Its storage backends are vector stores
+that receive embeddings, while past dev takes text and does its own
+extraction, embedding and ranking. So this integration subclasses ``Memory``
+and replaces the operations a crew calls: a save is a past dev Ingest and a
+search is a past dev Recall. A crew accepts it wherever it accepts a
+``Memory``::
+
+    crew = Crew(agents=..., tasks=..., memory=PastDevMemory(identity="user-42"))
+"""
+
+from __future__ import annotations
+
+import time
+from datetime import datetime
+from typing import Annotated, Any, Literal
+
+from crewai.events.event_bus import crewai_event_bus
+from crewai.events.types.memory_events import (
+    MemoryQueryCompletedEvent,
+    MemoryQueryFailedEvent,
+    MemoryQueryStartedEvent,
+)
+from crewai.memory.types import MemoryMatch, MemoryRecord
+from crewai.memory.unified_memory import Memory
+from crewai.memory.utils import join_scope_paths
+from pydantic import Field, PlainValidator, PrivateAttr, SecretStr, field_validator, model_validator
+
+from crewai_pastdotdev._common import (
+    check_identity,
+    clamp_limit,
+    make_client,
+    parse_datetime,
+    source_id_for,
+)
+from crewai_pastdotdev.client import PastDevClient, PastDevError, RecallLevel
+
+_SOURCE_TYPE = "past_dev"
+
+
+def _passthrough(value: Any) -> Any:
+    return value
+
+
+class _NoLocalStore:
+    """Stands in for CrewAI's local vector store, which past dev replaces.
+
+    past dev keeps memory on its servers, so the local browse and edit
+    operations (``tree``, ``info``, ``list_records``, ``update`` ...) have
+    nothing to read. They raise with a pointer to what to use instead.
+    """
+
+    _MESSAGE = (
+        "past dev keeps memory on its servers, not in a local store. "
+        "Use recall() to read, remember() to ingest, forget(record_ids=[...]) "
+        "to delete data points, and the past dev console to browse."
+    )
+
+    def _unsupported(self, *args: Any, **kwargs: Any) -> Any:
+        raise NotImplementedError(self._MESSAGE)
+
+    save = search = delete = update = get_record = list_records = _unsupported
+    get_scope_info = list_scopes = list_categories = count = reset = _unsupported
+    asave = asearch = adelete = _unsupported
+
+    def __deepcopy__(self, memo: dict[int, Any]) -> _NoLocalStore:
+        return self
+
+
+class PastDevMemory(Memory):
+    """CrewAI memory backed by past dev.
+
+    Saves are past dev Ingests and searches are past dev Recalls, for one
+    fixed identity. The identity is the id of the person (or account) the
+    memory belongs to; your code sets it, never the model.
+
+    Args:
+        identity: The past dev identity every Ingest and Recall uses.
+        api_key: A project API key (``past_sk_...``). Defaults to the
+            ``PAST_API_KEY`` environment variable.
+        api_host: Defaults to ``PAST_API_HOST``, else ``https://api.past.dev``.
+        audience: An audience slug for ingested memories. Omit it for
+            project-visible memory.
+        label: An optional short title stored with each ingested data point.
+        recall_level: The recall evidence budget: ``low`` (default),
+            ``medium``, ``high`` or ``extra-high``.
+        recall_max_tokens: An explicit evidence budget in tokens, instead of
+            ``recall_level``.
+        client: A ready :class:`PastDevClient`, instead of ``api_key`` and
+            ``api_host``.
+
+    past dev extracts memories on its side, so ``extract_memories`` does not
+    call an LLM: a crew's task result is ingested as one data point, as
+    written. CrewAI scopes and categories are kept in the data point's
+    metadata; recall does not filter on them.
+    """
+
+    identity: str = Field(description="The past dev identity for every Ingest and Recall.")
+    api_key: SecretStr | None = Field(default=None, exclude=True, repr=False)
+    api_host: str | None = Field(default=None)
+    audience: str | None = Field(default=None)
+    label: str | None = Field(default=None)
+    recall_level: RecallLevel | None = Field(default=None)
+    recall_max_tokens: int | None = Field(default=None, ge=1)
+    client: Annotated[PastDevClient | None, PlainValidator(_passthrough)] = Field(
+        default=None, exclude=True, repr=False
+    )
+    storage: Annotated[Any, PlainValidator(_passthrough)] = Field(
+        default_factory=_NoLocalStore, exclude=True, repr=False
+    )
+
+    _client: PastDevClient = PrivateAttr()
+    _owns_client: bool = PrivateAttr(default=False)
+
+    @field_validator("identity")
+    @classmethod
+    def _valid_identity(cls, value: str) -> str:
+        return check_identity(value)
+
+    @model_validator(mode="after")
+    def _one_budget(self) -> PastDevMemory:
+        if self.recall_level is not None and self.recall_max_tokens is not None:
+            raise ValueError("Set recall_level or recall_max_tokens, never both.")
+        return self
+
+    def model_post_init(self, context: Any, /) -> None:
+        super().model_post_init(context)
+        self._owns_client = self.client is None
+        self._client = make_client(self.client, self.api_key, self.api_host)
+
+    def __deepcopy__(self, memo: dict[int, Any] | None = None) -> PastDevMemory:
+        # Memory.__deepcopy__ fails on Python 3.12 and earlier. A copy gets its
+        # own save thread and shares the HTTP client, which is thread-safe.
+        values = {name: getattr(self, name) for name in type(self).model_fields}
+        values["client"] = self._client
+        clone = type(self)(**values)
+        clone._owns_client = False
+        return clone
+
+    # -- save: Ingest -------------------------------------------------------
+
+    def extract_memories(self, content: str) -> list[str]:
+        """Return the content as one item; past dev extracts memories itself."""
+        text = content.strip() if content else ""
+        return [text] if text else []
+
+    def remember_many(
+        self,
+        contents: list[str],
+        scope: str | None = None,
+        categories: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        importance: float | None = None,
+        source: str | None = None,
+        private: bool = False,
+        agent_role: str | None = None,
+        root_scope: str | None = None,
+    ) -> list[MemoryRecord]:
+        # A crew passes the role of the agent that produced the result; keep it.
+        if agent_role:
+            metadata = {"crewai_agent_role": agent_role, **(metadata or {})}
+        return super().remember_many(
+            contents,
+            scope=scope,
+            categories=categories,
+            metadata=metadata,
+            importance=importance,
+            source=source,
+            private=private,
+            agent_role=agent_role,
+            root_scope=root_scope,
+        )
+
+    def _encode_batch(
+        self,
+        contents: list[str],
+        scope: str | None = None,
+        categories: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        importance: float | None = None,
+        source: str | None = None,
+        private: bool = False,
+        root_scope: str | None = None,
+    ) -> list[MemoryRecord]:
+        # Called by Memory.remember() and remember_many() on the save thread,
+        # so events, the write barrier and drain_writes() work unchanged.
+        scope_path: str | None = scope or root_scope
+        if root_scope and scope:
+            scope_path = join_scope_paths(root_scope, scope)
+        sent_metadata = dict(metadata or {})
+        if scope_path:
+            sent_metadata.setdefault("crewai_scope", scope_path)
+        if categories:
+            sent_metadata.setdefault("crewai_categories", list(categories))
+
+        records: list[MemoryRecord] = []
+        for content in contents:
+            if not content or not content.strip():
+                continue
+            receipt = self._client.ingest(
+                content,
+                identity=self.identity,
+                id=source_id_for(self.identity, content),
+                audience=self.audience,
+                label=self.label,
+                metadata=sent_metadata or None,
+            )
+            records.append(
+                MemoryRecord(
+                    id=str(receipt.get("sourceId")),
+                    content=content,
+                    scope=scope_path or "/",
+                    categories=list(categories or []),
+                    metadata={
+                        **sent_metadata,
+                        "ingestion_id": receipt.get("ingestionId"),
+                        "status": receipt.get("status"),
+                    },
+                    importance=importance if importance is not None else self.default_importance,
+                    source=source,
+                    private=private,
+                )
+            )
+        return records
+
+    # -- search: Recall -----------------------------------------------------
+
+    def recall(
+        self,
+        query: str,
+        scope: str | None = None,
+        categories: list[str] | None = None,
+        limit: int = 10,
+        depth: Literal["shallow", "deep"] = "deep",
+        source: str | None = None,
+        include_private: bool = False,
+    ) -> list[MemoryMatch]:
+        """Recall memories for ``query`` through past dev.
+
+        ``limit`` is the number of documents (1 to 200). ``scope``,
+        ``categories``, ``depth``, ``source`` and ``include_private`` are
+        CrewAI options for its local store; past dev ranks on its own and
+        applies the identity's audiences instead.
+        """
+        self.drain_writes()
+        if not query or not query.strip():
+            return []
+        crewai_event_bus.emit(
+            self,
+            MemoryQueryStartedEvent(
+                query=query, limit=limit, score_threshold=None, source_type=_SOURCE_TYPE
+            ),
+        )
+        start = time.perf_counter()
+        try:
+            response = self._client.recall(
+                query,
+                identity=self.identity,
+                limit=clamp_limit(limit),
+                level=self.recall_level,
+                max_tokens=self.recall_max_tokens,
+            )
+            matches = [_to_match(result) for result in response.get("results") or []]
+        except Exception as exc:
+            crewai_event_bus.emit(
+                self,
+                MemoryQueryFailedEvent(
+                    query=query,
+                    limit=limit,
+                    score_threshold=None,
+                    error=str(exc),
+                    source_type=_SOURCE_TYPE,
+                ),
+            )
+            raise
+        crewai_event_bus.emit(
+            self,
+            MemoryQueryCompletedEvent(
+                query=query,
+                results=matches,
+                limit=limit,
+                score_threshold=None,
+                query_time_ms=(time.perf_counter() - start) * 1000,
+                source_type=_SOURCE_TYPE,
+            ),
+        )
+        return matches
+
+    # -- delete: Delete data point -----------------------------------------
+
+    def forget(
+        self,
+        scope: str | None = None,
+        categories: list[str] | None = None,
+        older_than: datetime | None = None,
+        metadata_filter: dict[str, Any] | None = None,
+        record_ids: list[str] | None = None,
+    ) -> int:
+        """Delete data points by source id; returns how many were found.
+
+        The ids are the ``MemoryRecord.id`` values that ``remember()``
+        returns. past dev deletes by source id only, so the other filters
+        are refused.
+        """
+        if scope is not None or categories or older_than is not None or metadata_filter:
+            raise NotImplementedError(
+                "past dev deletes data points by source id only: pass record_ids=[...]."
+            )
+        self.drain_writes()
+        deleted = 0
+        for record_id in record_ids or []:
+            try:
+                self._client.delete_data_point(record_id)
+            except PastDevError as exc:
+                if exc.status == 404:
+                    continue
+                raise
+            deleted += 1
+        return deleted
+
+    def update(self, *args: Any, **kwargs: Any) -> MemoryRecord:
+        raise NotImplementedError(
+            "To change a past dev memory, remember() the new content; "
+            "past dev keeps both and marks the earlier statement as superseded."
+        )
+
+    def reset(self, scope: str | None = None) -> None:
+        raise NotImplementedError(
+            "past dev does not erase a project from CrewAI. Delete data points "
+            "with forget(record_ids=[...]), or use the past dev console."
+        )
+
+    def reset_all(self) -> None:
+        self.reset()
+
+    def close(self) -> None:
+        super().close()
+        if self._owns_client:
+            self._client.close()
+
+
+def _to_match(result: dict[str, Any]) -> MemoryMatch:
+    artifact = result.get("artifact") or {}
+    sources = result.get("sources") or []
+    occurred_at = parse_datetime(result.get("occurredAt"))
+    metadata: dict[str, Any] = {
+        "occurred_at": result.get("occurredAt"),
+        "kind": artifact.get("kind"),
+        "superseded_at": artifact.get("supersededAt"),
+        "source_ids": [s.get("sourceId") for s in sources] or None,
+        "excerpts": [e for s in sources for e in (s.get("excerpts") or [])] or None,
+    }
+    record_fields: dict[str, Any] = {
+        "id": str(result.get("id")),
+        "content": str(result.get("content", "")),
+        "metadata": {k: v for k, v in metadata.items() if v is not None},
+    }
+    if occurred_at is not None:
+        record_fields["created_at"] = occurred_at
+    rank = int(result.get("rank") or 1)
+    return MemoryMatch(
+        record=MemoryRecord(**record_fields),
+        score=1.0 / rank,
+        match_reasons=[f"past dev rank {rank}"],
+    )

crewai_pastdotdev/tools.py

@@ -0,0 +1,168 @@
+"""past dev Recall and Ingest as CrewAI tools.
+
+The model gives only the query or the content. The identity, the key and
+every other setting are fixed when you build the tool, so an agent can never
+read or write the memory of another person.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Annotated, Any
+
+from crewai.tools import BaseTool, EnvVar
+from pydantic import BaseModel, Field, PlainValidator, PrivateAttr, SecretStr, field_validator
+
+from crewai_pastdotdev._common import (
+    check_identity,
+    clamp_limit,
+    format_recall,
+    make_client,
+    source_id_for,
+)
+from crewai_pastdotdev.client import PastDevClient, PastDevError, RecallLevel
+
+
+def _passthrough(value: Any) -> Any:
+    return value
+
+
+def _describe(error: PastDevError, operation: str) -> str:
+    text = f"past dev {operation} failed: {error}."
+    if error.status in (400, 401, 402, 403, 404, 409, 413) or error.code.endswith("-cap-reached"):
+        text += " Do not retry this call."
+    return text
+
+
+class PastDevRecallInput(BaseModel):
+    query: str = Field(
+        ...,
+        description="What to look for in memory, as a natural-language question or topic.",
+    )
+
+
+class PastDevIngestInput(BaseModel):
+    content: str = Field(
+        ...,
+        description=(
+            "The facts, decisions or observations to keep, written as complete, "
+            "self-contained text."
+        ),
+    )
+
+
+def _env_vars() -> list[EnvVar]:
+    return [
+        EnvVar(name="PAST_API_KEY", description="A past dev project API key (past_sk_...)."),
+        EnvVar(
+            name="PAST_API_HOST",
+            description="The past dev API host, for a deployment in your own cloud.",
+            required=False,
+            default="https://api.past.dev",
+        ),
+    ]
+
+
+class _PastDevTool(BaseTool):
+    identity: str = Field(description="The past dev identity, fixed by the builder.")
+    env_vars: list[EnvVar] = Field(default_factory=_env_vars)
+    api_key: SecretStr | None = Field(default=None, exclude=True, repr=False)
+    api_host: str | None = Field(default=None)
+    client: Annotated[PastDevClient | None, PlainValidator(_passthrough)] = Field(
+        default=None, exclude=True, repr=False
+    )
+
+    _client: PastDevClient = PrivateAttr()
+
+    @field_validator("identity")
+    @classmethod
+    def _valid_identity(cls, value: str) -> str:
+        return check_identity(value)
+
+    def model_post_init(self, context: Any, /) -> None:
+        super().model_post_init(context)
+        self._client = make_client(self.client, self.api_key, self.api_host)
+
+
+class PastDevRecallTool(_PastDevTool):
+    """Recall what past dev remembers about the fixed identity.
+
+    Args:
+        identity: The past dev identity to recall for. Set by your code.
+        api_key: A project API key; defaults to ``PAST_API_KEY``.
+        api_host: Defaults to ``PAST_API_HOST``, else ``https://api.past.dev``.
+        limit: The maximum number of memories returned (1 to 200).
+        level: The evidence budget: ``low``, ``medium``, ``high`` or ``extra-high``.
+    """
+
+    name: str = "past dev Recall"
+    description: str = (
+        "Recall memories from past dev: earlier facts, decisions, preferences and "
+        "events about the current user. Returns the most relevant memories with "
+        "their dates and quotations from their sources."
+    )
+    args_schema: type[BaseModel] = PastDevRecallInput
+    limit: int = Field(default=10, ge=1, le=200)
+    level: RecallLevel | None = Field(default=None)
+
+    def _run(self, query: str, **kwargs: Any) -> str:
+        if not query or not query.strip():
+            return "past dev Recall needs a query."
+        try:
+            response = self._client.recall(
+                query, identity=self.identity, limit=clamp_limit(self.limit), level=self.level
+            )
+        except PastDevError as error:
+            return _describe(error, "Recall")
+        return format_recall(response)
+
+    async def _arun(self, query: str, **kwargs: Any) -> str:
+        return await asyncio.to_thread(self._run, query)
+
+
+class PastDevIngestTool(_PastDevTool):
+    """Ingest new information into past dev for the fixed identity.
+
+    Args:
+        identity: The past dev identity the content belongs to. Set by your code.
+        api_key: A project API key; defaults to ``PAST_API_KEY``.
+        api_host: Defaults to ``PAST_API_HOST``, else ``https://api.past.dev``.
+        audience: An audience slug; omit it for project-visible memory.
+        label: An optional short title stored with each data point.
+        metadata: Optional JSON stored with each data point.
+    """
+
+    name: str = "past dev Ingest"
+    description: str = (
+        "Ingest information into past dev so it can be recalled later: facts, "
+        "decisions, preferences or outcomes worth keeping about the current user. "
+        "Send complete, self-contained text."
+    )
+    args_schema: type[BaseModel] = PastDevIngestInput
+    audience: str | None = Field(default=None)
+    label: str | None = Field(default=None)
+    metadata: dict[str, Any] | None = Field(default=None)
+
+    def _run(self, content: str, **kwargs: Any) -> str:
+        if not content or not content.strip():
+            return "past dev Ingest needs content."
+        try:
+            receipt = self._client.ingest(
+                content,
+                identity=self.identity,
+                id=source_id_for(self.identity, content),
+                audience=self.audience,
+                label=self.label,
+                metadata=self.metadata,
+            )
+        except PastDevError as error:
+            return _describe(error, "Ingest")
+        if receipt.get("unchanged"):
+            return f"past dev already has this content (source id {receipt.get('sourceId')})."
+        return (
+            f"Ingested into past dev (source id {receipt.get('sourceId')}, "
+            f"status {receipt.get('status')}). It can be recalled once processing completes."
+        )
+
+    async def _arun(self, content: str, **kwargs: Any) -> str:
+        return await asyncio.to_thread(self._run, content)

crewai_pastdotdev-0.1.0.dist-info/METADATA

@@ -0,0 +1,225 @@
+Metadata-Version: 2.5
+Name: crewai-pastdotdev
+Version: 0.1.0
+Summary: past dev for CrewAI: Ingest and Recall as crew memory and as agent tools.
+Project-URL: Homepage, https://past.dev
+Project-URL: Documentation, https://past.dev/docs/memory-api/quickstart
+Project-URL: API reference, https://past.dev/docs/memory-api/api-reference
+Project-URL: Source, https://github.com/pastdotdev/crewai-pastdotdev
+Author-email: "past.dev" <louis@past.dev>
+Maintainer-email: "past.dev" <louis@past.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,crewai,llm,memory,past dev,recall
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: <3.14,>=3.10
+Requires-Dist: crewai<2,>=1.14.6
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# crewai-pastdotdev
+
+past dev is a memory API for AI agents. This package connects it to
+[CrewAI](https://www.crewai.com): your crews keep what they learn in past dev
+and recall it in later runs, with the date and the source of every memory.
+
+It gives you two ways to use past dev:
+
+- **`PastDevMemory`**: crew memory. Pass it as `memory=` to a `Crew` or an
+  `Agent`. CrewAI recalls before each task and saves each task result. A save
+  is a past dev **Ingest** and a search is a past dev **Recall**.
+- **`PastDevRecallTool`** and **`PastDevIngestTool`**: tools that an agent
+  calls when it decides to. The model gives only the query or the content.
+
+[Website](https://past.dev) ·
+[Quickstart](https://past.dev/docs/memory-api/quickstart) ·
+[API reference](https://past.dev/docs/memory-api/api-reference)
+
+## Install
+
+```bash
+pip install crewai-pastdotdev
+```
+
+The package needs Python 3.10 to 3.13 and CrewAI 1.14.6 or later.
+
+## Set the API key
+
+Make a project API key in the past dev console. It starts with `past_sk_`.
+
+```bash
+export PAST_API_KEY="past_sk_..."
+```
+
+If you run past dev in your own cloud, also set the API host. The default is
+`https://api.past.dev`.
+
+```bash
+export PAST_API_HOST="https://past.example.com"
+```
+
+You can also give `api_key=` and `api_host=` to each class.
+
+## The identity
+
+Every memory in past dev belongs to an **identity**: the id of the person or
+account the memory is about, for example the user id in your application.
+Recall requires an identity. Ingest makes the identity the first time it sees
+it.
+
+**Your code sets the identity, never the model.** Take it from the user
+record or the trigger of the run, and give it to the constructor. The tools
+have no identity argument, so an agent cannot read or write the memory of
+another person. Make one memory or one tool for each user.
+
+## Use past dev as crew memory
+
+```python
+from crewai import Agent, Crew, Task
+from crewai_pastdotdev import PastDevMemory
+
+memory = PastDevMemory(identity=current_user.id)
+
+writer = Agent(
+    role="Account manager",
+    goal="Write the weekly report the way the customer wants it",
+    backstory="You know the customer well.",
+)
+report = Task(
+    description="Write this week's report for the customer.",
+    expected_output="A report in the format the customer prefers.",
+    agent=writer,
+)
+
+crew = Crew(agents=[writer], tasks=[report], memory=memory)
+crew.kickoff()
+```
+
+What happens in a run:
+
+1. Before each task, CrewAI recalls with the task description. The recalled
+   memories go into the agent's prompt.
+2. After each task, CrewAI saves the task and its result. `PastDevMemory`
+   ingests them as one data point. past dev extracts the memories on its own
+   side, so no extra LLM call runs in your crew.
+3. CrewAI also gives the agents its own "Search memory" and "Save to memory"
+   tools. They go through past dev too.
+
+You can also call the memory directly:
+
+```python
+record = memory.remember("The customer wants the report on Mondays.")
+for match in memory.recall("When does the customer want the report?"):
+    print(match.record.content, match.record.metadata["occurred_at"])
+memory.forget(record_ids=[record.id])  # Delete data point
+```
+
+### Settings
+
+| Argument | Default | What it does |
+| :- | :- | :- |
+| `identity` | required | The identity for every Ingest and Recall. |
+| `api_key` | `PAST_API_KEY` | The project API key. |
+| `api_host` | `PAST_API_HOST`, else `https://api.past.dev` | The API host. |
+| `audience` | none | An audience slug for ingested memories. Without it, a memory is visible to the whole project. |
+| `label` | none | A short title stored with each data point. |
+| `recall_level` | `low` | The evidence budget of a recall: `low`, `medium`, `high` or `extra-high`. |
+| `recall_max_tokens` | none | An exact evidence budget in tokens, instead of `recall_level`. |
+| `read_only` | `False` | Recall only. Nothing is ingested. |
+
+### How CrewAI concepts map to past dev
+
+| CrewAI | past dev |
+| :- | :- |
+| `remember()`, `remember_many()` | Ingest (`POST /api/v1/ingest`). The source id is stable for the same identity and content, so a repeated save is free. |
+| `recall()` | Recall (`POST /api/v1/recall`). `limit` is the number of memories, at most 200. |
+| `forget(record_ids=[...])` | Delete data point (`DELETE /api/v1/data-points/{sourceId}`). |
+| `MemoryMatch.score` | `1 / rank`. past dev ranks the results; it does not return a score. |
+| Scopes, categories, agent role | Kept in the data point's metadata (`crewai_scope`, `crewai_categories`, `crewai_agent_role`). Recall does not filter on them. |
+| `tree()`, `info()`, `list_records()`, `update()`, `reset()` | Not available: past dev keeps memory on its servers. Use the past dev console to browse. To change a fact, remember the new one: past dev marks the earlier statement as superseded. |
+
+## Use past dev as agent tools
+
+```python
+from crewai import Agent
+from crewai_pastdotdev import PastDevIngestTool, PastDevRecallTool
+
+agent = Agent(
+    role="Support agent",
+    goal="Help the customer with what you know about them",
+    backstory="You remember every earlier conversation.",
+    tools=[
+        PastDevRecallTool(identity=current_user.id),
+        PastDevIngestTool(identity=current_user.id),
+    ],
+)
+```
+
+| Tool | The model gives | Other settings (in the constructor) |
+| :- | :- | :- |
+| `PastDevRecallTool` ("past dev Recall") | `query` | `identity`, `limit` (10), `level`, `api_key`, `api_host` |
+| `PastDevIngestTool` ("past dev Ingest") | `content` | `identity`, `audience`, `label`, `metadata`, `api_key`, `api_host` |
+
+The recall tool returns the memories as text: rank, date, content, and the
+quotations from their sources. If a memory was superseded by a later
+statement, the text says so.
+
+## Credits and errors
+
+Every Ingest and every Recall spends credits on your past dev plan. The
+connection check (`PastDevClient().check_connection()`, which reads the
+project's audiences) and Delete data point are free.
+
+An error from the API raises `PastDevError` with the API's `code` (for
+example `out-of-credits`), the HTTP `status`, the message and the
+`request_id`. Give the request id to past dev support when you ask about a
+call. The tools return the error to the agent as text, and tell it not to
+retry when a retry cannot help.
+
+The client sends a request again only when the API answers 429 for the rate
+limit, after the wait the API asks for (two times at most). It never retries
+`402 out-of-credits`, a monthly cap, or a `400`.
+
+## The HTTP client
+
+`PastDevClient` is a small client for the calls this package uses. You can
+use it on its own:
+
+```python
+from crewai_pastdotdev import PastDevClient
+
+with PastDevClient() as past:
+    past.check_connection()
+    past.ingest("The customer moved to Lyon.", identity="user-42", id="crm-note-17")
+    page = past.recall("Where does the customer live?", identity="user-42", limit=5)
+    past.delete_data_point("crm-note-17")
+    audiences = past.list_audiences()
+    identities = list(past.list_identities())
+```
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[test]"
+pytest
+```
+
+The tests use `httpx.MockTransport` and a scripted LLM, so they need no key
+and no network. One live test runs a real Ingest, Recall and Delete data
+point when `PAST_API_KEY` is set. It spends a few credits.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

crewai_pastdotdev-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+crewai_pastdotdev/__init__.py,sha256=ziRGLh13Hjl-4JNUk8ARHsXPJDyhe5rKmvsEYkDFXB0,622
+crewai_pastdotdev/_common.py,sha256=IAbdDdocOcfHpOw4R9u2mIABviYJGWs_LECZwc1HJJk,3033
+crewai_pastdotdev/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+crewai_pastdotdev/client.py,sha256=Ojs6KAbOs1mA7HoWPD3bqy2RS-cA-nXv_uxw2qVXAEg,9919
+crewai_pastdotdev/memory.py,sha256=DStXICIc2w8ewm-IGZ37SowC2jp6tIExYrGgCMWm2eA,13860
+crewai_pastdotdev/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+crewai_pastdotdev/tools.py,sha256=vYZHF0_ZGqIkj_evoB4pcFJ8SX9-G7DmZINI9OEj2F4,6115
+crewai_pastdotdev-0.1.0.dist-info/METADATA,sha256=-BO6KWy6QJNrIBxXhkLrhzYXCwVS40Mq_e_A2gOXCmg,8655
+crewai_pastdotdev-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+crewai_pastdotdev-0.1.0.dist-info/licenses/LICENSE,sha256=IZOT7vW7GYUkxb0mb6kEAwmuFCEDN_0iZZZRvV-W0GI,1065
+crewai_pastdotdev-0.1.0.dist-info/RECORD,,

crewai_pastdotdev-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

crewai_pastdotdev-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 past.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.