Add actor-bound memory tools for Python (#8)

Add framework-neutral `memory_tools` and `async_memory_tools` factories for `memory_ingest` and `memory_search`. The application binds the user while model arguments exclude scope, credentials and endpoint settings. Search results are bounded and retain score, version and retrieval evidence. Errors are safe, and writes are never automatically retried.

Make HTTP 202 ingest explicit through `PendingIngestError`, validate backend ID arrays, add a separate-process save/recall/correction example and prepare package version 1.1.4. The new version is not published yet.

Validation: CI passes on Python 3.10, 3.11, 3.12 and 3.13. Local verification passes 622 tests and 76 tools/example tests from an installed wheel, plus Ruff, strict mypy and Vulture. Four live tests are gated; three sync/async parameter combinations are inapplicable. Local fixture correction does not prove actual engine or hosted correction behavior. Hosted persistence remains unverified.

Author: cuevaio

.github/workflows/ci.yml

@@ -50,7 +50,7 @@ jobs:
         run: uv run ruff format --check .
 
       - name: Mypy strict
-        run: uv run mypy atomicmemory --strict
+        run: uv run mypy atomicmemory examples/memory_tools.py --strict
 
       # `.vulture_whitelist.py` is required: it allowlists Protocol-method
       # parameter names and context-manager dunder args that vulture
@@ -62,3 +62,6 @@ jobs:
       # atomicmemory-core via ATOMICMEMORY_TEST_API_URL).
       - name: Pytest
         run: uv run pytest -m 'not integration'
+
+      - name: Verify tools from installed wheel
+        run: bash scripts/verify_tools_wheel.sh

CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to `atomicmemory` will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 1.1.4 (unreleased)
+
+- Add framework-neutral `memory_tools` and `async_memory_tools` factories with
+  fixed application user scope, strict argument schemas, bounded retrieval
+  output, and safe model-facing errors.
+- Reject HTTP 202 ingest responses with `PendingIngestError` instead of returning
+  an empty terminal result. Pending or failed writes must not be retried blindly.
+- Add a sync/async tools example and real-HTTP contract verification.
+
 ## [1.1.3] - 2026-09-22
 
 ### Fixed

README.md

@@ -22,7 +22,7 @@ This is a Python port of the TypeScript [`atomicmemory-sdk`](https://github.com/
 ## Status
 
 Stable releases are available on [PyPI](https://pypi.org/project/atomicmemory/).
-This source tree prepares version `1.1.3`; consult PyPI for publication status.
+This source tree prepares version `1.1.4`; consult PyPI for publication status.
 
 ## Installation
 
@@ -85,6 +85,68 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+## Agent-selected memory tools
+
+The following API is new in source version **1.1.4**, which is not yet published.
+The published 1.1.3 package does not export these factories. For contributor
+verification, use `uv sync --all-extras` in this checkout.
+
+```python
+import os
+from atomicmemory import MemoryClient, memory_tools
+
+with MemoryClient(providers={"atomicmemory": {
+    "api_url": "https://api.atomicstrata.ai",
+    "api_key": os.environ["ATOMICMEMORY_API_KEY"],
+}}) as client:
+    client.initialize()
+    tools = memory_tools(client=client, user="authenticated-app-user")
+    result = tools["memory_ingest"].execute({"content": "I prefer tea."})
+    page = tools["memory_search"].execute({"query": "drink preference"})
+```
+
+Each descriptor has `name`, `description`, `parameters` as JSON Schema, and
+`execute(arguments)`. Register those with your agent framework and serialize
+results with `model_dump(mode="json", exclude_none=True)`. For async code, use
+`AsyncMemoryClient`, `await client.initialize()`, `async_memory_tools`, and
+`await tools[name].execute(arguments)`.
+
+User identity, endpoint and credentials stay in application configuration.
+Arguments accept only `content` for ingest or `query` and an optional `limit`
+for search. Both operations keep the configured user, and reject model-supplied
+identity or transport fields. Search defaults to five hits, accepts limits up
+to 20, and bounds displayed text while retaining score, version and retrieval
+evidence. Backend metadata is excluded from model-facing hits.
+
+The tools propagate a safe `MemoryToolError` rather than raw backend errors.
+Async cancellation propagates. No write is automatically retried. HTTP 202
+is pending, and the direct SDK raises `PendingIngestError`; tools fail safely.
+Empty ingest arrays do not confirm a save. IDs are backend reports, not terminal
+correction receipts. See [ATO-2333](https://linear.app/atomic-strata/issue/ATO-2333)
+and [ATO-2334](https://linear.app/atomic-strata/issue/ATO-2334) for those contracts.
+
+The [single-operation example](examples/memory_tools.py) exercises separate
+processes against your explicitly configured backend:
+
+```bash
+export ATOMICMEMORY_API_KEY=your-server-key
+export ATOMICMEMORY_USER=synthetic-demo-user
+uv run python examples/memory_tools.py ingest 'I prefer tea.'
+uv run python examples/memory_tools.py search 'drink preference' --async
+uv run python examples/memory_tools.py ingest 'I now prefer coffee.' --async
+uv run python examples/memory_tools.py search 'drink preference'
+```
+
+Use `ATOMICMEMORY_API_URL=http://localhost:17350` for a local Core with its
+appropriate explicit key. A local transport fixture verifies sync/async wire
+parity, process restart and synthetic correction; it does not verify hosted
+persistence or actual engine correction. Hosted completion still depends on
+[ATO-2425](https://linear.app/atomic-strata/issue/ATO-2425). Python requires
+explicit provider configuration; it does not inherit TypeScript's zero-argument
+constructor behavior. Agent-selected tools let the agent choose when to read
+and write. Automatic capture/retrieval remains a separate deferred investigation
+in [ATO-2420](https://linear.app/atomic-strata/issue/ATO-2420).
+
 ## AtomicMemory-specific features
 
 When configured with the `atomicmemory` provider, the client exposes a typed handle for backend-specific routes:

atomicmemory/__init__.py

@@ -20,6 +20,7 @@
     InvalidScopeError,
     NetworkError,
     NotInitializedError,
+    PendingIngestError,
     ProviderError,
     RateLimitError,
     UnsupportedOperationError,
@@ -124,6 +125,16 @@
     VerificationResult,
     VerifyArtifactOptions,
 )
+from atomicmemory.tools import (
+    AsyncMemoryTool,
+    AsyncMemoryTools,
+    MemoryTool,
+    MemoryToolError,
+    MemoryTools,
+    async_memory_tools,
+    memory_tools,
+)
+from atomicmemory.tools_models import MemorySearchHit, MemorySearchOutput
 
 __all__ = [
     "DEFAULT_META_FACT_PATTERNS",
@@ -136,6 +147,8 @@
     "AsyncAtomicMemoryClient",
     "AsyncEntitiesClient",
     "AsyncMemoryClient",
+    "AsyncMemoryTool",
+    "AsyncMemoryTools",
     "AsyncProviderStatus",
     "AsyncStorageClient",
     "AtomicMemoryClient",
@@ -190,6 +203,11 @@
     "MemoryKind",
     "MemoryNamespaceConfig",
     "MemoryRef",
+    "MemorySearchHit",
+    "MemorySearchOutput",
+    "MemoryTool",
+    "MemoryToolError",
+    "MemoryTools",
     "MemoryVersion",
     "MemoryVersionEvent",
     "MergeEntitiesResult",
@@ -202,6 +220,7 @@
     "NotInitializedError",
     "PackageFormat",
     "PackageRequest",
+    "PendingIngestError",
     "PointerContentNotManagedError",
     "Profile",
     "Provenance",
@@ -230,9 +249,11 @@
     "VerificationResult",
     "VerifyArtifactOptions",
     "__version__",
+    "async_memory_tools",
     "capability_gaps",
     "filter_meta_facts",
     "is_meta_fact",
+    "memory_tools",
     "resolve_meta_fact_patterns",
     "satisfies_profile",
 ]

atomicmemory/_version.py

@@ -4,4 +4,4 @@
     __version__: The current package version string (PEP 440).
 """
 
-__version__ = "1.1.3"
+__version__ = "1.1.4"

atomicmemory/core/errors.py

@@ -75,6 +75,17 @@ def __init__(
         self.response_body = response_body
 
 
+class PendingIngestError(ProviderError):
+    """HTTP 202 accepted a write; no terminal ingest result is available."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "Ingest is pending; saving is not confirmed. Do not retry automatically.",
+            provider="atomicmemory",
+            status_code=202,
+        )
+
+
 class NetworkError(AtomicMemoryError):
     """A transport-level failure (timeout, connection refused, DNS, etc.)."""
 

atomicmemory/providers/atomicmemory/async_provider.py

@@ -110,7 +110,9 @@ async def close(self) -> None:
     async def do_ingest(self, input: IngestInput) -> IngestResult:
         body = _build_ingest_body(input)
         path = self._route("/memories/ingest/quick" if input.mode == "verbatim" else "/memories/ingest")
-        raw = await afetch_json(self._require_client(), self._http_options, path, method="POST", json=body)
+        raw = await afetch_json(
+            self._require_client(), self._http_options, path, method="POST", json=body, require_completed=True
+        )
         return to_ingest_result(raw)
 
     def _apply_meta_fact_filter(self, results: list[SearchResult]) -> list[SearchResult]:

atomicmemory/providers/atomicmemory/http.py

@@ -18,7 +18,7 @@
 
 import httpx
 
-from atomicmemory.core.errors import NetworkError, ProviderError, RateLimitError
+from atomicmemory.core.errors import NetworkError, PendingIngestError, ProviderError, RateLimitError
 
 _PROVIDER_NAME = "atomicmemory"
 
@@ -117,10 +117,13 @@ def fetch_json(
     *,
     method: str = "GET",
     json: Any | None = None,
+    require_completed: bool = False,
 ) -> Any:
     """Send a request and return the decoded JSON response body."""
     response = _request(client, options, method, path, json=json)
     _raise_for_status(response, path)
+    if require_completed and response.status_code == 202:
+        raise PendingIngestError()
     return response.json()
 
 
@@ -211,9 +214,12 @@ async def afetch_json(
     *,
     method: str = "GET",
     json: Any | None = None,
+    require_completed: bool = False,
 ) -> Any:
     response = await _arequest(client, options, method, path, json=json)
     _raise_for_status(response, path)
+    if require_completed and response.status_code == 202:
+        raise PendingIngestError()
     return response.json()
 
 

atomicmemory/providers/atomicmemory/mappers.py

@@ -9,7 +9,9 @@
 from __future__ import annotations
 
 from datetime import datetime, timezone
-from typing import Any
+from typing import Annotated, Any
+
+from pydantic import Field, TypeAdapter
 
 from atomicmemory.memory.types import (
     IngestResult,
@@ -22,6 +24,8 @@
     SearchResult,
 )
 
+_INGEST_IDS = TypeAdapter(list[Annotated[str, Field(min_length=1)]])
+
 _AUDIT_EVENTS: set[MemoryVersionEvent] = {"created", "updated", "superseded", "invalidated"}
 
 
@@ -132,8 +136,8 @@ def to_retrieval_receipt(raw: dict[str, Any]) -> RetrievalReceipt:
 def to_ingest_result(raw: dict[str, Any]) -> IngestResult:
     """Map ``POST /memories/ingest[/quick]`` response to V3 IngestResult."""
     return IngestResult(
-        created=list(raw.get("stored_memory_ids") or []),
-        updated=list(raw.get("updated_memory_ids") or []),
+        created=_INGEST_IDS.validate_python(raw.get("stored_memory_ids", []), strict=True),
+        updated=_INGEST_IDS.validate_python(raw.get("updated_memory_ids", []), strict=True),
         unchanged=[],
     )
 

atomicmemory/providers/atomicmemory/provider.py

@@ -102,7 +102,9 @@ def close(self) -> None:
     def do_ingest(self, input: IngestInput) -> IngestResult:
         body = _build_ingest_body(input)
         path = self._route("/memories/ingest/quick" if input.mode == "verbatim" else "/memories/ingest")
-        raw = fetch_json(self._require_client(), self._http_options, path, method="POST", json=body)
+        raw = fetch_json(
+            self._require_client(), self._http_options, path, method="POST", json=body, require_completed=True
+        )
         return to_ingest_result(raw)
 
     def _apply_meta_fact_filter(self, results: list[SearchResult]) -> list[SearchResult]: