Skip to content

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.lock
index 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.toml
index 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 = true
anyhow.workspace = true
clap.workspace = true
dirs.workspace = true
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index 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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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)
+}