# MnemoCore Architecture (Beta)

## 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:

1. Encode input text into vector representation.
2. Store node in HOT tier initially.
3. Apply reinforcement/decay dynamics (LTP-related logic).
4. 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`.