Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
wiki: per-project disk layout (UUID-namespaced); rename is now free
AkitaOnRailse7b9a17657e7
diff --git a/CLAUDE.md b/CLAUDE.mdindex dde1b615..12c575c3 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -94,17 +94,43 @@ blocking issue:**12. No global singletons / `lazy_static` configs.13. Zero-LLM default path. LLM features opt-in via env.14. Tracing subscribers explicitly filter their own module.-15. **Every command + storage operation is namespaced by the current- sub-dir as the project id.** The router derives the project from- `basename(cwd)`; bootstrap / lint / embed / forget-sweep /- purge-project / rename-project / consolidate ALL resolve through- the same helper. There is no generic `scratch` fallback in the- happy path — `scratch` exists only as a defensive default for- hook events that arrive without a `cwd` (e.g. early startup or- misconfigured agents). New commands/handlers that bake in a- `workspace_id`/`project_id` at construction time MUST look up- the session's actual project (via- `ReaderPool::session_project_ids` or equivalent) before writing.+15. **Every command + storage operation is namespaced by the+ project's stable surrogate `(workspace_id, project_id)` — all+ the way down to the on-disk wiki layout.** Two layers:++ a. **Surface (commands)**: the per-cwd router derives the project+ name from `basename(cwd)`; bootstrap / lint / embed /+ forget-sweep / purge-project / rename-project / consolidate /+ write-page ALL resolve through `commands::resolve_project_name`+ (or the router's `resolve_project_ids` on the server side). There+ is no generic `scratch` fallback in the happy path — `scratch`+ exists only as a defensive default for hook events that arrive+ without a `cwd` (e.g. early startup or misconfigured agents).+ Commands/handlers that bake in a `workspace_id`/`project_id` at+ construction time MUST look up the session's actual project (via+ `ReaderPool::session_project_ids`) before writing.++ b. **Storage layout**: wiki files live at+ `<wiki_root>/<workspace_id>/<project_id>/<page-path>`. The mutable+ project NAME never appears in any disk path; the stable UUID+ surrogate does. Consequences this rule enforces:+ - Renaming a project is a single column update on+ `projects.name`; no file moves ever.+ - Purging a project is `std::fs::remove_dir_all(project_root)` —+ atomic, no shared-file footgun.+ - Two projects can have the same `pages.path` (e.g.+ `decisions/0001.md`) without on-disk collision.+ - `log.md` and `bootstrap.md` are per-project files inside the+ project's namespaced dir, NOT shared at the wiki root.++ Every `Wiki` API call carries `(workspace_id, project_id)`+ either as explicit args (read_page, delete_page) or via+ `WritePageRequest`. No call ever reads/writes at+ `<wiki_root>/<path>` directly; always go through+ `Wiki::project_root(ws, proj).join(path)`. The filesystem+ watcher parses the first two path segments of every event as+ UUIDs and uses those to stamp the reindex — events outside the+ namespaced layout are ignored.16. **The CLI is always a thin HTTP client to the running MCP /admin server.** The server is the ground truth and the solewriter of wiki + SQLite. CLI commands NEVER call `Store::open`,diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rsindex 831e1a2b..5e795aa9 100644--- a/crates/ai-memory-cli/src/commands/serve.rs+++ b/crates/ai-memory-cli/src/commands/serve.rs@@ -95,7 +95,7 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {project = %args.project,"starting wiki watcher",);- Some(WatcherHandle::start(wiki.clone(), ws, proj)?)+ Some(WatcherHandle::start(wiki.clone())?)};let mut server = AiMemoryServer::new(store.reader.clone(), store.writer.clone(), ws, proj)diff --git a/crates/ai-memory-consolidate/src/bootstrap.rs b/crates/ai-memory-consolidate/src/bootstrap.rsindex caf28b27..e9b60a55 100644--- a/crates/ai-memory-consolidate/src/bootstrap.rs+++ b/crates/ai-memory-consolidate/src/bootstrap.rs@@ -283,14 +283,16 @@ impl Bootstrap {sources: Vec<BootstrapSource>,) -> Result<BootstrapOutcome, BootstrapError> {// ---- idempotency check ------------------------------------- // The reader pool's recent_pages isn't (workspace, project)-- // scoped, so we use the wiki's filesystem read as the cheap- // existence check: if `wiki/bootstrap.md` parses, this- // project was bootstrapped before.+ // Check whether bootstrap.md already exists on disk in the per-project+ // directory. If it parses cleanly, this project was bootstrapped before.if !cfg.force {let manifest_path =PagePath::new("bootstrap.md").expect("hard-coded manifest path is valid");- if self.wiki.read_page(&manifest_path).is_ok() {+ if self+ .wiki+ .read_page(cfg.workspace_id, cfg.project_id, &manifest_path)+ .is_ok()+ {return Err(BootstrapError::AlreadyBootstrapped);}}diff --git a/crates/ai-memory-consolidate/src/consolidator.rs b/crates/ai-memory-consolidate/src/consolidator.rsindex c24e95ac..682facfb 100644--- a/crates/ai-memory-consolidate/src/consolidator.rs+++ b/crates/ai-memory-consolidate/src/consolidator.rs@@ -124,7 +124,7 @@ impl Consolidator {let path = PagePath::new(format!("sessions/{session_id}.md"))?;let current_body = self.wiki- .read_page(&path)+ .read_page(ws, proj, &path).map(|md| md.body).unwrap_or_default();let request = build_request(session_id, &observations, ¤t_body);diff --git a/crates/ai-memory-consolidate/src/lint.rs b/crates/ai-memory-consolidate/src/lint.rsindex 521af792..9c637ac4 100644--- a/crates/ai-memory-consolidate/src/lint.rs+++ b/crates/ai-memory-consolidate/src/lint.rs@@ -93,7 +93,15 @@ pub async fn run_lint(let mut findings = rule_based_findings(&candidates);if let Some(provider) = llm {- match contradiction_pass(provider.clone(), wiki, &candidates).await {+ match contradiction_pass(+ provider.clone(),+ wiki,+ workspace_id,+ project_id,+ &candidates,+ )+ .await+ {Ok(mut extra) => findings.append(&mut extra),Err(e) => warn!(error = %e, "lint LLM contradiction pass failed"),}@@ -184,6 +192,8 @@ fn rule_based_findings(candidates: &[DecayCandidate]) -> Vec<LintFinding> {async fn contradiction_pass(provider: std::sync::Arc<dyn LlmProvider>,wiki: &Wiki,+ workspace_id: WorkspaceId,+ project_id: ProjectId,candidates: &[DecayCandidate],) -> Result<Vec<LintFinding>, LintError> {// Focus on semantic / procedural pages — those are the ones the@@ -206,7 +216,7 @@ async fn contradiction_pass();for c in &subset {let preview = wiki- .read_page(&c.path)+ .read_page(workspace_id, project_id, &c.path).map(|md| md.body.chars().take(400).collect::<String>()).unwrap_or_else(|_| "(unable to read)".into());prompt.push_str(&format!("## `{}`\n\n{}\n\n---\n\n", c.path, preview));diff --git a/crates/ai-memory-hooks/src/log.rs b/crates/ai-memory-hooks/src/log.rsindex b0f783e9..31de83b8 100644--- a/crates/ai-memory-hooks/src/log.rs+++ b/crates/ai-memory-hooks/src/log.rs@@ -8,24 +8,31 @@use std::io::Write;use std::path::Path;+use ai_memory_core::{ProjectId, WorkspaceId};use jiff::{Timestamp, ToSpan, tz::TimeZone};use tracing::debug;use crate::payload::HookEvent;-/// Append one line to `<wiki_root>/log.md`. POSIX `O_APPEND` writes of-/// less than `PIPE_BUF` (4 KiB) are atomic, so concurrent appenders do-/// not interleave.+/// Append one line to `<wiki_root>/<workspace_id>/<project_id>/log.md`.+///+/// POSIX `O_APPEND` writes of less than `PIPE_BUF` (4 KiB) are atomic, so+/// concurrent appenders do not interleave.////// # Errors/// Propagates any I/O failure from opening or writing the file.pub fn append_event(wiki_root: &Path,+ workspace_id: WorkspaceId,+ project_id: ProjectId,when: Timestamp,event: HookEvent,title: &str,) -> std::io::Result<()> {- let log_path = wiki_root.join("log.md");+ let log_path = wiki_root+ .join(workspace_id.to_string())+ .join(project_id.to_string())+ .join("log.md");let line = format_line(when, event, title);debug!(path = %log_path.display(), bytes = line.len(), "appending log entry");@@ -93,10 +100,16 @@ mod tests {fn append_creates_file_and_grows() {let tmp = TempDir::new().unwrap();let root = tmp.path();+ let ws = WorkspaceId::new();+ let proj = ProjectId::new();let now = Timestamp::now();- append_event(root, now, HookEvent::SessionStart, "first").unwrap();- append_event(root, now, HookEvent::UserPrompt, "second").unwrap();- let contents = std::fs::read_to_string(root.join("log.md")).unwrap();+ append_event(root, ws, proj, now, HookEvent::SessionStart, "first").unwrap();+ append_event(root, ws, proj, now, HookEvent::UserPrompt, "second").unwrap();+ let log_path = root+ .join(ws.to_string())+ .join(proj.to_string())+ .join("log.md");+ let contents = std::fs::read_to_string(&log_path).unwrap();assert!(contents.contains("session-start | first"));assert!(contents.contains("user-prompt | second"));// Two lines.diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rsindex 8181b49a..b102eedb 100644--- a/crates/ai-memory-hooks/src/router.rs+++ b/crates/ai-memory-hooks/src/router.rs@@ -286,9 +286,11 @@ async fn process(state: &HookState, env: HookEnvelope) -> anyhow::Result<()> {.insert_observation(sanitized.inner().clone()).await?;- // Append the log line.+ // Append the log line to the per-project log.md.if let Err(e) = log::append_event(state.wiki.root(),+ ws,+ proj,Timestamp::now(),env.event,sanitized.inner().title.as_str(),diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rsindex 392f79ea..d07594e9 100644--- a/crates/ai-memory-mcp/src/admin.rs+++ b/crates/ai-memory-mcp/src/admin.rs@@ -29,9 +29,7 @@ use ai_memory_consolidate::{};use ai_memory_core::{PagePath, ProjectId, SessionId, Tier, WorkspaceId};use ai_memory_llm::{Embedder, LlmProvider};-use ai_memory_store::{- DecayParams, PurgeSummary, ReaderPool, StoreError, WriterHandle, f32_vec_to_bytes,-};+use ai_memory_store::{DecayParams, ReaderPool, StoreError, WriterHandle, f32_vec_to_bytes};use ai_memory_wiki::{Wiki, WritePageRequest};use axum::Json;use axum::Router;@@ -856,7 +854,7 @@ async fn handle_embed(would_embed += 1;continue;}- let md = match state.wiki.read_page(&cand.path) {+ let md = match state.wiki.read_page(ws, proj, &cand.path) {Ok(m) => m,Err(e) => {warn!(path = %cand.path, error = %e, "embed: skip unreadable page");@@ -968,32 +966,12 @@ pub struct PurgeProjectReport {pub handoffs_deleted: u64,/// Number of `page_embeddings` rows deleted.pub embeddings_deleted: u64,- /// Paths of wiki files that were removed from disk.+ /// Paths removed from disk (the project's UUID-namespaced directory).pub files_deleted: Vec<String>,- /// Paths whose wiki file was kept because another project still- /// references the same path. The wiki is flat on disk so the file- /// is shared between projects — deleting it would 404 the sibling.- pub files_skipped_shared: Vec<String>,/// Paths that could not be removed from disk (non-fatal; DB rows are gone).pub files_failed: Vec<String>,}-impl From<&PurgeSummary> for PurgeProjectReport {- fn from(s: &PurgeSummary) -> Self {- Self {- label: s.label.clone(),- pages_deleted: s.pages_deleted,- sessions_deleted: s.sessions_deleted,- observations_deleted: s.observations_deleted,- handoffs_deleted: s.handoffs_deleted,- embeddings_deleted: s.embeddings_deleted,- files_deleted: Vec::new(),- files_skipped_shared: Vec::new(),- files_failed: Vec::new(),- }- }-}-async fn handle_purge_project(State(state): State<Arc<AdminState>>,Json(req): Json<PurgeProjectRequest>,@@ -1058,49 +1036,35 @@ async fn handle_purge_project(}};- // Remove wiki files — but ONLY when no other project still has an- // is_latest=1 page row pointing at the same path. The wiki is flat- // on disk (`wiki/concepts/foo.md` is shared across all projects- // with that path), so naïvely deleting every purged page's file- // would clobber files still owned by sibling projects. The DB-row- // purge already happened (cascaded by FK); this loop only fixes- // the on-disk side. Partial failures are accumulated but never- // abort the response.+ // Remove the entire per-project directory: <wiki_root>/<ws_uuid>/<proj_uuid>/.+ // DB cascade already deleted all rows; the dir removal is best-effort.+ let proj_root = state.wiki.project_root(ws_id, proj_id);+ let proj_root_str = proj_root.display().to_string();let mut files_deleted: Vec<String> = Vec::new();- let mut files_skipped_shared: Vec<String> = Vec::new();let mut files_failed: Vec<String> = Vec::new();- for raw_path in &summary.page_paths {- let still_referenced = match state.reader.path_still_referenced(raw_path.clone()).await {- Ok(b) => b,- Err(e) => {- warn!(path = %raw_path, error = %e, "purge-project: cross-project ref check failed; skipping delete defensively");- files_skipped_shared.push(raw_path.clone());- continue;- }- };- if still_referenced {- files_skipped_shared.push(raw_path.clone());- continue;+ match std::fs::remove_dir_all(&proj_root) {+ Ok(()) => {+ files_deleted.push(proj_root_str);}- match ai_memory_core::PagePath::new(raw_path.clone()) {- Ok(pp) => match state.wiki.delete_page(&pp) {- Ok(()) => files_deleted.push(raw_path.clone()),- Err(e) => {- warn!(path = %raw_path, error = %e, "purge-project: failed to delete wiki file");- files_failed.push(raw_path.clone());- }- },- Err(e) => {- warn!(path = %raw_path, error = %e, "purge-project: invalid page path skipped");- files_failed.push(raw_path.clone());- }+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => {+ // Already absent; nothing to do.+ }+ Err(e) => {+ warn!(path = %proj_root_str, error = %e, "purge-project: failed to remove project dir");+ files_failed.push(proj_root_str);}}- let mut report = PurgeProjectReport::from(&summary);- report.files_deleted = files_deleted;- report.files_skipped_shared = files_skipped_shared;- report.files_failed = files_failed;+ let report = PurgeProjectReport {+ label: summary.label,+ pages_deleted: summary.pages_deleted,+ sessions_deleted: summary.sessions_deleted,+ observations_deleted: summary.observations_deleted,+ handoffs_deleted: summary.handoffs_deleted,+ embeddings_deleted: summary.embeddings_deleted,+ files_deleted,+ files_failed,+ };(StatusCode::OK,diff --git a/crates/ai-memory-mcp/tests/admin_purge.rs b/crates/ai-memory-mcp/tests/admin_purge.rsindex c9d4f99b..1093f5af 100644--- a/crates/ai-memory-mcp/tests/admin_purge.rs+++ b/crates/ai-memory-mcp/tests/admin_purge.rs@@ -5,7 +5,8 @@//! with `tower::ServiceExt::oneshot`.use ai_memory_core::{- AgentKind, NewHandoff, NewObservation, NewSession, ObservationKind, PagePath, SessionId, Tier,+ AgentKind, NewHandoff, NewObservation, NewSession, ObservationKind, PagePath, ProjectId,+ SessionId, Tier, WorkspaceId,};use ai_memory_mcp::{AdminState, admin_router};use ai_memory_store::{DecayParams, Store};@@ -32,8 +33,8 @@ async fn make_state(tmp: &TempDir) -> (AdminState, Store) {embedder: None,decay_params: DecayParams::default(),data_dir: tmp.path().to_path_buf(),- db_path,bind: "127.0.0.1:0".to_string(),+ db_path,};(state, store)}@@ -57,9 +58,9 @@ async fn post(state: AdminState, uri: &str, body: serde_json::Value) -> axum::re}/// Seed two projects (`default/keep` and `default/doomed`), each with one-/// page, one session, some observations, and a handoff. Returns the wiki-/// page path seeded for the doomed project.-async fn seed_two_projects(store: &Store, wiki: &Wiki) -> String {+/// page, one session, some observations, and a handoff. Returns IDs for+/// both projects so callers can construct the per-project wiki paths.+async fn seed_two_projects(store: &Store, wiki: &Wiki) -> (WorkspaceId, ProjectId, ProjectId) {let ws = store.writer.get_or_create_workspace("default")@@ -76,7 +77,7 @@ async fn seed_two_projects(store: &Store, wiki: &Wiki) -> String {.await.unwrap();- // Write pages through the wiki so they land on disk.+ // Write pages through the wiki so they land on disk in per-project dirs.wiki.write_page(WritePageRequest {workspace_id: ws,project_id: keep,@@ -90,11 +91,10 @@ async fn seed_two_projects(store: &Store, wiki: &Wiki) -> String {.await.unwrap();- let doomed_path = "notes/doomed.md";wiki.write_page(WritePageRequest {workspace_id: ws,project_id: doomed,- path: PagePath::new(doomed_path).unwrap(),+ path: PagePath::new("notes/doomed.md").unwrap(),frontmatter: serde_json::json!({"title": "Doomed page"}),body: "This page will be destroyed.".into(),tier: Tier::Semantic,@@ -154,7 +154,7 @@ async fn seed_two_projects(store: &Store, wiki: &Wiki) -> String {}}- doomed_path.to_string()+ (ws, keep, doomed)}// ---------------------------------------------------------------------------@@ -232,17 +232,21 @@ async fn purge_project_nonexistent_workspace_returns_404() {assert_eq!(resp.status(), StatusCode::NOT_FOUND);}-/// Happy path: purge the doomed project, verify counts and file removal.+/// Happy path: purge the doomed project, verify counts and directory removal.#[tokio::test]async fn purge_project_deletes_data_and_files() {let tmp = TempDir::new().unwrap();let (state, store) = make_state(&tmp).await;- let doomed_path = seed_two_projects(&store, &state.wiki).await;+ let (ws, _keep, doomed) = seed_two_projects(&store, &state.wiki).await;- // File must exist before purge.- let file_on_disk = tmp.path().join("wiki").join(&doomed_path);- assert!(file_on_disk.exists(), "wiki file must exist before purge");+ // The per-project directory must exist before purge.+ let proj_dir = tmp+ .path()+ .join("wiki")+ .join(ws.to_string())+ .join(doomed.to_string());+ assert!(proj_dir.exists(), "project dir must exist before purge");let resp = post(state,@@ -279,20 +283,20 @@ async fn purge_project_deletes_data_and_files() {"one handoff deleted: {body}");- // On-disk file must be gone.+ // The entire project directory must be gone.assert!(- !file_on_disk.exists(),- "wiki file must be removed after purge"+ !proj_dir.exists(),+ "project directory must be removed after purge");}-/// After purging `doomed`, `keep` must still have all its data intact.+/// After purging `doomed`, `keep` must still have all its data and files intact.#[tokio::test]async fn purge_project_preserves_sibling_project() {let tmp = TempDir::new().unwrap();let (state, store) = make_state(&tmp).await;- seed_two_projects(&store, &state.wiki).await;+ let (ws, keep, _doomed) = seed_two_projects(&store, &state.wiki).await;let resp = post(state,@@ -318,8 +322,14 @@ async fn purge_project_preserves_sibling_project() {"keep's observations must survive: {counts:?}");- // keep's wiki file must still exist.- let keep_file = tmp.path().join("wiki/notes/keep.md");+ // keep's wiki directory must still exist with its page.+ let keep_dir = tmp+ .path()+ .join("wiki")+ .join(ws.to_string())+ .join(keep.to_string());+ assert!(keep_dir.exists(), "keep's project dir must survive");+ let keep_file = keep_dir.join("notes/keep.md");assert!(keep_file.exists(), "keep's wiki file must survive");}diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rsindex f8577023..bf77060b 100644--- a/crates/ai-memory-store/src/reader.rs+++ b/crates/ai-memory-store/src/reader.rs@@ -147,6 +147,10 @@ pub struct PageMeta {pub workspace_name: String,/// Name of the project.pub project_name: String,+ /// UUID of the workspace — used to construct the per-project wiki path.+ pub workspace_id: WorkspaceId,+ /// UUID of the project — used to construct the per-project wiki path.+ pub project_id: ProjectId,/// Relative wiki path.pub path: String,/// Page title.@@ -328,26 +332,6 @@ impl ReaderPool {.await}- /// True when any `is_latest = 1` page row anywhere in the store- /// still references the given wiki path. Used by purge-project to- /// avoid deleting a wiki file on disk when another project still- /// has a page row pointing at the same path (the wiki is flat on- /// disk, so paths can collide across projects).- ///- /// # Errors- /// Propagates any SQL or pool error.- pub async fn path_still_referenced(&self, path: String) -> StoreResult<bool> {- self.with_conn(move |conn| {- let n: i64 = conn.query_row(- "SELECT EXISTS (SELECT 1 FROM pages WHERE path = ?1 AND is_latest = 1)",- params![path],- |row| row.get(0),- )?;- Ok(n != 0)- })- .await- }-/// Look up the `(workspace_id, project_id)` a session belongs to./// Returns `None` when no such session row exists.///@@ -793,7 +777,7 @@ impl ReaderPool {self.with_conn(move |conn| {let row_opt = conn.query_row(- "SELECT w.name, p.name, pg.path, pg.title, \+ "SELECT w.name, p.name, w.id, p.id, pg.path, pg.title, \COALESCE(json_extract(pg.frontmatter_json, '$.kind'), 'fact'), \pg.tier, pg.pinned, pg.created_at, pg.updated_at, \sp.path AS supersedes_path \@@ -807,17 +791,21 @@ impl ReaderPool {|row| {let workspace_name: String = row.get(0)?;let project_name: String = row.get(1)?;- let path: String = row.get(2)?;- let title: String = row.get(3)?;- let kind: String = row.get(4)?;- let tier: String = row.get(5)?;- let pinned: i64 = row.get(6)?;- let created_us: i64 = row.get(7)?;- let updated_us: i64 = row.get(8)?;- let supersedes_path: Option<String> = row.get(9)?;+ let ws_id_bytes: Vec<u8> = row.get(2)?;+ let proj_id_bytes: Vec<u8> = row.get(3)?;+ let path: String = row.get(4)?;+ let title: String = row.get(5)?;+ let kind: String = row.get(6)?;+ let tier: String = row.get(7)?;+ let pinned: i64 = row.get(8)?;+ let created_us: i64 = row.get(9)?;+ let updated_us: i64 = row.get(10)?;+ let supersedes_path: Option<String> = row.get(11)?;Ok((workspace_name,project_name,+ ws_id_bytes,+ proj_id_bytes,path,title,kind,@@ -834,6 +822,8 @@ impl ReaderPool {let Some((workspace_name,project_name,+ ws_id_bytes,+ proj_id_bytes,path,title,kind,@@ -847,6 +837,11 @@ impl ReaderPool {return Ok(None);};+ let workspace_id = WorkspaceId::from_slice(&ws_id_bytes)+ .map_err(|_| rusqlite::Error::IntegralValueOutOfRange(2, 0))?;+ let project_id = ProjectId::from_slice(&proj_id_bytes)+ .map_err(|_| rusqlite::Error::IntegralValueOutOfRange(3, 0))?;+let created_at = jiff::Timestamp::from_microsecond(created_us).map(|ts| ts.to_string()).unwrap_or_default();@@ -857,6 +852,8 @@ impl ReaderPool {Ok(Some(PageMeta {workspace_name,project_name,+ workspace_id,+ project_id,path,title,kind,@@ -984,7 +981,7 @@ impl ReaderPool {self.with_conn(move |conn| {let row_opt = conn.query_row(- "SELECT w.name, p.name, pg.path, pg.title, \+ "SELECT w.name, p.name, w.id, p.id, pg.path, pg.title, \COALESCE(json_extract(pg.frontmatter_json, '$.kind'), 'fact'), \pg.tier, pg.pinned, pg.created_at, pg.updated_at, \sp.path AS supersedes_path \@@ -997,17 +994,21 @@ impl ReaderPool {|row| {let workspace_name: String = row.get(0)?;let project_name: String = row.get(1)?;- let path: String = row.get(2)?;- let title: String = row.get(3)?;- let kind: String = row.get(4)?;- let tier: String = row.get(5)?;- let pinned: i64 = row.get(6)?;- let created_us: i64 = row.get(7)?;- let updated_us: i64 = row.get(8)?;- let supersedes_path: Option<String> = row.get(9)?;+ let ws_id_bytes: Vec<u8> = row.get(2)?;+ let proj_id_bytes: Vec<u8> = row.get(3)?;+ let path: String = row.get(4)?;+ let title: String = row.get(5)?;+ let kind: String = row.get(6)?;+ let tier: String = row.get(7)?;+ let pinned: i64 = row.get(8)?;+ let created_us: i64 = row.get(9)?;+ let updated_us: i64 = row.get(10)?;+ let supersedes_path: Option<String> = row.get(11)?;Ok((workspace_name,project_name,+ ws_id_bytes,+ proj_id_bytes,path,title,kind,@@ -1024,6 +1025,8 @@ impl ReaderPool {let Some((workspace_name,project_name,+ ws_id_bytes,+ proj_id_bytes,path,title,kind,@@ -1037,6 +1040,11 @@ impl ReaderPool {return Ok(None);};+ let workspace_id = WorkspaceId::from_slice(&ws_id_bytes)+ .map_err(|_| rusqlite::Error::IntegralValueOutOfRange(2, 0))?;+ let project_id = ProjectId::from_slice(&proj_id_bytes)+ .map_err(|_| rusqlite::Error::IntegralValueOutOfRange(3, 0))?;+let created_at = jiff::Timestamp::from_microsecond(created_us).map(|ts| ts.to_string()).unwrap_or_default();@@ -1047,6 +1055,8 @@ impl ReaderPool {Ok(Some(PageMeta {workspace_name,project_name,+ workspace_id,+ project_id,path,title,kind,diff --git a/crates/ai-memory-web/src/routes/page.rs b/crates/ai-memory-web/src/routes/page.rsindex e9e44fa3..155111e3 100644--- a/crates/ai-memory-web/src/routes/page.rs+++ b/crates/ai-memory-web/src/routes/page.rs@@ -28,7 +28,10 @@ pub(crate) async fn handler(Err(_) => return StatusCode::BAD_REQUEST.into_response(),};- let markdown_doc = match state.wiki.read_page(&page_path) {+ let markdown_doc = match state+ .wiki+ .read_page(meta.workspace_id, meta.project_id, &page_path)+ {Ok(doc) => doc,Err(_) => return not_found_response(),};diff --git a/crates/ai-memory-wiki/src/watcher.rs b/crates/ai-memory-wiki/src/watcher.rsindex d2867391..4d21f626 100644--- a/crates/ai-memory-wiki/src/watcher.rs+++ b/crates/ai-memory-wiki/src/watcher.rs@@ -18,6 +18,7 @@//! store updates via [`Wiki::write_page`].use std::path::Path;+use std::str::FromStr;use std::time::Duration;use ai_memory_core::{PagePath, ProjectId, WorkspaceId};@@ -46,10 +47,14 @@ impl WatcherHandle {/// Start watching `wiki.root()` recursively. Spawns one tokio task/// that consumes debounced events and runs the reconciliation timer.///+ /// Events are attributed to their `(workspace_id, project_id)` by+ /// parsing the first two path segments as UUIDs. Events outside the+ /// `<ws_uuid>/<proj_uuid>/...` layout are silently ignored.+ ////// # Errors/// Propagates any notify error encountered when installing the OS/// watcher.- pub fn start(wiki: Wiki, workspace_id: WorkspaceId, project_id: ProjectId) -> WikiResult<Self> {+ pub fn start(wiki: Wiki) -> WikiResult<Self> {let (event_tx, event_rx) = mpsc::unbounded_channel();let mut debouncer = new_debouncer(@@ -75,13 +80,7 @@ impl WatcherHandle {.map_err(|e| WikiError::Io(std::io::Error::other(e.to_string())))?;let (shutdown_tx, shutdown_rx) = tokio::sync::oneshot::channel::<()>();- let task = tokio::spawn(run_loop(- wiki,- workspace_id,- project_id,- event_rx,- shutdown_rx,- ));+ let task = tokio::spawn(run_loop(wiki, event_rx, shutdown_rx));Ok(Self {_debouncer: debouncer,@@ -111,8 +110,6 @@ impl Drop for WatcherHandle {async fn run_loop(wiki: Wiki,- ws: WorkspaceId,- proj: ProjectId,mut rx: mpsc::UnboundedReceiver<notify_debouncer_full::DebouncedEvent>,mut shutdown: tokio::sync::oneshot::Receiver<()>,) {@@ -137,10 +134,10 @@ async fn run_loop(return;}Some(event) = rx.recv() => {- handle_event(&wiki, ws, proj, event).await;+ handle_event(&wiki, event).await;}_ = tick.tick() => {- match reconcile(&wiki, ws, proj).await {+ match reconcile(&wiki).await {Ok(()) => {if consecutive_failures > 0 {tracing::info!(@@ -176,12 +173,7 @@ async fn run_loop(}}-async fn handle_event(- wiki: &Wiki,- ws: WorkspaceId,- proj: ProjectId,- event: notify_debouncer_full::DebouncedEvent,-) {+async fn handle_event(wiki: &Wiki, event: notify_debouncer_full::DebouncedEvent) {if !matches!(event.kind,EventKind::Create(_) | EventKind::Modify(_) | EventKind::Other@@ -195,7 +187,7 @@ async fn handle_event(if is_tempfile(raw_path) {continue;}- let Some(page_path) = page_path_relative_to(wiki.root(), raw_path) else {+ let Some((ws, proj, page_path)) = extract_project_ids(wiki.root(), raw_path) else {continue;};if !raw_path.is_file() {@@ -209,22 +201,107 @@ async fn handle_event(}}-async fn reconcile(wiki: &Wiki, ws: WorkspaceId, proj: ProjectId) -> WikiResult<()> {+async fn reconcile(wiki: &Wiki) -> WikiResult<()> {let root = wiki.root().to_path_buf();- let paths = tokio::task::spawn_blocking(move || walk_markdown(&root))+ // Walk all per-project subdirectories: <ws_uuid>/<proj_uuid>/+ let project_dirs = tokio::task::spawn_blocking(move || walk_project_dirs(&root)).await.map_err(|e| WikiError::Io(std::io::Error::other(e.to_string())))??;- let count = paths.len();- for path in paths {- if let Err(e) = wiki.reindex_page(ws, proj, path.clone()).await {- warn!(path = %path, error = %e, "reconcile reindex failed");+ let mut total = 0_usize;+ for (ws, proj, proj_root) in project_dirs {+ let pages = tokio::task::spawn_blocking(move || walk_markdown(&proj_root))+ .await+ .map_err(|e| WikiError::Io(std::io::Error::other(e.to_string())))??;+ total += pages.len();+ for path in pages {+ if let Err(e) = wiki.reindex_page(ws, proj, path.clone()).await {+ warn!(path = %path, error = %e, "reconcile reindex failed");+ }}}- info!(count, "reconciliation pass complete");+ info!(count = total, "reconciliation pass complete");Ok(())}+/// Walk `<wiki_root>` and return all `(WorkspaceId, ProjectId, proj_root)` tuples+/// whose first two path segments parse as valid UUIDs.+fn walk_project_dirs(+ wiki_root: &Path,+) -> WikiResult<Vec<(WorkspaceId, ProjectId, std::path::PathBuf)>> {+ let mut out = Vec::new();+ let ws_read = match std::fs::read_dir(wiki_root) {+ Ok(r) => r,+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(out),+ Err(e) => return Err(WikiError::Io(e)),+ };+ for ws_entry in ws_read {+ let ws_entry = ws_entry?;+ if !ws_entry.file_type()?.is_dir() {+ continue;+ }+ let ws_name = ws_entry.file_name();+ let Some(ws_str) = ws_name.to_str() else {+ continue;+ };+ let Ok(ws_id) = WorkspaceId::from_str(ws_str) else {+ continue;+ };+ let proj_read = match std::fs::read_dir(ws_entry.path()) {+ Ok(r) => r,+ Err(_) => continue,+ };+ for proj_entry in proj_read {+ let proj_entry = proj_entry?;+ if !proj_entry.file_type()?.is_dir() {+ continue;+ }+ let proj_name = proj_entry.file_name();+ let Some(proj_str) = proj_name.to_str() else {+ continue;+ };+ let Ok(proj_id) = ProjectId::from_str(proj_str) else {+ continue;+ };+ out.push((ws_id, proj_id, proj_entry.path()));+ }+ }+ Ok(out)+}++/// Parse `(WorkspaceId, ProjectId, PagePath)` from a filesystem event path.+///+/// Expects the path to have the structure:+/// `<wiki_root>/<ws_uuid>/<proj_uuid>/<page-path...>`+///+/// Returns `None` when:+/// - The path does not start with `wiki_root`.+/// - The first segment is not a valid UUID (`WorkspaceId`).+/// - The second segment is not a valid UUID (`ProjectId`).+/// - There are no remaining segments (the page path would be empty).+pub(crate) fn extract_project_ids(+ wiki_root: &Path,+ event_path: &Path,+) -> Option<(WorkspaceId, ProjectId, PagePath)> {+ let rel = event_path.strip_prefix(wiki_root).ok()?;+ let mut components = rel.components();++ let ws_seg = components.next()?.as_os_str().to_str()?;+ let ws_id = WorkspaceId::from_str(ws_seg).ok()?;++ let proj_seg = components.next()?.as_os_str().to_str()?;+ let proj_id = ProjectId::from_str(proj_seg).ok()?;++ // Rejoin remaining segments as the page path.+ let page_rel: std::path::PathBuf = components.collect();+ let page_str = page_rel.to_string_lossy().replace('\\', "/");+ if page_str.is_empty() {+ return None;+ }+ let page_path = PagePath::new(page_str).ok()?;+ Some((ws_id, proj_id, page_path))+}+fn walk_markdown(root: &Path) -> WikiResult<Vec<PagePath>> {let mut out = Vec::new();let mut stack = vec![root.to_path_buf()];@@ -300,18 +377,73 @@ mod tests {(tmp, store, wiki, ws, proj)}+ /// `extract_project_ids` must parse a valid `<ws>/<proj>/<path>` triplet.+ #[test]+ fn extract_project_ids_valid_path() {+ let wiki_root = Path::new("/data/wiki");+ let ws_id = WorkspaceId::new();+ let proj_id = ProjectId::new();+ let event_path =+ std::path::PathBuf::from(format!("/data/wiki/{}/{}/decisions/foo.md", ws_id, proj_id));+ let result = extract_project_ids(wiki_root, &event_path);+ assert!(+ result.is_some(),+ "must extract IDs from valid namespaced path"+ );+ let (ws, proj, pp) = result.unwrap();+ assert_eq!(ws, ws_id);+ assert_eq!(proj, proj_id);+ assert_eq!(pp.as_str(), "decisions/foo.md");+ }++ /// `extract_project_ids` must return `None` when the first segment is not a UUID.+ #[test]+ fn extract_project_ids_garbage_first_segment() {+ let wiki_root = Path::new("/data/wiki");+ let event_path = Path::new("/data/wiki/not-a-uuid/some-proj/foo.md");+ assert!(+ extract_project_ids(wiki_root, event_path).is_none(),+ "garbage first segment must return None"+ );+ }++ /// `extract_project_ids` must return `None` for flat (non-namespaced) paths.+ #[test]+ fn extract_project_ids_flat_path_returns_none() {+ let wiki_root = Path::new("/data/wiki");+ let event_path = Path::new("/data/wiki/foo.md");+ assert!(+ extract_project_ids(wiki_root, event_path).is_none(),+ "flat path with no namespace must return None"+ );+ }+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]async fn picks_up_externally_created_file() {let (tmp, store, wiki, ws, proj) = setup().await;- let handle = WatcherHandle::start(wiki.clone(), ws, proj).unwrap();- // Drop a file *bypassing* the wiki write API (simulating an- // external editor).- let target = tmp.path().join("wiki/external.md");+ // Create the project directory BEFORE starting the watcher so+ // the inotify backend adds a watch for it immediately. If we+ // created it after, there is a race between the new-dir event+ // and the file-write event that can cause the watcher to miss+ // the file on slower Linux inotify instances.+ let proj_dir = tmp+ .path()+ .join("wiki")+ .join(ws.to_string())+ .join(proj.to_string());+ std::fs::create_dir_all(&proj_dir).unwrap();++ let handle = WatcherHandle::start(wiki.clone()).unwrap();++ // Drop a file inside the per-project directory, bypassing the wiki write API+ // (simulating an external editor).+ let target = proj_dir.join("external.md");std::fs::write(&target, "Hello from outside the wiki API.\n").unwrap();- // Poll for the row to land. Watcher debounces at 300ms.- let deadline = std::time::Instant::now() + Duration::from_secs(3);+ // Poll for the row to land. Watcher debounces at 300ms; extra+ // margin for slow CI environments.+ let deadline = std::time::Instant::now() + Duration::from_secs(5);let mut hits = Vec::new();while std::time::Instant::now() < deadline {hits = store@@ -332,13 +464,20 @@ mod tests {#[tokio::test(flavor = "multi_thread", worker_threads = 2)]async fn reconcile_picks_up_file_added_while_watcher_offline() {let (tmp, store, wiki, ws, proj) = setup().await;- // Write a file BEFORE starting the watcher.- let target = tmp.path().join("wiki/preexisting.md");++ // Write a file BEFORE starting the watcher — directly in the project dir.+ let proj_dir = tmp+ .path()+ .join("wiki")+ .join(ws.to_string())+ .join(proj.to_string());+ std::fs::create_dir_all(&proj_dir).unwrap();+ let target = proj_dir.join("preexisting.md");std::fs::write(&target, "I existed first.\n").unwrap();- let handle = WatcherHandle::start(wiki.clone(), ws, proj).unwrap();+ let handle = WatcherHandle::start(wiki.clone()).unwrap();// Hit reconcile manually instead of waiting 30s.- reconcile(&wiki, ws, proj).await.unwrap();+ reconcile(&wiki).await.unwrap();let hits = store.reader@@ -364,23 +503,23 @@ mod tests {#[tokio::test(flavor = "multi_thread", worker_threads = 2)]async fn walk_markdown_skips_symlinks() {let tmp = TempDir::new().unwrap();- let wiki_root = tmp.path().join("wiki");- std::fs::create_dir_all(&wiki_root).unwrap();+ let proj_root = tmp.path().join("proj");+ std::fs::create_dir_all(&proj_root).unwrap();// A real file (should be picked up).- std::fs::write(wiki_root.join("real.md"), "real content\n").unwrap();+ std::fs::write(proj_root.join("real.md"), "real content\n").unwrap();- // A "secret" file outside the wiki root.+ // A "secret" file outside the project root.let secret = tmp.path().join("secret.md");std::fs::write(&secret, "this is sensitive\n").unwrap();- // Plant a symlink inside wiki/ pointing at the outside file.+ // Plant a symlink inside proj/ pointing at the outside file.#[cfg(unix)]- std::os::unix::fs::symlink(&secret, wiki_root.join("symlinked.md")).unwrap();+ std::os::unix::fs::symlink(&secret, proj_root.join("symlinked.md")).unwrap();#[cfg(windows)]- std::os::windows::fs::symlink_file(&secret, wiki_root.join("symlinked.md")).unwrap();+ std::os::windows::fs::symlink_file(&secret, proj_root.join("symlinked.md")).unwrap();- let found = walk_markdown(&wiki_root).unwrap();+ let found = walk_markdown(&proj_root).unwrap();let names: Vec<_> = found.iter().map(|p| p.as_str().to_string()).collect();assert!(names.contains(&"real.md".to_string()), "real file present");assert!(diff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rsindex 25073a1c..586082dc 100644--- a/crates/ai-memory-wiki/src/wiki.rs+++ b/crates/ai-memory-wiki/src/wiki.rs@@ -98,24 +98,44 @@ impl Wiki {&self.root}- /// Absolute on-disk path for a given [`PagePath`].+ /// Resolve the on-disk root for a project: `<wiki_root>/<ws>/<proj>`.+ /// All page files for this project live under this directory.#[must_use]- pub fn abs_path(&self, path: &PagePath) -> PathBuf {- self.root.join(path.as_str())+ pub fn project_root(&self, workspace_id: WorkspaceId, project_id: ProjectId) -> PathBuf {+ self.root+ .join(workspace_id.to_string())+ .join(project_id.to_string())}- /// Read the page at `path` from disk.+ /// Absolute on-disk path for a page within a specific project.+ #[must_use]+ pub fn abs_path(+ &self,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ path: &PagePath,+ ) -> PathBuf {+ self.project_root(workspace_id, project_id)+ .join(path.as_str())+ }++ /// Read the page at `path` from disk for the given project.////// # 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);+ pub fn read_page(+ &self,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ path: &PagePath,+ ) -> WikiResult<Markdown> {+ let abs = self.abs_path(workspace_id, project_id, path);let raw = std::fs::read_to_string(&abs)?;parse(&raw)}- /// Delete the on-disk file for `path`.+ /// Delete the on-disk file for `path` within the given project.////// Returns `Ok(())` when the file was removed or did not exist (idempotent)./// The file watcher will observe the deletion; the sha256 short-circuit in@@ -124,8 +144,13 @@ impl Wiki {////// # Errors/// Returns [`WikiError::Io`] for any OS error other than "not found".- pub fn delete_page(&self, path: &PagePath) -> WikiResult<()> {- let abs = self.abs_path(path);+ pub fn delete_page(+ &self,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ path: &PagePath,+ ) -> WikiResult<()> {+ let abs = self.abs_path(workspace_id, project_id, path);match std::fs::remove_file(&abs) {Ok(()) => Ok(()),Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),@@ -155,7 +180,7 @@ impl Wiki {project_id: ProjectId,path: PagePath,) -> WikiResult<PageId> {- let md = self.read_page(&path)?;+ let md = self.read_page(workspace_id, project_id, &path)?;let title = derive_title(&md.frontmatter, &md.body, &path);let id = self.writer@@ -202,7 +227,7 @@ impl Wiki {body: req.body.clone(),};let emitted = emit(&markdown)?;- let abs = self.abs_path(&req.path);+ let abs = self.abs_path(req.workspace_id, req.project_id, &req.path);let parent = abs.parent().ok_or_else(|| {ai_memory_wiki_error("page path has no parent (cannot stage tempfile)")})?;@@ -282,7 +307,10 @@ impl Wiki {body: body.clone(),};let emitted = emit(&markdown)?;- let abs = self.abs_path(&path);+ let abs = self.abs_path(workspace_id, project_id, &path);+ if let Some(parent) = abs.parent() {+ std::fs::create_dir_all(parent)?;+ }atomic::write_atomic(&abs, emitted.as_bytes())?;let page_id = self@@ -406,8 +434,15 @@ mod tests {.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();+ // File is on disk at the per-project location.+ let on_disk = std::fs::read_to_string(+ tmp.path()+ .join("wiki")+ .join(ws.to_string())+ .join(proj.to_string())+ .join("notes/karpathy.md"),+ )+ .unwrap();assert!(on_disk.starts_with("---\n"));assert!(on_disk.contains("title: Karpathy LLM Wiki"));assert!(on_disk.contains("Karpathy says"));@@ -456,7 +491,14 @@ mod tests {.await.unwrap();- let on_disk = std::fs::read_to_string(tmp.path().join("wiki/notes/leaky.md")).unwrap();+ let on_disk = std::fs::read_to_string(+ tmp.path()+ .join("wiki")+ .join(ws.to_string())+ .join(proj.to_string())+ .join("notes/leaky.md"),+ )+ .unwrap();// The on-disk page must not contain any of the planted// secrets; each should have been replaced with [REDACTED].assert!(@@ -518,7 +560,12 @@ mod tests {let ids = wiki.apply_batch(batch).await.unwrap();assert_eq!(ids.len(), 5);for i in 0..5 {- let path = tmp.path().join(format!("wiki/batch/{i}.md"));+ let path = tmp+ .path()+ .join("wiki")+ .join(ws.to_string())+ .join(proj.to_string())+ .join(format!("batch/{i}.md"));assert!(path.is_file(), "missing file {i}");let body = std::fs::read_to_string(&path).unwrap();assert!(body.contains(&format!("Page {i}")));@@ -529,6 +576,78 @@ mod tests {assert_eq!(hits.len(), 5);}+ /// Two projects writing the same relative path must produce two distinct+ /// files under their respective UUID-namespaced directories.+ #[tokio::test]+ async fn two_projects_same_path_no_collision() {+ 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_a = store+ .writer+ .get_or_create_project(ws, "alpha", None)+ .await+ .unwrap();+ let proj_b = store+ .writer+ .get_or_create_project(ws, "beta", None)+ .await+ .unwrap();+ let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();++ wiki.write_page(WritePageRequest {+ workspace_id: ws,+ project_id: proj_a,+ path: PagePath::new("decisions/foo.md").unwrap(),+ frontmatter: serde_json::json!({"title": "Alpha decision"}),+ body: "Alpha body".into(),+ tier: Tier::Semantic,+ pinned: false,+ title: None,+ })+ .await+ .unwrap();++ wiki.write_page(WritePageRequest {+ workspace_id: ws,+ project_id: proj_b,+ path: PagePath::new("decisions/foo.md").unwrap(),+ frontmatter: serde_json::json!({"title": "Beta decision"}),+ body: "Beta body".into(),+ tier: Tier::Semantic,+ pinned: false,+ title: None,+ })+ .await+ .unwrap();++ let path_a = tmp+ .path()+ .join("wiki")+ .join(ws.to_string())+ .join(proj_a.to_string())+ .join("decisions/foo.md");+ let path_b = tmp+ .path()+ .join("wiki")+ .join(ws.to_string())+ .join(proj_b.to_string())+ .join("decisions/foo.md");++ assert!(path_a.is_file(), "alpha file must exist");+ assert!(path_b.is_file(), "beta file must exist");+ assert_ne!(path_a, path_b, "distinct paths on disk");++ let content_a = std::fs::read_to_string(&path_a).unwrap();+ let content_b = std::fs::read_to_string(&path_b).unwrap();+ assert!(content_a.contains("Alpha body"), "alpha content intact");+ assert!(content_b.contains("Beta body"), "beta content intact");+ }+#[tokio::test]async fn rewriting_same_body_is_idempotent() {let tmp = TempDir::new().unwrap();