crewai-memory-core 0.1.0__tar.gz

crewai_memory_core-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.venv/
+dist/
+build/
+uv.lock
+.env

crewai_memory_core-0.1.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.5
+Name: crewai-memory-core
+Version: 0.1.0
+Summary: Shared core for CrewAI unified-memory StorageBackend implementations — build a Memory backend with five small primitives
+Project-URL: Homepage, https://github.com/skamalj/crewai-memory
+Project-URL: Repository, https://github.com/skamalj/crewai-memory.git
+Project-URL: Documentation, https://skamalj.github.io/agentstate-reducer/
+Author-email: Kamal <skamalj@gmail.com>
+Keywords: agent-memory,crewai,long-term-memory,memory,storage-backend,vector-search
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: crewai>=1.10.0
+Description-Content-Type: text/markdown
+
+# crewai-memory-core
+
+Shared core for building [CrewAI](https://docs.crewai.com/en/concepts/memory) unified-memory **`StorageBackend`** implementations. CrewAI 1.10+ has one `Memory` engine (LLM analysis, consolidation, scope inference, composite scoring) over a pluggable storage protocol; this core implements the *whole* protocol — `save` / `search` / `delete` / `update` / `get_record` / `list_records` / `get_scope_info` / `list_scopes` / `list_categories` / `count` / `reset` / `touch_records` and the async variants — so a backend only supplies five primitives:
+
+```python
+from crewai_memory_core import MemoryBackend
+
+class MyBackend(MemoryBackend):
+    def _put(self, rows): ...                    # upsert rows by id
+    def _get(self, record_id): ...               # -> row | None
+    def _delete_ids(self, ids): ...              # -> int deleted
+    def _scan(self, scope_prefix): ...           # every row in the scope subtree
+    # optional — native ANN; default ranks _scan rows by cosine in Python
+    def _vector_search(self, vector, scope_prefix, limit): ...   # -> [(row, score), ...]
+```
+
+A `row` is a dict of the `MemoryRecord` fields plus `embedding`. Scope paths are hierarchical (`/company/team/user`); a prefix matches the scope itself and everything under it, never a sibling that merely shares characters (`/a` does not match `/ab`).
+
+Use a backend with CrewAI:
+
+```python
+from crewai import Crew
+from crewai.memory import Memory
+
+memory = Memory(storage=MyBackend(...))
+crew = Crew(agents=[...], tasks=[...], memory=memory)     # or set_memory_storage_factory(...) once at startup
+```
+
+`crewai_memory_core.testing` ships `FakeEmbedder` (deterministic, no network — pass as `Memory(embedder=...)`) and `InMemoryBackend`; `crewai_memory_core.contract` is an importable test suite every provider runs, including an end-to-end pass through CrewAI's real `Memory` engine with zero LLM calls.
+
+Concrete backends: [`crewai-memory-dynamodb`](https://pypi.org/project/crewai-memory-dynamodb/), [`crewai-memory-postgres`](https://pypi.org/project/crewai-memory-postgres/), [`crewai-memory-cosmosdb`](https://pypi.org/project/crewai-memory-cosmosdb/), [`crewai-memory-firestore`](https://pypi.org/project/crewai-memory-firestore/).
+
+Docs: <https://skamalj.github.io/agentstate-reducer/>
+
+## License
+
+MIT

crewai_memory_core-0.1.0/README.md

@@ -0,0 +1,37 @@
+# crewai-memory-core
+
+Shared core for building [CrewAI](https://docs.crewai.com/en/concepts/memory) unified-memory **`StorageBackend`** implementations. CrewAI 1.10+ has one `Memory` engine (LLM analysis, consolidation, scope inference, composite scoring) over a pluggable storage protocol; this core implements the *whole* protocol — `save` / `search` / `delete` / `update` / `get_record` / `list_records` / `get_scope_info` / `list_scopes` / `list_categories` / `count` / `reset` / `touch_records` and the async variants — so a backend only supplies five primitives:
+
+```python
+from crewai_memory_core import MemoryBackend
+
+class MyBackend(MemoryBackend):
+    def _put(self, rows): ...                    # upsert rows by id
+    def _get(self, record_id): ...               # -> row | None
+    def _delete_ids(self, ids): ...              # -> int deleted
+    def _scan(self, scope_prefix): ...           # every row in the scope subtree
+    # optional — native ANN; default ranks _scan rows by cosine in Python
+    def _vector_search(self, vector, scope_prefix, limit): ...   # -> [(row, score), ...]
+```
+
+A `row` is a dict of the `MemoryRecord` fields plus `embedding`. Scope paths are hierarchical (`/company/team/user`); a prefix matches the scope itself and everything under it, never a sibling that merely shares characters (`/a` does not match `/ab`).
+
+Use a backend with CrewAI:
+
+```python
+from crewai import Crew
+from crewai.memory import Memory
+
+memory = Memory(storage=MyBackend(...))
+crew = Crew(agents=[...], tasks=[...], memory=memory)     # or set_memory_storage_factory(...) once at startup
+```
+
+`crewai_memory_core.testing` ships `FakeEmbedder` (deterministic, no network — pass as `Memory(embedder=...)`) and `InMemoryBackend`; `crewai_memory_core.contract` is an importable test suite every provider runs, including an end-to-end pass through CrewAI's real `Memory` engine with zero LLM calls.
+
+Concrete backends: [`crewai-memory-dynamodb`](https://pypi.org/project/crewai-memory-dynamodb/), [`crewai-memory-postgres`](https://pypi.org/project/crewai-memory-postgres/), [`crewai-memory-cosmosdb`](https://pypi.org/project/crewai-memory-cosmosdb/), [`crewai-memory-firestore`](https://pypi.org/project/crewai-memory-firestore/).
+
+Docs: <https://skamalj.github.io/agentstate-reducer/>
+
+## License
+
+MIT

crewai_memory_core-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "crewai-memory-core"
+version = "0.1.0"
+description = "Shared core for CrewAI unified-memory StorageBackend implementations — build a Memory backend with five small primitives"
+authors = [{name = "Kamal", email = "skamalj@gmail.com"}]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "crewai>=1.10.0",
+]
+keywords = ["crewai", "memory", "storage-backend", "long-term-memory", "agent-memory", "vector-search"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://github.com/skamalj/crewai-memory"
+Repository = "https://github.com/skamalj/crewai-memory.git"
+Documentation = "https://skamalj.github.io/agentstate-reducer/"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/crewai_memory_core"]

crewai_memory_core-0.1.0/src/crewai_memory_core/__init__.py

@@ -0,0 +1,290 @@
+"""Shared core for CrewAI unified-memory ``StorageBackend`` implementations.
+
+CrewAI 1.10+ has one ``Memory`` engine (LLM analysis, consolidation, composite
+scoring) and a pluggable ``crewai.memory.storage.backend.StorageBackend``
+protocol underneath it. ``MemoryBackend`` implements the *whole* protocol —
+save / search / delete / update / get_record / list_records / get_scope_info /
+list_scopes / list_categories / count / reset / touch_records and the async
+variants — on top of five primitives a datastore supplies:
+
+    _put(rows)                       -> None          upsert rows by id
+    _get(record_id)                  -> row | None
+    _delete_ids(ids)                 -> int
+    _scan(scope_prefix)              -> list[row]     every row in the scope subtree
+    _vector_search(vector, scope_prefix, limit) -> list[(row, score)]   (optional)
+
+A ``row`` is a plain dict with the ``MemoryRecord`` fields (``id``, ``content``,
+``scope``, ``categories``, ``metadata``, ``importance``, ``created_at``,
+``last_accessed``, ``source``, ``private``) plus ``embedding``. ``score`` is a
+cosine similarity, higher is better. The default ``_vector_search`` ranks
+``_scan`` rows in Python, so a backend works before it has a native path.
+
+Scope semantics: ``scope_prefix="/a"`` matches ``/a`` and everything under
+``/a/...`` but not ``/ab``; ``"/"`` or ``None`` matches everything.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import math
+from datetime import datetime
+from typing import Any, Callable, Dict, Iterable, List, Optional, Sequence, Tuple
+
+from crewai.memory.types import MemoryRecord, ScopeInfo
+
+__all__ = ["MemoryBackend", "record_to_row", "row_to_record", "in_scope", "norm_scope", "cosine_similarity"]
+
+ROW_FIELDS = (
+    "id", "content", "scope", "categories", "metadata", "importance",
+    "created_at", "last_accessed", "source", "private", "embedding",
+)
+
+
+def norm_scope(scope: Optional[str]) -> str:
+    """Normalise a scope path: leading slash, no trailing slash, ``/`` for root."""
+    s = (scope or "/").strip()
+    if not s.startswith("/"):
+        s = "/" + s
+    s = s.rstrip("/")
+    return s or "/"
+
+
+def in_scope(scope: str, prefix: Optional[str]) -> bool:
+    """True if ``scope`` is ``prefix`` itself or lies under it."""
+    p = norm_scope(prefix)
+    if p == "/":
+        return True
+    s = norm_scope(scope)
+    return s == p or s.startswith(p + "/")
+
+
+def cosine_similarity(a: Sequence[float], b: Sequence[float]) -> float:
+    dot = sum(x * y for x, y in zip(a, b))
+    na = math.sqrt(sum(x * x for x in a))
+    nb = math.sqrt(sum(y * y for y in b))
+    return dot / (na * nb) if na and nb else 0.0
+
+
+def _parse_dt(val: Any) -> datetime:
+    if isinstance(val, datetime):
+        return val
+    if val is None:
+        return datetime.utcnow()
+    return datetime.fromisoformat(str(val).replace("Z", "+00:00"))
+
+
+def record_to_row(record: MemoryRecord) -> dict:
+    return {
+        "id": record.id,
+        "content": record.content,
+        "scope": norm_scope(record.scope),
+        "categories": list(record.categories or []),
+        "metadata": dict(record.metadata or {}),
+        "importance": float(record.importance),
+        "created_at": record.created_at.isoformat(),
+        "last_accessed": record.last_accessed.isoformat(),
+        "source": record.source,
+        "private": bool(record.private),
+        "embedding": list(record.embedding) if record.embedding else None,
+    }
+
+
+def row_to_record(row: dict) -> MemoryRecord:
+    return MemoryRecord(
+        id=str(row["id"]),
+        content=str(row.get("content", "")),
+        scope=norm_scope(row.get("scope")),
+        categories=list(row.get("categories") or []),
+        metadata=dict(row.get("metadata") or {}),
+        importance=float(row.get("importance", 0.5)),
+        created_at=_parse_dt(row.get("created_at")),
+        last_accessed=_parse_dt(row.get("last_accessed")),
+        embedding=list(row["embedding"]) if row.get("embedding") else None,
+        source=row.get("source") or None,
+        private=bool(row.get("private", False)),
+    )
+
+
+def _matches(row: dict, categories: Optional[List[str]], metadata_filter: Optional[Dict[str, Any]],
+             older_than: Optional[datetime] = None) -> bool:
+    if categories and not any(c in (row.get("categories") or []) for c in categories):
+        return False
+    if metadata_filter:
+        md = row.get("metadata") or {}
+        if not all(md.get(k) == v for k, v in metadata_filter.items()):
+            return False
+    if older_than is not None and _parse_dt(row.get("created_at")) >= older_than:
+        return False
+    return True
+
+
+class MemoryBackend:
+    """A CrewAI ``StorageBackend`` implemented over five datastore primitives."""
+
+    supports_native_vector_search: bool = False
+
+    # ------------------------------------------------------------------ primitives
+    def _put(self, rows: List[dict]) -> None:
+        raise NotImplementedError
+
+    def _get(self, record_id: str) -> Optional[dict]:
+        raise NotImplementedError
+
+    def _delete_ids(self, ids: List[str]) -> int:
+        raise NotImplementedError
+
+    def _scan(self, scope_prefix: Optional[str]) -> List[dict]:
+        """Every row whose scope is ``scope_prefix`` or under it (all rows for "/" / None)."""
+        raise NotImplementedError
+
+    def _vector_search(
+        self, vector: List[float], scope_prefix: Optional[str], limit: int
+    ) -> List[Tuple[dict, float]]:
+        """Up to ``limit`` ``(row, cosine_similarity)`` pairs in the scope subtree, best first."""
+        scored = [
+            (row, cosine_similarity(vector, row["embedding"]))
+            for row in self._scan(scope_prefix)
+            if row.get("embedding")
+        ]
+        scored.sort(key=lambda rs: -rs[1])
+        return scored[:limit]
+
+    # ------------------------------------------------------------------ StorageBackend
+    def save(self, records: List[MemoryRecord]) -> None:
+        if records:
+            self._put([record_to_row(r) for r in records])
+
+    def update(self, record: MemoryRecord) -> None:
+        self._put([record_to_row(record)])
+
+    def get_record(self, record_id: str) -> Optional[MemoryRecord]:
+        row = self._get(record_id)
+        return row_to_record(row) if row else None
+
+    def search(
+        self,
+        query_embedding: List[float],
+        scope_prefix: Optional[str] = None,
+        categories: Optional[List[str]] = None,
+        metadata_filter: Optional[Dict[str, Any]] = None,
+        limit: int = 10,
+        min_score: float = 0.0,
+    ) -> List[Tuple[MemoryRecord, float]]:
+        if not query_embedding:
+            return []
+        oversample = limit * 3 if (categories or metadata_filter) else limit
+        hits = self._vector_search(list(query_embedding), scope_prefix, oversample)
+        out: List[Tuple[MemoryRecord, float]] = []
+        for row, score in hits:
+            if not in_scope(row["scope"], scope_prefix):
+                continue
+            if not _matches(row, categories, metadata_filter):
+                continue
+            if score >= min_score:
+                out.append((row_to_record(row), float(score)))
+            if len(out) >= limit:
+                break
+        return out
+
+    def delete(
+        self,
+        scope_prefix: Optional[str] = None,
+        categories: Optional[List[str]] = None,
+        record_ids: Optional[List[str]] = None,
+        older_than: Optional[datetime] = None,
+        metadata_filter: Optional[Dict[str, Any]] = None,
+    ) -> int:
+        if record_ids and not (categories or metadata_filter or older_than):
+            return self._delete_ids(list(record_ids))
+        rows = self._scan(scope_prefix)
+        if record_ids:
+            wanted = set(record_ids)
+            rows = [r for r in rows if r["id"] in wanted]
+        ids = [r["id"] for r in rows if _matches(r, categories, metadata_filter, older_than)]
+        return self._delete_ids(ids) if ids else 0
+
+    def list_records(self, scope_prefix: Optional[str] = None, limit: int = 200, offset: int = 0) -> List[MemoryRecord]:
+        rows = sorted(self._scan(scope_prefix), key=lambda r: _parse_dt(r.get("created_at")), reverse=True)
+        return [row_to_record(r) for r in rows[offset : offset + limit]]
+
+    def get_scope_info(self, scope: str) -> ScopeInfo:
+        scope = norm_scope(scope)
+        rows = self._scan(scope)
+        cats: set = set()
+        oldest = newest = None
+        children: set = set()
+        child_prefix = "/" if scope == "/" else scope + "/"
+        for r in rows:
+            sc = norm_scope(r["scope"])
+            if sc.startswith(child_prefix):
+                first = sc[len(child_prefix):].split("/", 1)[0]
+                if first:
+                    children.add(child_prefix + first)
+            cats.update(r.get("categories") or [])
+            dt = _parse_dt(r.get("created_at"))
+            oldest = dt if oldest is None or dt < oldest else oldest
+            newest = dt if newest is None or dt > newest else newest
+        return ScopeInfo(
+            path=scope, record_count=len(rows), categories=sorted(cats),
+            oldest_record=oldest, newest_record=newest, child_scopes=sorted(children),
+        )
+
+    def list_scopes(self, parent: str = "/") -> List[str]:
+        parent = norm_scope(parent)
+        child_prefix = "/" if parent == "/" else parent + "/"
+        children: set = set()
+        for r in self._scan(parent):
+            sc = norm_scope(r["scope"])
+            if sc.startswith(child_prefix) and sc != parent:
+                first = sc[len(child_prefix):].split("/", 1)[0]
+                if first:
+                    children.add(child_prefix + first)
+        return sorted(children)
+
+    def list_categories(self, scope_prefix: Optional[str] = None) -> Dict[str, int]:
+        counts: Dict[str, int] = {}
+        for r in self._scan(scope_prefix):
+            for c in r.get("categories") or []:
+                counts[c] = counts.get(c, 0) + 1
+        return counts
+
+    def count(self, scope_prefix: Optional[str] = None) -> int:
+        return len(self._scan(scope_prefix))
+
+    def reset(self, scope_prefix: Optional[str] = None) -> None:
+        ids = [r["id"] for r in self._scan(scope_prefix)]
+        if ids:
+            self._delete_ids(ids)
+
+    def touch_records(self, record_ids: List[str]) -> None:
+        """Bump ``last_accessed`` (called by ``Memory.recall``; best-effort)."""
+        now = datetime.utcnow().isoformat()
+        rows = []
+        for rid in record_ids:
+            row = self._get(rid)
+            if row:
+                row["last_accessed"] = now
+                rows.append(row)
+        if rows:
+            self._put(rows)
+
+    def close(self) -> None:  # pragma: no cover - default no-op
+        pass
+
+    # ------------------------------------------------------------------ async surface
+    async def asave(self, records: List[MemoryRecord]) -> None:
+        await asyncio.to_thread(self.save, records)
+
+    async def asearch(self, query_embedding: List[float], scope_prefix: Optional[str] = None,
+                      categories: Optional[List[str]] = None, metadata_filter: Optional[Dict[str, Any]] = None,
+                      limit: int = 10, min_score: float = 0.0) -> List[Tuple[MemoryRecord, float]]:
+        return await asyncio.to_thread(
+            self.search, query_embedding, scope_prefix, categories, metadata_filter, limit, min_score
+        )
+
+    async def adelete(self, scope_prefix: Optional[str] = None, categories: Optional[List[str]] = None,
+                      record_ids: Optional[List[str]] = None, older_than: Optional[datetime] = None,
+                      metadata_filter: Optional[Dict[str, Any]] = None) -> int:
+        return await asyncio.to_thread(
+            self.delete, scope_prefix, categories, record_ids, older_than, metadata_filter
+        )

crewai_memory_core-0.1.0/src/crewai_memory_core/contract.py

@@ -0,0 +1,244 @@
+"""Reusable ``StorageBackend`` contract tests.
+
+A provider's test module supplies a ``backend`` fixture (fresh, empty store)
+and does ``from crewai_memory_core.contract import *``. Every test below then
+runs against that backend, including an end-to-end pass through CrewAI's real
+``Memory`` engine with the deterministic ``FakeEmbedder`` (no LLM: all record
+fields are provided so the encoding flow takes its zero-LLM fast path, and
+recall uses ``depth="shallow"``).
+"""
+
+from __future__ import annotations
+
+import time
+from datetime import datetime, timedelta
+
+import pytest
+from crewai.memory.types import MemoryRecord
+
+from .testing import FakeEmbedder
+
+DIMS = 64
+EMB = FakeEmbedder(DIMS)
+
+__all__ = [n for n in dir() if n.startswith("test_")]  # filled after definitions
+
+
+def _rec(content, scope="/", categories=None, importance=0.5, metadata=None, source=None, private=False, created=None):
+    return MemoryRecord(
+        content=content, scope=scope, categories=categories or [], importance=importance,
+        metadata=metadata or {}, source=source, private=private,
+        embedding=EMB([content])[0], **({"created_at": created} if created else {}),
+    )
+
+
+def _seed(b):
+    recs = [
+        _rec("the user loves sushi and japanese food", "/crew/support/user/kamal", ["food", "pref"], 0.9, {"lang": "en"}),
+        _rec("the user writes python every day", "/crew/support/user/kamal", ["tech"], 0.6, {"lang": "en"}),
+        _rec("the user lives by the sea in a big city", "/crew/support/user/kamal", ["place"], 0.4, {"lang": "fr"}),
+        _rec("priya loves sushi", "/crew/support/user/priya", ["food"], 0.5),
+        _rec("company policy: remote work allowed", "/company", ["policy"], 0.8),
+    ]
+    b.save(recs)
+    return recs
+
+
+def _wait(fn, cond, tries=15, delay=1.0):
+    for _ in range(tries):
+        out = fn()
+        if cond(out):
+            return out
+        time.sleep(delay)
+    return fn()
+
+
+# ── save / get / update / delete ──────────────────────────────────────────────
+
+
+def test_save_and_get_roundtrip(backend):
+    r = _rec("hello world", "/a/b", ["x"], 0.7, {"k": 1, "s": "v"}, source="u1", private=True)
+    backend.save([r])
+    got = _wait(lambda: backend.get_record(r.id), lambda g: g is not None)
+    assert got.id == r.id and got.content == "hello world" and got.scope == "/a/b"
+    assert got.categories == ["x"] and got.metadata == {"k": 1, "s": "v"}
+    assert got.importance == pytest.approx(0.7) and got.source == "u1" and got.private is True
+    assert abs((got.created_at - r.created_at).total_seconds()) < 1
+
+
+def test_get_missing_is_none(backend):
+    assert backend.get_record("nope") is None
+
+
+def test_update_replaces_record(backend):
+    r = _rec("v1", "/a")
+    backend.save([r])
+    r2 = r.model_copy(update={"content": "v2", "importance": 0.99, "embedding": EMB(["v2"])[0]})
+    backend.update(r2)
+    got = _wait(lambda: backend.get_record(r.id), lambda g: g and g.content == "v2")
+    assert got.content == "v2" and got.importance == pytest.approx(0.99)
+    assert backend.count() == 1
+
+
+def test_delete_by_ids(backend):
+    recs = _seed(backend)
+    _wait(lambda: backend.count(), lambda n: n == 5)
+    assert backend.delete(record_ids=[recs[0].id, recs[1].id]) == 2
+    assert _wait(lambda: backend.count(), lambda n: n == 3) == 3
+
+
+def test_delete_by_scope_categories_metadata_and_age(backend):
+    _seed(backend)
+    old = _rec("ancient fact", "/crew/support/user/kamal", ["old"], created=datetime.utcnow() - timedelta(days=400))
+    backend.save([old])
+    _wait(lambda: backend.count(), lambda n: n == 6)
+    assert backend.delete(scope_prefix="/crew/support/user/kamal", categories=["tech"]) == 1
+    assert backend.delete(scope_prefix="/crew", metadata_filter={"lang": "fr"}) == 1
+    assert backend.delete(older_than=datetime.utcnow() - timedelta(days=30)) == 1
+    assert _wait(lambda: backend.count(), lambda n: n == 3) == 3
+    assert backend.delete(scope_prefix="/crew/support/user/kamal") == 1   # remaining kamal record
+    assert backend.count("/company") == 1
+
+
+def test_reset_scope_and_all(backend):
+    _seed(backend)
+    _wait(lambda: backend.count(), lambda n: n == 5)
+    backend.reset("/crew/support/user")
+    assert _wait(lambda: backend.count(), lambda n: n == 1) == 1
+    backend.reset()
+    assert _wait(lambda: backend.count(), lambda n: n == 0) == 0
+
+
+# ── scopes / categories / listing ─────────────────────────────────────────────
+
+
+def test_scope_prefix_is_path_aware(backend):
+    backend.save([_rec("a", "/a"), _rec("ab", "/ab"), _rec("a-child", "/a/child")])
+    _wait(lambda: backend.count(), lambda n: n == 3)
+    assert backend.count("/a") == 2          # /a and /a/child, not /ab
+    assert backend.count("/ab") == 1
+    assert backend.count("/") == 3 and backend.count(None) == 3
+
+
+def test_list_scopes_immediate_children(backend):
+    _seed(backend)
+    _wait(lambda: backend.count(), lambda n: n == 5)
+    assert backend.list_scopes("/") == ["/company", "/crew"]
+    assert backend.list_scopes("/crew/support") == ["/crew/support/user"]
+    assert backend.list_scopes("/crew/support/user") == ["/crew/support/user/kamal", "/crew/support/user/priya"]
+    assert backend.list_scopes("/nowhere") == []
+
+
+def test_get_scope_info(backend):
+    _seed(backend)
+    _wait(lambda: backend.count(), lambda n: n == 5)
+    info = backend.get_scope_info("/crew/support/user")
+    assert info.path == "/crew/support/user" and info.record_count == 4
+    assert set(info.categories) == {"food", "pref", "tech", "place"}
+    assert info.child_scopes == ["/crew/support/user/kamal", "/crew/support/user/priya"]
+    assert info.oldest_record is not None and info.newest_record is not None
+    assert backend.get_scope_info("/empty").record_count == 0
+
+
+def test_list_categories_counts(backend):
+    _seed(backend)
+    _wait(lambda: backend.count(), lambda n: n == 5)
+    assert backend.list_categories() == {"food": 2, "pref": 1, "tech": 1, "place": 1, "policy": 1}
+    assert backend.list_categories("/crew/support/user/kamal") == {"food": 1, "pref": 1, "tech": 1, "place": 1}
+
+
+def test_list_records_newest_first_with_paging(backend):
+    recs = [_rec(f"r{i}", "/x", created=datetime.utcnow() - timedelta(minutes=10 - i)) for i in range(5)]
+    backend.save(recs)
+    _wait(lambda: backend.count(), lambda n: n == 5)
+    page1 = backend.list_records("/x", limit=2)
+    page2 = backend.list_records("/x", limit=2, offset=2)
+    assert [r.content for r in page1] == ["r4", "r3"] and [r.content for r in page2] == ["r2", "r1"]
+
+
+# ── search ────────────────────────────────────────────────────────────────────
+
+
+def test_search_ranks_by_similarity_with_scores(backend):
+    _seed(backend)
+    q = EMB(["sushi and japanese food"])[0]
+    hits = _wait(lambda: backend.search(q, scope_prefix="/crew/support/user/kamal", limit=3), lambda h: len(h) == 3)
+    assert hits[0][0].content.startswith("the user loves sushi")
+    scores = [s for _, s in hits]
+    assert scores == sorted(scores, reverse=True) and all(-1.0 <= s <= 1.0001 for s in scores)
+
+
+def test_search_scope_prefix_covers_subtree_only(backend):
+    _seed(backend)
+    q = EMB(["sushi"])[0]
+    hits = _wait(lambda: backend.search(q, scope_prefix="/crew/support/user", limit=10), lambda h: len(h) == 4)
+    assert {r.scope for r, _ in hits} == {"/crew/support/user/kamal", "/crew/support/user/priya"}
+    assert all(r.scope.startswith("/crew") for r, _ in backend.search(q, scope_prefix="/crew", limit=10))
+    assert backend.search(q, scope_prefix="/nowhere", limit=10) == []
+    assert len(backend.search(q, limit=10)) == 5
+
+
+def test_search_categories_metadata_and_min_score(backend):
+    _seed(backend)
+    q = EMB(["the user"])[0]
+    food = _wait(lambda: backend.search(q, scope_prefix="/crew", categories=["food"], limit=10), lambda h: len(h) == 2)
+    assert all("food" in r.categories for r, _ in food)
+    en = backend.search(q, scope_prefix="/crew", metadata_filter={"lang": "en"}, limit=10)
+    assert len(en) == 2 and all(r.metadata.get("lang") == "en" for r, _ in en)
+    assert backend.search(q, scope_prefix="/crew", min_score=0.999, limit=10) == []
+
+
+def test_search_limit(backend):
+    _seed(backend)
+    q = EMB(["user"])[0]
+    assert len(_wait(lambda: backend.search(q, limit=2), lambda h: len(h) == 2)) == 2
+
+
+def test_touch_records_bumps_last_accessed(backend):
+    r = _rec("touch me", "/t")
+    backend.save([r])
+    _wait(lambda: backend.get_record(r.id), lambda g: g is not None)
+    before = backend.get_record(r.id).last_accessed
+    time.sleep(0.01)
+    backend.touch_records([r.id])
+    after = _wait(lambda: backend.get_record(r.id).last_accessed, lambda a: a > before)
+    assert after > before
+
+
+async def test_async_surface(backend):
+    r = _rec("async fact", "/async", ["a"])
+    await backend.asave([r])
+    _wait(lambda: backend.count("/async"), lambda n: n == 1)
+    hits = await backend.asearch(EMB(["async fact"])[0], scope_prefix="/async", limit=5)
+    assert hits and hits[0][0].id == r.id
+    assert await backend.adelete(record_ids=[r.id]) == 1
+
+
+# ── end to end through CrewAI's Memory engine (no LLM) ────────────────────────
+
+
+def test_crewai_memory_engine_roundtrip(backend):
+    from crewai.memory import Memory
+
+    mem = Memory(storage=backend, embedder=EMB, consolidation_threshold=1.0)   # 1.0 disables LLM consolidation
+    try:
+        r1 = mem.remember("the user loves sushi", scope="/user/kamal", categories=["food"], importance=0.9)
+        r2 = mem.remember("the user writes python", scope="/user/kamal", categories=["tech"], importance=0.6)
+        mem.remember("weather is sunny", scope="/misc", categories=["weather"], importance=0.1)
+        assert r1 is not None and r2 is not None
+        _wait(lambda: backend.count(), lambda n: n == 3)
+
+        matches = _wait(lambda: mem.recall("what food does the user like?", scope="/user/kamal", depth="shallow", limit=2),
+                        lambda m: len(m) == 2)
+        assert matches[0].record.content == "the user loves sushi"
+        assert 0.0 <= matches[0].score <= 1.0 and "semantic" in matches[0].match_reasons
+
+        assert mem.list_scopes("/") == ["/misc", "/user"]
+        assert mem.info("/user/kamal").record_count == 2
+        assert mem.forget(scope="/misc") == 1
+        assert _wait(lambda: backend.count(), lambda n: n == 2) == 2
+    finally:
+        mem.close()
+
+
+__all__ = [n for n in list(globals()) if n.startswith("test_")]

crewai_memory_core-0.1.0/src/crewai_memory_core/testing.py

@@ -0,0 +1,63 @@
+"""Test helpers shared by the provider suites (and handy for users' tests).
+
+``FakeEmbedder`` is a deterministic, dependency-free embedder with CrewAI's
+embedder call signature (``list[str] -> list[list[float]]``): a hashed
+bag-of-words projected into ``dims`` dimensions and L2-normalised. Texts that
+share words are close; no network call is made. Pass it as
+``Memory(embedder=FakeEmbedder(64))``.
+
+``InMemoryBackend`` is the smallest ``MemoryBackend`` — a dict — used to test
+the core machinery without any datastore.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import re
+from typing import Dict, List, Optional
+
+from . import MemoryBackend, in_scope
+
+__all__ = ["FakeEmbedder", "InMemoryBackend"]
+
+_WORD = re.compile(r"[a-z0-9]+")
+
+
+class FakeEmbedder:
+    def __init__(self, dims: int = 64) -> None:
+        self.dims = dims
+
+    def _embed(self, text: str) -> List[float]:
+        vec = [0.0] * self.dims
+        for word in _WORD.findall(text.lower()):
+            h = int(hashlib.md5(word.encode()).hexdigest(), 16)
+            vec[h % self.dims] += 1.0
+        norm = math.sqrt(sum(v * v for v in vec))
+        return [v / norm for v in vec] if norm else [1.0 / math.sqrt(self.dims)] * self.dims
+
+    def __call__(self, texts: List[str]) -> List[List[float]]:
+        return [self._embed(t) for t in texts]
+
+
+class InMemoryBackend(MemoryBackend):
+    def __init__(self) -> None:
+        self._rows: Dict[str, dict] = {}
+
+    def _put(self, rows: List[dict]) -> None:
+        for r in rows:
+            self._rows[r["id"]] = dict(r)
+
+    def _get(self, record_id: str) -> Optional[dict]:
+        r = self._rows.get(record_id)
+        return dict(r) if r else None
+
+    def _delete_ids(self, ids: List[str]) -> int:
+        n = 0
+        for i in ids:
+            if self._rows.pop(i, None) is not None:
+                n += 1
+        return n
+
+    def _scan(self, scope_prefix: Optional[str]) -> List[dict]:
+        return [dict(r) for r in self._rows.values() if in_scope(r["scope"], scope_prefix)]

crewai_memory_core-0.1.0/tests/test_core_backend.py

@@ -0,0 +1,17 @@
+"""Core contract on the dict-backed InMemoryBackend (offline)."""
+import pytest
+
+from crewai_memory_core.contract import *  # noqa: F401,F403
+from crewai_memory_core import in_scope, norm_scope
+from crewai_memory_core.testing import InMemoryBackend
+
+
+@pytest.fixture()
+def backend():
+    return InMemoryBackend()
+
+
+def test_norm_and_in_scope():
+    assert norm_scope(None) == "/" and norm_scope("a/b/") == "/a/b" and norm_scope("/") == "/"
+    assert in_scope("/a/b", "/a") and in_scope("/a", "/a") and not in_scope("/ab", "/a")
+    assert in_scope("/anything", "/") and in_scope("/x", None)