perf(api): add optional Redis read caching

[phernandez]

Why

Repeated Basic Memory reads currently execute the authoritative database or storage path even
when agents and the web explorer ask for the same data again. This PR gives Basic Memory
ownership of its semantic read-cache policy while preserving the existing boundary: Cloud owns
tenant/control-plane caching and rate limiting; Basic Memory owns caching for its own read API.

Production Logfire data from July 30 calibrated the phase-one surface:

Production path	Calls	Average	p95
Web project tree	1,073	1.79 s	4.66 s
Web folder note list	789	1.69 s	3.30 s
Web project list	145	1.54 s	3.27 s
MCP read_note	2,636	2.78 s	4.37 s
MCP search	723	3.39 s	5.80 s

The existing Cloud gateway cache showed useful directory locality: 62.5% for directory
structures, 23.0% for directory lists, and 14.8% for full directory trees. On web folder-list
traces, a directory miss plus a project-list tenant dispatch averaged about 2.4 seconds, while
requests with cached dependencies averaged about 0.64 seconds. That evidence moves Basic Memory
directory reads into phase one. Search remains deferred because latency and volume are clear but
exact repeated-query locality is not yet observable.

Redis remains optional. Local-first installations keep the current default behavior and do not
need a Redis server or import redis-py.

What Changed

• Added an optional redis>=8,<9 package extra and a narrow async ReadCache protocol.
  The configured backend is ReadCache | None; disabled installations do not construct or call
  a no-op cache.
• Added a namespace-bound redis-py adapter with tenant/project-scoped keys, project-generation
  invalidation, bounded generation and response TTLs, payload limits, stale-fill protection,
  operational bypass behavior, and low-cardinality cache telemetry.
• Added lightweight ModelReadCache[ResponseType] facades. Each facade binds one Pydantic
  response type and its policy while all facades share one injected backend, Redis pool,
  namespace, and project generation.
• Added Python async context managers for read-through and unconditional invalidation. Routes
  define a named cache key, enter read_cache.read(...), and keep the authoritative operation
  inline. Mutation and indexing flows use invalidate_cache(...) at their durable boundary.
• Added read-through caching for:
  • entity responses by external ID;
  • successful same-project identifier resolution;
  • bounded Markdown resources;
  • directory trees;
  • directory structures;
  • paginated and filtered directory lists.
• Added failure-safe and cancellation-safe project invalidation around accepted note mutations,
  hosted read repair, import attempts, direct and watcher indexing, project indexing and search
  reindexing, relation resolution, directory moves and deletes, project-root changes, and startup
  recovery. These hooks do not make indexing read from Redis; they prevent API responses from
  remaining valid after an authoritative mutation commits.
• Deferred accepted-note materialization advances the generation immediately after terminal
  status publication, before potentially slow indexing begins, and again after indexing. Status
  polling therefore cannot retain a cached pending or writing entity throughout the index.
• Added InvalidatingIndexFileExecutor, which wraps the transaction-bearing individual-file
  indexing operation. Local watcher indexing composes it only when caching is enabled. Hosted
  storage-event workers can compose the same decorator at the equivalent boundary.
• Added real Redis 8.8 integration tests for cache behavior, route behavior, invalidation, races,
  failures, payload policy, and cancellation. Redis is not mocked or emulated.
• Updated docs/REDIS_READ_CACHE_PLAN.md with the measured production calibration, Cloud
  integration requirements, testing strategy, rollout stages, and intentionally deferred work.

Implementation Details

Key and invalidation model

The keyspace is versioned and Redis Cluster compatible:

bm:read:v1:{scope_digest}:generation
bm:read:v1:{scope_digest}:<operation>:<request_digest>

scope_digest hashes a host-owned namespace plus the canonical project external UUID. The host
namespace is the tenant isolation boundary; the project UUID is an inner semantic scope.
Authorization and tenant database selection still happen before cache lookup.

Cache values carry the project generation observed by their lookup. Lua scripts initialize
generations atomically and store a completed miss only while that generation is still current, so
a slow read cannot repopulate stale data after a concurrent mutation. Generation keys and
responses both have bounded TTLs; inactive projects age out without scans.

Operational Redis failures such as connection, timeout, capacity, read-only replica, and server
response errors bypass reads or become observable best-effort invalidation failures after a
committed write. Invalid data, client-input errors, and local programming errors fail fast. The
initial 60-second response TTL bounds stale exposure if post-commit invalidation is temporarily
unavailable.

Python and FastAPI composition

The Core composition root exposes an optional raw backend. FastAPI dependencies wrap that backend
in response-specific ModelReadCache[ResponseType] facades. Routes do not pass a model type for
each lookup, reach through to Redis, install loader callbacks, or implement disabled states.

The read path stays ordinary Python:

cache_key = ReadCacheKey(...)

if read_cache is None:
    return await authoritative_read()

async with read_cache.read(key=cache_key) as cached:
    if cached.value is not None:
        return cached.value

    cached.value = await authoritative_read()
    return cached.value

The actual routes keep the authoritative flow inline rather than extracting artificial callbacks.
Named keys make the context-manager boundary easy to scan.

Directory list keys include directory name, depth, file-name glob, page, and page size. Directory
tree and structure responses use a measured two MiB payload ceiling: today's production
directory-tree maximum was about 1.29 MiB and the seven-day structure maximum was about 0.92 MiB.
Directory-list responses keep the generic one MiB ceiling.

Cloud requirements

No Cloud code changes are included in this PR. Cloud must complete the following wiring before
enabling Basic Memory cached reads:

1. Reuse one long-lived async Redis client and pool. Create lightweight namespace-bound adapters
   for authenticated requests and workers; do not create a Redis server, client, pool, or model
   facade per tenant.
2. Derive the cache namespace from trusted authenticated tenant or workspace identity, preferably
   its UUID. Never accept the namespace from a public request or derive it from a display name,
   slug, or API key.
3. Keep the canonical Basic Memory project UUID inside that tenant namespace. A project UUID does
   not replace the tenant isolation boundary.
4. Use one canonical tenant-to-namespace function in HTTP handling and every worker that can
   publish project state. Do not enable cached reads until request and worker invalidation have
   namespace parity.
5. Override Core's low-level optional cache dependency. Let Core continue to own the
   response-specific facades, types, TTLs, payload limits, and generation behavior.
6. In build_cloud_index_file_runtime, decorate the transaction-bearing FileIndexer with
   InvalidatingIndexFileExecutor before passing it to run_index_file. This places invalidation
   after each committed file even when cancellation or later search/reconciliation work fails.
7. Inject the same namespace-bound invalidator into accepted-note materialization, storage-event
   workers, project indexing and reindexing, read repair, import, relation resolution, moves,
   deletes, and recovery. Preserve Core's cancellation-safe committed-mutation boundaries.
8. Treat terminal materialization publication and indexing as separate freshness phases.
   Invalidate immediately after the terminal status transaction returns, before indexing starts,
   and retain a second invalidation after indexing.
9. Keep Cloud's later GatewayCache invalidation temporarily for outer response-cache and
   live-update parity. It is not the Basic Memory semantic-cache correctness boundary.
10. Keep Cloud project-list caching and optimization in Cloud. GET /api/v2/projects composes
    accessible workspaces and active-project tenant queries; it is not a Basic Memory semantic
    read and this PR does not accelerate it.
11. Roll out by tenant cohort while comparing hit/miss/bypass outcomes, Redis latency, tenant
    database queries, and end-to-end MCP and web latency. Remove overlapping Cloud directory,
    entity, and resource response caches only after behavior and observability reach parity.

These requirements are also checked in at docs/REDIS_READ_CACHE_PLAN.md.

Testing

All cache integration tests use a real Redis 8.8 server through testcontainers unless
BASIC_MEMORY_TEST_REDIS_URL points to an existing server.

• LOGFIRE_IGNORE_NO_CONFIG=1 uv run pytest -p pytest_mock --no-cov -q test-int/read_cache
  • 60 passed with SQLite plus real Redis.
• BASIC_MEMORY_TEST_POSTGRES=1 LOGFIRE_IGNORE_NO_CONFIG=1 uv run pytest -p pytest_mock --no-cov -q test-int/read_cache
  • 60 passed with PostgreSQL plus real Redis.
• LOGFIRE_IGNORE_NO_CONFIG=1 uv run pytest -p pytest_mock --no-cov -q test-int/read_cache/test_materialization_invalidation.py tests/cloud/test_note_content_materialization.py
  • 19 passed; the real Redis regression blocks indexing and proves the terminal publication
    advances the generation before the final post-index bump.
• LOGFIRE_IGNORE_NO_CONFIG=1 uv run pytest -p pytest_mock --no-cov -q test-int/read_cache/test_api_read_cache.py tests/api/v2/test_directory_router.py
  • 24 passed.
• Exact watcher-index transaction-exit cancellation regression
  • 1 passed with a real database and real Redis.
• LOGFIRE_IGNORE_NO_CONFIG=1 just test-sqlite
  • Earlier branch-wide gate: 4,527 unit tests and 424 integration tests passed, with documented
    platform/backend skips and semantic benchmark deselections.
• just fast-check
  • Passed Ruff fix/check/format and strict ty on the current head.
• just doctor
  • Passed the end-to-end file/database loop on the current head.
• uv lock --check
  • Passed.
• uv run mdformat --check docs/REDIS_READ_CACHE_PLAN.md
  • Passed.
• git diff --check
  • Passed.

GitHub-hosted Windows skips the real-Redis integration module when no external
BASIC_MEMORY_TEST_REDIS_URL is configured because it cannot start the Linux testcontainer. The
Linux SQLite and PostgreSQL jobs retain the real-server gate.

Local benchmarks prove that hits avoid authoritative database work; they are not hosted-latency
promises:

Backend	Authoritative median	Cached median	SQL statements across 20 reads
SQLite	15.518 ms	7.329 ms	180 -> 60
PostgreSQL	102.712 ms	40.221 ms	140 -> 20

Risks / Follow-ups

• Project-wide generations favor correctness and simple invalidation over maximum hit rate.
  Narrower invalidation should follow only if production telemetry shows that unrelated writes
  materially reduce useful hits.
• A Redis outage during post-commit invalidation can leave a prior response reachable until its
  60-second TTL expires. The failure is observable and deliberately does not fail an already
  committed authoritative write.
• Cross-project identifier resolutions are not cached because one project generation cannot
  safely represent both dependency scopes. The broader resolve API contract is tracked
  separately.
• Search caching is deferred until exact-query locality is measured. Its production latency makes
  it promising, but caching cannot help predominantly unique queries.
• Cloud project enumeration needs a Cloud-side follow-up. Core directory caching should reduce
  tree and folder navigation work, but it does not remove active-project reconciliation or
  Cloud-side excerpt, share, sorting, and pagination work.
• Overlapping Cloud gateway caches are transitional. Keeping two permanent response-cache layers
  would complicate freshness reasoning and obscure which layer produced the benefit.
• The pull request must remain unmerged until current-head CI passes, all non-outdated Codex
  threads are resolved, and Codex posts a fresh current-head approval.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8bff587dd7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1f146493ae

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 621f642efc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 87ee016a53

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c80d631212

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 78e109d750

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5994aca43f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2b7eea3ffc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9f02ff39d8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d4121acdf2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 007b54ca43

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b8c5f72470

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1badd6fbf4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 53076d7731

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 930b61f2de

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d46d420805

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 596356038d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 305c85879b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a562574723

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: efed2c8ab8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[phernandez]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7428125a10

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[phernandez]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. What shall we delve into next?

Reviewed commit: 310c743fd4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".