starpod_memory/lib.rs
1//! # starpod-memory
2//!
3//! Memory system for Starpod — manages markdown files on disk with a
4//! hybrid search pipeline backed by SQLite FTS5 and optional vector embeddings.
5//!
6//! ## Architecture
7//!
8//! ```text
9//! .starpod/
10//! ├── SOUL.md # Agent personality (evergreen)
11//! ├── HEARTBEAT.md # Periodic task instructions (evergreen)
12//! ├── BOOT.md # Startup instructions (evergreen)
13//! ├── BOOTSTRAP.md # One-time init (self-destructing)
14//! ├── db/
15//! │ └── memory.db # SQLite: FTS5 index + vector embeddings
16//! └── users/<id>/
17//! ├── USER.md # User profile (per-user)
18//! ├── MEMORY.md # Long-term memory (per-user)
19//! └── memory/
20//! └── YYYY-MM-DD.md # Daily logs (per-user, temporal decay)
21//! ```
22//!
23//! ## Search Pipeline
24//!
25//! When the `embeddings` feature is enabled and an embedder is configured,
26//! [`MemoryStore::hybrid_search`] runs the full pipeline:
27//!
28//! 1. **FTS5 (BM25)** — keyword search with Porter stemming
29//! 2. **Vector search** — cosine similarity against stored embeddings
30//! 3. **RRF fusion** — Reciprocal Rank Fusion merges both ranked lists
31//! 4. **Temporal decay** — older daily logs are penalized (configurable half-life)
32//! 5. **MMR re-ranking** — Maximal Marginal Relevance promotes diversity
33//!
34//! Without embeddings, [`MemoryStore::search`] provides FTS5 + temporal decay.
35//!
36//! ## Features
37//!
38//! - `embeddings` — enables vector search via [`fastembed`] (BGE-Small-EN v1.5, 384 dims, ~45 MB)
39//!
40//! ## Security
41//!
42//! All file operations validate paths against traversal attacks, reject
43//! non-`.md` extensions, and enforce a 1 MB write size cap via [`scoring::validate_path`]
44//! and [`scoring::validate_content_size`].
45
46pub mod defaults;
47pub mod embedder;
48pub mod fusion;
49pub mod indexer;
50pub mod schema;
51pub mod scoring;
52pub mod store;
53pub mod user_view;
54
55pub use embedder::Embedder;
56pub use store::{MemoryStore, SearchResult};
57pub use user_view::UserMemoryView;