Beta Context

This document describes the current implementation direction in beta. It is not a guarantee of final architecture, performance, or feature completeness.

Core Components

src/core/engine.py: Main orchestration for memory storage, encoding, query, and synaptic augmentation.
src/core/binary_hdv.py: Binary hyperdimensional vector operations.
src/core/tier_manager.py: HOT/WARM/COLD placement and movement logic.
src/core/config.py: Typed config loading from YAML + env overrides.
src/core/async_storage.py: Async Redis metadata operations.
src/api/main.py: FastAPI interface.

Memory Model

MnemoCore represents memory as high-dimensional vectors and metadata-rich nodes:

Encode input text into vector representation.
Store node in HOT tier initially.
Apply reinforcement/decay dynamics (LTP-related logic).
Move between tiers based on thresholds and access patterns.

Tiering Model

HOT: In-memory dictionary for fastest access.
WARM: Qdrant-backed where available; filesystem fallback when unavailable.
COLD: Filesystem archival path for long-lived storage.

Query Flow (Current Beta)

Current query behavior prioritizes HOT tier recall and synaptic score augmentation. Cross-tier retrieval is still evolving and should be treated as beta behavior.

Async + External Services

Redis is used for async metadata and event stream operations.
API startup checks Redis health and can operate in degraded mode.
Qdrant usage is enabled through tier manager and can fall back to local files.

Observability

Prometheus metrics endpoint mounted at /metrics in API server.
Logging behavior controlled through config.

Practical Limitations

Some roadmap functionality remains TODO-marked in code.
Interface contracts may change across beta releases.
Performance can vary significantly by hardware and data profile.

For active limitations and next work items, see docs/ROADMAP.md.