perf(api): add optional Redis read caching

pyproject.toml

@@ -68,6 +68,9 @@ milvus = [
     "pymilvus>=3.0.0,<4; sys_platform == 'win32'",
     "pymilvus[milvus-lite]>=3.0.0,<4; sys_platform != 'win32'",
 ]
+redis = [
+    "redis>=8.0.0,<9",
+]
 
 [project.urls]
 Homepage = "https://github.com/basicmachines-co/basic-memory"
@@ -103,6 +106,7 @@ markers = [
     "benchmark: Performance benchmark tests (deselect with '-m \"not benchmark\"')",
     "slow: Slow-running tests (deselect with '-m \"not slow\"')",
     "postgres: Tests that run against Postgres backend (deselect with '-m \"not postgres\"')",
+    "redis: Tests that run against a real Redis server",
     "windows: Windows-specific tests (deselect with '-m \"not windows\"')",
     "smoke: Fast end-to-end smoke tests for MCP flows",
     "semantic: Tests requiring semantic dependencies (fastembed, sqlite-vec, openai)",
@@ -131,6 +135,7 @@ dev = [
     "ruff>=0.16.0",
     "freezegun>=1.5.5",
     "testcontainers[postgres]>=4.0.0",
+    "redis>=8.0.0,<9",
     "psycopg>=3.2.0",
     "pyright>=1.1.408",
     "pytest-testmon>=2.2.0",

src/basic_memory/api/container.py

@@ -17,6 +17,7 @@
 
 from basic_memory import db
 from basic_memory.config import BasicMemoryConfig, ConfigManager
+from basic_memory.read_cache import ReadCache
 from basic_memory.runtime.mode import RuntimeMode, resolve_runtime_mode
 
 if TYPE_CHECKING:  # pragma: no cover
@@ -39,6 +40,11 @@ class ApiContainer:
     engine: AsyncEngine | None = None
     session_maker: async_sessionmaker[AsyncSession] | None = None
 
+    # --- Optional semantic read cache ---
+    # Hosts inject a namespace-bound implementation; local and off-lifespan
+    # ASGI requests deliberately stay dependency-free by default.
+    read_cache: ReadCache | None = None
+
     @classmethod
     def create(cls) -> "ApiContainer":  # pragma: no cover
         """Create container by reading ConfigManager.
@@ -91,6 +97,7 @@ def create_watch_coordinator(self) -> "WatchCoordinator":  # pragma: no cover
             config=self.config,
             should_watch=self.should_watch_files,
             skip_reason=self.watch_skip_reason,
+            read_cache=self.read_cache,
         )
 
     # --- Database Factory ---

src/basic_memory/api/v2/routers/directory_router.py

@@ -9,11 +9,24 @@
 - Better performance through indexed queries
 """
 
-from typing import Optional
+from contextlib import nullcontext
+from typing import Annotated
 
-from fastapi import APIRouter, Query, Path
+from fastapi import APIRouter, Depends, Path, Query
 
-from basic_memory.deps import DirectoryServiceV2ExternalDep
+from basic_memory.deps import (
+    create_model_read_cache,
+    DirectoryServiceV2ExternalDep,
+    ReadCacheDep,
+)
+from basic_memory.read_cache import (
+    ModelReadCache,
+    ReadCacheKey,
+    ReadCacheOperation,
+    ReadCacheScope,
+    read_cache_request_digest,
+)
+from basic_memory.read_cache.policy import DIRECTORY_READ_CACHE_MAX_PAYLOAD_BYTES
 from basic_memory.schemas.directory import (
     DEFAULT_DIRECTORY_PAGE_SIZE,
     MAX_DIRECTORY_PAGE_SIZE,
@@ -24,11 +37,42 @@
 router = APIRouter(prefix="/directory", tags=["directory-v2"])
 
 
+def get_directory_node_read_cache(
+    read_cache: ReadCacheDep,
+) -> ModelReadCache[DirectoryNode] | None:
+    """Bind directory trees and structures to the optional cache backend."""
+    return create_model_read_cache(
+        read_cache,
+        DirectoryNode,
+        max_payload_bytes=DIRECTORY_READ_CACHE_MAX_PAYLOAD_BYTES,
+    )
+
+
+DirectoryNodeReadCacheDep = Annotated[
+    ModelReadCache[DirectoryNode] | None,
+    Depends(get_directory_node_read_cache),
+]
+
+
+def get_directory_list_read_cache(
+    read_cache: ReadCacheDep,
+) -> ModelReadCache[DirectoryListResponse] | None:
+    """Bind paginated directory listings to the optional cache backend."""
+    return create_model_read_cache(read_cache, DirectoryListResponse)
+
+
+DirectoryListReadCacheDep = Annotated[
+    ModelReadCache[DirectoryListResponse] | None,
+    Depends(get_directory_list_read_cache),
+]
+
+
 @router.get("/tree", response_model=DirectoryNode, response_model_exclude_none=True)
 async def get_directory_tree(
     directory_service: DirectoryServiceV2ExternalDep,
+    read_cache: DirectoryNodeReadCacheDep,
     project_id: str = Path(..., description="Project external UUID"),
-):
+) -> DirectoryNode:
     """Get hierarchical directory structure from the knowledge base.
 
     Args:
@@ -38,18 +82,31 @@ async def get_directory_tree(
     Returns:
         DirectoryNode representing the root of the hierarchical tree structure
     """
-    # Get a hierarchical directory tree for the specific project
-    tree = await directory_service.get_directory_tree()
+    cache_key = ReadCacheKey(
+        project_id=project_id,
+        operation=ReadCacheOperation.directory_tree,
+        request_digest=read_cache_request_digest("tree"),
+    )
+    cache_scope = (
+        read_cache.read(key=cache_key)
+        if read_cache is not None
+        else nullcontext(ReadCacheScope[DirectoryNode]())
+    )
+    async with cache_scope as cached:
+        if cached.value is not None:
+            return cached.value
 
-    # Return the hierarchical tree
-    return tree
+        result = await directory_service.get_directory_tree()
+        cached.value = result
+        return result
 
 
 @router.get("/structure", response_model=DirectoryNode, response_model_exclude_none=True)
 async def get_directory_structure(
     directory_service: DirectoryServiceV2ExternalDep,
+    read_cache: DirectoryNodeReadCacheDep,
     project_id: str = Path(..., description="Project external UUID"),
-):
+) -> DirectoryNode:
     """Get folder structure for navigation (no files).
 
     Optimized endpoint for folder tree navigation. Returns only directory nodes
@@ -62,8 +119,23 @@ async def get_directory_structure(
     Returns:
         DirectoryNode tree containing only folders (type="directory")
     """
-    structure = await directory_service.get_directory_structure()
-    return structure
+    cache_key = ReadCacheKey(
+        project_id=project_id,
+        operation=ReadCacheOperation.directory_structure,
+        request_digest=read_cache_request_digest("structure"),
+    )
+    cache_scope = (
+        read_cache.read(key=cache_key)
+        if read_cache is not None
+        else nullcontext(ReadCacheScope[DirectoryNode]())
+    )
+    async with cache_scope as cached:
+        if cached.value is not None:
+            return cached.value
+
+        result = await directory_service.get_directory_structure()
+        cached.value = result
+        return result
 
 
 @router.get(
@@ -73,20 +145,19 @@ async def get_directory_structure(
 )
 async def list_directory(
     directory_service: DirectoryServiceV2ExternalDep,
+    read_cache: DirectoryListReadCacheDep,
     project_id: str = Path(..., description="Project external UUID"),
     dir_name: str = Query("/", description="Directory path to list"),
     depth: int = Query(1, ge=1, le=10, description="Recursion depth (1-10)"),
-    file_name_glob: Optional[str] = Query(
-        None, description="Glob pattern for filtering file names"
-    ),
+    file_name_glob: str | None = Query(None, description="Glob pattern for filtering file names"),
     page: int = Query(1, ge=1, description="One-indexed result page"),
     page_size: int = Query(
         DEFAULT_DIRECTORY_PAGE_SIZE,
         ge=1,
         le=MAX_DIRECTORY_PAGE_SIZE,
         description="Number of nodes per page",
     ),
-):
+) -> DirectoryListResponse:
     """List directory contents with filtering and depth control.
 
     Args:
@@ -101,11 +172,32 @@ async def list_directory(
     Returns:
         Bounded page of DirectoryNode objects matching the criteria
     """
-    # Get directory listing with filtering
-    return await directory_service.list_directory(
-        dir_name=dir_name,
-        depth=depth,
-        file_name_glob=file_name_glob,
-        page=page,
-        page_size=page_size,
+    cache_key = ReadCacheKey(
+        project_id=project_id,
+        operation=ReadCacheOperation.directory_list,
+        request_digest=read_cache_request_digest(
+            dir_name,
+            str(depth),
+            file_name_glob or "",
+            str(page),
+            str(page_size),
+        ),
+    )
+    cache_scope = (
+        read_cache.read(key=cache_key)
+        if read_cache is not None
+        else nullcontext(ReadCacheScope[DirectoryListResponse]())
     )
+    async with cache_scope as cached:
+        if cached.value is not None:
+            return cached.value
+
+        result = await directory_service.list_directory(
+            dir_name=dir_name,
+            depth=depth,
+            file_name_glob=file_name_glob,
+            page=page,
+            page_size=page_size,
+        )
+        cached.value = result
+        return result