aimem_core/lib.rs
1//! # aimem-core
2//!
3//! **Give your AI a memory — reusable core library.**
4//!
5//! `aimem-core` is a pure-Rust library that stores, retrieves, and searches
6//! text memories using [Turso](https://github.com/tursodatabase/turso) (an in-process
7//! SQLite engine with native vector support) as the sole storage backend.
8//! No external vector database, no cloud service, no API key.
9//!
10//! ## Feature overview
11//!
12//! | Feature | Implementation |
13//! |---------|---------------|
14//! | Vector storage | Turso `vector32()` BLOB column |
15//! | Semantic search | `vector_distance_cos()` — SimSIMD-accelerated cosine |
16//! | Full-text search | SQL `LIKE` scan (Turso FTS index optional) |
17//! | Embedding generation | [`fastembed`](https://crates.io/crates/fastembed) — `all-MiniLM-L6-v2` locally |
18//! | Knowledge graph | Temporal entity-relationship triples in SQLite |
19//! | Graph traversal | BFS over wing/room adjacency — no graph DB needed |
20//! | MCP protocol | Implemented in `aimem-mcp` (separate crate) |
21//!
22//! ## Architecture: 4-Layer Memory Stack
23//!
24//! ```text
25//! ┌─────────────────────────────────────────────────────────┐
26//! │ L0 Identity text ~100 tokens always loaded │
27//! │ L1 Essential story ~500-800 tok always loaded │
28//! │ L2 On-demand recall ~200-500 tok loaded on ask │
29//! │ L3 Deep semantic search unlimited full palace │
30//! └─────────────────────────────────────────────────────────┘
31//! ```
32//!
33//! ## Storage model
34//!
35//! Everything lives in a **single Turso DB file** (default: `~/.aimem/aimem.db`):
36//!
37//! ```text
38//! aimem.db
39//! ├── drawers — verbatim text chunks + vector32 embeddings
40//! ├── entities — knowledge graph nodes
41//! └── triples — temporal (subject → predicate → object) edges
42//! ```
43//!
44//! ## Concepts
45//!
46//! | Term | Meaning |
47//! |------|---------|
48//! | **Palace** | The entire memory store (one DB file) |
49//! | **Wing** | A named project or domain (e.g. `"my_app"`, `"journal"`) |
50//! | **Room** | A topic within a wing (e.g. `"backend"`, `"decisions"`) |
51//! | **Drawer** | One verbatim text chunk (800 chars) with its embedding |
52//! | **Tunnel** | A room that spans multiple wings — a conceptual bridge |
53//!
54//! ## Quick start
55//!
56//! ```toml
57//! # Cargo.toml
58//! [dependencies]
59//! aimem-core = "0.1.0"
60//! tokio = { version = "1", features = ["full"] }
61//! ```
62//!
63//! ```rust,no_run
64//! use aimem_core::{Config, Embedder, MemoryStack, PalaceDb};
65//!
66//! #[tokio::main]
67//! async fn main() -> anyhow::Result<()> {
68//! // 1. Load config (env > ~/.aimem/config.json > defaults)
69//! let cfg = Config::load()?;
70//!
71//! // 2. Open the palace (creates DB + schema on first run)
72//! let db = PalaceDb::open(&cfg.db_path).await?;
73//!
74//! // 3. Load local embedding model (downloads ~23 MB on first use)
75//! let embedder = Embedder::new()?;
76//!
77//! // 4. Build the memory stack
78//! let stack = MemoryStack::new(db, embedder, &cfg);
79//!
80//! // 5. Wake-up prompt: L0 (identity) + L1 (top memories) — inject into LLM context
81//! println!("{}", stack.wake_up(None).await?);
82//!
83//! // 6. Semantic search — uses Turso vector_distance_cos() natively
84//! println!("{}", stack.search("why did we choose Rust?", None, None).await?);
85//!
86//! Ok(())
87//! }
88//! ```
89//!
90//! ## Mining a project
91//!
92//! ```rust,no_run
93//! use aimem_core::{Config, Embedder, Miner, PalaceDb};
94//!
95//! #[tokio::main]
96//! async fn main() -> anyhow::Result<()> {
97//! let cfg = Config::load()?;
98//! let db = PalaceDb::open(&cfg.db_path).await?;
99//! let embedder = Embedder::new()?;
100//!
101//! let miner = Miner::new(db, Some(embedder));
102//!
103//! // Reads aimem.yaml in the project directory for wing/room config
104//! let stats = miner.mine("~/projects/my_app", None, "claude", 0, false).await?;
105//!
106//! println!(
107//! "Mined {} drawers from {} files",
108//! stats.drawers_added,
109//! stats.files_scanned - stats.files_skipped,
110//! );
111//! Ok(())
112//! }
113//! ```
114//!
115//! ## Keyword-only search without embeddings
116//!
117//! If you mine with `Miner::new(db, None)` or `ConvoMiner::new(db, None)`,
118//! drawers still participate in SQL keyword search even though they have no embeddings.
119//!
120//! ```rust,no_run
121//! use aimem_core::{Drawer, PalaceDb, Searcher};
122//!
123//! #[tokio::main]
124//! async fn main() -> anyhow::Result<()> {
125//! let db = PalaceDb::memory().await?;
126//! let drawer = Drawer {
127//! id: "drawer_kw_001".into(),
128//! wing: "demo".into(),
129//! room: "backend".into(),
130//! content: "Turso keeps the backend local and simple.".into(),
131//! source_file: None,
132//! chunk_index: 0,
133//! added_by: "example".into(),
134//! filed_at: chrono::Utc::now().to_rfc3339(),
135//! };
136//! db.insert_drawer(&drawer, None).await?;
137//!
138//! let searcher = Searcher::keyword_only(db);
139//! let hits = searcher.keyword_search("Turso", Some("demo"), None, 5).await?;
140//! assert_eq!(hits.len(), 1);
141//! Ok(())
142//! }
143//! ```
144//!
145//! ## Knowledge graph
146//!
147//! ```rust,no_run
148//! use aimem_core::{KnowledgeGraph, PalaceDb};
149//!
150//! #[tokio::main]
151//! async fn main() -> anyhow::Result<()> {
152//! let db = PalaceDb::memory().await?; // in-memory for demo
153//! let kg = KnowledgeGraph::new(db);
154//!
155//! // Store a temporal fact
156//! kg.add_triple("Max", "does", "swimming", Some("2025-01-01"), None).await?;
157//! kg.add_triple("Max", "loves", "chess", Some("2025-10-01"), None).await?;
158//!
159//! // Query all outgoing facts for "Max"
160//! let facts = kg.query_entity("Max", None, "outgoing").await?;
161//! for f in &facts {
162//! println!("{} → {} → {}", f.subject, f.predicate, f.object);
163//! }
164//!
165//! // Invalidate a fact (set valid_to = today)
166//! kg.invalidate("Max", "does", "swimming", None).await?;
167//!
168//! Ok(())
169//! }
170//! ```
171//!
172//! ## Low-level storage operations
173//!
174//! ```rust,no_run
175//! use aimem_core::{Drawer, Embedder, PalaceDb};
176//!
177//! #[tokio::main]
178//! async fn main() -> anyhow::Result<()> {
179//! let db = PalaceDb::memory().await?;
180//! let embedder = Embedder::new()?;
181//!
182//! let content = "We decided to use Rust for performance and memory safety.";
183//! let embedding = embedder.embed_one(content)?;
184//!
185//! let drawer = Drawer {
186//! id: "drawer_test_decision_001".to_string(),
187//! wing: "my_project".to_string(),
188//! room: "decisions".to_string(),
189//! content: content.to_string(),
190//! source_file: Some("DECISIONS.md".to_string()),
191//! chunk_index: 0,
192//! added_by: "claude".to_string(),
193//! filed_at: chrono::Utc::now().to_rfc3339(),
194//! };
195//!
196//! let inserted = db.insert_drawer(&drawer, Some(&embedding)).await?;
197//! println!("Inserted: {inserted}");
198//! println!("Total drawers: {}", db.drawer_count().await?);
199//!
200//! Ok(())
201//! }
202//! ```
203//!
204//! ## Crate feature flags
205//!
206//! `aimem-core` has no optional features itself — the embedding model
207//! is always available. The `hf-hub` feature of `fastembed` controls whether
208//! `Embedder::new()` can download models automatically.
209//!
210//! ## Reusing in other projects
211//!
212//! Because this is a library crate with no binary, any project can depend on it:
213//!
214//! ```toml
215//! [dependencies]
216//! aimem-core = { git = "https://github.com/v1cc0/aimem" }
217//! # or local path:
218//! aimem-core = { path = "/path/to/aimem/crates/aimem-core" }
219//! ```
220//!
221//! The public re-exports in this file form the stable API surface.
222//! Everything else is implementation detail.
223
224pub mod config;
225pub mod convo;
226pub mod db;
227pub mod embedder;
228pub mod extractor;
229pub mod graph;
230pub mod knowledge;
231pub mod layers;
232pub mod miner;
233pub mod search;
234pub mod types;
235
236pub use config::Config;
237pub use convo::{ConvoMineStats, ConvoMiner};
238pub use db::PalaceDb;
239pub use embedder::Embedder;
240pub use graph::{PalaceGraph, TraversalNode};
241pub use knowledge::KnowledgeGraph;
242pub use layers::MemoryStack;
243pub use miner::Miner;
244pub use search::Searcher;
245pub use types::{Drawer, DrawerMeta, Entity, RoomNode, SearchResult, Triple, Tunnel};