Skip to content

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