Feat/memory2

dimos/core/library_config.py

@@ -0,0 +1,27 @@
+# Copyright 2026 Dimensional Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Process-wide library defaults.
+# Modules that need different settings can override in their own start().
+
+
+def apply_library_config() -> None:
+    """Apply process-wide library defaults. Call once per process."""
+    # Limit OpenCV internal threads to avoid idle thread contention.
+    try:
+        import cv2
+
+        cv2.setNumThreads(2)
+    except ImportError:
+        pass

dimos/core/resource.py

@@ -12,10 +12,19 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from abc import ABC, abstractmethod
+from __future__ import annotations
 
+from abc import abstractmethod
+from typing import TYPE_CHECKING, Self
 
-class Resource(ABC):
+if TYPE_CHECKING:
+    from types import TracebackType
+
+from reactivex.abc import DisposableBase
+from reactivex.disposable import CompositeDisposable
+
+
+class Resource(DisposableBase):
     @abstractmethod
     def start(self) -> None: ...
 
@@ -43,3 +52,35 @@ def dispose(self) -> None:
 
         """
         self.stop()
+
+    def __enter__(self) -> Self:
+        self.start()
+        return self
+
+    def __exit__(
+        self,
+        exctype: type[BaseException] | None,
+        excinst: BaseException | None,
+        exctb: TracebackType | None,
+    ) -> None:
+        self.stop()
+
+
+class CompositeResource(Resource):
+    """Resource that owns child disposables, disposed on stop()."""
+
+    _disposables: CompositeDisposable
+
+    def __init__(self) -> None:
+        self._disposables = CompositeDisposable()
+
+    def register_disposables(self, *disposables: DisposableBase) -> None:
+        """Register child disposables to be disposed when this resource stops."""
+        for d in disposables:
+            self._disposables.add(d)
+
+    def start(self) -> None:
+        pass
+
+    def stop(self) -> None:
+        self._disposables.dispose()

dimos/core/worker.py

@@ -23,6 +23,7 @@
 from typing import TYPE_CHECKING, Any
 
 from dimos.core.global_config import GlobalConfig, global_config
+from dimos.core.library_config import apply_library_config
 from dimos.utils.logging_config import setup_logger
 from dimos.utils.sequential_ids import SequentialIds
 
@@ -292,6 +293,7 @@ def _suppress_console_output() -> None:
 
 
 def _worker_entrypoint(conn: Connection, worker_id: int) -> None:
+    apply_library_config()
     instances: dict[int, Any] = {}
 
     try:

dimos/mapping/occupancy/gradient.py

@@ -53,7 +53,7 @@ def gradient(
     distance_cells = ndimage.distance_transform_edt(1 - obstacle_map)
 
     # Convert to meters and clip to max distance
-    distance_meters = np.clip(distance_cells * occupancy_grid.resolution, 0, max_distance)
+    distance_meters = np.clip(distance_cells * occupancy_grid.resolution, 0, max_distance)  # type: ignore[operator]
 
     # Invert and scale to 0-100 range
     # Far from obstacles (max_distance) -> 0

dimos/memory2/architecture.md

@@ -0,0 +1,114 @@
+# memory
+
+Observation storage and streaming layer for DimOS. Pull-based, lazy, composable.
+
+## Architecture
+
+```
+             Live Sensor Data
+                    ↓
+Store → Stream → [filters / transforms / terminals] → Stream  → [filters / transforms / terminals] → Stream → Live hooks
+                    ↓                                              ↓                                             ↓
+    Backend (ObservationStore + BlobStore + VectorStore + Notifier)     Backend                                      In Memory
+```
+
+**Store** owns a storage location (file, in-memory) and directly manages named streams. **Stream** is the query/iteration surface — lazy until a terminal is called. **Backend** is a concrete composite that orchestrates ObservationStore + BlobStore + VectorStore + Notifier for each stream.
+
+Supporting Systems:
+
+- BlobStore — separates large payloads from metadata. FileBlobStore (files on disk) and SqliteBlobStore (blob table per stream). Supports lazy loading.
+- Codecs — codec_for() auto-selects: JpegCodec for images (TurboJPEG, ~10-20x compression), LcmCodec for DimOS messages, PickleCodec fallback.
+- Transformers — Transformer[T,R] ABC wrapping iterator-to-iterator. EmbedImages/EmbedText enrich observations with embeddings. QualityWindow keeps best per time window.
+- Backpressure Buffers — KeepLast, Bounded, DropNew, Unbounded — bridge push/pull for live mode.
+
+
+## Modules
+
+| Module         | What                                                              |
+|----------------|-------------------------------------------------------------------|
+| `stream.py`    | Stream node — filters, transforms, terminals                      |
+| `backend.py`   | Concrete Backend composite (ObservationStore + Blob + Vector + Live)         |
+| `store.py`     | Store, StoreConfig                                                |
+| `transform.py` | Transformer ABC, FnTransformer, FnIterTransformer, QualityWindow  |
+| `buffer.py`    | Backpressure buffers for live mode (KeepLast, Bounded, Unbounded) |
+| `embed.py`     | EmbedImages / EmbedText transformers                              |
+
+## Subpackages
+
+| Package         | What                                                 | Docs                                             |
+|-----------------|------------------------------------------------------|--------------------------------------------------|
+| `type/`         | Observation, EmbeddedObservation, Filter/StreamQuery  | |
+| `store/`        | Store ABC + implementations (MemoryStore, SqliteStore) | [store/README.md](store/README.md)               |
+| `notifier/`     | Notifier ABC + SubjectNotifier                       |                                                  |
+| `blobstore/`    | BlobStore ABC + implementations (file, sqlite)       | [blobstore/blobstore.md](blobstore/blobstore.md) |
+| `codecs/`       | Encode/decode for storage (pickle, JPEG, LCM)        | [codecs/README.md](codecs/README.md)             |
+| `vectorstore/`  | VectorStore ABC + implementations (memory, sqlite)   |                                                  |
+| `observationstore/` | ObservationStore Protocol + implementations      |                                                  |
+
+## Docs
+
+| Doc | What |
+|-----|------|
+| [streaming.md](streaming.md) | Lazy vs materializing vs terminal — evaluation model, live safety |
+| [embeddings.md](embeddings.md) | Embedding layer design — EmbeddedObservation, vector search, EmbedImages/EmbedText |
+| [blobstore/blobstore.md](blobstore/blobstore.md) | BlobStore architecture — separate payload storage from metadata |
+
+## Query execution
+
+`StreamQuery` holds the full query spec (filters, text search, vector search, ordering, offset/limit). It also provides `apply(iterator)` — a Python-side execution path that runs all operations as in-memory predicates, brute-force cosine, and list sorts.
+
+This is the **default fallback**. ObservationStore implementations are free to push down operations using store-specific strategies instead:
+
+| Operation      | Python fallback (`StreamQuery.apply`) | Store push-down (example)        |
+|----------------|---------------------------------------|----------------------------------|
+| Filters        | `filter.matches()` predicates         | SQL WHERE clauses                |
+| Text search    | Case-insensitive substring            | FTS5 full-text index             |
+| Vector search  | Brute-force cosine similarity         | vec0 / FAISS ANN index           |
+| Ordering       | `sorted()` materialization            | SQL ORDER BY                     |
+| Offset / limit | `islice()`                            | SQL OFFSET / LIMIT               |
+
+`ListObservationStore` delegates entirely to `StreamQuery.apply()`. `SqliteObservationStore` translates the query into SQL and only falls back to Python for operations it can't express natively.
+
+Transform-sourced streams (post `.transform()`) always use `StreamQuery.apply()` since there's no index to push down to.
+
+## Quick start
+
+```python
+from dimos.memory2 import MemoryStore
+
+store = MemoryStore()
+images = store.stream("images")
+
+# Write
+images.append(frame, ts=time.time(), pose=(x, y, z), tags={"camera": "front"})
+
+# Query
+recent = images.after(t).limit(10).fetch()
+nearest = images.near(pose, radius=2.0).fetch()
+latest = images.last()
+
+# Transform (class or bare generator function)
+edges = images.transform(Canny()).save(store.stream("edges"))
+
+def running_avg(upstream):
+    total, n = 0.0, 0
+    for obs in upstream:
+        total += obs.data; n += 1
+        yield obs.derive(data=total / n)
+avgs = stream.transform(running_avg).fetch()
+
+# Live
+for obs in images.live().transform(process):
+    handle(obs)
+
+# Embed + search
+images.transform(EmbedImages(clip)).save(store.stream("embedded"))
+results = store.stream("embedded").search(query_vec, k=5).fetch()
+```
+
+## Implementations
+
+| ObservationStore           | Status   | Storage                                |
+|-----------------|----------|----------------------------------------|
+| `ListObservationStore`     | Complete | In-memory (lists + brute-force search) |
+| `SqliteObservationStore`   | Complete | SQLite (WAL, FTS5, vec0)               |