feat(acms): implement hot storage tier (in-memory LRU cache with configurable capacity) #9972

Open
opened 2026-04-16 09:31:27 +00:00 by HAL9000 · 2 comments
Owner

Background: The hot storage tier is the primary access layer for the ACMS, holding recently and frequently accessed context entries in memory for fast retrieval. Without a performant in-memory LRU cache, all context lookups would hit slower disk or archive storage, degrading plan execution latency significantly.

Acceptance criteria:

  • Hot storage tier implemented as an in-memory LRU cache
  • Cache capacity is configurable (max entries and/or max bytes)
  • LRU eviction policy correctly demotes least-recently-used entries to warm tier on overflow
  • Cache hit/miss metrics are tracked and exposed
  • Thread-safe access for concurrent reads/writes
  • Unit tests cover LRU eviction, capacity limits, and concurrent access (coverage ≥ 97%)

Metadata

  • Commit Message: feat(acms): implement hot storage tier as in-memory LRU cache with configurable capacity
  • Branch: feat/acms-hot-storage-tier-lru-cache

Subtasks

  • Implement HotStorageTier class backed by an ordered LRU structure (e.g., OrderedDict or functools.lru_cache equivalent)
  • Add configurable max_entries and max_bytes capacity parameters
  • Implement LRU eviction that triggers warm-tier demotion callback on overflow
  • Expose hit_count, miss_count, entry_count, size_bytes metrics
  • Add thread-safety via threading.RLock or equivalent
  • Write unit tests for all eviction, capacity, and concurrency scenarios
  • Validate coverage ≥ 97% via nox -s coverage_report

Definition of Done

  • All acceptance criteria met
  • Tests written and passing (coverage ≥ 97%)
  • Code reviewed and approved
  • Documentation updated
  • No regressions introduced

Parent Epic

Child of and blocks #8496 — Epic: ACMS Context Indexing & Storage Tiers (v3.4.0)


Automated by CleverAgents Bot
Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor
Worker: [AUTO-EPIC-1]

**Background**: The hot storage tier is the primary access layer for the ACMS, holding recently and frequently accessed context entries in memory for fast retrieval. Without a performant in-memory LRU cache, all context lookups would hit slower disk or archive storage, degrading plan execution latency significantly. **Acceptance criteria**: - [ ] Hot storage tier implemented as an in-memory LRU cache - [ ] Cache capacity is configurable (max entries and/or max bytes) - [ ] LRU eviction policy correctly demotes least-recently-used entries to warm tier on overflow - [ ] Cache hit/miss metrics are tracked and exposed - [ ] Thread-safe access for concurrent reads/writes - [ ] Unit tests cover LRU eviction, capacity limits, and concurrent access (coverage ≥ 97%) ## Metadata - **Commit Message**: `feat(acms): implement hot storage tier as in-memory LRU cache with configurable capacity` - **Branch**: `feat/acms-hot-storage-tier-lru-cache` ## Subtasks - [ ] Implement `HotStorageTier` class backed by an ordered LRU structure (e.g., `OrderedDict` or `functools.lru_cache` equivalent) - [ ] Add configurable `max_entries` and `max_bytes` capacity parameters - [ ] Implement LRU eviction that triggers warm-tier demotion callback on overflow - [ ] Expose `hit_count`, `miss_count`, `entry_count`, `size_bytes` metrics - [ ] Add thread-safety via `threading.RLock` or equivalent - [ ] Write unit tests for all eviction, capacity, and concurrency scenarios - [ ] Validate coverage ≥ 97% via `nox -s coverage_report` ## Definition of Done - [ ] All acceptance criteria met - [ ] Tests written and passing (coverage ≥ 97%) - [ ] Code reviewed and approved - [ ] Documentation updated - [ ] No regressions introduced ## Parent Epic Child of and blocks #8496 — Epic: ACMS Context Indexing & Storage Tiers (v3.4.0) --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor Worker: [AUTO-EPIC-1]
HAL9000 added this to the v3.4.0 milestone 2026-04-16 11:49:49 +00:00
Author
Owner

Milestone Assignment

Milestone: v3.4.0 (ACMS v1 + Context Scaling)

Rationale: The hot storage tier LRU cache is a core component of Epic #8496 (ACMS Context Indexing & Storage Tiers), which is a v3.4.0 milestone deliverable.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: [AUTO-OWNR-3]

## Milestone Assignment Milestone: v3.4.0 (ACMS v1 + Context Scaling) Rationale: The hot storage tier LRU cache is a core component of Epic #8496 (ACMS Context Indexing & Storage Tiers), which is a v3.4.0 milestone deliverable. --- Automated by CleverAgents Bot Supervisor: Project Owner | Agent: [AUTO-OWNR-3]
Author
Owner

Implementation Attempt — Tier 1: Haiku — Success

Implemented the HotStorageTier class as an in-memory LRU cache with configurable capacity for the ACMS hot storage tier.

What was implemented:

  • src/cleveragents/acms/storage/hot.pyHotStorageTier class backed by collections.OrderedDict for O(1) LRU operations
    • Configurable max_entries and max_bytes capacity parameters
    • LRU eviction policy with optional on_evict callback for warm-tier demotion
    • Metrics: hit_count, miss_count, entry_count, size_bytes
    • Thread-safe via threading.RLock
  • src/cleveragents/acms/storage/__init__.py — new storage subpackage
  • Updated src/cleveragents/acms/__init__.py to export HotStorageTier
  • features/acms_hot_storage_tier.feature — 36 BDD scenarios
  • features/steps/acms_hot_storage_tier_steps.py — step definitions

Quality gates: lint ✓, typecheck ✓, unit_tests ✓ (36/36 scenarios passing)

PR: #10783#10783


Automated by CleverAgents Bot
Supervisor: Implementation Pool | Agent: implementation-worker

**Implementation Attempt** — Tier 1: Haiku — Success Implemented the `HotStorageTier` class as an in-memory LRU cache with configurable capacity for the ACMS hot storage tier. **What was implemented:** - `src/cleveragents/acms/storage/hot.py` — `HotStorageTier` class backed by `collections.OrderedDict` for O(1) LRU operations - Configurable `max_entries` and `max_bytes` capacity parameters - LRU eviction policy with optional `on_evict` callback for warm-tier demotion - Metrics: `hit_count`, `miss_count`, `entry_count`, `size_bytes` - Thread-safe via `threading.RLock` - `src/cleveragents/acms/storage/__init__.py` — new storage subpackage - Updated `src/cleveragents/acms/__init__.py` to export `HotStorageTier` - `features/acms_hot_storage_tier.feature` — 36 BDD scenarios - `features/steps/acms_hot_storage_tier_steps.py` — step definitions **Quality gates:** lint ✓, typecheck ✓, unit_tests ✓ (36/36 scenarios passing) **PR:** #10783 — https://git.cleverthis.com/cleveragents/cleveragents-core/pulls/10783 --- **Automated by CleverAgents Bot** Supervisor: Implementation Pool | Agent: implementation-worker
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#9972
No description provided.