Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
M1-B: read pool, FTS5 search command, real status counts
AkitaOnRails8aebd2a7c9b4
diff --git a/Cargo.lock b/Cargo.lockindex 308fdeda..0536fc86 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -28,6 +28,7 @@ name = "ai-memory-cli"version = "0.1.0"dependencies = ["ai-memory-core",+ "ai-memory-store","anyhow","clap","dirs",diff --git a/crates/ai-memory-cli/Cargo.toml b/crates/ai-memory-cli/Cargo.tomlindex 315b3597..4300fa44 100644--- a/crates/ai-memory-cli/Cargo.toml+++ b/crates/ai-memory-cli/Cargo.toml@@ -14,6 +14,7 @@ path = "src/main.rs"[dependencies]ai-memory-core.workspace = true+ai-memory-store.workspace = trueanyhow.workspace = trueclap.workspace = truedirs.workspace = truediff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex 8d463ccc..a19c3061 100644--- a/crates/ai-memory-cli/src/cli.rs+++ b/crates/ai-memory-cli/src/cli.rs@@ -31,6 +31,8 @@ pub enum Command {Init(InitArgs),/// Print runtime status (counts, paths, version).Status(StatusArgs),+ /// Full-text search the wiki via FTS5.+ Search(SearchArgs),}/// Arguments for `init`.@@ -48,3 +50,16 @@ pub struct StatusArgs {#[arg(long)]pub json: bool,}++/// Arguments for `search`.+#[derive(Debug, Args)]+pub struct SearchArgs {+ /// FTS5 query string (e.g. `"karpathy wiki"` or `quick OR slow`).+ pub query: String,+ /// Maximum number of hits to return.+ #[arg(short = 'n', long, default_value_t = 10)]+ pub limit: usize,+ /// Emit results as JSON.+ #[arg(long)]+ pub json: bool,+}diff --git a/crates/ai-memory-cli/src/commands/mod.rs b/crates/ai-memory-cli/src/commands/mod.rsindex 586123b5..13d35b5b 100644--- a/crates/ai-memory-cli/src/commands/mod.rs+++ b/crates/ai-memory-cli/src/commands/mod.rs@@ -1,4 +1,5 @@//! Subcommand implementations.pub mod init;+pub mod search;pub mod status;diff --git a/crates/ai-memory-cli/src/commands/search.rs b/crates/ai-memory-cli/src/commands/search.rsnew file mode 100644index 00000000..ed7b3eb5--- /dev/null+++ b/crates/ai-memory-cli/src/commands/search.rs@@ -0,0 +1,35 @@+//! `ai-memory search` — run an FTS5 query against the wiki index.++use ai_memory_store::Store;+use anyhow::{Context, Result};++use crate::cli::SearchArgs;+use crate::config::Config;++/// Run the `search` subcommand.+///+/// # Errors+/// Returns an error if the store cannot be opened, the query is malformed,+/// or JSON serialisation fails.+pub async fn run(config: &Config, args: SearchArgs) -> Result<()> {+ let store = Store::open(&config.data_dir)+ .with_context(|| format!("opening store at {}", config.data_dir.display()))?;+ let hits = store+ .reader+ .search_pages(args.query.clone(), args.limit)+ .await?;++ if args.json {+ println!("{}", serde_json::to_string_pretty(&hits)?);+ } else if hits.is_empty() {+ println!("no results for {:?}", args.query);+ } else {+ println!("{} result(s) for {:?}:", hits.len(), args.query);+ for hit in &hits {+ println!(" {} rank={:.4}", hit.path, hit.rank);+ println!(" {}", hit.title);+ println!(" {}", hit.snippet);+ }+ }+ Ok(())+}diff --git a/crates/ai-memory-cli/src/commands/status.rs b/crates/ai-memory-cli/src/commands/status.rsindex 6bb446fb..1ce743bc 100644--- a/crates/ai-memory-cli/src/commands/status.rs+++ b/crates/ai-memory-cli/src/commands/status.rs@@ -1,11 +1,9 @@-//! `ai-memory status` — report runtime config and counts.-//!-//! M0 ships a placeholder that prints paths and version. M1 wires in the-//! store and replaces the placeholder with real counts.+//! `ai-memory status` — report runtime config and persisted counts.use std::path::Path;-use anyhow::Result;+use ai_memory_store::{StatusCounts, Store};+use anyhow::{Context, Result};use serde::Serialize;use crate::cli::StatusArgs;@@ -16,28 +14,40 @@ struct Report<'a> {version: &'a str,data_dir: &'a Path,bind: &'a str,- notes: &'static str,+ db_path: &'a Path,+ counts: StatusCounts,}/// Run the `status` subcommand.////// # Errors-/// Returns an error if JSON serialization fails.-pub fn run(config: &Config, args: StatusArgs) -> Result<()> {+/// Returns an error if the store cannot be opened or JSON serialisation fails.+pub async fn run(config: &Config, args: StatusArgs) -> Result<()> {+ let store = Store::open(&config.data_dir)+ .with_context(|| format!("opening store at {}", config.data_dir.display()))?;+ let counts = store.reader.status_counts().await?;+let report = Report {version: env!("CARGO_PKG_VERSION"),data_dir: &config.data_dir,bind: &config.bind,- notes: "M0 placeholder; counts arrive in M1",+ db_path: store.db_path(),+ counts,};if args.json {println!("{}", serde_json::to_string_pretty(&report)?);} else {println!("ai-memory {}", report.version);- println!(" data-dir: {}", report.data_dir.display());- println!(" bind: {}", report.bind);- println!(" note: {}", report.notes);+ println!(" data-dir: {}", report.data_dir.display());+ println!(" db: {}", report.db_path.display());+ println!(" bind: {}", report.bind);+ println!(+ " pages: {} (all versions: {})",+ report.counts.pages_latest, report.counts.pages_all+ );+ println!(" sessions: {}", report.counts.sessions);+ println!(" observations: {}", report.counts.observations);}Ok(())}diff --git a/crates/ai-memory-cli/src/main.rs b/crates/ai-memory-cli/src/main.rsindex 01d9053e..2d8b63ff 100644--- a/crates/ai-memory-cli/src/main.rs+++ b/crates/ai-memory-cli/src/main.rs@@ -37,6 +37,7 @@ async fn main() -> Result<()> {match cli.command {Command::Init(args) => commands::init::run(&config, args),- Command::Status(args) => commands::status::run(&config, args),+ Command::Status(args) => commands::status::run(&config, args).await,+ Command::Search(args) => commands::search::run(&config, args).await,}}diff --git a/crates/ai-memory-store/src/error.rs b/crates/ai-memory-store/src/error.rsindex f2806ad3..fb3d7154 100644--- a/crates/ai-memory-store/src/error.rs+++ b/crates/ai-memory-store/src/error.rs@@ -31,6 +31,10 @@ pub enum StoreError {#[error("writer actor is no longer running")]WriterClosed,+ /// A `spawn_blocking` task panicked or was cancelled.+ #[error("reader pool task did not complete: {0}")]+ PoolPanic(String),+/// Re-export of [`MemoryError`] for cross-crate propagation.#[error(transparent)]Memory(#[from] MemoryError),diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rsindex 9881b230..044290b0 100644--- a/crates/ai-memory-store/src/lib.rs+++ b/crates/ai-memory-store/src/lib.rs@@ -15,24 +15,32 @@ use rusqlite::Connection;mod error;mod migrations;mod ops;+mod reader;mod writer;pub use error::{StoreError, StoreResult};+pub use reader::{PageHit, ReaderPool, StatusCounts};pub use writer::WriterHandle;/// Filename used inside the data dir's `db/` subdirectory.pub const DB_FILENAME: &str = "memory.sqlite";+/// Default soft cap for the read-only connection pool.+const READER_POOL_SOFT_CAP: usize = 4;+/// Open (and migrate) a [`Store`] rooted at the given data directory.pub struct Store {/// Cloneable handle to submit mutations.pub writer: WriterHandle,+ /// Cloneable handle for read-only queries.+ pub reader: ReaderPool,db_path: PathBuf,}impl Store {/// Open the SQLite file at `<data_dir>/db/memory.sqlite`, applying any- /// outstanding migrations, then spawn the writer thread.+ /// outstanding migrations, then spawn the writer thread and prepare+ /// the read-only connection pool.////// # Errors/// Returns [`StoreError`] if the file cannot be opened, migrations@@ -51,7 +59,12 @@ impl Store {migrations::run(&mut conn)?;let writer = WriterHandle::spawn(conn);- Ok(Self { writer, db_path })+ let reader = ReaderPool::new(&db_path, READER_POOL_SOFT_CAP)?;+ Ok(Self {+ writer,+ reader,+ db_path,+ })}/// Path of the SQLite file on disk.@@ -143,4 +156,70 @@ mod tests {h.await.unwrap().unwrap();}}++ #[tokio::test]+ async fn status_counts_zero_on_fresh_db() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let counts = store.reader.status_counts().await.unwrap();+ assert_eq!(counts.pages_latest, 0);+ assert_eq!(counts.pages_all, 0);+ assert_eq!(counts.sessions, 0);+ assert_eq!(counts.observations, 0);+ }++ #[tokio::test]+ async fn search_finds_inserted_page_and_counts_reflect_supersession() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let ws = WorkspaceId::new();+ let proj = ProjectId::new();+ store.writer.ensure_workspace(ws, "default").await.unwrap();+ store+ .writer+ .ensure_project(proj, ws, "ai-memory", None)+ .await+ .unwrap();++ store+ .writer+ .upsert_page(sample_page(+ ws,+ proj,+ "alpha.md",+ "the quick brown fox jumps over the lazy dog",+ ))+ .await+ .unwrap();++ let hits = store.reader.search_pages("quick".into(), 10).await.unwrap();+ assert_eq!(hits.len(), 1);+ assert_eq!(hits[0].path.as_str(), "alpha.md");+ assert!(hits[0].snippet.contains("<mark>quick</mark>"));++ // Supersede: only the latest version should appear in counts'+ // pages_latest, and search should still return exactly one hit.+ store+ .writer+ .upsert_page(sample_page(+ ws,+ proj,+ "alpha.md",+ "a different sentence with quick still inside",+ ))+ .await+ .unwrap();++ let counts = store.reader.status_counts().await.unwrap();+ assert_eq!(counts.pages_latest, 1);+ assert_eq!(counts.pages_all, 2);++ let hits = store.reader.search_pages("quick".into(), 10).await.unwrap();+ assert_eq!(hits.len(), 1);+ assert!(+ hits[0].snippet.contains("different"),+ "snippet should come from the latest version, got: {}",+ hits[0].snippet+ );+ }}diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rsnew file mode 100644index 00000000..2998d45f--- /dev/null+++ b/crates/ai-memory-store/src/reader.rs@@ -0,0 +1,191 @@+//! Read-only connection pool and query helpers.+//!+//! WAL mode lets us have unlimited concurrent readers alongside the single+//! writer, so the pool is mostly about bounding file-descriptor usage and+//! avoiding `Connection::open` overhead on hot paths. Pool eviction is a+//! soft cap: a connection that comes back when the pool is already full+//! is simply dropped.++use std::path::{Path, PathBuf};+use std::sync::Arc;++use ai_memory_core::{PageId, PagePath};+use parking_lot::Mutex;+use rusqlite::{Connection, OpenFlags, OptionalExtension, params};+use serde::Serialize;++use crate::error::{StoreError, StoreResult};++/// One hit returned by [`ReaderPool::search_pages`].+#[derive(Debug, Clone, Serialize)]+pub struct PageHit {+ /// Stable identifier for this page version.+ pub id: PageId,+ /// Relative path within the wiki tree.+ pub path: PagePath,+ /// Page title.+ pub title: String,+ /// FTS5 snippet of the body around the matched terms (HTML-marked).+ pub snippet: String,+ /// FTS5 rank score (lower is better — closer to query terms).+ pub rank: f64,+}++/// Aggregate counts surfaced by [`ReaderPool::status_counts`] and consumed+/// by `ai-memory status`.+#[derive(Debug, Clone, Default, Serialize)]+pub struct StatusCounts {+ /// Pages with `is_latest = 1`.+ pub pages_latest: u64,+ /// All page versions including superseded ones.+ pub pages_all: u64,+ /// Total sessions ever recorded.+ pub sessions: u64,+ /// Total observations across all sessions.+ pub observations: u64,+}++/// Cheap, cloneable read-only connection pool handle.+#[derive(Clone)]+pub struct ReaderPool {+ inner: Arc<Inner>,+}++struct Inner {+ db_path: PathBuf,+ pool: Mutex<Vec<Connection>>,+ soft_cap: usize,+}++impl ReaderPool {+ /// Initialise the pool. Connections are opened lazily on first use.+ ///+ /// # Errors+ /// Currently infallible, but reserved so we can pre-open connections+ /// in a later milestone.+ pub fn new(db_path: &Path, soft_cap: usize) -> StoreResult<Self> {+ Ok(Self {+ inner: Arc::new(Inner {+ db_path: db_path.to_path_buf(),+ pool: Mutex::new(Vec::with_capacity(soft_cap.max(1))),+ soft_cap: soft_cap.max(1),+ }),+ })+ }++ /// Run a synchronous closure against a pooled read-only connection.+ ///+ /// The closure runs on the tokio blocking pool so it never starves the+ /// async runtime. If the pool is empty we open a fresh connection;+ /// on return we keep it only when the pool is below its soft cap.+ ///+ /// # Errors+ /// Returns [`StoreError::PoolPanic`] if the blocking task panics; any+ /// error returned by the closure is propagated unchanged.+ pub async fn with_conn<F, T>(&self, f: F) -> StoreResult<T>+ where+ F: FnOnce(&Connection) -> StoreResult<T> + Send + 'static,+ T: Send + 'static,+ {+ let inner = self.inner.clone();+ tokio::task::spawn_blocking(move || {+ let conn = checkout(&inner)?;+ let result = f(&conn);+ checkin(&inner, conn);+ result+ })+ .await+ .map_err(|e| StoreError::PoolPanic(e.to_string()))?+ }++ /// Run a full-text search against the FTS5 index and return the top+ /// matches, limited to `is_latest = 1` rows.+ ///+ /// # Errors+ /// Propagates any SQL or pool error.+ pub async fn search_pages(&self, query: String, limit: usize) -> StoreResult<Vec<PageHit>> {+ self.with_conn(move |conn| {+ let mut stmt = conn.prepare(+ "SELECT pages.id, pages.path, pages.title, \+ snippet(pages_fts, 1, '<mark>', '</mark>', '…', 24) AS snip, \+ pages_fts.rank \+ FROM pages_fts \+ JOIN pages ON pages.rowid = pages_fts.rowid \+ WHERE pages_fts MATCH ?1 AND pages.is_latest = 1 \+ ORDER BY pages_fts.rank \+ LIMIT ?2",+ )?;+ #[allow(clippy::cast_possible_wrap)]+ let rows = stmt.query_map(params![query, limit as i64], |row| {+ let id_bytes: Vec<u8> = row.get(0)?;+ let path: String = row.get(1)?;+ let title: String = row.get(2)?;+ let snippet: String = row.get(3)?;+ let rank: f64 = row.get(4)?;+ Ok((id_bytes, path, title, snippet, rank))+ })?;++ let mut hits = Vec::new();+ for row in rows {+ let (id_bytes, path, title, snippet, rank) = row?;+ hits.push(PageHit {+ id: PageId::from_slice(&id_bytes)?,+ path: PagePath::new(path)?,+ title,+ snippet,+ rank,+ });+ }+ Ok(hits)+ })+ .await+ }++ /// Return aggregate counts for the `status` view.+ ///+ /// # Errors+ /// Propagates any SQL or pool error.+ pub async fn status_counts(&self) -> StoreResult<StatusCounts> {+ self.with_conn(|conn| {+ let pages_latest: u64 = count(conn, "SELECT COUNT(*) FROM pages WHERE is_latest = 1")?;+ let pages_all: u64 = count(conn, "SELECT COUNT(*) FROM pages")?;+ let sessions: u64 = count(conn, "SELECT COUNT(*) FROM sessions")?;+ let observations: u64 = count(conn, "SELECT COUNT(*) FROM observations")?;+ Ok(StatusCounts {+ pages_latest,+ pages_all,+ sessions,+ observations,+ })+ })+ .await+ }+}++fn count(conn: &Connection, sql: &str) -> StoreResult<u64> {+ let n: Option<i64> = conn.query_row(sql, [], |row| row.get(0)).optional()?;+ Ok(u64::try_from(n.unwrap_or(0)).unwrap_or(0))+}++fn checkout(inner: &Inner) -> StoreResult<Connection> {+ if let Some(conn) = inner.pool.lock().pop() {+ return Ok(conn);+ }+ open_read_only(&inner.db_path)+}++fn checkin(inner: &Inner, conn: Connection) {+ let mut pool = inner.pool.lock();+ if pool.len() < inner.soft_cap {+ pool.push(conn);+ }+}++fn open_read_only(path: &Path) -> StoreResult<Connection> {+ let flags = OpenFlags::SQLITE_OPEN_READ_ONLY+ | OpenFlags::SQLITE_OPEN_URI+ | OpenFlags::SQLITE_OPEN_NO_MUTEX;+ let conn = Connection::open_with_flags(path, flags)?;+ conn.pragma_update(None, "busy_timeout", 5_000)?;+ Ok(conn)+}