Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
M1-C: ai-memory-wiki crate + write-page CLI, atomic write-through
AkitaOnRails4eaf66d17b09
diff --git a/Cargo.lock b/Cargo.lockindex 0536fc86..a7e893fd 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -29,6 +29,7 @@ version = "0.1.0"dependencies = ["ai-memory-core","ai-memory-store",+ "ai-memory-wiki","anyhow","clap","dirs",@@ -106,6 +107,16 @@ name = "ai-memory-wiki"version = "0.1.0"dependencies = ["ai-memory-core",+ "ai-memory-store",+ "anyhow",+ "jiff",+ "serde",+ "serde_json",+ "serde_yaml",+ "tempfile",+ "thiserror 2.0.18",+ "tokio",+ "tracing",][[package]]@@ -1113,6 +1124,12 @@ version = "1.0.22"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"+[[package]]+name = "ryu"+version = "1.0.23"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"+[[package]]name = "same-file"version = "1.0.6"@@ -1186,6 +1203,19 @@ dependencies = ["serde",]+[[package]]+name = "serde_yaml"+version = "0.9.34+deprecated"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "6a8b1a1a2ebf674015cc02edccce75287f1a0130d394307b36743c2f5d504b47"+dependencies = [+ "indexmap",+ "itoa",+ "ryu",+ "serde",+ "unsafe-libyaml",+]+[[package]]name = "sha2"version = "0.10.9"@@ -1576,6 +1606,12 @@ version = "0.2.6"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853"+[[package]]+name = "unsafe-libyaml"+version = "0.2.11"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "673aac59facbab8a9007c7f6108d11f63b603f7cabff99fabf650fea5c32b861"+[[package]]name = "url"version = "2.5.8"diff --git a/crates/ai-memory-cli/Cargo.toml b/crates/ai-memory-cli/Cargo.tomlindex 4300fa44..a2b26443 100644--- a/crates/ai-memory-cli/Cargo.toml+++ b/crates/ai-memory-cli/Cargo.toml@@ -15,6 +15,7 @@ path = "src/main.rs"[dependencies]ai-memory-core.workspace = trueai-memory-store.workspace = true+ai-memory-wiki.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 a19c3061..1f56cceb 100644--- a/crates/ai-memory-cli/src/cli.rs+++ b/crates/ai-memory-cli/src/cli.rs@@ -33,6 +33,8 @@ pub enum Command {Status(StatusArgs),/// Full-text search the wiki via FTS5.Search(SearchArgs),+ /// Write or update a wiki page atomically (also indexes it in the store).+ WritePage(WritePageArgs),}/// Arguments for `init`.@@ -63,3 +65,33 @@ pub struct SearchArgs {#[arg(long)]pub json: bool,}++/// Arguments for `write-page`.+#[derive(Debug, Args)]+pub struct WritePageArgs {+ /// Relative wiki path (e.g. `notes/foo.md`).+ #[arg(long, visible_alias = "p")]+ pub path: String,+ /// Markdown body. Use `-` to read from stdin.+ #[arg(long, visible_alias = "b")]+ pub body: String,+ /// Optional page title; otherwise derived from the first `# heading`+ /// in the body, or the path stem.+ #[arg(long)]+ pub title: Option<String>,+ /// Repeatable tag to add to the frontmatter `tags` array.+ #[arg(long, short = 't')]+ pub tag: Vec<String>,+ /// Tier (`working`, `episodic`, `semantic`, `procedural`).+ #[arg(long, default_value = "semantic")]+ pub tier: String,+ /// Pin the page so the future decay sweep skips it.+ #[arg(long)]+ pub pinned: bool,+ /// Workspace name (auto-created if absent).+ #[arg(long, default_value = "default")]+ pub workspace: String,+ /// Project name within the workspace (auto-created if absent).+ #[arg(long, default_value = "scratch")]+ pub project: String,+}diff --git a/crates/ai-memory-cli/src/commands/mod.rs b/crates/ai-memory-cli/src/commands/mod.rsindex 13d35b5b..c22a60c0 100644--- a/crates/ai-memory-cli/src/commands/mod.rs+++ b/crates/ai-memory-cli/src/commands/mod.rs@@ -3,3 +3,4 @@pub mod init;pub mod search;pub mod status;+pub mod write_page;diff --git a/crates/ai-memory-cli/src/commands/write_page.rs b/crates/ai-memory-cli/src/commands/write_page.rsnew file mode 100644index 00000000..aba587c8--- /dev/null+++ b/crates/ai-memory-cli/src/commands/write_page.rs@@ -0,0 +1,84 @@+//! `ai-memory write-page` — testing helper for the M1-C wiki write path.+//!+//! Once hooks (M3) and consolidation (M7) are wired, real callers will+//! flow through those, not this command. It stays around as a manual+//! escape hatch and to exercise the chain in development.++use std::io::Read;++use ai_memory_core::{PagePath, Tier};+use ai_memory_store::Store;+use ai_memory_wiki::{Wiki, WritePageRequest};+use anyhow::{Context, Result};+use serde_json::{Map, Value};++use crate::cli::WritePageArgs;+use crate::config::Config;++/// Run the `write-page` subcommand.+///+/// # Errors+/// Returns an error if the store cannot be opened, the path is invalid,+/// the tier is unknown, the body cannot be read, or the underlying+/// `Wiki::write_page` call fails.+pub async fn run(config: &Config, args: WritePageArgs) -> Result<()> {+ let body = if args.body == "-" {+ let mut buf = String::new();+ std::io::stdin().read_to_string(&mut buf)?;+ buf+ } else {+ args.body+ };+ let tier: Tier = args.tier.parse()?;+ let path = PagePath::new(args.path.clone())?;++ let store = Store::open(&config.data_dir)+ .with_context(|| format!("opening store at {}", config.data_dir.display()))?;+ let ws = store+ .writer+ .get_or_create_workspace(args.workspace.clone())+ .await?;+ let proj = store+ .writer+ .get_or_create_project(ws, args.project.clone(), None)+ .await?;++ let wiki = Wiki::new(&config.data_dir, store.writer.clone())?;++ let mut fm = Map::new();+ if let Some(title) = args.title {+ fm.insert("title".into(), Value::String(title));+ }+ if !args.tag.is_empty() {+ fm.insert(+ "tags".into(),+ Value::Array(args.tag.into_iter().map(Value::String).collect()),+ );+ }+ if args.pinned {+ fm.insert("pinned".into(), Value::Bool(true));+ }+ let frontmatter = if fm.is_empty() {+ Value::Null+ } else {+ Value::Object(fm)+ };++ let id = wiki+ .write_page(WritePageRequest {+ workspace_id: ws,+ project_id: proj,+ path: path.clone(),+ frontmatter,+ body,+ tier,+ pinned: args.pinned,+ })+ .await?;++ println!(+ "wrote {} ({}) under workspace={} project={}",+ path, id, args.workspace, args.project+ );+ Ok(())+}diff --git a/crates/ai-memory-cli/src/main.rs b/crates/ai-memory-cli/src/main.rsindex 2d8b63ff..734bf0e4 100644--- a/crates/ai-memory-cli/src/main.rs+++ b/crates/ai-memory-cli/src/main.rs@@ -39,5 +39,6 @@ async fn main() -> Result<()> {Command::Init(args) => commands::init::run(&config, args),Command::Status(args) => commands::status::run(&config, args).await,Command::Search(args) => commands::search::run(&config, args).await,+ Command::WritePage(args) => commands::write_page::run(&config, args).await,}}diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rsindex 044290b0..3e75ef51 100644--- a/crates/ai-memory-store/src/lib.rs+++ b/crates/ai-memory-store/src/lib.rs@@ -97,12 +97,14 @@ mod tests {async fn open_and_upsert_page() {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+ let ws = store+ .writer+ .get_or_create_workspace("default")+ .await+ .unwrap();+ let proj = store.writer- .ensure_project(proj, ws, "ai-memory", None)+ .get_or_create_project(ws, "ai-memory", None).await.unwrap();let id_a = store@@ -126,16 +128,46 @@ mod tests {assert_ne!(id_b, id_c);}+ #[tokio::test]+ async fn get_or_create_is_idempotent() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let a = store+ .writer+ .get_or_create_workspace("default")+ .await+ .unwrap();+ let b = store+ .writer+ .get_or_create_workspace("default")+ .await+ .unwrap();+ assert_eq!(a, b);+ let pa = store+ .writer+ .get_or_create_project(a, "scratch", None)+ .await+ .unwrap();+ let pb = store+ .writer+ .get_or_create_project(a, "scratch", None)+ .await+ .unwrap();+ assert_eq!(pa, pb);+ }+#[tokio::test]async fn serialises_parallel_writes() {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+ let ws = store.writer- .ensure_project(proj, ws, "ai-memory", None)+ .get_or_create_workspace("default")+ .await+ .unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "ai-memory", None).await.unwrap();// Spawn 16 concurrent writes; the writer must serialise them.@@ -172,12 +204,14 @@ mod tests {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+ let ws = store+ .writer+ .get_or_create_workspace("default")+ .await+ .unwrap();+ let proj = store.writer- .ensure_project(proj, ws, "ai-memory", None)+ .get_or_create_project(ws, "ai-memory", None).await.unwrap();diff --git a/crates/ai-memory-store/src/ops.rs b/crates/ai-memory-store/src/ops.rsindex b3c43629..98e74f1c 100644--- a/crates/ai-memory-store/src/ops.rs+++ b/crates/ai-memory-store/src/ops.rs@@ -120,41 +120,68 @@ pub fn upsert_page(conn: &mut Connection, page: &NewPage) -> StoreResult<PageId>Ok(result_id)}-/// Ensure a workspace exists; insert a stub row keyed on `name` otherwise.-pub fn ensure_workspace(+/// Resolve a workspace by name, creating it if missing. Atomic.+pub fn get_or_create_workspace(conn: &mut Connection,- id: &ai_memory_core::WorkspaceId,name: &str,-) -> StoreResult<()> {- conn.execute(- "INSERT INTO workspaces (id, name, created_at) VALUES (?1, ?2, ?3) \- ON CONFLICT(name) DO NOTHING",- params![id.as_bytes(), name, Timestamp::now().as_microsecond()],- )?;- Ok(())+) -> StoreResult<ai_memory_core::WorkspaceId> {+ let tx = conn.transaction()?;+ let existing: Option<Vec<u8>> = tx+ .query_row(+ "SELECT id FROM workspaces WHERE name = ?1",+ params![name],+ |row| row.get(0),+ )+ .optional()?;+ let id = if let Some(bytes) = existing {+ ai_memory_core::WorkspaceId::from_slice(&bytes)?+ } else {+ let id = ai_memory_core::WorkspaceId::new();+ tx.execute(+ "INSERT INTO workspaces (id, name, created_at) VALUES (?1, ?2, ?3)",+ params![id.as_bytes(), name, Timestamp::now().as_microsecond()],+ )?;+ id+ };+ tx.commit()?;+ Ok(id)}-/// Ensure a project exists under the given workspace.-pub fn ensure_project(+/// Resolve a project by `(workspace_id, name)`, creating it if missing.+/// Atomic.+pub fn get_or_create_project(conn: &mut Connection,- id: &ai_memory_core::ProjectId,workspace_id: &ai_memory_core::WorkspaceId,name: &str,repo_path: Option<&str>,-) -> StoreResult<()> {- conn.execute(- "INSERT INTO projects (id, workspace_id, name, repo_path, created_at) \- VALUES (?1, ?2, ?3, ?4, ?5) \- ON CONFLICT(workspace_id, name) DO NOTHING",- params![- id.as_bytes(),- workspace_id.as_bytes(),- name,- repo_path,- Timestamp::now().as_microsecond()- ],- )?;- Ok(())+) -> StoreResult<ai_memory_core::ProjectId> {+ let tx = conn.transaction()?;+ let existing: Option<Vec<u8>> = tx+ .query_row(+ "SELECT id FROM projects WHERE workspace_id = ?1 AND name = ?2",+ params![workspace_id.as_bytes(), name],+ |row| row.get(0),+ )+ .optional()?;+ let id = if let Some(bytes) = existing {+ ai_memory_core::ProjectId::from_slice(&bytes)?+ } else {+ let id = ai_memory_core::ProjectId::new();+ tx.execute(+ "INSERT INTO projects (id, workspace_id, name, repo_path, created_at) \+ VALUES (?1, ?2, ?3, ?4, ?5)",+ params![+ id.as_bytes(),+ workspace_id.as_bytes(),+ name,+ repo_path,+ Timestamp::now().as_microsecond()+ ],+ )?;+ id+ };+ tx.commit()?;+ Ok(id)}fn audit(diff --git a/crates/ai-memory-store/src/writer.rs b/crates/ai-memory-store/src/writer.rsindex 7e9ddaa8..e0fbf533 100644--- a/crates/ai-memory-store/src/writer.rs+++ b/crates/ai-memory-store/src/writer.rs@@ -19,17 +19,15 @@ use crate::ops;/// Commands accepted by the writer thread.pub(crate) enum WriteCmd {- EnsureWorkspace {- id: WorkspaceId,+ GetOrCreateWorkspace {name: String,- reply: oneshot::Sender<StoreResult<()>>,+ reply: oneshot::Sender<StoreResult<WorkspaceId>>,},- EnsureProject {- id: ProjectId,+ GetOrCreateProject {workspace_id: WorkspaceId,name: String,repo_path: Option<String>,- reply: oneshot::Sender<StoreResult<()>>,+ reply: oneshot::Sender<StoreResult<ProjectId>>,},UpsertPage {page: NewPage,@@ -66,19 +64,17 @@ impl WriterHandle {}}- /// Ensure a workspace row exists.+ /// Resolve a workspace by name, creating it atomically if missing.////// # Errors/// Returns [`StoreError::WriterClosed`] if the actor has shut down, or- /// propagates the SQL error from [`ops::ensure_workspace`].- pub async fn ensure_workspace(+ /// propagates the SQL error from [`ops::get_or_create_workspace`].+ pub async fn get_or_create_workspace(&self,- id: WorkspaceId,name: impl Into<String>,- ) -> StoreResult<()> {+ ) -> StoreResult<WorkspaceId> {let (tx, rx) = oneshot::channel();- self.send(WriteCmd::EnsureWorkspace {- id,+ self.send(WriteCmd::GetOrCreateWorkspace {name: name.into(),reply: tx,})@@ -86,21 +82,20 @@ impl WriterHandle {rx.await.map_err(|_| StoreError::WriterClosed)?}- /// Ensure a project row exists under the given workspace.+ /// Resolve a project by `(workspace_id, name)`, creating it atomically+ /// if missing.////// # Errors/// Returns [`StoreError::WriterClosed`] if the actor has shut down, or- /// propagates the SQL error from [`ops::ensure_project`].- pub async fn ensure_project(+ /// propagates the SQL error from [`ops::get_or_create_project`].+ pub async fn get_or_create_project(&self,- id: ProjectId,workspace_id: WorkspaceId,name: impl Into<String>,repo_path: Option<String>,- ) -> StoreResult<()> {+ ) -> StoreResult<ProjectId> {let (tx, rx) = oneshot::channel();- self.send(WriteCmd::EnsureProject {- id,+ self.send(WriteCmd::GetOrCreateProject {workspace_id,name: name.into(),repo_path,@@ -144,19 +139,22 @@ fn worker_loop(mut conn: Connection, mut rx: mpsc::Receiver<WriteCmd>) {while let Some(cmd) = rx.blocking_recv() {match cmd {WriteCmd::Shutdown => break,- WriteCmd::EnsureWorkspace { id, name, reply } => {- let result = ops::ensure_workspace(&mut conn, &id, &name);+ WriteCmd::GetOrCreateWorkspace { name, reply } => {+ let result = ops::get_or_create_workspace(&mut conn, &name);let _ = reply.send(result);}- WriteCmd::EnsureProject {- id,+ WriteCmd::GetOrCreateProject {workspace_id,name,repo_path,reply,} => {- let result =- ops::ensure_project(&mut conn, &id, &workspace_id, &name, repo_path.as_deref());+ let result = ops::get_or_create_project(+ &mut conn,+ &workspace_id,+ &name,+ repo_path.as_deref(),+ );let _ = reply.send(result);}WriteCmd::UpsertPage { page, reply } => {diff --git a/crates/ai-memory-wiki/Cargo.toml b/crates/ai-memory-wiki/Cargo.tomlindex 3de02529..38e36a5c 100644--- a/crates/ai-memory-wiki/Cargo.toml+++ b/crates/ai-memory-wiki/Cargo.toml@@ -10,6 +10,18 @@ description = "Markdown wiki read/write, file watcher and git versioning."[dependencies]ai-memory-core.workspace = true+ai-memory-store.workspace = true+anyhow.workspace = true+thiserror.workspace = true+serde.workspace = true+serde_json.workspace = true+serde_yaml.workspace = true+tempfile.workspace = true+jiff.workspace = true+tracing.workspace = true+tokio.workspace = true++[dev-dependencies][lints]workspace = truediff --git a/crates/ai-memory-wiki/src/atomic.rs b/crates/ai-memory-wiki/src/atomic.rsnew file mode 100644index 00000000..9231e971--- /dev/null+++ b/crates/ai-memory-wiki/src/atomic.rs@@ -0,0 +1,95 @@+//! Atomic file writes.+//!+//! Every file the wiki owns is written via a tmp + rename + fsync dance.+//! Two payoffs: a crash mid-write never produces a torn file, and the+//! upcoming watcher (M1-D) can ignore "own writes" by inode tracking.++use std::fs::File;+use std::io::Write;+use std::path::Path;++use crate::error::{WikiError, WikiResult};++/// Atomically replace the file at `path` with `bytes`.+///+/// Steps: write to a `tempfile` in the same directory, `sync_data` the+/// tempfile, `persist` it over the destination, then best-effort `sync_all`+/// the parent directory so the rename hits stable storage.+///+/// Returns the inode number of the persisted file (used by the watcher to+/// skip its own writes).+///+/// # Errors+/// Propagates I/O and [`tempfile::PersistError`] failures.+pub fn write_atomic(path: &Path, bytes: &[u8]) -> WikiResult<u64> {+ let parent = path+ .parent()+ .ok_or_else(|| WikiError::Io(std::io::Error::other("path has no parent")))?;+ std::fs::create_dir_all(parent)?;++ let mut tmp = tempfile::Builder::new()+ .prefix(".ai-memory-tmp.")+ .tempfile_in(parent)?;+ tmp.write_all(bytes)?;+ tmp.as_file().sync_data()?;++ let persisted: File = tmp.persist(path)?;+ persisted.sync_data()?;++ // Best-effort: fsync the parent so the rename is durable too.+ if let Ok(dir) = File::open(parent) {+ let _ = dir.sync_all();+ }++ Ok(inode_of(path).unwrap_or(0))+}++#[cfg(unix)]+fn inode_of(path: &Path) -> std::io::Result<u64> {+ use std::os::unix::fs::MetadataExt;+ Ok(std::fs::metadata(path)?.ino())+}++#[cfg(not(unix))]+fn inode_of(_path: &Path) -> std::io::Result<u64> {+ Ok(0)+}++#[cfg(test)]+mod tests {+ use super::*;+ use tempfile::TempDir;++ #[test]+ fn writes_atomically_and_creates_parents() {+ let tmp = TempDir::new().unwrap();+ let target = tmp.path().join("nested/dir/page.md");+ let ino = write_atomic(&target, b"hello").unwrap();+ assert!(target.is_file());+ assert_eq!(std::fs::read(&target).unwrap(), b"hello");+ if cfg!(unix) {+ assert_ne!(ino, 0);+ }+ }++ #[test]+ fn overwrites_existing_file() {+ let tmp = TempDir::new().unwrap();+ let target = tmp.path().join("page.md");+ write_atomic(&target, b"first").unwrap();+ write_atomic(&target, b"second").unwrap();+ assert_eq!(std::fs::read(&target).unwrap(), b"second");+ }++ #[test]+ fn does_not_leave_tmp_files_on_success() {+ let tmp = TempDir::new().unwrap();+ let target = tmp.path().join("page.md");+ write_atomic(&target, b"x").unwrap();+ let leftover = std::fs::read_dir(tmp.path())+ .unwrap()+ .map(|e| e.unwrap().file_name())+ .any(|n| n.to_string_lossy().starts_with(".ai-memory-tmp."));+ assert!(!leftover, "tempfile leaked");+ }+}diff --git a/crates/ai-memory-wiki/src/error.rs b/crates/ai-memory-wiki/src/error.rsnew file mode 100644index 00000000..d64f86be--- /dev/null+++ b/crates/ai-memory-wiki/src/error.rs@@ -0,0 +1,49 @@+//! Wiki-layer error type.++use ai_memory_core::MemoryError;+use ai_memory_store::StoreError;+use thiserror::Error;++/// Result alias used throughout the wiki crate.+pub type WikiResult<T> = Result<T, WikiError>;++/// Errors raised by the wiki layer.+#[derive(Debug, Error)]+#[non_exhaustive]+pub enum WikiError {+ /// Filesystem I/O failed.+ #[error(transparent)]+ Io(#[from] std::io::Error),++ /// Atomic-write tempfile crate error.+ #[error(transparent)]+ Persist(#[from] tempfile::PersistError),++ /// Frontmatter could not be parsed as YAML.+ #[error("frontmatter yaml: {0}")]+ Yaml(String),++ /// Frontmatter could not be converted to JSON.+ #[error("frontmatter json: {0}")]+ Json(String),++ /// Domain-level error.+ #[error(transparent)]+ Memory(#[from] MemoryError),++ /// Store-level error.+ #[error(transparent)]+ Store(#[from] StoreError),+}++impl From<serde_yaml::Error> for WikiError {+ fn from(value: serde_yaml::Error) -> Self {+ Self::Yaml(value.to_string())+ }+}++impl From<serde_json::Error> for WikiError {+ fn from(value: serde_json::Error) -> Self {+ Self::Json(value.to_string())+ }+}diff --git a/crates/ai-memory-wiki/src/lib.rs b/crates/ai-memory-wiki/src/lib.rsindex 72ecc217..691ea2e7 100644--- a/crates/ai-memory-wiki/src/lib.rs+++ b/crates/ai-memory-wiki/src/lib.rs@@ -1,4 +1,15 @@//! Wiki filesystem layer.//!-//! Owns the markdown-on-disk source of truth: atomic writes, watcher with-//! reconciliation pass, git versioning. Implementation lands in milestone M1.+//! Owns the markdown-on-disk source of truth: atomic writes, frontmatter+//! parsing/emission, and write-through to the [`ai_memory_store`] writer+//! actor so the SQLite index never diverges from the file. The watcher ++//! git layer arrive in M1-D and M5.++mod atomic;+mod error;+mod markdown;+mod wiki;++pub use error::{WikiError, WikiResult};+pub use markdown::{Markdown, derive_title, emit, parse};+pub use wiki::{Wiki, WritePageRequest};diff --git a/crates/ai-memory-wiki/src/markdown.rs b/crates/ai-memory-wiki/src/markdown.rsnew file mode 100644index 00000000..7aaf223a--- /dev/null+++ b/crates/ai-memory-wiki/src/markdown.rs@@ -0,0 +1,162 @@+//! YAML-frontmatter aware markdown parser and emitter.+//!+//! We deliberately do *not* use `gray_matter` here: it parses fine but+//! loses comments and key ordering on re-serialise, which is exactly the+//! "duplicate frontmatter on already-frontmatter'd files" class of bug+//! basic-memory hit (#528). Going through `serde_yaml` directly keeps the+//! round-trip predictable.++use ai_memory_core::PagePath;+use serde::{Deserialize, Serialize};++use crate::error::WikiResult;++/// A parsed markdown document with detached frontmatter.+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]+pub struct Markdown {+ /// Frontmatter as JSON for cheap querying (and stable serialisation).+ /// `Null` when the source had no frontmatter at all.+ pub frontmatter: serde_json::Value,+ /// Body excluding the frontmatter block (and the closing `---\n`).+ pub body: String,+}++/// Parse markdown text into [`Markdown`].+///+/// Recognises only the canonical `---\n<yaml>\n---\n` block at the very+/// start of the document. Anything else is treated as body.+///+/// # Errors+/// Returns [`WikiError::Yaml`] if the frontmatter block exists but does+/// not parse as YAML.+pub fn parse(input: &str) -> WikiResult<Markdown> {+ let trimmed = input.strip_prefix('\u{FEFF}').unwrap_or(input);+ if let Some(rest) = trimmed.strip_prefix("---\n")+ && let Some(end) = rest.find("\n---\n")+ {+ let fm_str = &rest[..end];+ let body = rest[end + 5..].to_string();+ let fm_yaml: serde_yaml::Value = serde_yaml::from_str(fm_str)?;+ let fm_json: serde_json::Value = serde_json::to_value(fm_yaml)?;+ return Ok(Markdown {+ frontmatter: fm_json,+ body,+ });+ }+ Ok(Markdown {+ frontmatter: serde_json::Value::Null,+ body: input.to_string(),+ })+}++/// Emit a [`Markdown`] back to a string. Frontmatter is serialised through+/// `serde_yaml` (so it round-trips deterministically); a `Null` or empty+/// object frontmatter is omitted entirely.+///+/// # Errors+/// Returns [`WikiError::Yaml`] if frontmatter cannot be serialised.+pub fn emit(md: &Markdown) -> WikiResult<String> {+ let has_fm = match &md.frontmatter {+ serde_json::Value::Null => false,+ serde_json::Value::Object(m) => !m.is_empty(),+ _ => true,+ };+ let mut out = String::with_capacity(md.body.len() + 32);+ if has_fm {+ let yaml = serde_yaml::to_string(&md.frontmatter)?;+ out.push_str("---\n");+ out.push_str(&yaml);+ if !yaml.ends_with('\n') {+ out.push('\n');+ }+ out.push_str("---\n");+ }+ out.push_str(&md.body);+ Ok(out)+}++/// Derive a page title.+///+/// Priority: frontmatter.title (string) → first `# ` heading in body →+/// path stem with the `.md` suffix stripped.+#[must_use]+pub fn derive_title(frontmatter: &serde_json::Value, body: &str, path: &PagePath) -> String {+ if let Some(t) = frontmatter.get("title").and_then(serde_json::Value::as_str) {+ let trimmed = t.trim();+ if !trimmed.is_empty() {+ return trimmed.to_string();+ }+ }+ for line in body.lines() {+ if let Some(rest) = line.strip_prefix("# ") {+ let trimmed = rest.trim();+ if !trimmed.is_empty() {+ return trimmed.to_string();+ }+ }+ }+ let s = path.as_str();+ let stem = s.rsplit_once('/').map_or(s, |(_, name)| name);+ stem.strip_suffix(".md").unwrap_or(stem).to_string()+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn parses_frontmatter_and_body() {+ let src = "---\ntitle: Hello\ntags:\n - a\n - b\n---\nThe body.\n";+ let md = parse(src).unwrap();+ assert_eq!(md.frontmatter["title"], "Hello");+ assert_eq!(md.frontmatter["tags"][0], "a");+ assert_eq!(md.body, "The body.\n");+ }++ #[test]+ fn parses_body_without_frontmatter() {+ let src = "Just a body, no frontmatter.\n";+ let md = parse(src).unwrap();+ assert!(md.frontmatter.is_null());+ assert_eq!(md.body, src);+ }++ #[test]+ fn round_trip_emit_then_parse() {+ let original = Markdown {+ frontmatter: serde_json::json!({ "title": "X", "tags": ["a"] }),+ body: "Line 1\nLine 2\n".into(),+ };+ let emitted = emit(&original).unwrap();+ let parsed = parse(&emitted).unwrap();+ assert_eq!(parsed.frontmatter["title"], "X");+ assert_eq!(parsed.body, original.body);+ }++ #[test]+ fn emit_omits_empty_frontmatter() {+ let md = Markdown {+ frontmatter: serde_json::Value::Object(serde_json::Map::new()),+ body: "Hello\n".into(),+ };+ assert_eq!(emit(&md).unwrap(), "Hello\n");+ }++ #[test]+ fn title_priority_frontmatter_then_heading_then_stem() {+ let path = PagePath::new("notes/foo.md").unwrap();+ // Frontmatter wins.+ let fm = serde_json::json!({ "title": "Explicit" });+ assert_eq!(derive_title(&fm, "# Other\nbody", &path), "Explicit");+ // Heading wins over stem.+ assert_eq!(+ derive_title(&serde_json::Value::Null, "# From Body\n", &path),+ "From Body"+ );+ // Stem fallback.+ assert_eq!(+ derive_title(&serde_json::Value::Null, "no heading", &path),+ "foo"+ );+ }+}diff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rsnew file mode 100644index 00000000..2c59df80--- /dev/null+++ b/crates/ai-memory-wiki/src/wiki.rs@@ -0,0 +1,218 @@+//! [`Wiki`] — the only correct write path for the markdown source-of-truth.++use std::path::{Path, PathBuf};++use ai_memory_core::{NewPage, PageId, PagePath, ProjectId, Tier, WorkspaceId};+use ai_memory_store::WriterHandle;++use crate::atomic;+use crate::error::WikiResult;+use crate::markdown::{Markdown, derive_title, emit, parse};++/// Wiki filesystem handle.+///+/// Owns the path of the wiki root (`<data_dir>/wiki/`) and a cloneable+/// [`WriterHandle`] so that every public mutation writes the markdown+/// file *and* sends a `WriteCmd::UpsertPage` to the store in a single+/// call — no background-task indexing-after-return (basic-memory #763+/// lesson).+#[derive(Clone)]+pub struct Wiki {+ root: PathBuf,+ writer: WriterHandle,+}++impl Wiki {+ /// Construct a wiki handle rooted at `<data_dir>/wiki/`. Creates the+ /// directory if absent.+ ///+ /// # Errors+ /// Returns [`WikiError::Io`] if the wiki root cannot be created.+ pub fn new(data_dir: &Path, writer: WriterHandle) -> WikiResult<Self> {+ let root = data_dir.join("wiki");+ std::fs::create_dir_all(&root)?;+ Ok(Self { root, writer })+ }++ /// Path of the wiki root on disk.+ #[must_use]+ pub fn root(&self) -> &Path {+ &self.root+ }++ /// Absolute on-disk path for a given [`PagePath`].+ #[must_use]+ pub fn abs_path(&self, path: &PagePath) -> PathBuf {+ self.root.join(path.as_str())+ }++ /// Read the page at `path` from disk.+ ///+ /// # Errors+ /// Returns [`WikiError::Io`] if the file is missing or unreadable, or+ /// [`WikiError::Yaml`] if the frontmatter block is malformed.+ pub fn read_page(&self, path: &PagePath) -> WikiResult<Markdown> {+ let abs = self.abs_path(path);+ let raw = std::fs::read_to_string(&abs)?;+ parse(&raw)+ }++ /// Write `body` (with optional `frontmatter`) atomically to+ /// `<wiki_root>/<path>` and upsert the matching page row in the store.+ ///+ /// The store side does the sha256 short-circuit + supersession dance.+ /// Returns the id of the page version that is now `is_latest = 1`.+ ///+ /// # Errors+ /// Returns [`WikiError`] for any filesystem, parsing, or store error.+ pub async fn write_page(&self, req: WritePageRequest) -> WikiResult<PageId> {+ let WritePageRequest {+ workspace_id,+ project_id,+ path,+ frontmatter,+ body,+ tier,+ pinned,+ } = req;++ let title = derive_title(&frontmatter, &body, &path);+ let markdown = Markdown {+ frontmatter: frontmatter.clone(),+ body: body.clone(),+ };+ let emitted = emit(&markdown)?;+ let abs = self.abs_path(&path);+ atomic::write_atomic(&abs, emitted.as_bytes())?;++ let page_id = self+ .writer+ .upsert_page(NewPage {+ workspace_id,+ project_id,+ path,+ title,+ body,+ tier,+ frontmatter_json: frontmatter,+ pinned,+ })+ .await?;+ Ok(page_id)+ }+}++/// Input bundle for [`Wiki::write_page`]. Carries the full 3-tuple+/// identity (`workspace_id`, `project_id`, `path`) plus body & metadata.+#[derive(Debug, Clone)]+pub struct WritePageRequest {+ /// Owning workspace.+ pub workspace_id: WorkspaceId,+ /// Owning project.+ pub project_id: ProjectId,+ /// Relative wiki path.+ pub path: PagePath,+ /// Optional frontmatter (JSON object). May be `Null` for no frontmatter.+ pub frontmatter: serde_json::Value,+ /// Markdown body (excluding any frontmatter block).+ pub body: String,+ /// Tier classification.+ pub tier: Tier,+ /// `true` if the user has pinned this page.+ pub pinned: bool,+}++#[cfg(test)]+mod tests {+ use super::*;+ use ai_memory_store::Store;+ use tempfile::TempDir;++ fn req(+ ws: WorkspaceId,+ proj: ProjectId,+ path: &str,+ body: &str,+ fm: serde_json::Value,+ ) -> WritePageRequest {+ WritePageRequest {+ workspace_id: ws,+ project_id: proj,+ path: PagePath::new(path).unwrap(),+ frontmatter: fm,+ body: body.into(),+ tier: Tier::Semantic,+ pinned: false,+ }+ }++ #[tokio::test]+ async fn write_page_writes_file_and_indexes_in_store() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let ws = store+ .writer+ .get_or_create_workspace("default")+ .await+ .unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "scratch", None)+ .await+ .unwrap();+ let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();++ let id = wiki+ .write_page(req(+ ws,+ proj,+ "notes/karpathy.md",+ "Karpathy says: compile, do not retrieve.\n",+ serde_json::json!({ "title": "Karpathy LLM Wiki" }),+ ))+ .await+ .unwrap();+ let _ = id; // any non-zero PageId is sufficient++ // File is on disk with the frontmatter back.+ let on_disk = std::fs::read_to_string(tmp.path().join("wiki/notes/karpathy.md")).unwrap();+ assert!(on_disk.starts_with("---\n"));+ assert!(on_disk.contains("title: Karpathy LLM Wiki"));+ assert!(on_disk.contains("Karpathy says"));++ // FTS5 finds it via the store reader.+ let hits = store+ .reader+ .search_pages("karpathy".into(), 5)+ .await+ .unwrap();+ assert_eq!(hits.len(), 1);+ assert_eq!(hits[0].title, "Karpathy LLM Wiki");+ assert!(hits[0].snippet.contains("compile"));+ }++ #[tokio::test]+ async fn rewriting_same_body_is_idempotent() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let ws = store+ .writer+ .get_or_create_workspace("default")+ .await+ .unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "scratch", None)+ .await+ .unwrap();+ let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();++ let r = |body: &str| req(ws, proj, "a.md", body, serde_json::json!({ "title": "A" }));++ let a = wiki.write_page(r("body one")).await.unwrap();+ let b = wiki.write_page(r("body one")).await.unwrap();+ assert_eq!(a, b);+ let c = wiki.write_page(r("body two")).await.unwrap();+ assert_ne!(b, c);+ }+}