3tears-agent-memory 0.14.0__py3-none-any.whl

3tears_agent_memory-0.14.0.dist-info/METADATA

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: 3tears-agent-memory
+Version: 0.14.0
+Summary: Memory system for LLM agents -- extraction, retrieval, hybrid search, and MMR reranking
+Project-URL: Repository, https://github.com/pacepace/3tears
+Author: pace
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: 3tears
+Requires-Dist: 3tears-agent-acl
+Requires-Dist: 3tears-langgraph
+Requires-Dist: 3tears-observe
+Requires-Dist: langchain-core
+Requires-Dist: pgvector
+Description-Content-Type: text/markdown
+
+# 3tears Agent Memory
+
+Memory system for LLM agents. Handles extraction of memorable facts from conversations, hybrid retrieval (semantic + full-text + recency), and memory lifecycle management.
+
+Part of the [3tears](https://github.com/pacepace/3tears) framework.
+
+## Installation
+
+```bash
+pip install 3tears-agent-memory
+```
+
+## Components
+
+### Collections are the single entry point for memory-table SQL
+
+Every memory-table write, single-row read, batch read, and hybrid-search query goes through one of four `BaseCollection` subclasses; no consumer of this package holds an `asyncpg.Pool` reference directly.
+
+- `MemoriesCollection` -- `memories` table. CRUD through `get` / `save_entity` / `delete`; complex queries through `hybrid_search`, `search_by_ids`, `search_by_semantic`, `search_by_fts`, `find_similar_for_dedup`, `count_by_user`, `fetch_content_for_recall`.
+- `MediaCollection` -- `media` parent table. CRUD only.
+- `MediaContentCollection` -- `media_content` child table. CRUD + `hybrid_search`, `search_by_ids`, `search_by_semantic`, `search_by_fts`, `fetch_content_for_recall`.
+- `MemoryChunkCollection` -- `memory_chunks` child table. CRUD + `hybrid_search`, `search_by_ids`, `search_by_semantic`, `fetch_content_for_recall`.
+
+All four resolve their L3 pool through `CollectionRegistry` (same pattern `ConversationCollection` uses); an L1 `SQLiteBackend` attached to the registry populates on `save_entity` and serves subsequent by-id `get` calls without an L3 round-trip. The `media` / `media_content` / `memory_chunks` tables are introduced by migrations v006 / v007.
+
+Hybrid-search methods carry documented `# cache-bypass: <reason>` inline comments because the query shape (vector distance, FTS rank, multi-table joins) is not primary-key-addressable and the L1 row cache cannot serve the lookup. Keeping the SQL on the Collection preserves the single entry point. The cache-primitive enforcement walker recognises in-Collection bypass sites as legitimate and reports any bypass that leaks back into `retrieval.py` / `extraction.py` / `tools.py` as a violation.
+
+### MemoryExtractor
+
+Extracts memorable facts from conversation turns. Uses a multi-stage pipeline: candidate extraction via LLM, deduplication against existing memories via embedding similarity, and action resolution (ADD / UPDATE / DELETE).
+
+```python
+from threetears.agent.memory import (
+    MemoriesCollection,
+    MemoryConfig,
+    MemoryExtractor,
+)
+
+extractor = MemoryExtractor(
+    config=MemoryConfig(),
+    embedding_provider=my_embedding_provider,
+    chat_model_factory=my_chat_model_factory,
+    authorizer=authorizer_bundle,
+    memories_collection=memories_collection,
+    summary_callback=on_new_memory,
+)
+
+await extractor.extract(
+    user_id=user_id,
+    conversation_id=conv_id,
+    message_id_source=msg_id,
+    user_message="I just moved to Portland",
+    assistant_response="That's exciting! Portland has great food...",
+    turn_count=5,
+    agent_id=agent_id,
+    customer_id=customer_id,
+)
+```
+
+### MemoryRetriever
+
+Retrieves relevant memories using hybrid search: pgvector semantic similarity, PostgreSQL full-text search, recency decay, and MMR reranking for diversity. Takes the three search-bearing Collections at construction; no pool.
+
+```python
+from threetears.agent.memory import MemoryRetriever, MemoryConfig
+
+retriever = MemoryRetriever(
+    config=MemoryConfig(),
+    embedding_provider=my_embedding_provider,
+    authorizer=authorizer_bundle,
+    memories_collection=memories_collection,
+    media_content_collection=media_content_collection,
+    memory_chunk_collection=memory_chunk_collection,
+)
+
+result = await retriever.retrieve_with_candidates(
+    user_id,
+    "Tell me about Portland",
+    agent_id=agent_id,
+    customer_id=customer_id,
+    caller_user_id=user_id,
+    caller_agent_id=agent_id,
+)
+
+# result.context     -- formatted string for injection into system prompt
+# result.memories    -- raw memory dicts with similarity scores
+# result.media_content -- matched media content
+# result.memory_chunks -- matched document chunks
+```
+
+### Protocols
+
+Implement these to integrate with your infrastructure:
+
+```python
+from threetears.agent.memory import EmbeddingProvider, ChatModelFactory
+
+class MyEmbeddingProvider(EmbeddingProvider):
+    async def embed(self, text: str) -> tuple[list[float], int, UUID]:
+        # Returns (embedding_vector, token_count, model_id)
+        ...
+
+class MyChatModelFactory(ChatModelFactory):
+    async def create_chat_model(self, purpose: str = "extraction"):
+        # Returns a langchain BaseChatModel
+        ...
+```
+
+### Tools
+
+LangChain tools for agent use: memory search, recall, and explicit add. Factories take Collection references; no pool:
+
+```python
+from threetears.agent.memory import (
+    load_memory_add_tool,
+    load_memory_search_tool,
+    load_memory_recall_tool,
+)
+
+search_tool = await load_memory_search_tool(
+    user_id=user_id,
+    embedding_provider=embedding_provider,
+    agent_id=agent_id,
+    customer_id=customer_id,
+    authorizer=authorizer_bundle,
+    memories_collection=memories_collection,
+    media_content_collection=media_content_collection,
+    memory_chunk_collection=memory_chunk_collection,
+)
+recall_tool = await load_memory_recall_tool(
+    user_id=user_id,
+    agent_id=agent_id,
+    customer_id=customer_id,
+    authorizer=authorizer_bundle,
+    memories_collection=memories_collection,
+    media_content_collection=media_content_collection,
+    memory_chunk_collection=memory_chunk_collection,
+)
+add_tool = await load_memory_add_tool(
+    user_id=user_id,
+    conversation_id=conv_id,
+    message_id=msg_id,
+    embedding_provider=embedding_provider,
+    agent_id=agent_id,
+    customer_id=customer_id,
+    authorizer=authorizer_bundle,
+    memories_collection=memories_collection,
+)
+```
+
+### Configuration
+
+```python
+from threetears.agent.memory import MemoryConfig
+
+config = MemoryConfig(
+    similarity_threshold=0.4,      # minimum cosine similarity for retrieval
+    detail_threshold=0.85,         # threshold for including full memory detail
+    context_budget=15,             # max memories in context
+    dedup_threshold=0.85,          # similarity threshold for deduplication
+    max_candidates=10,             # max candidates per extraction
+)
+```
+
+## Database Schema
+
+Requires PostgreSQL with the `pgvector` extension. The package's own migration runner (`threetears.agent.memory.migrations.register`) produces the full schema per agent schema. Registered versions:
+
+- **v001** -- `memories` (PK `memory_id`, pgvector `embedding`, scoping ids, content, summary, lifecycle timestamps).
+- **v002** -- `conversation_memory_refs` (ledger of per-conversation surfaced items).
+- **v003** -- column reconciliation: renames PK and discriminator to match the package code (`id` to `memory_id`, `memory_type` to `type_memory`), drops columns the code does not read (`embedding_model`, `importance`, `metadata`, `date_accessed`), loosens `agent_id`/`customer_id` to NULL.
+- **v004** -- lifecycle + conversation-link columns on `memories` (`conversation_id`, `message_id_source`, `is_deleted`, `media_id`, `date_deleted`, `summary`) with indexes.
+- **v005** -- FTS: `search_vector TSVECTOR` + GIN index + maintenance trigger on `memories`.
+- **v006** -- `media` (parent) + `media_content` (chunked extracted text with embedding + FTS).
+- **v007** -- `memory_chunks` (document-style chunks with heading / page metadata + embedding + FTS).
+
+Every FTS column is trigger-maintained from `content` + `summary` (weighted A/B); callers do not have to populate `search_vector` manually. Integration tests under `tests/integration/` exercise the full chain + every public API surface against `pgvector/pgvector:pg16` via testcontainers.
+
+## RBAC Enforcement
+
+Memory reads, writes, and extractions flow through the unified rbac evaluator in `threetears.agent.acl`. Every (agent, customer) pair is a `memory`-type namespace in the `namespaces` table; each access resolves the namespace and evaluates one of three canonical actions against the caller's `(user_id, agent_id)` pair:
+
+- `memory.read` -- retrieval / search / recall. Guarded on `MemoryRetriever.retrieve*`, `MemoriesCollection.find_by_user`, `MemoriesCollection.find_by_scope`, the `memory_search` + `memory_recall` LangChain tools.
+- `memory.write` -- user-initiated writes. Guarded on `MemoriesCollection.save_memory` and the `memory_add` LangChain tool.
+- `memory.extract` -- agent-internal extraction path. Guarded on `MemoryExtractor.extract`; the owner short-circuit keeps the common case (agent emitting memories on its own namespace) grant-free.
+
+Owner short-circuit: the evaluator allows any action when the calling agent owns the memory namespace. Agent-internal retrieval and extraction therefore work without explicit grants; user-initiated reads and writes require evaluator assignments.
+
+Auto-assignment on first user-write: `memory_add` ensures a `MemoryOwner` assignment for the calling user on their first write (idempotent-by-state; the ensurer only fires when the user has zero memory rows in the target schema). Subsequent writes authorize against the materialized grant; admin-revoked grants stay revoked (the ensurer does not resurrect them).
+
+Wiring shape: every consumer of the memory surface REQUIRES a `MemoryAuthorizerDependencies` bundle exposing:
+
+- `acl_cache` -- shared `threetears.agent.acl.AclCache` instance;
+- `membership_loader` + `grant_loader` -- the evaluator's loaders (`threetears.agent.acl.MembershipLoader` / `GrantLoader`);
+- `namespace_collection` -- three-tier `NamespaceCollection` used to resolve the memory namespace via `get_by_owner_and_customer(namespace_type="memory", owner_agent_id, customer_id)` (create-if-absent flows through `save_entity`);
+- `group_collection` + `group_member_collection` + `role_collection` + `role_assignment_collection` -- the rbac Collections the first-write owner-assignment path uses via `ensure_memory_owner_assignment(...)`.
+
+There is no bypass. Every `MemoriesCollection`, `MemoryRetriever`, `MemoryExtractor`, and LangChain tool factory (`load_memory_search_tool`, `load_memory_add_tool`, `load_memory_recall_tool`) takes the bundle as a required constructor/factory argument; every code path that touches a memory row runs `authorize_memory_access` first. Callers that omit the bundle fail at the type checker and the Python signature boundary.
+
+- Production wiring builds the bundle directly from the agent-side three-tier stack's Collections (`NatsProxyL3Backend`-backed `NamespaceCollection` / `GroupCollection` / ...).
+- Test wiring injects a permissive fixture `permissive_memory_authorizer` (see `tests/conftest.py`) that carries in-memory Collection stand-ins and a permissive evaluator. Fixture usage is explicit in every test file that constructs a memory surface.
+- Back-office / admin tooling that genuinely needs to read or write memories without an identity must construct its own bundle with Collections bound directly to an asyncpg pool; there is no global escape hatch.
+
+See `threetears.agent.memory.authorize` for the full public surface.
+
+The three platform roles (`MemoryOwner` / `MemoryReader` / `MemoryWriter`) carry the canonical action vocabulary. Platform-side migrations seed these roles and backfill the rbac rows required for evaluator resolution.

3tears_agent_memory-0.14.0.dist-info/RECORD

@@ -0,0 +1,44 @@
+threetears/agent/memory/__init__.py,sha256=jGo_9QlPJ8eFMX6e6VBAlH5WJYt4Q5zSPMYAjgQJ7do,10678
+threetears/agent/memory/access.py,sha256=Hk9WQda_ssC-kcR2PfiTDx5uUCfh5uPgihQEqfFZu_w,8309
+threetears/agent/memory/authorize.py,sha256=07mPdKHSjFgilmdOgBXxVFLKklDcCc5Dwk7deJfSfLY,19705
+threetears/agent/memory/collections.py,sha256=QCojKCUVKAdsRdXnP1gRiyumvaNV3oHJSrM5Gp2S3Vk,128370
+threetears/agent/memory/embedding_utils.py,sha256=cFZ4pHxzAShLCFfytDA8fwwRtCUExku8ILj0HE-5YzU,5323
+threetears/agent/memory/entities.py,sha256=0PocHbBQUtOY_WNw8RgvnyJzxvXnmdxfTetxAhIvg6U,34495
+threetears/agent/memory/events.py,sha256=8yhFcprivqFgLiZyJfs-UdMWifGodGJQtxp5gNd-X30,9355
+threetears/agent/memory/extraction.py,sha256=LamsymOrCwwsRLaqchtSdB-0goNjR0gg0ZZ7K3oGSi4,31173
+threetears/agent/memory/integration.py,sha256=aKJXO5rOdwTPpY_JpWW-edpd8FNG9XeBrrzH029Wd_o,13406
+threetears/agent/memory/merge.py,sha256=mjNja4X94OR9un3gKCG9B_mw4fGV3gCEnmmQAVR8jXY,7400
+threetears/agent/memory/middleware.py,sha256=YGDfLBpnuj1ZEeM4iZvKiVjgLjHl0U01vF_C5sqWgQM,15072
+threetears/agent/memory/prompts.py,sha256=ms1OEM295Zd-2eJvpCjFTIcK4oh6S6wzMzgQ-PIIn80,6217
+threetears/agent/memory/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+threetears/agent/memory/retrieval.py,sha256=lAVW648E6Fi893eXlsnD8szAOISdBK6QoIgoIy8yNw0,24338
+threetears/agent/memory/tools.py,sha256=2h-XNpefK79Lr1IhjZBriOADLPKLa8AJe30CvZVOcN0,64570
+threetears/agent/memory/types.py,sha256=MesgOsGGgjbdgWUh7g84ADCxzcdgfa9H_8NQAR8S5RE,1980
+threetears/agent/memory/migrations/__init__.py,sha256=H5olHd_veZC9dVvaUSg1Nx2dNM5ZVKxjSnFJOJGoja4,8808
+threetears/agent/memory/migrations/v001_create_memories_table.py,sha256=Ls_rkYDdVSMO5ioVG-_J2GGhVx3kWXlxIt0BjYoata8,2602
+threetears/agent/memory/migrations/v002_create_conversation_memory_refs.py,sha256=pXV_yBm44NswVIGYvCIEoxdAExAw-0yFehe96LjuVx4,1544
+threetears/agent/memory/migrations/v003_memory_column_reconciliation.py,sha256=LU7q2KIAFbvMy86yp9WjAw94RHjC2TJD_nvD6LUSE50,4055
+threetears/agent/memory/migrations/v004_memory_lifecycle_columns.py,sha256=jhb4uLZqe9SZJtgBezyZAMl9Au7JagmEGKBTZwxL1bA,2952
+threetears/agent/memory/migrations/v005_memory_fts.py,sha256=lTerrZ9_i4oWbkttN6rZDDEBstcO0YIzeYWwJktTaLc,2519
+threetears/agent/memory/migrations/v006_memory_media_content.py,sha256=FmB8og7DCKjG2pBDLu8-NMfGbnWg23T92eTuLQQQabk,4076
+threetears/agent/memory/migrations/v007_memory_chunks.py,sha256=muGDAttKEn411MBX3kI45TT_bObzA39u8qXJIKLLd0g,3341
+threetears/agent/memory/migrations/v008_restore_memories_agent_customer_not_null.py,sha256=UhyDYOTEsoeP3Oj_fZuiK57eceTpRps_WoOe0MqoqV8,2842
+threetears/agent/memory/migrations/v009_media_composite_fk.py,sha256=wlM19dxcz836wQCunOQkFWgh1lJ3xNhrvBozEJEyuis,4937
+threetears/agent/memory/migrations/v010_media_content_composite_fk.py,sha256=IU0RfAWqY2Ukwu-YclyRtDKqOxqFvPKefkCy3oqe_wc,3188
+threetears/agent/memory/migrations/v011_memory_chunks_composite_fk.py,sha256=_hwAkREFlIcwrDcok5EqOFiB1JVcsydXjD1MK3utw9c,3105
+threetears/agent/memory/migrations/v012_memories_media_composite_fk.py,sha256=vRhn97Vz6Sqmz_kkl1VpQtDfzTeTQWLewrZOA1jXlqQ,5069
+threetears/agent/memory/migrations/v013_datetime_to_datetimetz.py,sha256=mjSDeZiES7PtPYzzw9tcJddm7xHg63h5ww-siK1F1lA,8081
+threetears/agent/memory/migrations/v014_memory_refs_date_columns.py,sha256=KDSCeWXz9obpOPFdn6B_zzS1snBrzmC00PdE2GLBhV0,4546
+threetears/agent/memory/migrations/v015_unified_memory_columns.py,sha256=aifypnMEji3y3GW0uqsNwM-BTyHNZ7sJiDHJHolsVTw,5112
+threetears/agent/memory/migrations/v016_backfill_memory_ids.py,sha256=Lng6Hih_FShYtLOjvnKWjA5zN26xgDTyLSiWfHD9dK0,9594
+threetears/agent/memory/migrations/v017_memory_fk_flip.py,sha256=COGO7QrgLTULE4-5MO4DnNoy5a35xtpiaGIFRd4GXMM,5423
+threetears/agent/memory/migrations/v018_drop_legacy_memory_columns.py,sha256=S65m9ujHQgp89Ti03x_dRnu2zO_YXWBy9C8rbD7Z5E8,5936
+threetears/agent/memory/migrations/v019_conversation_id_not_null.py,sha256=8GHKou_JBqWA1BT8gGuPxG5H2Hel0xnZK_mtP4FSEe8,2390
+threetears/agent/memory/migrations/v020_memories_alias.py,sha256=yyl6GYnl5gzA5glfXuubSO47kun_ixzWVgo-BYvZCZ8,1763
+threetears/agent/memory/migrations/v021_memory_chunks_index_and_token.py,sha256=QY5mysFEnnTsePLo0C4t2gkXyewjQNa9WzV3ZN5SbW4,14088
+threetears/agent/memory/migrations/v022_add_hnsw_gin_indexes.py,sha256=55zu4kDqTsWmiH3JR34lfeEpkgM9wjzKOB9NkSbI8Pc,9652
+threetears/agent/memory/migrations/v023_fix_idx_chunks_message_id_start.py,sha256=4nZZVR_94XapT0PSBMYExBVbMVNuQhzstrNtXnPtcok,2995
+3tears_agent_memory-0.14.0.dist-info/METADATA,sha256=MUXbhpydR3YibUXsj5ujV-Q9D3yqI_R8H_QmZKQdF9E,12216
+3tears_agent_memory-0.14.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+3tears_agent_memory-0.14.0.dist-info/licenses/LICENSE,sha256=7GWEoEOcFJenZLt4LDzqH2K7QLxo_2m8rzG7Vv8VGXo,1066
+3tears_agent_memory-0.14.0.dist-info/RECORD,,

3tears_agent_memory-0.14.0.dist-info/WHEEL

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

3tears_agent_memory-0.14.0.dist-info/licenses/LICENSE

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

threetears/agent/memory/__init__.py

@@ -0,0 +1,229 @@
+"""Agent memory package -- memory entities, collections, and embedding protocol."""
+
+from __future__ import annotations
+
+# Version derived from pyproject.toml so the metadata is the single
+# source of truth -- a future release that bumps pyproject without
+# updating ``__init__.py`` can't drift the runtime ``__version__``.
+# The except guard handles the rare case where the package isn't
+# installed via importlib.metadata (e.g. running directly from a
+# checked-out source tree without ``uv sync``); the fallback keeps
+# imports working but reports ``unknown`` rather than crashing.
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError
+from importlib.metadata import version as _version
+from typing import TYPE_CHECKING
+
+try:
+    __version__ = _version("3tears-agent-memory")
+except _PackageNotFoundError:  # pragma: no cover - dev fallback
+    __version__ = "unknown"
+
+# lazy public API (PEP 562). the package namespace no longer imports its
+# implementation modules eagerly: importing this package (or any of its
+# submodules) costs only this file, and each public attribute resolves
+# its defining module on first access. the TYPE_CHECKING block carries
+# the real imports so mypy and IDEs see the full statically-typed API;
+# the _LAZY map is the runtime equivalent. the three-way agreement
+# between __all__, _LAZY, and the TYPE_CHECKING block is pinned by the
+# package's lazy-surface consistency test.
+# decision record: docs/separate-concerns-decisions.md (hand-rolled
+# PEP 562 over lazy_loader -- zero added runtime deps, no stub drift).
+if TYPE_CHECKING:
+    from threetears.agent.memory.access import MemoryAccessService
+    from threetears.agent.memory.authorize import (
+        ACTION_MEMORY_EXTRACT,
+        ACTION_MEMORY_READ,
+        ACTION_MEMORY_WRITE,
+        MEMORY_NAMESPACE_TYPE,
+        MEMORY_OWNER_GROUP_PREFIX,
+        MEMORY_OWNER_ROLE_NAME,
+        MemoryAccessDenied,
+        MemoryAuthorizerDependencies,
+        authorize_memory_access,
+        ensure_memory_owner_assignment,
+        memory_namespace_name,
+    )
+    from threetears.agent.memory.collections import (
+        MediaCollection,
+        MediaContentCollection,
+        MemoriesCollection,
+        MemoryChunkCollection,
+        MemoryRefsCollection,
+        conversation_memory_refs_table,
+    )
+    from threetears.agent.memory.embedding_utils import embedding_attribution_scope
+    from threetears.agent.memory.entities import (
+        MediaContentEntity,
+        MediaEntity,
+        MemoryChunkEntity,
+        MemoryEntity,
+        MemoryRefEntity,
+    )
+    from threetears.agent.memory.events import (
+        MemoryCreatedEvent,
+        MemoryRetrievedEvent,
+        default_memory_created_dispatcher,
+    )
+    from threetears.agent.memory.extraction import ChatModelFactory, MemoryExtractor
+    from threetears.agent.memory.integration import (
+        MemoryIntegration,
+        NatsEmbeddingAdapter,
+        extract_memories,
+        retrieve_memories,
+    )
+    from threetears.agent.memory.merge import MemoryRepointResult, repoint_user
+    from threetears.agent.memory.middleware import MemoryInjectionMiddleware
+    from threetears.agent.memory.prompts import ExtractionPrompts
+    from threetears.agent.memory.retrieval import MemoryRetriever, RetrievalResult
+    from threetears.agent.memory.tools import (
+        ChunkRecallInput,
+        ChunkSearchInput,
+        MemoryAddInput,
+        MemoryRecallInput,
+        MemorySearchInput,
+        load_chunk_recall_tool,
+        load_chunk_search_tool,
+        load_memory_add_tool,
+        load_memory_recall_tool,
+        load_memory_search_tool,
+    )
+    from threetears.agent.memory.types import MemoryConfig, MemoryType
+
+# public attribute -> (defining module, attribute name in that module)
+_LAZY: dict[str, tuple[str, str]] = {
+    "ACTION_MEMORY_EXTRACT": ("threetears.agent.memory.authorize", "ACTION_MEMORY_EXTRACT"),
+    "ACTION_MEMORY_READ": ("threetears.agent.memory.authorize", "ACTION_MEMORY_READ"),
+    "ACTION_MEMORY_WRITE": ("threetears.agent.memory.authorize", "ACTION_MEMORY_WRITE"),
+    "ChatModelFactory": ("threetears.agent.memory.extraction", "ChatModelFactory"),
+    "ChunkRecallInput": ("threetears.agent.memory.tools", "ChunkRecallInput"),
+    "ChunkSearchInput": ("threetears.agent.memory.tools", "ChunkSearchInput"),
+    "ExtractionPrompts": ("threetears.agent.memory.prompts", "ExtractionPrompts"),
+    "MEMORY_NAMESPACE_TYPE": ("threetears.agent.memory.authorize", "MEMORY_NAMESPACE_TYPE"),
+    "MEMORY_OWNER_GROUP_PREFIX": ("threetears.agent.memory.authorize", "MEMORY_OWNER_GROUP_PREFIX"),
+    "MEMORY_OWNER_ROLE_NAME": ("threetears.agent.memory.authorize", "MEMORY_OWNER_ROLE_NAME"),
+    "MediaCollection": ("threetears.agent.memory.collections", "MediaCollection"),
+    "MediaContentCollection": ("threetears.agent.memory.collections", "MediaContentCollection"),
+    "MediaContentEntity": ("threetears.agent.memory.entities", "MediaContentEntity"),
+    "MediaEntity": ("threetears.agent.memory.entities", "MediaEntity"),
+    "MemoriesCollection": ("threetears.agent.memory.collections", "MemoriesCollection"),
+    "MemoryAccessDenied": ("threetears.agent.memory.authorize", "MemoryAccessDenied"),
+    "MemoryAccessService": ("threetears.agent.memory.access", "MemoryAccessService"),
+    "MemoryAddInput": ("threetears.agent.memory.tools", "MemoryAddInput"),
+    "MemoryAuthorizerDependencies": ("threetears.agent.memory.authorize", "MemoryAuthorizerDependencies"),
+    "MemoryChunkCollection": ("threetears.agent.memory.collections", "MemoryChunkCollection"),
+    "MemoryChunkEntity": ("threetears.agent.memory.entities", "MemoryChunkEntity"),
+    "MemoryConfig": ("threetears.agent.memory.types", "MemoryConfig"),
+    "MemoryCreatedEvent": ("threetears.agent.memory.events", "MemoryCreatedEvent"),
+    "MemoryEntity": ("threetears.agent.memory.entities", "MemoryEntity"),
+    "MemoryExtractor": ("threetears.agent.memory.extraction", "MemoryExtractor"),
+    "MemoryInjectionMiddleware": ("threetears.agent.memory.middleware", "MemoryInjectionMiddleware"),
+    "MemoryIntegration": ("threetears.agent.memory.integration", "MemoryIntegration"),
+    "MemoryRecallInput": ("threetears.agent.memory.tools", "MemoryRecallInput"),
+    "MemoryRefEntity": ("threetears.agent.memory.entities", "MemoryRefEntity"),
+    "MemoryRefsCollection": ("threetears.agent.memory.collections", "MemoryRefsCollection"),
+    "MemoryRetrievedEvent": ("threetears.agent.memory.events", "MemoryRetrievedEvent"),
+    "MemoryRepointResult": ("threetears.agent.memory.merge", "MemoryRepointResult"),
+    "MemoryRetriever": ("threetears.agent.memory.retrieval", "MemoryRetriever"),
+    "MemorySearchInput": ("threetears.agent.memory.tools", "MemorySearchInput"),
+    "MemoryType": ("threetears.agent.memory.types", "MemoryType"),
+    "NatsEmbeddingAdapter": ("threetears.agent.memory.integration", "NatsEmbeddingAdapter"),
+    "RetrievalResult": ("threetears.agent.memory.retrieval", "RetrievalResult"),
+    "authorize_memory_access": ("threetears.agent.memory.authorize", "authorize_memory_access"),
+    "conversation_memory_refs_table": ("threetears.agent.memory.collections", "conversation_memory_refs_table"),
+    "default_memory_created_dispatcher": ("threetears.agent.memory.events", "default_memory_created_dispatcher"),
+    "embedding_attribution_scope": ("threetears.agent.memory.embedding_utils", "embedding_attribution_scope"),
+    "ensure_memory_owner_assignment": ("threetears.agent.memory.authorize", "ensure_memory_owner_assignment"),
+    "extract_memories": ("threetears.agent.memory.integration", "extract_memories"),
+    "load_chunk_recall_tool": ("threetears.agent.memory.tools", "load_chunk_recall_tool"),
+    "load_chunk_search_tool": ("threetears.agent.memory.tools", "load_chunk_search_tool"),
+    "load_memory_add_tool": ("threetears.agent.memory.tools", "load_memory_add_tool"),
+    "load_memory_recall_tool": ("threetears.agent.memory.tools", "load_memory_recall_tool"),
+    "load_memory_search_tool": ("threetears.agent.memory.tools", "load_memory_search_tool"),
+    "memory_namespace_name": ("threetears.agent.memory.authorize", "memory_namespace_name"),
+    "repoint_user": ("threetears.agent.memory.merge", "repoint_user"),
+    "retrieve_memories": ("threetears.agent.memory.integration", "retrieve_memories"),
+}
+
+__all__ = [
+    "ACTION_MEMORY_EXTRACT",
+    "ACTION_MEMORY_READ",
+    "ACTION_MEMORY_WRITE",
+    "ChatModelFactory",
+    "ChunkRecallInput",
+    "ChunkSearchInput",
+    "ExtractionPrompts",
+    "MEMORY_NAMESPACE_TYPE",
+    "MEMORY_OWNER_GROUP_PREFIX",
+    "MEMORY_OWNER_ROLE_NAME",
+    "MediaCollection",
+    "MediaContentCollection",
+    "MediaContentEntity",
+    "MediaEntity",
+    "MemoriesCollection",
+    "MemoryAccessDenied",
+    "MemoryAccessService",
+    "MemoryAddInput",
+    "MemoryAuthorizerDependencies",
+    "MemoryChunkCollection",
+    "MemoryChunkEntity",
+    "MemoryConfig",
+    "MemoryCreatedEvent",
+    "MemoryEntity",
+    "MemoryExtractor",
+    "MemoryInjectionMiddleware",
+    "MemoryIntegration",
+    "MemoryRecallInput",
+    "MemoryRefEntity",
+    "MemoryRefsCollection",
+    "MemoryRepointResult",
+    "MemoryRetrievedEvent",
+    "MemoryRetriever",
+    "MemorySearchInput",
+    "MemoryType",
+    "NatsEmbeddingAdapter",
+    "RetrievalResult",
+    "authorize_memory_access",
+    "conversation_memory_refs_table",
+    "default_memory_created_dispatcher",
+    "embedding_attribution_scope",
+    "ensure_memory_owner_assignment",
+    "extract_memories",
+    "load_chunk_recall_tool",
+    "load_chunk_search_tool",
+    "load_memory_add_tool",
+    "load_memory_recall_tool",
+    "load_memory_search_tool",
+    "memory_namespace_name",
+    "repoint_user",
+    "retrieve_memories",
+]
+
+
+def __getattr__(name: str) -> object:
+    """resolve a public attribute from its defining module on first access.
+
+    :param name: attribute name being resolved
+    :ptype name: str
+    :return: the resolved attribute (also cached in module globals so
+        ``__getattr__`` fires at most once per name)
+    :rtype: object
+    :raises AttributeError: when ``name`` is not part of the public API
+    """
+    entry = _LAZY.get(name)
+    if entry is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from importlib import import_module
+
+    module_name, attr = entry
+    value: object = getattr(import_module(module_name), attr)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """include lazy attributes in ``dir()`` output.
+
+    :return: sorted union of materialized globals and lazy names
+    :rtype: list[str]
+    """
+    return sorted(set(globals()) | set(_LAZY))