atomicmemory 1.0.0__tar.gz

atomicmemory-1.0.0/.gitignore

@@ -0,0 +1,55 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# uv
+.uv-cache/
+
+# Tooling
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.hypothesis/
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local
+*.log
+.env
+.env.local

atomicmemory-1.0.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+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).
+
+## [Unreleased]
+
+## [1.0.0]
+
+Initial public stable release.
+
+### Added
+- `AtomicMemoryClient` and `AsyncAtomicMemoryClient` as the primary public client surfaces.
+- Memory ingestion, search, package, get, list, and delete support.
+- AtomicMemory and Mem0 provider adapters.
+- Typed AtomicMemory namespace handles for lifecycle, audit, lessons, agents, and runtime config.
+- Direct artifact storage client with pointer and managed artifact workflows.
+- Local embedding, semantic search, and KV cache helpers.
+- Pydantic models, typed exceptions, and `py.typed` marker for downstream type checkers.

atomicmemory-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AtomicMemory
+
+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.

atomicmemory-1.0.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: atomicmemory
+Version: 1.0.0
+Summary: Python client SDK for AtomicMemory memory and artifact storage.
+Project-URL: Homepage, https://github.com/atomicstrata/atomicmemory-python
+Project-URL: Repository, https://github.com/atomicstrata/atomicmemory-python
+Project-URL: Issues, https://github.com/atomicstrata/atomicmemory-python/issues
+Author: AtomicMemory
+License: MIT
+License-File: LICENSE
+Keywords: agent,atomicmemory,llm,mem0,memory,rag
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: vulture>=2.11; extra == 'dev'
+Provides-Extra: embeddings
+Requires-Dist: sentence-transformers>=3.0; extra == 'embeddings'
+Description-Content-Type: text/markdown
+
+# atomicmemory-python
+
+Python client SDK for [AtomicMemory](https://github.com/atomicstrata) memory and artifact storage.
+
+A backend-agnostic memory and storage client: ingest conversations and documents, search them semantically, package retrieval-ready context, register or upload raw artifacts, and access AtomicMemory-specific features (lifecycle, audit, lessons, agents/trust, runtime config) through typed namespace handles.
+
+This is a Python port of the TypeScript [`atomicmemory-sdk`](https://github.com/atomicstrata/atomicmemory-sdk). It mirrors the public surface 1:1 while staying idiomatic to Python (Pydantic models, `httpx` sync + async clients, `match` statements, `snake_case`).
+
+## Status
+
+Stable release — `1.0.0` on [PyPI](https://pypi.org/project/atomicmemory/).
+
+## Quick start
+
+```python
+from atomicmemory import AtomicMemoryClient
+
+with AtomicMemoryClient({
+    "apiUrl": "http://localhost:3050",
+    "apiKey": "server-api-key",
+    "userId": "demo",
+}) as client:
+    client.memory.initialize()
+
+    client.memory.ingest({
+        "mode": "messages",
+        "messages": [
+            {"role": "user", "content": "I prefer aisle seats on flights."},
+        ],
+        "scope": {"user": "demo"},
+    })
+
+    page = client.memory.search({"query": "seat preference", "scope": {"user": "demo"}})
+    for hit in page.results:
+        print(hit.memory.content, hit.score)
+
+    artifact = client.storage.put({
+        "mode": "pointer",
+        "uri": "https://example.com/manual.pdf",
+        "contentType": "application/pdf",
+    })
+    print(artifact.artifact_id)
+```
+
+## Async usage
+
+```python
+import asyncio
+from atomicmemory import AsyncAtomicMemoryClient
+
+async def main() -> None:
+    async with AsyncAtomicMemoryClient({
+        "apiUrl": "http://localhost:3050",
+        "apiKey": "server-api-key",
+        "userId": "demo",
+    }) as client:
+        await client.memory.initialize()
+        results = await client.memory.search({"query": "seat preference", "scope": {"user": "demo"}})
+        for hit in results.results:
+            print(hit.memory.content)
+
+asyncio.run(main())
+```
+
+## AtomicMemory-specific features
+
+When configured with the `atomicmemory` provider, the client exposes a typed handle for backend-specific routes:
+
+```python
+trail = client.memory.atomicmemory.audit.trail(memory_id="mem-123", user_id="demo")
+health = client.memory.atomicmemory.config.health()
+```
+
+Categories: `lifecycle`, `audit`, `lessons`, `config`, `agents`.
+
+## Artifact storage
+
+The `client.storage` namespace mirrors the TypeScript SDK's direct storage API:
+
+- `capabilities()` reports active backend support.
+- `put({"mode": "pointer", ...})` registers a pointer to caller-owned bytes.
+- `put({"mode": "managed", "body": b"...", ...})` uploads known-length bytes to the configured raw content store.
+- `get`, `get_content`, `head`, `delete`, and `verify` address artifacts by `artifact_id`.
+- `stream_content` streams large artifact bodies without buffering the entire response in memory.
+
+Every storage request sends `Authorization: Bearer <apiKey>` and `X-AtomicMemory-User-Id`. The SDK never sends the legacy `?user_id=` URL parameter.
+
+## Installation
+
+```bash
+pip install atomicmemory                    # core + local search + SQLite store
+pip install 'atomicmemory[embeddings]'      # + sentence-transformers for local embeddings
+```
+
+## Development
+
+```bash
+uv sync --extra dev --extra embeddings
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy atomicmemory --strict
+uv run vulture atomicmemory tests .vulture_whitelist.py --min-confidence 90
+```
+
+## License
+
+MIT

atomicmemory-1.0.0/README.md

@@ -0,0 +1,108 @@
+# atomicmemory-python
+
+Python client SDK for [AtomicMemory](https://github.com/atomicstrata) memory and artifact storage.
+
+A backend-agnostic memory and storage client: ingest conversations and documents, search them semantically, package retrieval-ready context, register or upload raw artifacts, and access AtomicMemory-specific features (lifecycle, audit, lessons, agents/trust, runtime config) through typed namespace handles.
+
+This is a Python port of the TypeScript [`atomicmemory-sdk`](https://github.com/atomicstrata/atomicmemory-sdk). It mirrors the public surface 1:1 while staying idiomatic to Python (Pydantic models, `httpx` sync + async clients, `match` statements, `snake_case`).
+
+## Status
+
+Stable release — `1.0.0` on [PyPI](https://pypi.org/project/atomicmemory/).
+
+## Quick start
+
+```python
+from atomicmemory import AtomicMemoryClient
+
+with AtomicMemoryClient({
+    "apiUrl": "http://localhost:3050",
+    "apiKey": "server-api-key",
+    "userId": "demo",
+}) as client:
+    client.memory.initialize()
+
+    client.memory.ingest({
+        "mode": "messages",
+        "messages": [
+            {"role": "user", "content": "I prefer aisle seats on flights."},
+        ],
+        "scope": {"user": "demo"},
+    })
+
+    page = client.memory.search({"query": "seat preference", "scope": {"user": "demo"}})
+    for hit in page.results:
+        print(hit.memory.content, hit.score)
+
+    artifact = client.storage.put({
+        "mode": "pointer",
+        "uri": "https://example.com/manual.pdf",
+        "contentType": "application/pdf",
+    })
+    print(artifact.artifact_id)
+```
+
+## Async usage
+
+```python
+import asyncio
+from atomicmemory import AsyncAtomicMemoryClient
+
+async def main() -> None:
+    async with AsyncAtomicMemoryClient({
+        "apiUrl": "http://localhost:3050",
+        "apiKey": "server-api-key",
+        "userId": "demo",
+    }) as client:
+        await client.memory.initialize()
+        results = await client.memory.search({"query": "seat preference", "scope": {"user": "demo"}})
+        for hit in results.results:
+            print(hit.memory.content)
+
+asyncio.run(main())
+```
+
+## AtomicMemory-specific features
+
+When configured with the `atomicmemory` provider, the client exposes a typed handle for backend-specific routes:
+
+```python
+trail = client.memory.atomicmemory.audit.trail(memory_id="mem-123", user_id="demo")
+health = client.memory.atomicmemory.config.health()
+```
+
+Categories: `lifecycle`, `audit`, `lessons`, `config`, `agents`.
+
+## Artifact storage
+
+The `client.storage` namespace mirrors the TypeScript SDK's direct storage API:
+
+- `capabilities()` reports active backend support.
+- `put({"mode": "pointer", ...})` registers a pointer to caller-owned bytes.
+- `put({"mode": "managed", "body": b"...", ...})` uploads known-length bytes to the configured raw content store.
+- `get`, `get_content`, `head`, `delete`, and `verify` address artifacts by `artifact_id`.
+- `stream_content` streams large artifact bodies without buffering the entire response in memory.
+
+Every storage request sends `Authorization: Bearer <apiKey>` and `X-AtomicMemory-User-Id`. The SDK never sends the legacy `?user_id=` URL parameter.
+
+## Installation
+
+```bash
+pip install atomicmemory                    # core + local search + SQLite store
+pip install 'atomicmemory[embeddings]'      # + sentence-transformers for local embeddings
+```
+
+## Development
+
+```bash
+uv sync --extra dev --extra embeddings
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy atomicmemory --strict
+uv run vulture atomicmemory tests .vulture_whitelist.py --min-confidence 90
+```
+
+## License
+
+MIT

atomicmemory-1.0.0/atomicmemory/__init__.py

@@ -0,0 +1,166 @@
+"""atomicmemory — Python client SDK for AtomicMemory.
+
+Top-level re-exports for the public API. Users typically only need to
+import `AtomicMemoryClient` plus the type they're working with — every
+type they could need is re-exported here.
+"""
+
+from atomicmemory._version import __version__
+from atomicmemory.client.async_memory_client import AsyncMemoryClient, AsyncProviderStatus
+from atomicmemory.client.atomic_memory_client import (
+    AsyncAtomicMemoryClient,
+    AtomicMemoryClient,
+    AtomicMemoryClientConfig,
+    MemoryNamespaceConfig,
+)
+from atomicmemory.client.memory_client import MemoryClient, ProviderStatus
+from atomicmemory.core.errors import (
+    AtomicMemoryError,
+    ConfigError,
+    NetworkError,
+    NotInitializedError,
+    ProviderError,
+    RateLimitError,
+    ValidationError,
+)
+from atomicmemory.memory.filters import FieldFilter, FieldFilterOp, FilterExpr
+from atomicmemory.memory.types import (
+    Capabilities,
+    CapabilitiesExtensions,
+    CapabilitiesRequiredScope,
+    ContextPackage,
+    GraphEdge,
+    GraphNode,
+    GraphResult,
+    GraphSearchRequest,
+    HealthStatus,
+    IngestBase,
+    IngestInput,
+    IngestResult,
+    Insight,
+    ListRequest,
+    ListResultPage,
+    Memory,
+    MemoryKind,
+    MemoryRef,
+    MemoryVersion,
+    MemoryVersionEvent,
+    Message,
+    MessageIngest,
+    MessageRole,
+    PackageFormat,
+    PackageRequest,
+    Profile,
+    Provenance,
+    Scope,
+    SearchRequest,
+    SearchResult,
+    SearchResultPage,
+    TextIngest,
+    VerbatimIngest,
+)
+from atomicmemory.storage import (
+    ArtifactHead,
+    ArtifactInUseError,
+    ArtifactMetadata,
+    ArtifactNotFoundError,
+    ArtifactRange,
+    ArtifactRef,
+    AsyncStorageClient,
+    DeleteArtifactOptions,
+    DeleteArtifactPolicy,
+    DeleteArtifactResult,
+    FilecoinDirectStorageNotSupportedError,
+    PointerContentNotManagedError,
+    PutArtifactInput,
+    PutManagedInput,
+    PutPointerInput,
+    StorageArtifactStatus,
+    StorageCapabilities,
+    StorageClient,
+    StorageClientConfig,
+    StorageClientError,
+    StoredArtifact,
+    UnsupportedCapabilityError,
+    VerificationResult,
+    VerifyArtifactOptions,
+)
+
+__all__ = [
+    "ArtifactHead",
+    "ArtifactInUseError",
+    "ArtifactMetadata",
+    "ArtifactNotFoundError",
+    "ArtifactRange",
+    "ArtifactRef",
+    "AsyncAtomicMemoryClient",
+    "AsyncMemoryClient",
+    "AsyncProviderStatus",
+    "AsyncStorageClient",
+    "AtomicMemoryClient",
+    "AtomicMemoryClientConfig",
+    "AtomicMemoryError",
+    "Capabilities",
+    "CapabilitiesExtensions",
+    "CapabilitiesRequiredScope",
+    "ConfigError",
+    "ContextPackage",
+    "DeleteArtifactOptions",
+    "DeleteArtifactPolicy",
+    "DeleteArtifactResult",
+    "FieldFilter",
+    "FieldFilterOp",
+    "FilecoinDirectStorageNotSupportedError",
+    "FilterExpr",
+    "GraphEdge",
+    "GraphNode",
+    "GraphResult",
+    "GraphSearchRequest",
+    "HealthStatus",
+    "IngestBase",
+    "IngestInput",
+    "IngestResult",
+    "Insight",
+    "ListRequest",
+    "ListResultPage",
+    "Memory",
+    "MemoryClient",
+    "MemoryKind",
+    "MemoryNamespaceConfig",
+    "MemoryRef",
+    "MemoryVersion",
+    "MemoryVersionEvent",
+    "Message",
+    "MessageIngest",
+    "MessageRole",
+    "NetworkError",
+    "NotInitializedError",
+    "PackageFormat",
+    "PackageRequest",
+    "PointerContentNotManagedError",
+    "Profile",
+    "Provenance",
+    "ProviderError",
+    "ProviderStatus",
+    "PutArtifactInput",
+    "PutManagedInput",
+    "PutPointerInput",
+    "RateLimitError",
+    "Scope",
+    "SearchRequest",
+    "SearchResult",
+    "SearchResultPage",
+    "StorageArtifactStatus",
+    "StorageCapabilities",
+    "StorageClient",
+    "StorageClientConfig",
+    "StorageClientError",
+    "StoredArtifact",
+    "TextIngest",
+    "UnsupportedCapabilityError",
+    "ValidationError",
+    "VerbatimIngest",
+    "VerificationResult",
+    "VerifyArtifactOptions",
+    "__version__",
+]

atomicmemory-1.0.0/atomicmemory/_version.py

@@ -0,0 +1,3 @@
+"""Version metadata for the atomicmemory Python SDK."""
+
+__version__ = "1.0.0"

atomicmemory-1.0.0/atomicmemory/client/__init__.py

@@ -0,0 +1,22 @@
+"""Public client facades for memory and storage namespaces."""
+
+from atomicmemory.client.async_memory_client import AsyncMemoryClient, AsyncProviderStatus
+from atomicmemory.client.atomic_memory_client import (
+    AsyncAtomicMemoryClient,
+    AtomicMemoryClient,
+    AtomicMemoryClientConfig,
+    MemoryNamespaceConfig,
+)
+from atomicmemory.client.memory_client import MemoryClient, MemoryProviderConfigs, ProviderStatus
+
+__all__ = [
+    "AsyncAtomicMemoryClient",
+    "AsyncMemoryClient",
+    "AsyncProviderStatus",
+    "AtomicMemoryClient",
+    "AtomicMemoryClientConfig",
+    "MemoryClient",
+    "MemoryNamespaceConfig",
+    "MemoryProviderConfigs",
+    "ProviderStatus",
+]