llama-index-memory-pastdotdev 0.1.0__tar.gz

llama_index_memory_pastdotdev-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+dist/
+build/
+*.egg-info/
+.DS_Store

llama_index_memory_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.

llama_index_memory_pastdotdev-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.5
+Name: llama-index-memory-pastdotdev
+Version: 0.1.0
+Summary: past dev memory block for LlamaIndex agents: recall and ingest long-term memory with the past dev Memory API
+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: Repository, https://github.com/pastdotdev/llama-index-pastdotdev
+Author-email: "past.dev" <louis@past.dev>
+Maintainer-email: "past.dev" <louis@past.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent memory,llama-index,llamaindex,long-term memory,memory,past dev,past.dev
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <4.0,>=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: llama-index-core<0.15,>=0.13.0
+Description-Content-Type: text/markdown
+
+# LlamaIndex Memory Integration: past dev
+
+past dev is a memory API for AI agents. This package gives a LlamaIndex agent
+long-term memory in [past dev](https://past.dev), as a memory block for the
+LlamaIndex `Memory` class.
+
+- **Get:** the block does a past dev **Recall**. The query is the latest user
+  message. The recalled memory goes into the system message, with the date,
+  the kind and the quoted evidence of each entry.
+- **Put:** when the `Memory` flushes old messages from its short-term queue,
+  the block does a past dev **Ingest** of the user and assistant text, as one
+  data point.
+
+## Install
+
+```bash
+pip install llama-index-memory-pastdotdev
+```
+
+## Get a key
+
+1. Sign up at [past.dev](https://past.dev) and open a project.
+2. Make a project API key. It starts with `past_sk_`.
+3. Set it in the environment as `PAST_API_KEY`, or give it to the block as `api_key`.
+
+## Use
+
+```python
+from llama_index.core.agent.workflow import FunctionAgent
+from llama_index.core.memory import Memory
+from llama_index.llms.openai import OpenAI
+from llama_index.memory.pastdotdev import PastDevMemoryBlock
+
+memory = Memory.from_defaults(
+    session_id="session-42",
+    token_limit=30000,
+    memory_blocks=[
+        PastDevMemoryBlock(
+            identity=current_user.id,  # your id for the end user, from your own user record
+        )
+    ],
+)
+
+agent = FunctionAgent(tools=[], llm=OpenAI(model="gpt-4.1-mini"))
+response = await agent.run("How should you contact me?", memory=memory)
+```
+
+### The identity
+
+past dev keeps memory per identity: your id for the end user. Recall needs an
+identity, and the first ingest for an identity creates it.
+
+Set `identity` in your code, from your trigger or your user record. Do not let
+the model choose it. The block has no tool and no prompt that can change the
+identity, so each user reads and writes only their own memory.
+
+## Parameters
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `identity` | (required) | Your id for the end user. |
+| `api_key` | `PAST_API_KEY` | A past dev project API key (`past_sk_...`). |
+| `api_host` | `PAST_API_HOST`, else `https://api.past.dev` | The API base URL. Change it only if you run past dev in your own cloud. |
+| `audience` | none | The audience slug for ingested memory. Without it, the memory is visible to the project. |
+| `level` | `low` (on the server) | The recall evidence budget: `low`, `medium`, `high` or `extra-high`. |
+| `max_tokens` | none | An explicit recall evidence budget in tokens. Use `level` or `max_tokens`, not both. |
+| `limit` | 100 (on the server) | The maximum number of recalled documents. |
+| `label` | `LlamaIndex chat` | The label of each ingested data point. |
+| `name` | `past_dev_memory` | The name of the block in the memory template. |
+| `priority` | `0` | The `BaseMemoryBlock` truncation priority. `0` means never truncate. |
+| `raise_on_error` | `True` | When `False`, the block logs an API error and continues without memory. |
+
+## What the block sends
+
+- **Recall** (`POST /api/v1/recall`): `query` (the latest user message),
+  `identity`, and `level`, `maxTokens` or `limit` if you set them.
+- **Ingest** (`POST /api/v1/ingest`): `content` (the flushed user and assistant
+  messages as `role: text` lines; system and tool messages are not sent),
+  `identity`, `timestamp`, `label`, `audience` if you set it, and `metadata`
+  with `{"source": "llama-index", "sessionId": ...}`.
+
+The `timestamp` is the `timestamp` of the first flushed message, if your
+application puts one in `message.additional_kwargs["timestamp"]`. Otherwise it
+is the time of the flush.
+
+## Credits
+
+Each recall and each ingest spends credits on your past dev plan. The block
+recalls once each time the agent reads its memory, and ingests once each time
+the `Memory` flushes messages.
+
+## Errors
+
+An API error raises `PastDevError`, with the error `code`, the HTTP `status`,
+the message and the `X-Request-Id` of the request. The block retries a `429`
+once, after its `Retry-After` delay. It does not retry other errors, for
+example `402 out-of-credits` or a `400`.
+
+## Links
+
+- [Quickstart](https://past.dev/docs/memory-api/quickstart)
+- [API reference](https://past.dev/docs/memory-api/api-reference)
+- [LlamaIndex memory guide](https://developers.llamaindex.ai/python/framework/module_guides/deploying/agents/memory/)
+- Tools for the same API: [`llama-index-tools-pastdotdev`](https://pypi.org/project/llama-index-tools-pastdotdev/)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

llama_index_memory_pastdotdev-0.1.0/README.md

@@ -0,0 +1,108 @@
+# LlamaIndex Memory Integration: past dev
+
+past dev is a memory API for AI agents. This package gives a LlamaIndex agent
+long-term memory in [past dev](https://past.dev), as a memory block for the
+LlamaIndex `Memory` class.
+
+- **Get:** the block does a past dev **Recall**. The query is the latest user
+  message. The recalled memory goes into the system message, with the date,
+  the kind and the quoted evidence of each entry.
+- **Put:** when the `Memory` flushes old messages from its short-term queue,
+  the block does a past dev **Ingest** of the user and assistant text, as one
+  data point.
+
+## Install
+
+```bash
+pip install llama-index-memory-pastdotdev
+```
+
+## Get a key
+
+1. Sign up at [past.dev](https://past.dev) and open a project.
+2. Make a project API key. It starts with `past_sk_`.
+3. Set it in the environment as `PAST_API_KEY`, or give it to the block as `api_key`.
+
+## Use
+
+```python
+from llama_index.core.agent.workflow import FunctionAgent
+from llama_index.core.memory import Memory
+from llama_index.llms.openai import OpenAI
+from llama_index.memory.pastdotdev import PastDevMemoryBlock
+
+memory = Memory.from_defaults(
+    session_id="session-42",
+    token_limit=30000,
+    memory_blocks=[
+        PastDevMemoryBlock(
+            identity=current_user.id,  # your id for the end user, from your own user record
+        )
+    ],
+)
+
+agent = FunctionAgent(tools=[], llm=OpenAI(model="gpt-4.1-mini"))
+response = await agent.run("How should you contact me?", memory=memory)
+```
+
+### The identity
+
+past dev keeps memory per identity: your id for the end user. Recall needs an
+identity, and the first ingest for an identity creates it.
+
+Set `identity` in your code, from your trigger or your user record. Do not let
+the model choose it. The block has no tool and no prompt that can change the
+identity, so each user reads and writes only their own memory.
+
+## Parameters
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `identity` | (required) | Your id for the end user. |
+| `api_key` | `PAST_API_KEY` | A past dev project API key (`past_sk_...`). |
+| `api_host` | `PAST_API_HOST`, else `https://api.past.dev` | The API base URL. Change it only if you run past dev in your own cloud. |
+| `audience` | none | The audience slug for ingested memory. Without it, the memory is visible to the project. |
+| `level` | `low` (on the server) | The recall evidence budget: `low`, `medium`, `high` or `extra-high`. |
+| `max_tokens` | none | An explicit recall evidence budget in tokens. Use `level` or `max_tokens`, not both. |
+| `limit` | 100 (on the server) | The maximum number of recalled documents. |
+| `label` | `LlamaIndex chat` | The label of each ingested data point. |
+| `name` | `past_dev_memory` | The name of the block in the memory template. |
+| `priority` | `0` | The `BaseMemoryBlock` truncation priority. `0` means never truncate. |
+| `raise_on_error` | `True` | When `False`, the block logs an API error and continues without memory. |
+
+## What the block sends
+
+- **Recall** (`POST /api/v1/recall`): `query` (the latest user message),
+  `identity`, and `level`, `maxTokens` or `limit` if you set them.
+- **Ingest** (`POST /api/v1/ingest`): `content` (the flushed user and assistant
+  messages as `role: text` lines; system and tool messages are not sent),
+  `identity`, `timestamp`, `label`, `audience` if you set it, and `metadata`
+  with `{"source": "llama-index", "sessionId": ...}`.
+
+The `timestamp` is the `timestamp` of the first flushed message, if your
+application puts one in `message.additional_kwargs["timestamp"]`. Otherwise it
+is the time of the flush.
+
+## Credits
+
+Each recall and each ingest spends credits on your past dev plan. The block
+recalls once each time the agent reads its memory, and ingests once each time
+the `Memory` flushes messages.
+
+## Errors
+
+An API error raises `PastDevError`, with the error `code`, the HTTP `status`,
+the message and the `X-Request-Id` of the request. The block retries a `429`
+once, after its `Retry-After` delay. It does not retry other errors, for
+example `402 out-of-credits` or a `400`.
+
+## Links
+
+- [Quickstart](https://past.dev/docs/memory-api/quickstart)
+- [API reference](https://past.dev/docs/memory-api/api-reference)
+- [LlamaIndex memory guide](https://developers.llamaindex.ai/python/framework/module_guides/deploying/agents/memory/)
+- Tools for the same API: [`llama-index-tools-pastdotdev`](https://pypi.org/project/llama-index-tools-pastdotdev/)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

llama_index_memory_pastdotdev-0.1.0/llama_index/memory/pastdotdev/__init__.py

@@ -0,0 +1,4 @@
+from llama_index.memory.pastdotdev.base import PastDevMemoryBlock
+from llama_index.memory.pastdotdev.client import PastDevError
+
+__all__ = ["PastDevMemoryBlock", "PastDevError"]

llama_index_memory_pastdotdev-0.1.0/llama_index/memory/pastdotdev/base.py

@@ -0,0 +1,180 @@
+"""past dev memory block for the LlamaIndex Memory class."""
+
+import logging
+from datetime import datetime
+from typing import Any, Dict, List, Literal, Optional
+
+import httpx
+from llama_index.core.base.llms.types import ChatMessage, MessageRole
+from llama_index.core.bridge.pydantic import Field, PrivateAttr, model_validator
+from llama_index.core.memory.memory import BaseMemoryBlock
+
+from llama_index.memory.pastdotdev.client import (
+    DEFAULT_API_HOST,
+    AsyncPastDevClient,
+    PastDevError,
+    format_recall_results,
+    now_iso,
+    resolve_api_key,
+    to_iso,
+)
+
+logger = logging.getLogger(__name__)
+
+__version__ = "0.1.0"
+
+DEFAULT_NAME = "past_dev_memory"
+DEFAULT_DESCRIPTION = (
+    "Long-term memory recalled from past dev for the current user. "
+    "Each entry has a rank, a date and a kind; evidence lines quote the source."
+)
+DEFAULT_LABEL = "LlamaIndex chat"
+INGESTED_ROLES = (MessageRole.USER, MessageRole.ASSISTANT)
+
+
+class PastDevMemoryBlock(BaseMemoryBlock[str]):
+    """
+    A memory block that keeps long-term memory in past dev.
+
+    On get, it recalls with the latest user message as the query. On put (the
+    messages that the Memory flushes from its short-term queue), it ingests the
+    user and assistant text as one data point. The identity is fixed when you
+    make the block: the model never chooses it.
+
+    Args:
+        identity: Your id for the end user. Recall reads, and ingest writes, as this identity.
+        api_key: A past dev project API key (past_sk_...). Defaults to PAST_API_KEY.
+        api_host: The API base URL. Defaults to PAST_API_HOST, else https://api.past.dev.
+        audience: The audience slug for ingested memory. Omit it for project-visible memory.
+        level: The recall evidence budget: low, medium, high or extra-high.
+        max_tokens: An explicit recall evidence budget in tokens. Send level or max_tokens, not both.
+        limit: The maximum number of recalled documents.
+        label: The label of each ingested data point.
+        raise_on_error: When False, an API error is logged and the block returns nothing.
+
+    """
+
+    name: str = Field(default=DEFAULT_NAME, description="The name of the memory block.")
+    description: Optional[str] = Field(default=DEFAULT_DESCRIPTION)
+    identity: str = Field(
+        description="The end user's id. Fixed by the builder, never by the model."
+    )
+    api_key: Optional[str] = Field(default=None, exclude=True, repr=False)
+    api_host: Optional[str] = Field(
+        default=None, description=f"Defaults to PAST_API_HOST, else {DEFAULT_API_HOST}."
+    )
+    audience: Optional[str] = Field(default=None)
+    level: Optional[Literal["low", "medium", "high", "extra-high"]] = Field(default=None)
+    max_tokens: Optional[int] = Field(default=None, ge=1)
+    limit: Optional[int] = Field(default=None, ge=1, le=200)
+    label: str = Field(default=DEFAULT_LABEL)
+    timeout: float = Field(default=30.0, gt=0)
+    raise_on_error: bool = Field(default=True)
+
+    _client: AsyncPastDevClient = PrivateAttr()
+
+    def __init__(self, http_client: Optional[httpx.AsyncClient] = None, **data: Any) -> None:
+        super().__init__(**data)
+        self._client = AsyncPastDevClient(
+            api_key=resolve_api_key(self.api_key),
+            api_host=self.api_host,
+            timeout=self.timeout,
+            user_agent=f"llama-index-memory-pastdotdev/{__version__}",
+            http_client=http_client,
+        )
+
+    @model_validator(mode="after")
+    def _check(self) -> "PastDevMemoryBlock":
+        if not self.identity or not self.identity.strip():
+            raise ValueError("identity is required: set it from your user record.")
+        if self.level is not None and self.max_tokens is not None:
+            raise ValueError("Set level or max_tokens, never both.")
+        return self
+
+    @classmethod
+    def class_name(cls) -> str:
+        return "PastDevMemoryBlock"
+
+    async def _aget(self, messages: Optional[List[ChatMessage]] = None, **block_kwargs: Any) -> str:
+        query = _latest_user_text(messages or [])
+        if not query:
+            return ""
+        try:
+            response = await self._client.recall(
+                query=query,
+                identity=self.identity,
+                limit=self.limit,
+                level=self.level,
+                max_tokens=self.max_tokens,
+            )
+        except (PastDevError, httpx.HTTPError) as error:
+            if self.raise_on_error:
+                raise
+            logger.warning("past dev recall failed: %s", error)
+            return ""
+        return "\n\n".join(format_recall_results(response.get("results") or []))
+
+    async def _aput(self, messages: List[ChatMessage]) -> None:
+        content = _transcript(messages)
+        if not content:
+            return
+        try:
+            await self._client.ingest(
+                content=content,
+                identity=self.identity,
+                timestamp=_first_timestamp(messages) or now_iso(),
+                audience=self.audience,
+                label=self.label,
+                metadata=_metadata(messages),
+            )
+        except (PastDevError, httpx.HTTPError) as error:
+            if self.raise_on_error:
+                raise
+            logger.warning("past dev ingest failed: %s", error)
+
+    async def atruncate(self, content: str, tokens_to_truncate: int) -> Optional[str]:
+        """Drop the lowest-ranked entries until about tokens_to_truncate tokens are gone."""
+        entries = content.split("\n\n") if content else []
+        to_remove = tokens_to_truncate * 4  # about four characters a token
+        while entries and to_remove > 0:
+            to_remove -= len(entries.pop()) + 2
+        return "\n\n".join(entries) or None
+
+
+def _text(message: ChatMessage) -> str:
+    return (message.content or "").strip()
+
+
+def _latest_user_text(messages: List[ChatMessage]) -> str:
+    for message in reversed(messages):
+        if message.role == MessageRole.USER and _text(message):
+            return _text(message)
+    return ""
+
+
+def _transcript(messages: List[ChatMessage]) -> str:
+    lines = [
+        f"{message.role.value}: {_text(message)}"
+        for message in messages
+        if message.role in INGESTED_ROLES and _text(message)
+    ]
+    return "\n\n".join(lines)
+
+
+def _first_timestamp(messages: List[ChatMessage]) -> Optional[str]:
+    """Use a timestamp that the application put on a message, if there is one."""
+    for message in messages:
+        value = message.additional_kwargs.get("timestamp")
+        if isinstance(value, (datetime, str)):
+            return to_iso(value)
+    return None
+
+
+def _metadata(messages: List[ChatMessage]) -> Dict[str, Any]:
+    metadata: Dict[str, Any] = {"source": "llama-index"}
+    for message in messages:
+        session_id = message.additional_kwargs.get("session_id")
+        if isinstance(session_id, str):
+            metadata["sessionId"] = session_id
+            break
+    return metadata

llama_index_memory_pastdotdev-0.1.0/llama_index/memory/pastdotdev/client.py

@@ -0,0 +1,311 @@
+"""A small HTTP client for the past dev Memory API.
+
+This file is the same in llama-index-memory-pastdotdev and
+llama-index-tools-pastdotdev, so that each package installs without the other.
+"""
+
+import asyncio
+import os
+import time
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+DEFAULT_API_HOST = "https://api.past.dev"
+API_KEY_ENV = "PAST_API_KEY"
+API_HOST_ENV = "PAST_API_HOST"
+RECALL_LEVELS = ("low", "medium", "high", "extra-high")
+RECALL_SORTS = ("relevance", "chronological")
+
+# A 429 is retried once, after the Retry-After delay, when that delay is short.
+MAX_RETRY_AFTER_SECONDS = 30.0
+
+
+class PastDevError(Exception):
+    """An error response from the past dev Memory API."""
+
+    def __init__(
+        self,
+        code: str,
+        status: int,
+        message: Optional[str] = None,
+        request_id: Optional[str] = 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 resolve_api_key(api_key: Optional[str]) -> str:
+    key = api_key or os.environ.get(API_KEY_ENV)
+    if not key:
+        raise ValueError(
+            "past dev needs a project API key: pass api_key or set the "
+            f"{API_KEY_ENV} environment variable."
+        )
+    return key
+
+
+def resolve_api_host(api_host: Optional[str]) -> str:
+    host = api_host or os.environ.get(API_HOST_ENV) or DEFAULT_API_HOST
+    return host.rstrip("/")
+
+
+def to_iso(value: Any) -> Optional[str]:
+    """Return an ISO 8601 string for a datetime or a string, else None."""
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            value = value.replace(tzinfo=timezone.utc)
+        return value.isoformat()
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return None
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def build_recall_body(
+    query: str,
+    identity: str,
+    limit: Optional[int] = None,
+    level: Optional[str] = None,
+    max_tokens: Optional[int] = None,
+    query_timestamp: Optional[str] = None,
+    occurred_from: Optional[str] = None,
+    occurred_to: Optional[str] = None,
+    sort: Optional[str] = None,
+) -> Dict[str, Any]:
+    if level is not None and max_tokens is not None:
+        raise ValueError("Send level or max_tokens to recall, never both.")
+    if level is not None and level not in RECALL_LEVELS:
+        raise ValueError(f"level must be one of {', '.join(RECALL_LEVELS)}.")
+    if sort is not None and sort not in RECALL_SORTS:
+        raise ValueError(f"sort must be one of {', '.join(RECALL_SORTS)}.")
+    body: Dict[str, Any] = {"query": query, "identity": identity}
+    optional = {
+        "limit": limit,
+        "level": level,
+        "maxTokens": max_tokens,
+        "queryTimestamp": query_timestamp,
+        "occurredFrom": occurred_from,
+        "occurredTo": occurred_to,
+        "sort": sort,
+    }
+    body.update({key: value for key, value in optional.items() if value is not None})
+    return body
+
+
+def build_ingest_body(
+    content: str,
+    identity: str,
+    timestamp: Optional[str] = None,
+    source_id: Optional[str] = None,
+    audience: Optional[str] = None,
+    label: Optional[str] = None,
+    metadata: Any = None,
+    idempotency_key: Optional[str] = None,
+) -> Dict[str, Any]:
+    if not content or not content.strip():
+        raise ValueError("past dev refuses empty content: send some text to ingest.")
+    body: Dict[str, Any] = {"content": content, "identity": identity}
+    optional = {
+        "timestamp": timestamp,
+        "id": source_id,
+        "audience": audience,
+        "label": label,
+        "metadata": metadata,
+        "idempotencyKey": idempotency_key,
+    }
+    body.update({key: value for key, value in optional.items() if value is not None})
+    return body
+
+
+def format_recall(response: Dict[str, Any]) -> str:
+    """Render a recall response as plain text for a model to read."""
+    results = response.get("results") or []
+    return "\n\n".join(format_recall_results(results))
+
+
+def format_recall_results(results: List[Dict[str, Any]]) -> List[str]:
+    rendered = []
+    for result in results:
+        content = (result.get("content") or "").strip()
+        if not content:
+            continue
+        artifact = result.get("artifact") or {}
+        kind = artifact.get("kind") or "memory"
+        head = (
+            f"[{result.get('rank', len(rendered) + 1)}] {_date(result.get('occurredAt'))} · {kind}"
+        )
+        superseded = artifact.get("supersededAt")
+        if superseded:
+            head += f" · superseded {_date(superseded)}"
+        lines = [head, content]
+        for source in result.get("sources") or []:
+            where = source.get("label") or source.get("sourceId") or "source"
+            when = _date(source.get("occurredAt"))
+            for excerpt in source.get("excerpts") or []:
+                lines.append(f'  evidence ({where}, {when}): "{excerpt}"')
+        rendered.append("\n".join(lines))
+    return rendered
+
+
+def _date(value: Optional[str]) -> str:
+    return value[:10] if isinstance(value, str) else "undated"
+
+
+class _Base:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        api_host: Optional[str] = None,
+        timeout: float = 30.0,
+        user_agent: str = "llama-index-pastdotdev",
+    ) -> None:
+        self.api_host = resolve_api_host(api_host)
+        self._headers = {
+            "Authorization": f"Bearer {resolve_api_key(api_key)}",
+            "Accept": "application/json",
+            "User-Agent": user_agent,
+        }
+        self.timeout = timeout
+
+    def _url(self, path: str) -> str:
+        return f"{self.api_host}{path}"
+
+    @staticmethod
+    def _retry_delay(response: httpx.Response) -> Optional[float]:
+        if response.status_code != 429:
+            return None
+        header = response.headers.get("Retry-After", "1")
+        try:
+            delay = float(header)
+        except ValueError:
+            return None
+        return delay if 0 <= delay <= MAX_RETRY_AFTER_SECONDS else None
+
+    @staticmethod
+    def _result(response: httpx.Response) -> Any:
+        if response.is_success:
+            return response.json() if response.content else None
+        request_id = response.headers.get("X-Request-Id")
+        try:
+            body = response.json()
+        except ValueError:
+            body = None
+        if isinstance(body, dict) and body.get("code"):
+            raise PastDevError(
+                code=str(body["code"]),
+                status=int(body.get("status") or response.status_code),
+                message=body.get("debugMessage"),
+                request_id=request_id,
+                data=body.get("data"),
+            )
+        raise PastDevError(
+            code="http-error",
+            status=response.status_code,
+            message=response.text[:200] or None,
+            request_id=request_id,
+        )
+
+
+class PastDevClient(_Base):
+    """Synchronous client."""
+
+    def __init__(
+        self, *args: Any, http_client: Optional[httpx.Client] = None, **kwargs: Any
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self._http = http_client or httpx.Client(timeout=self.timeout)
+
+    def request(self, method: str, path: str, json: Any = None, params: Any = None) -> Any:
+        for attempt in range(2):
+            response = self._http.request(
+                method, self._url(path), json=json, params=params, headers=self._headers
+            )
+            delay = self._retry_delay(response)
+            if delay is None or attempt == 1:
+                return self._result(response)
+            time.sleep(delay)
+        return None  # pragma: no cover
+
+    def ingest(self, **kwargs: Any) -> Dict[str, Any]:
+        return self.request("POST", "/api/v1/ingest", json=build_ingest_body(**kwargs))
+
+    def recall(self, **kwargs: Any) -> Dict[str, Any]:
+        return self.request("POST", "/api/v1/recall", json=build_recall_body(**kwargs))
+
+    def delete_data_point(self, source_id: str) -> Dict[str, Any]:
+        return self.request("DELETE", f"/api/v1/data-points/{_path(source_id)}")
+
+    def list_audiences(self) -> Dict[str, Any]:
+        """List the project's audiences. It costs no credits, so it also tests a key."""
+        return self.request("GET", "/api/v1/audiences")
+
+    def list_identities(self, after: Optional[str] = None) -> Dict[str, Any]:
+        return self.request("GET", "/api/v1/identities", params={"after": after} if after else None)
+
+    def close(self) -> None:
+        self._http.close()
+
+
+class AsyncPastDevClient(_Base):
+    """Asynchronous client."""
+
+    def __init__(
+        self, *args: Any, http_client: Optional[httpx.AsyncClient] = None, **kwargs: Any
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self._http = http_client or httpx.AsyncClient(timeout=self.timeout)
+
+    async def request(self, method: str, path: str, json: Any = None, params: Any = None) -> Any:
+        for attempt in range(2):
+            response = await self._http.request(
+                method, self._url(path), json=json, params=params, headers=self._headers
+            )
+            delay = self._retry_delay(response)
+            if delay is None or attempt == 1:
+                return self._result(response)
+            await asyncio.sleep(delay)
+        return None  # pragma: no cover
+
+    async def ingest(self, **kwargs: Any) -> Dict[str, Any]:
+        return await self.request("POST", "/api/v1/ingest", json=build_ingest_body(**kwargs))
+
+    async def recall(self, **kwargs: Any) -> Dict[str, Any]:
+        return await self.request("POST", "/api/v1/recall", json=build_recall_body(**kwargs))
+
+    async def delete_data_point(self, source_id: str) -> Dict[str, Any]:
+        return await self.request("DELETE", f"/api/v1/data-points/{_path(source_id)}")
+
+    async def list_audiences(self) -> Dict[str, Any]:
+        """List the project's audiences. It costs no credits, so it also tests a key."""
+        return await self.request("GET", "/api/v1/audiences")
+
+    async def list_identities(self, after: Optional[str] = None) -> Dict[str, Any]:
+        return await self.request(
+            "GET", "/api/v1/identities", params={"after": after} if after else None
+        )
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+
+def _path(segment: str) -> str:
+    from urllib.parse import quote
+
+    return quote(segment, safe="")

llama_index_memory_pastdotdev-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=6.1.1",
+    "ruff>=0.11",
+]
+
+[project]
+name = "llama-index-memory-pastdotdev"
+version = "0.1.0"
+description = "past dev memory block for LlamaIndex agents: recall and ingest long-term memory with the past dev Memory API"
+authors = [{name = "past.dev", email = "louis@past.dev"}]
+maintainers = [{name = "past.dev", email = "louis@past.dev"}]
+requires-python = ">=3.10,<4.0"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["llama-index", "llamaindex", "past dev", "past.dev", "memory", "agent memory", "long-term memory"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "llama-index-core>=0.13.0,<0.15",
+    "httpx>=0.27,<1",
+]
+
+[project.urls]
+Homepage = "https://past.dev"
+Documentation = "https://past.dev/docs/memory-api/quickstart"
+"API reference" = "https://past.dev/docs/memory-api/api-reference"
+Repository = "https://github.com/pastdotdev/llama-index-pastdotdev"
+
+[tool.hatch.build.targets.sdist]
+include = ["llama_index/", "tests/", "README.md", "LICENSE"]
+
+[tool.hatch.build.targets.wheel]
+include = ["llama_index/"]
+
+[tool.llamahub]
+contains_example = false
+import_path = "llama_index.memory.pastdotdev"
+
+[tool.llamahub.class_authors]
+PastDevMemoryBlock = "pastdotdev"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = ["live: calls the real past dev API; skipped unless PAST_API_KEY is set"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B"]
+# The formatter wraps code; long lines left are docstrings, which the model reads.
+ignore = ["E501"]

llama_index_memory_pastdotdev-0.1.0/tests/test_client.py

@@ -0,0 +1,78 @@
+import json
+from typing import List
+
+import httpx
+import pytest
+
+from llama_index.memory.pastdotdev.client import (
+    AsyncPastDevClient,
+    PastDevClient,
+    build_recall_body,
+)
+
+
+def recorder(requests: List[httpx.Request]) -> httpx.MockTransport:
+    def handler(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        if request.method == "DELETE":
+            return httpx.Response(202, json={"operationId": "op-1", "ids": ["chat/1"]})
+        if request.url.path == "/api/v1/identities":
+            return httpx.Response(200, json={"identities": [], "hasMore": False, "endCursor": None})
+        return httpx.Response(200, json={"audiences": []})
+
+    return httpx.MockTransport(handler)
+
+
+def test_sync_client_paths() -> None:
+    requests: List[httpx.Request] = []
+    client = PastDevClient(
+        api_key="past_sk_test", http_client=httpx.Client(transport=recorder(requests))
+    )
+    assert client.delete_data_point("chat/1")["ids"] == ["chat/1"]
+    assert client.list_audiences() == {"audiences": []}
+    assert client.list_identities(after="cursor-1")["hasMore"] is False
+    client.close()
+    assert [(r.method, r.url.raw_path.decode()) for r in requests] == [
+        ("DELETE", "/api/v1/data-points/chat%2F1"),
+        ("GET", "/api/v1/audiences"),
+        ("GET", "/api/v1/identities?after=cursor-1"),
+    ]
+
+
+async def test_async_client_paths() -> None:
+    requests: List[httpx.Request] = []
+    client = AsyncPastDevClient(
+        api_key="past_sk_test", http_client=httpx.AsyncClient(transport=recorder(requests))
+    )
+    await client.delete_data_point("chat/1")
+    await client.list_audiences()
+    await client.list_identities()
+    await client.aclose()
+    assert [(r.method, r.url.raw_path.decode()) for r in requests] == [
+        ("DELETE", "/api/v1/data-points/chat%2F1"),
+        ("GET", "/api/v1/audiences"),
+        ("GET", "/api/v1/identities"),
+    ]
+
+
+def test_recall_body_uses_api_keys() -> None:
+    body = build_recall_body(
+        query="q",
+        identity="u",
+        max_tokens=500,
+        query_timestamp="2026-10-01T00:00:00Z",
+        occurred_to="2026-09-01T00:00:00Z",
+        sort="chronological",
+    )
+    assert json.loads(json.dumps(body)) == {
+        "query": "q",
+        "identity": "u",
+        "maxTokens": 500,
+        "queryTimestamp": "2026-10-01T00:00:00Z",
+        "occurredTo": "2026-09-01T00:00:00Z",
+        "sort": "chronological",
+    }
+    with pytest.raises(ValueError):
+        build_recall_body(query="q", identity="u", level="huge")
+    with pytest.raises(ValueError):
+        build_recall_body(query="q", identity="u", sort="random")

llama_index_memory_pastdotdev-0.1.0/tests/test_live.py

@@ -0,0 +1,34 @@
+"""One smoke test against the real past dev API.
+
+It is skipped unless PAST_API_KEY is set. It spends a few credits: one ingest and one recall.
+"""
+
+import os
+
+import pytest
+from llama_index.core.base.llms.types import ChatMessage, MessageRole
+
+from llama_index.memory.pastdotdev import PastDevMemoryBlock
+
+pytestmark = [
+    pytest.mark.live,
+    pytest.mark.skipif(not os.environ.get("PAST_API_KEY"), reason="PAST_API_KEY is not set"),
+]
+
+
+async def test_live_put_and_get() -> None:
+    block = PastDevMemoryBlock(identity="llama-index-smoke-test", label="LlamaIndex smoke test")
+    # The connection test: listing audiences costs no credits.
+    audiences = await block._client.list_audiences()
+    assert isinstance(audiences["audiences"], list)
+
+    await block.aput(
+        [
+            ChatMessage(role=MessageRole.USER, content="My favourite colour is teal."),
+            ChatMessage(role=MessageRole.ASSISTANT, content="Noted: teal."),
+        ]
+    )
+    content = await block.aget(
+        [ChatMessage(role=MessageRole.USER, content="What is my favourite colour?")]
+    )
+    assert isinstance(content, str)

llama_index_memory_pastdotdev-0.1.0/tests/test_memory_pastdotdev.py

@@ -0,0 +1,302 @@
+import json
+from typing import Any, Callable, Dict, List
+
+import httpx
+import pytest
+from llama_index.core.base.llms.types import ChatMessage, MessageRole
+from llama_index.core.memory import Memory
+from llama_index.core.memory.memory import BaseMemoryBlock
+
+from llama_index.memory.pastdotdev import PastDevError, PastDevMemoryBlock
+
+KEY = "past_sk_test"
+
+RECALL_RESPONSE = {
+    "asOf": "2026-10-16T12:00:00Z",
+    "usedEvidenceTokens": 42,
+    "results": [
+        {
+            "id": "7f1c3a4e-0000-4000-8000-000000000001",
+            "rank": 1,
+            "occurredAt": "2026-10-01T09:00:00Z",
+            "content": "Ada prefers email to phone calls.",
+            "artifact": {
+                "id": "7f1c3a4e-0000-4000-8000-000000000001",
+                "kind": "observation",
+                "occurredAt": "2026-10-01T09:00:00Z",
+            },
+            "sources": [
+                {
+                    "sourceId": "chat-1",
+                    "occurredAt": "2026-10-01T09:00:00Z",
+                    "label": "Support chat",
+                    "excerpts": ["please email me, never call"],
+                }
+            ],
+        },
+        {
+            "id": "7f1c3a4e-0000-4000-8000-000000000002",
+            "rank": 2,
+            "occurredAt": "2026-09-01T09:00:00Z",
+            "content": "Ada lives in Lyon.",
+            "artifact": {
+                "id": "7f1c3a4e-0000-4000-8000-000000000002",
+                "kind": "claim",
+                "occurredAt": "2026-09-01T09:00:00Z",
+                "supersededAt": "2026-10-02T09:00:00Z",
+            },
+            "sources": [],
+        },
+    ],
+}
+
+INGEST_RESPONSE = {
+    "projectId": 1,
+    "ingestionId": "7f1c3a4e-0000-4000-8000-0000000000aa",
+    "sourceId": "abc",
+    "status": "queued",
+}
+
+
+class FakeApi:
+    """Records each request and answers with a handler."""
+
+    def __init__(self, handler: Callable[[httpx.Request], httpx.Response]) -> None:
+        self.handler = handler
+        self.requests: List[httpx.Request] = []
+
+    def __call__(self, request: httpx.Request) -> httpx.Response:
+        self.requests.append(request)
+        return self.handler(request)
+
+    def bodies(self, path: str) -> List[Dict[str, Any]]:
+        return [json.loads(r.content) for r in self.requests if r.url.path == path]
+
+
+def default_handler(request: httpx.Request) -> httpx.Response:
+    if request.url.path == "/api/v1/recall":
+        return httpx.Response(200, json=RECALL_RESPONSE)
+    if request.url.path == "/api/v1/ingest":
+        return httpx.Response(202, json=INGEST_RESPONSE)
+    return httpx.Response(404, json={"code": "not-found", "status": 404})
+
+
+def make_block(api: FakeApi, **kwargs: Any) -> PastDevMemoryBlock:
+    kwargs.setdefault("api_key", KEY)
+    kwargs.setdefault("identity", "user-ada")
+    return PastDevMemoryBlock(
+        http_client=httpx.AsyncClient(transport=httpx.MockTransport(api)), **kwargs
+    )
+
+
+def test_is_a_memory_block() -> None:
+    names = [b.__name__ for b in PastDevMemoryBlock.__mro__]
+    assert BaseMemoryBlock.__name__ in names
+
+
+def test_requires_identity() -> None:
+    with pytest.raises(ValueError):
+        make_block(FakeApi(default_handler), identity="  ")
+
+
+def test_requires_api_key(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("PAST_API_KEY", raising=False)
+    with pytest.raises(ValueError, match="PAST_API_KEY"):
+        PastDevMemoryBlock(identity="user-ada")
+
+
+def test_reads_key_and_host_from_environment(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("PAST_API_KEY", "past_sk_from_env")
+    monkeypatch.setenv("PAST_API_HOST", "https://memory.example.com/")
+    api = FakeApi(default_handler)
+    block = PastDevMemoryBlock(
+        identity="user-ada", http_client=httpx.AsyncClient(transport=httpx.MockTransport(api))
+    )
+    assert block._client.api_host == "https://memory.example.com"
+
+
+def test_refuses_level_and_max_tokens_together() -> None:
+    with pytest.raises(ValueError):
+        make_block(FakeApi(default_handler), level="high", max_tokens=1000)
+
+
+def test_api_key_is_not_serialized() -> None:
+    block = make_block(FakeApi(default_handler))
+    assert KEY not in json.dumps(block.model_dump())
+    assert KEY not in repr(block)
+
+
+async def test_get_recalls_with_latest_user_message() -> None:
+    api = FakeApi(default_handler)
+    block = make_block(api, level="medium", limit=5)
+    content = await block.aget(
+        [
+            ChatMessage(role=MessageRole.USER, content="Where does Ada live?"),
+            ChatMessage(role=MessageRole.ASSISTANT, content="Let me check."),
+            ChatMessage(role=MessageRole.USER, content="How should I contact Ada?"),
+        ]
+    )
+    assert api.bodies("/api/v1/recall") == [
+        {
+            "query": "How should I contact Ada?",
+            "identity": "user-ada",
+            "level": "medium",
+            "limit": 5,
+        }
+    ]
+    request = api.requests[0]
+    assert request.method == "POST"
+    assert request.url.host == "api.past.dev"
+    assert request.headers["Authorization"] == f"Bearer {KEY}"
+    assert "Ada prefers email to phone calls." in content
+    assert '"please email me, never call"' in content
+    assert "Support chat" in content
+    assert "superseded 2026-10-02" in content
+
+
+async def test_get_without_user_message_calls_nothing() -> None:
+    api = FakeApi(default_handler)
+    block = make_block(api)
+    assert await block.aget([ChatMessage(role=MessageRole.SYSTEM, content="Be kind.")]) == ""
+    assert await block.aget(None) == ""
+    assert api.requests == []
+
+
+async def test_put_ingests_conversation_text() -> None:
+    api = FakeApi(default_handler)
+    block = make_block(api, audience="support-team", label="Support chat")
+    await block.aput(
+        [
+            ChatMessage(role=MessageRole.SYSTEM, content="You are a helpful agent."),
+            ChatMessage(
+                role=MessageRole.USER,
+                content="Please email me, never call.",
+                additional_kwargs={"timestamp": "2026-10-01T09:00:00Z"},
+            ),
+            ChatMessage(role=MessageRole.TOOL, content='{"ok": true}'),
+            ChatMessage(role=MessageRole.ASSISTANT, content="Noted: email only."),
+        ],
+        session_id="session-1",
+    )
+    assert api.bodies("/api/v1/ingest") == [
+        {
+            "content": "user: Please email me, never call.\n\nassistant: Noted: email only.",
+            "identity": "user-ada",
+            "timestamp": "2026-10-01T09:00:00Z",
+            "audience": "support-team",
+            "label": "Support chat",
+            "metadata": {"source": "llama-index", "sessionId": "session-1"},
+        }
+    ]
+
+
+async def test_put_defaults_timestamp_to_now() -> None:
+    api = FakeApi(default_handler)
+    await make_block(api).aput([ChatMessage(role=MessageRole.USER, content="Hello")])
+    body = api.bodies("/api/v1/ingest")[0]
+    assert body["timestamp"].startswith("20")
+    assert body["label"] == "LlamaIndex chat"
+    assert "audience" not in body
+
+
+async def test_put_with_no_text_calls_nothing() -> None:
+    api = FakeApi(default_handler)
+    await make_block(api).aput([ChatMessage(role=MessageRole.TOOL, content="result")])
+    assert api.requests == []
+
+
+async def test_out_of_credits_is_raised_and_not_retried() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            402,
+            json={"code": "out-of-credits", "status": 402, "debugMessage": "No credits left."},
+            headers={"X-Request-Id": "req-123"},
+        )
+
+    api = FakeApi(handler)
+    with pytest.raises(PastDevError) as caught:
+        await make_block(api).aget([ChatMessage(role=MessageRole.USER, content="Hi")])
+    assert caught.value.code == "out-of-credits"
+    assert caught.value.status == 402
+    assert caught.value.request_id == "req-123"
+    assert "No credits left." in str(caught.value)
+    assert len(api.requests) == 1
+
+
+async def test_rate_limit_is_retried_once_after_retry_after() -> None:
+    calls = {"n": 0}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        if calls["n"] == 1:
+            return httpx.Response(
+                429, json={"code": "rate-limited", "status": 429}, headers={"Retry-After": "0"}
+            )
+        return httpx.Response(200, json=RECALL_RESPONSE)
+
+    api = FakeApi(handler)
+    content = await make_block(api).aget([ChatMessage(role=MessageRole.USER, content="Hi")])
+    assert len(api.requests) == 2
+    assert "Ada" in content
+
+
+async def test_long_retry_after_is_raised() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            429, json={"code": "rate-limited", "status": 429}, headers={"Retry-After": "3600"}
+        )
+
+    api = FakeApi(handler)
+    with pytest.raises(PastDevError, match="rate-limited"):
+        await make_block(api).aget([ChatMessage(role=MessageRole.USER, content="Hi")])
+    assert len(api.requests) == 1
+
+
+async def test_errors_can_be_logged_instead_of_raised() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(503, json={"code": "unavailable", "status": 503})
+
+    api = FakeApi(handler)
+    block = make_block(api, raise_on_error=False)
+    assert await block.aget([ChatMessage(role=MessageRole.USER, content="Hi")]) == ""
+    await block.aput([ChatMessage(role=MessageRole.USER, content="Hi")])
+    assert len(api.requests) == 2
+
+
+async def test_non_json_error_is_reported() -> None:
+    api = FakeApi(lambda request: httpx.Response(502, text="Bad gateway"))
+    with pytest.raises(PastDevError) as caught:
+        await make_block(api).aget([ChatMessage(role=MessageRole.USER, content="Hi")])
+    assert caught.value.code == "http-error"
+    assert caught.value.status == 502
+
+
+async def test_truncate_drops_lowest_ranked_entries() -> None:
+    block = make_block(FakeApi(default_handler))
+    content = "[1] first\n\n[2] second\n\n[3] third"
+    assert await block.atruncate(content, 2) == "[1] first\n\n[2] second"
+    assert await block.atruncate(content, 1000) is None
+
+
+async def test_works_inside_llama_index_memory() -> None:
+    api = FakeApi(default_handler)
+    memory = Memory.from_defaults(
+        session_id="session-1",
+        token_limit=60,
+        chat_history_token_ratio=0.5,
+        token_flush_size=20,
+        memory_blocks=[make_block(api)],
+    )
+    for turn in range(4):
+        await memory.aput(ChatMessage(role=MessageRole.USER, content=f"Question {turn} about Ada?"))
+        await memory.aput(ChatMessage(role=MessageRole.ASSISTANT, content=f"Answer {turn}."))
+
+    ingested = api.bodies("/api/v1/ingest")
+    assert ingested, "the memory flushed no messages to the block"
+    assert ingested[0]["identity"] == "user-ada"
+    assert ingested[0]["metadata"]["sessionId"] == "session-1"
+    assert ingested[0]["content"].startswith("user: Question 0 about Ada?")
+
+    messages = await memory.aget()
+    assert "Ada prefers email to phone calls." in str(messages[0].content)
+    assert api.bodies("/api/v1/recall")[-1]["query"] == "Question 3 about Ada?"