crewai-pastdotdev 0.1.0__tar.gz

crewai_pastdotdev-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.egg-info/
+.venv/
+.pytest_cache/
+dist/
+build/
+.crewai/

crewai_pastdotdev-0.1.0/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.

crewai_pastdotdev-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,195 @@
+# 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/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "crewai-pastdotdev"
+dynamic = ["version"]
+description = "past dev for CrewAI: Ingest and Recall as crew memory and as agent tools."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "past.dev", email = "louis@past.dev" }]
+maintainers = [{ name = "past.dev", email = "louis@past.dev" }]
+requires-python = ">=3.10,<3.14"
+dependencies = [
+    "crewai>=1.14.6,<2",
+    "httpx>=0.27,<1",
+]
+keywords = ["crewai", "memory", "agents", "llm", "past dev", "recall"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://past.dev"
+Documentation = "https://past.dev/docs/memory-api/quickstart"
+"API reference" = "https://past.dev/docs/memory-api/api-reference"
+Source = "https://github.com/pastdotdev/crewai-pastdotdev"
+
+[tool.hatch.version]
+path = "src/crewai_pastdotdev/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/crewai_pastdotdev"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "pyproject.toml"]
+exclude = ["DOCS_PR.md", "PUBLISHING.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["live: calls the real past dev API (skipped unless PAST_API_KEY is set)"]

crewai_pastdotdev-0.1.0/src/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-0.1.0/src/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-0.1.0/src/crewai_pastdotdev/_version.py

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