Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
audit cleanup + log-md monthly rotation
AkitaOnRails71002a33545d
diff --git a/README.md b/README.mdindex 6a9357a0..9641dc34 100644--- a/README.md+++ b/README.md@@ -324,10 +324,11 @@ export AI_MEMORY_SERVER_URL="http://localhost:49374"ai-memory bootstrap --workspace homelab --project myproj```-Bootstrap produces a `wiki/bootstrap.md` manifest listing every page-generated + a one-paragraph rationale. Run with `--dry-run` first to-preview which sources would be sent without paying for the LLM call.-Re-running on the same project requires `--force`.+Bootstrap produces a per-project `bootstrap.md` manifest (under+`<wiki>/<workspace>/<project>/`) listing every page generated + a+one-paragraph rationale. Run with `--dry-run` first to preview which+sources would be sent without paying for the LLM call. Re-running on+the same project requires `--force`.See [`docs/install.md`](docs/install.md#bootstrap-mid-project) forthe full flag reference + per-source priority order.diff --git a/crates/ai-memory-consolidate/src/bootstrap.rs b/crates/ai-memory-consolidate/src/bootstrap.rsindex e9b60a55..696d13c2 100644--- a/crates/ai-memory-consolidate/src/bootstrap.rs+++ b/crates/ai-memory-consolidate/src/bootstrap.rs@@ -25,10 +25,10 @@//!//! ## Idempotency//!-//! First write produces `wiki/bootstrap.md` recording the run-//! (timestamp, source counts, generated page count). Re-running-//! refuses unless `--force` is passed. The user can always delete-//! `wiki/bootstrap.md` (and the generated pages) to reset.+//! First write produces `<wiki>/<workspace>/<project>/bootstrap.md`+//! recording the run (timestamp, source counts, generated page count).+//! Re-running refuses unless `--force` is passed. The user can always+//! delete the manifest (and the generated pages) to reset.use std::path::{Path, PathBuf};use std::sync::Arc;@@ -55,9 +55,12 @@ pub enum BootstrapError {/// Project repo path doesn't exist or isn't a git repo.#[error("repo path {0} is not a git repository")]NotARepo(PathBuf),- /// The wiki already has a `bootstrap.md` manifest. Re-run with+ /// The project already has a `bootstrap.md` manifest. Re-run with/// `--force` to overwrite.- #[error("project already bootstrapped (wiki/bootstrap.md exists). Pass --force to re-run.")]+ #[error(+ "this project is already bootstrapped (its bootstrap manifest already exists). \+ Pass --force to re-run."+ )]AlreadyBootstrapped,/// All source categories were excluded; nothing to do.#[error("no input sources selected; remove at least one --exclude-* flag")]diff --git a/crates/ai-memory-hooks/src/log.rs b/crates/ai-memory-hooks/src/log.rsindex 31de83b8..f03ddc93 100644--- a/crates/ai-memory-hooks/src/log.rs+++ b/crates/ai-memory-hooks/src/log.rs@@ -1,20 +1,43 @@-//! `log.md` append helper.+//! Per-project rolling event log.//!//! The log is the chronological ledger Karpathy's gist insists on — a//! grep-able audit trail of "what happened, when". Lines use the exact//! prefix `## [YYYY-MM-DDTHH:MM:SSZ] <event> | <title>` so unix tools//! (`grep "^## \["`) can parse it without a markdown library.+//!+//! ## Rotation+//!+//! Each calendar month gets its own file: `log-YYYY-MM.md` under the+//! project root. The filename is derived from the event timestamp, so+//! events written across a month boundary land in their respective+//! month's file. Old months never grow once closed — perfect for git's+//! per-blob storage (one terminal blob per month per project). The+//! watcher's reserved-name check (`is_reserved_filename`) covers the+//! `log-*.md` pattern so rotated files are not indexed as wiki pages.+//!+//! No explicit retention sweep yet — git history bounds growth+//! sub-linearly and old monthly blobs are tiny. A future+//! `forget-sweep --logs --older-than 12m` could delete cold files if+//! it becomes worthwhile.use std::io::Write;-use std::path::Path;use ai_memory_core::{ProjectId, WorkspaceId};+use ai_memory_wiki::Wiki;use jiff::{Timestamp, ToSpan, tz::TimeZone};use tracing::debug;use crate::payload::HookEvent;-/// Append one line to `<wiki_root>/<workspace_id>/<project_id>/log.md`.+/// Append one line to the current month's log file:+/// `<wiki.project_root(ws, proj)>/log-YYYY-MM.md`. The filename is+/// derived from `when` so events written across a month boundary land+/// in their respective month's file; no in-process rotation step is+/// needed.+///+/// Using [`Wiki::project_root`] ensures the path is derived from the+/// single canonical location (CLAUDE.md §15 invariant — no hand-rolled+/// path joins outside the Wiki type).////// POSIX `O_APPEND` writes of less than `PIPE_BUF` (4 KiB) are atomic, so/// concurrent appenders do not interleave.@@ -22,17 +45,16 @@ use crate::payload::HookEvent;/// # Errors/// Propagates any I/O failure from opening or writing the file.pub fn append_event(- wiki_root: &Path,+ wiki: &Wiki,workspace_id: WorkspaceId,project_id: ProjectId,when: Timestamp,event: HookEvent,title: &str,) -> std::io::Result<()> {- let log_path = wiki_root- .join(workspace_id.to_string())- .join(project_id.to_string())- .join("log.md");+ let log_path = wiki+ .project_root(workspace_id, project_id)+ .join(log_filename_for(when));let line = format_line(when, event, title);debug!(path = %log_path.display(), bytes = line.len(), "appending log entry");@@ -50,6 +72,15 @@ pub fn append_event(Ok(())}+/// Compute the per-month log filename for an event with timestamp+/// `when`: `log-YYYY-MM.md` in UTC. Exposed only to the test module+/// (and the watcher's reserved-name check, which uses a glob).+pub(crate) fn log_filename_for(when: Timestamp) -> String {+ when.to_zoned(TimeZone::UTC)+ .strftime("log-%Y-%m.md")+ .to_string()+}+fn format_line(when: Timestamp, event: HookEvent, title: &str) -> String {let stamp = when.to_zoned(TimeZone::UTC).strftime("%Y-%m-%dT%H:%M:%SZ");let kind = match event {@@ -79,6 +110,8 @@ fn now() -> Timestamp {#[cfg(test)]mod tests {use super::*;+ use ai_memory_store::Store;+ use ai_memory_wiki::Wiki;use jiff::civil::DateTime;use tempfile::TempDir;@@ -96,23 +129,76 @@ mod tests {);}- #[test]- fn append_creates_file_and_grows() {+ #[tokio::test]+ async fn append_creates_file_and_grows() {let tmp = TempDir::new().unwrap();- let root = tmp.path();- let ws = WorkspaceId::new();- let proj = ProjectId::new();+ let store = Store::open(tmp.path()).unwrap();+ let wiki = Wiki::new(tmp.path(), store.writer.clone()).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 now = Timestamp::now();- 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");+ append_event(&wiki, ws, proj, now, HookEvent::SessionStart, "first").unwrap();+ append_event(&wiki, ws, proj, now, HookEvent::UserPrompt, "second").unwrap();+ let log_path = wiki.project_root(ws, proj).join(log_filename_for(now));let contents = std::fs::read_to_string(&log_path).unwrap();assert!(contents.contains("session-start | first"));assert!(contents.contains("user-prompt | second"));// Two lines.assert_eq!(contents.matches("\n## [").count(), 1);}++ #[tokio::test]+ async fn append_rotates_across_month_boundary() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let wiki = Wiki::new(tmp.path(), store.writer.clone()).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 may: Timestamp = DateTime::new(2026, 5, 31, 23, 59, 0, 0)+ .unwrap()+ .to_zoned(TimeZone::UTC)+ .unwrap()+ .timestamp();+ let june: Timestamp = DateTime::new(2026, 6, 1, 0, 0, 5, 0)+ .unwrap()+ .to_zoned(TimeZone::UTC)+ .unwrap()+ .timestamp();+ append_event(&wiki, ws, proj, may, HookEvent::SessionStart, "may-evt").unwrap();+ append_event(&wiki, ws, proj, june, HookEvent::UserPrompt, "june-evt").unwrap();++ let root = wiki.project_root(ws, proj);+ let may_log = std::fs::read_to_string(root.join("log-2026-05.md")).unwrap();+ let june_log = std::fs::read_to_string(root.join("log-2026-06.md")).unwrap();+ assert!(may_log.contains("may-evt"));+ assert!(!may_log.contains("june-evt"));+ assert!(june_log.contains("june-evt"));+ assert!(!june_log.contains("may-evt"));+ }++ #[test]+ fn log_filename_uses_utc_year_month() {+ let when: Timestamp = DateTime::new(2026, 1, 2, 3, 4, 5, 0)+ .unwrap()+ .to_zoned(TimeZone::UTC)+ .unwrap()+ .timestamp();+ assert_eq!(log_filename_for(when), "log-2026-01.md");+ }}diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rsindex b102eedb..0d66ab48 100644--- a/crates/ai-memory-hooks/src/router.rs+++ b/crates/ai-memory-hooks/src/router.rs@@ -288,7 +288,7 @@ async fn process(state: &HookState, env: HookEnvelope) -> anyhow::Result<()> {// Append the log line to the per-project log.md.if let Err(e) = log::append_event(- state.wiki.root(),+ &state.wiki,ws,proj,Timestamp::now(),diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rsindex d07594e9..62ea602d 100644--- a/crates/ai-memory-mcp/src/admin.rs+++ b/crates/ai-memory-mcp/src/admin.rs@@ -313,6 +313,42 @@ async fn resolve_ws_proj(Ok((ws, proj))}+/// Look up workspace + project by name **without** auto-creating them.+/// Returns `(WorkspaceId, ProjectId)` on success, or a ready-to-return+/// 404/500 error response. Used by destructive handlers (purge, rename)+/// where auto-creation would silently succeed on a typo.+async fn lookup_ws_proj_no_create(+ state: &AdminState,+ workspace: &str,+ project: &str,+) -> Result<(WorkspaceId, ProjectId), (StatusCode, Json<serde_json::Value>)> {+ let ws_id = match state.reader.find_workspace(workspace.to_string()).await {+ Ok(Some(id)) => id,+ Ok(None) => {+ return Err((+ StatusCode::NOT_FOUND,+ Json(serde_json::json!({+ "error": format!("workspace '{workspace}' not found")+ })),+ ));+ }+ Err(e) => return Err(internal_err(e.to_string())),+ };+ let proj_id = match state.reader.find_project(ws_id, project.to_string()).await {+ Ok(Some(id)) => id,+ Ok(None) => {+ return Err((+ StatusCode::NOT_FOUND,+ Json(serde_json::json!({+ "error": format!("project '{project}' not found in workspace '{workspace}'")+ })),+ ));+ }+ Err(e) => return Err(internal_err(e.to_string())),+ };+ Ok((ws_id, proj_id))+}+// ---------------------------------------------------------------------// bootstrap// ---------------------------------------------------------------------@@ -502,24 +538,12 @@ pub struct ReorgReport {pub summary: ReorgSummaryJson,}-async fn handle_reorg(- State(state): State<Arc<AdminState>>,- Json(req): Json<ReorgRequest>,-) -> impl IntoResponse {- // Step 1: ensure the default workspace exists.- let ws = match state.writer.get_or_create_workspace("default").await {- Ok(id) => id,- Err(e) => {- return (- StatusCode::INTERNAL_SERVER_ERROR,- Json(serde_json::json!({ "error": format!("workspace: {e}") })),- );- }- };-- // Step 2: read all sessions with a non-NULL, non-empty cwd.- let sessions_with_cwd: Vec<(SessionId, ProjectId, String)> = match state- .reader+/// Read every session that has a non-empty `cwd` field, returning+/// `(session_id, project_id, cwd)` triples ordered by `started_at`.+async fn list_sessions_with_cwd(+ reader: &ai_memory_store::ReaderPool,+) -> Result<Vec<(SessionId, ProjectId, String)>, StoreError> {+ reader.with_conn(move |conn| {let mut stmt = conn.prepare("SELECT id, project_id, cwd \@@ -543,37 +567,20 @@ async fn handle_reorg(Ok(out)}).await- {- Ok(v) => v,- Err(e) => {- return (- StatusCode::INTERNAL_SERVER_ERROR,- Json(serde_json::json!({ "error": e.to_string() })),- );- }- };-- if sessions_with_cwd.is_empty() {- let report = ReorgReport {- dry_run: req.dry_run,- plan: Vec::new(),- summary: ReorgSummaryJson {- sessions_moved: 0,- observations_updated: 0,- pages_graveyarded: 0,- distinct_new_projects: 0,- },- };- return (- StatusCode::OK,- Json(serde_json::to_value(&report).unwrap_or_else(|_| serde_json::json!({}))),- );- }+}- // Step 3: resolve target project per distinct cwd (basename-derived).+/// Build the reorg plan: for each session with a new project basename,+/// resolve-or-create the target project, return the plan entries plus+/// the set of session updates and the distinct-project count.+async fn build_reorg_plan(+ state: &AdminState,+ ws: WorkspaceId,+ sessions: Vec<(SessionId, ProjectId, String)>,+) -> Result<(Vec<ReorgPlanEntry>, Vec<(SessionId, ProjectId)>, usize), StoreError> {+ // Resolve target project per distinct cwd (basename-derived).let mut cwd_to_proj: std::collections::HashMap<String, (WorkspaceId, ProjectId, String)> =std::collections::HashMap::new();- for (_, _, cwd) in &sessions_with_cwd {+ for (_, _, cwd) in &sessions {if cwd_to_proj.contains_key(cwd.as_str()) {continue;}@@ -583,26 +590,17 @@ async fn handle_reorg(.filter(|s| !s.is_empty()).map(str::to_string).unwrap_or_else(|| "unknown".to_string());- let proj = match state+ let proj = state.writer.get_or_create_project(ws, project_name.clone(), Some(cwd.clone()))- .await- {- Ok(id) => id,- Err(e) => {- return (- StatusCode::INTERNAL_SERVER_ERROR,- Json(serde_json::json!({ "error": format!("project: {e}") })),- );- }- };+ .await?;cwd_to_proj.insert(cwd.clone(), (ws, proj, project_name));}- // Step 4: build plan — sessions whose project_id already matches are skipped.+ // Build plan — sessions whose project_id already matches are skipped.let mut plan_entries: Vec<ReorgPlanEntry> = Vec::new();let mut writer_plan: Vec<(SessionId, ProjectId)> = Vec::new();- for (session_id, old_project_id, cwd) in &sessions_with_cwd {+ for (session_id, old_project_id, cwd) in &sessions {let (_, new_project_id, project_name) = &cwd_to_proj[cwd.as_str()];if *new_project_id == *old_project_id {continue;@@ -618,7 +616,61 @@ async fn handle_reorg(let distinct_new_projects: std::collections::HashSet<ProjectId> =writer_plan.iter().map(|(_, pid)| *pid).collect();- // Step 5: dry-run → return the plan without writing.+ Ok((plan_entries, writer_plan, distinct_new_projects.len()))+}++async fn handle_reorg(+ State(state): State<Arc<AdminState>>,+ Json(req): Json<ReorgRequest>,+) -> impl IntoResponse {+ let ws = match state.writer.get_or_create_workspace("default").await {+ Ok(id) => id,+ Err(e) => {+ return (+ StatusCode::INTERNAL_SERVER_ERROR,+ Json(serde_json::json!({ "error": format!("workspace: {e}") })),+ );+ }+ };++ let sessions = match list_sessions_with_cwd(&state.reader).await {+ Ok(v) => v,+ Err(e) => {+ return (+ StatusCode::INTERNAL_SERVER_ERROR,+ Json(serde_json::json!({ "error": e.to_string() })),+ );+ }+ };++ if sessions.is_empty() {+ let report = ReorgReport {+ dry_run: req.dry_run,+ plan: Vec::new(),+ summary: ReorgSummaryJson {+ sessions_moved: 0,+ observations_updated: 0,+ pages_graveyarded: 0,+ distinct_new_projects: 0,+ },+ };+ return (+ StatusCode::OK,+ Json(serde_json::to_value(&report).unwrap_or_else(|_| serde_json::json!({}))),+ );+ }++ let (plan_entries, writer_plan, distinct_count) =+ match build_reorg_plan(&state, ws, sessions).await {+ Ok(t) => t,+ Err(e) => {+ return (+ StatusCode::INTERNAL_SERVER_ERROR,+ Json(serde_json::json!({ "error": format!("project: {e}") })),+ );+ }+ };+if req.dry_run || writer_plan.is_empty() {let report = ReorgReport {dry_run: req.dry_run,@@ -627,7 +679,7 @@ async fn handle_reorg(sessions_moved: 0,observations_updated: 0,pages_graveyarded: 0,- distinct_new_projects: distinct_new_projects.len(),+ distinct_new_projects: distinct_count,},};return (@@ -636,7 +688,6 @@ async fn handle_reorg();}- // Step 6: execute.let summary = match state.writer.reorg_sessions(writer_plan).await {Ok(s) => s,Err(e) => {@@ -654,7 +705,7 @@ async fn handle_reorg(sessions_moved: summary.sessions_moved,observations_updated: summary.observations_updated,pages_graveyarded: summary.pages_graveyarded,- distinct_new_projects: distinct_new_projects.len(),+ distinct_new_projects: distinct_count,},};(@@ -986,44 +1037,11 @@ async fn handle_purge_project(}// Look up workspace and project IDs without auto-creating.- let ws_id = match state.reader.find_workspace(req.workspace.clone()).await {- Ok(Some(id)) => id,- Ok(None) => {- return (- StatusCode::NOT_FOUND,- Json(serde_json::json!({- "error": format!("workspace '{}' not found", req.workspace)- })),- );- }- Err(e) => {- return (- StatusCode::INTERNAL_SERVER_ERROR,- Json(serde_json::json!({ "error": e.to_string() })),- );- }- };-- let proj_id = match state.reader.find_project(ws_id, req.project.clone()).await {- Ok(Some(id)) => id,- Ok(None) => {- return (- StatusCode::NOT_FOUND,- Json(serde_json::json!({- "error": format!(- "project '{}' not found in workspace '{}'",- req.project, req.workspace- )- })),- );- }- Err(e) => {- return (- StatusCode::INTERNAL_SERVER_ERROR,- Json(serde_json::json!({ "error": e.to_string() })),- );- }- };+ let (ws_id, proj_id) =+ match lookup_ws_proj_no_create(&state, &req.workspace, &req.project).await {+ Ok(ids) => ids,+ Err(e) => return e,+ };let label = format!("{}/{}", req.workspace, req.project);let summary = match state.writer.purge_project(ws_id, proj_id, &label).await {@@ -1105,45 +1123,10 @@ async fn handle_rename_project(State(state): State<Arc<AdminState>>,Json(req): Json<RenameProjectRequest>,) -> impl IntoResponse {- // Step 1: look up workspace; 404 if absent.- let ws_id = match state.reader.find_workspace(req.workspace.clone()).await {- Ok(Some(id)) => id,- Ok(None) => {- return (- StatusCode::NOT_FOUND,- Json(serde_json::json!({- "error": format!("workspace '{}' not found", req.workspace)- })),- );- }- Err(e) => {- return (- StatusCode::INTERNAL_SERVER_ERROR,- Json(serde_json::json!({ "error": e.to_string() })),- );- }- };-- // Step 2: look up the source project; 404 if absent.- let proj_id = match state.reader.find_project(ws_id, req.from.clone()).await {- Ok(Some(id)) => id,- Ok(None) => {- return (- StatusCode::NOT_FOUND,- Json(serde_json::json!({- "error": format!(- "project '{}' not found in workspace '{}'",- req.from, req.workspace- )- })),- );- }- Err(e) => {- return (- StatusCode::INTERNAL_SERVER_ERROR,- Json(serde_json::json!({ "error": e.to_string() })),- );- }+ // Look up workspace + source project; 404 if either is absent.+ let (ws_id, proj_id) = match lookup_ws_proj_no_create(&state, &req.workspace, &req.from).await {+ Ok(ids) => ids,+ Err(e) => return e,};// Step 3: execute the rename. The writer validates the name anddiff --git a/crates/ai-memory-mcp/tests/admin_backup.rs b/crates/ai-memory-mcp/tests/admin_backup.rsindex ac46186a..fa72d48d 100644--- a/crates/ai-memory-mcp/tests/admin_backup.rs+++ b/crates/ai-memory-mcp/tests/admin_backup.rs@@ -4,15 +4,17 @@//! seeds a page, POSTs to `/admin/backup`, and asserts://! - the response Content-Type is `application/gzip`,//! - the body is a valid gzip/tar stream,-//! - the seeded wiki file appears in the tarball.+//! - the seeded wiki file appears in the tarball at the per-project path,+//! - the seeded file's content inside the tarball matches the original body.-use ai_memory_core::{NewPage, PagePath, Tier};+use ai_memory_core::{PagePath, Tier};use ai_memory_mcp::{AdminState, admin_router};use ai_memory_store::{DecayParams, Store};-use ai_memory_wiki::Wiki;+use ai_memory_wiki::{Wiki, WritePageRequest};use axum::body::Body;use axum::http::{Request, StatusCode};use flate2::read::GzDecoder;+use std::io::Read as _;use tar::Archive;use tempfile::TempDir;use tower::ServiceExt;@@ -35,11 +37,10 @@ async fn make_state(tmp: &TempDir) -> (AdminState, Store) {(state, store)}-/// Seed a page directly into the store (index only — we also need the-/// on-disk wiki file for the tarball). Use `AdminState.wiki.write_page`-/// via the state, but here we seed through the store + write the file-/// directly to exercise the backup path.-async fn seed_page(store: &Store, tmp: &TempDir, path: &str, body: &str) {+/// Seed a page through [`Wiki::write_page`] so it lands in the correct+/// per-project directory (`<wiki>/<ws>/<proj>/<path>`), proving the+/// backup path picks up the production write layout.+async fn seed_page(state: &AdminState, store: &Store, path: &str, body: &str) {let ws = store.writer.get_or_create_workspace("default".to_string())@@ -50,34 +51,33 @@ async fn seed_page(store: &Store, tmp: &TempDir, path: &str, body: &str) {.get_or_create_project(ws, "scratch".to_string(), None).await.unwrap();- store- .writer- .upsert_page(NewPage {+ state+ .wiki+ .write_page(WritePageRequest {workspace_id: ws,project_id: proj,path: PagePath::new(path).unwrap(),- title: "Test".to_string(),+ frontmatter: serde_json::json!({ "title": "Test" }),body: body.to_string(),tier: Tier::Semantic,- frontmatter_json: serde_json::json!({}),pinned: false,+ title: Some("Test".into()),}).await.unwrap();-- // Also write the file on disk so the tarball picks it up.- let full = tmp.path().join("wiki").join(path);- if let Some(parent) = full.parent() {- std::fs::create_dir_all(parent).unwrap();- }- std::fs::write(&full, body).unwrap();}#[tokio::test]async fn backup_returns_application_gzip_content_type() {let tmp = TempDir::new().unwrap();let (state, store) = make_state(&tmp).await;- seed_page(&store, &tmp, "concepts/karpathy.md", "compile not retrieve").await;+ seed_page(+ &state,+ &store,+ "concepts/karpathy.md",+ "compile not retrieve",+ )+ .await;let router = admin_router(state);let req = Request::builder()@@ -103,13 +103,8 @@ async fn backup_returns_application_gzip_content_type() {async fn backup_body_is_valid_gzip_and_contains_seeded_page() {let tmp = TempDir::new().unwrap();let (state, store) = make_state(&tmp).await;- seed_page(- &store,- &tmp,- "concepts/karpathy.md",- "compile-not-retrieve from Karpathy LLM wiki",- )- .await;+ let known_body = "compile-not-retrieve from Karpathy LLM wiki";+ seed_page(&state, &store, "concepts/karpathy.md", known_body).await;let router = admin_router(state);let req = Request::builder()@@ -125,28 +120,35 @@ async fn backup_body_is_valid_gzip_and_contains_seeded_page() {.unwrap();assert!(!bytes.is_empty(), "backup body must not be empty");- // Decompress and list entries.+ // Decompress, list entries, and check the seeded file's content.let decoder = GzDecoder::new(bytes.as_ref());let mut archive = Archive::new(decoder);- let entries: Vec<String> = archive- .entries()- .expect("tarball must be readable")- .map(|e| {- e.expect("entry must be readable")- .path()- .unwrap()- .to_string_lossy()- .into_owned()- })- .collect();-+ let mut found_page = false;+ let mut found_db = false;+ let mut page_content = String::new();+ for entry in archive.entries().expect("tarball must be readable") {+ let mut entry = entry.expect("entry must be readable");+ let path = entry.path().unwrap().to_string_lossy().into_owned();+ if path.contains("concepts/karpathy.md") {+ entry+ .read_to_string(&mut page_content)+ .expect("page entry must be readable");+ found_page = true;+ }+ if path.contains("memory.sqlite") {+ found_db = true;+ }+ }assert!(- entries.iter().any(|p| p.contains("concepts/karpathy.md")),- "tarball must contain the seeded page; entries: {entries:?}"+ found_page,+ "tarball must contain the seeded page; no 'concepts/karpathy.md' entry found");+ assert!(found_db, "tarball must contain the db snapshot");+ // Verify the page body matches what was written — confirms the backup+ // captured the per-project write-path content, not stale or wrong data.assert!(- entries.iter().any(|p| p.contains("memory.sqlite")),- "tarball must contain the db snapshot; entries: {entries:?}"+ page_content.contains(known_body),+ "page content in tarball must contain the seeded body; got: {page_content:?}");}diff --git a/crates/ai-memory-mcp/tests/admin_purge.rs b/crates/ai-memory-mcp/tests/admin_purge.rsindex 1093f5af..80e49872 100644--- a/crates/ai-memory-mcp/tests/admin_purge.rs+++ b/crates/ai-memory-mcp/tests/admin_purge.rs@@ -241,11 +241,7 @@ async fn purge_project_deletes_data_and_files() {let (ws, _keep, doomed) = seed_two_projects(&store, &state.wiki).await;// The per-project directory must exist before purge.- let proj_dir = tmp- .path()- .join("wiki")- .join(ws.to_string())- .join(doomed.to_string());+ let proj_dir = state.wiki.project_root(ws, doomed);assert!(proj_dir.exists(), "project dir must exist before purge");let resp = post(@@ -297,6 +293,8 @@ async fn purge_project_preserves_sibling_project() {let (state, store) = make_state(&tmp).await;let (ws, keep, _doomed) = seed_two_projects(&store, &state.wiki).await;+ // Clone the wiki handle before state is consumed by `post`.+ let wiki = state.wiki.clone();let resp = post(state,@@ -323,11 +321,7 @@ async fn purge_project_preserves_sibling_project() {);// 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());+ let keep_dir = wiki.project_root(ws, keep);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-wiki/src/watcher.rs b/crates/ai-memory-wiki/src/watcher.rsindex 4d21f626..e19db418 100644--- a/crates/ai-memory-wiki/src/watcher.rs+++ b/crates/ai-memory-wiki/src/watcher.rs@@ -190,6 +190,9 @@ async fn handle_event(wiki: &Wiki, event: notify_debouncer_full::DebouncedEvent)let Some((ws, proj, page_path)) = extract_project_ids(wiki.root(), raw_path) else {continue;};+ if is_reserved_filename(&page_path) {+ continue;+ }if !raw_path.is_file() {// Likely a transient state (mv, atomic rename in flight).continue;@@ -330,6 +333,7 @@ fn walk_markdown(root: &Path) -> WikiResult<Vec<PagePath>> {&& is_markdown(&path)&& !is_tempfile(&path)&& let Some(pp) = page_path_relative_to(root, &path)+ && !is_reserved_filename(&pp){out.push(pp);}@@ -348,6 +352,21 @@ fn is_tempfile(path: &Path) -> bool {.is_some_and(|n| n.starts_with(".ai-memory-tmp."))}+/// Returns `true` for the per-project reserved files that are NOT wiki+/// pages: `log-YYYY-MM.md` (per-month rolling event ledger — see+/// `ai-memory-hooks::log::log_filename_for`), the legacy `log.md`+/// filename for backwards compatibility, and `bootstrap.md` (manifest).+/// The watcher must skip them to avoid supersession loops — every+/// `append_event` write triggers a watcher event, triggering an+/// `upsert_page`, creating a spurious new supersession version.+fn is_reserved_filename(page_path: &PagePath) -> bool {+ let s = page_path.as_str();+ s == "log.md"+ || s == "bootstrap.md"+ // log-YYYY-MM.md — 7 chars between the dash and the dot.+ || (s.starts_with("log-") && s.ends_with(".md") && s.len() == "log-YYYY-MM.md".len())+}+fn page_path_relative_to(root: &Path, abs: &Path) -> Option<PagePath> {let rel: &Path = abs.strip_prefix(root).ok()?;let s = rel.to_string_lossy().replace('\\', "/");@@ -418,6 +437,34 @@ mod tests {);}+ /// `extract_project_ids` must return `None` when the second segment is not a valid UUID.+ #[test]+ fn extract_rejects_garbage_in_project_segment() {+ let wiki_root = Path::new("/tmp/wiki");+ let ws = WorkspaceId::new().to_string();+ let event_path =+ std::path::PathBuf::from(format!("/tmp/wiki/{ws}/not-a-uuid/decisions/foo.md"));+ assert!(+ extract_project_ids(wiki_root, &event_path).is_none(),+ "garbage project segment must return None"+ );+ }++ /// `extract_project_ids` must return `None` when there is no page path+ /// after the two UUID segments (would produce an empty `PagePath`).+ #[test]+ fn extract_rejects_empty_page_path() {+ let wiki_root = Path::new("/tmp/wiki");+ let ws = WorkspaceId::new().to_string();+ let proj = ProjectId::new().to_string();+ // Just the project dir itself with no page path beneath.+ let event_path = std::path::PathBuf::from(format!("/tmp/wiki/{ws}/{proj}"));+ assert!(+ extract_project_ids(wiki_root, &event_path).is_none(),+ "missing page path 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;@@ -498,6 +545,78 @@ mod tests {assert!(!is_tempfile(q));}+ /// `walk_markdown` must not return `log.md` or `bootstrap.md`+ /// (reserved per-project files that must not become wiki pages).+ #[tokio::test(flavor = "multi_thread", worker_threads = 2)]+ async fn walk_markdown_skips_reserved_filenames() {+ let (tmp, store, wiki, ws, proj) = setup().await;++ let proj_dir = tmp+ .path()+ .join("wiki")+ .join(ws.to_string())+ .join(proj.to_string());+ std::fs::create_dir_all(&proj_dir).unwrap();++ // Write a legitimate page plus the reserved files (legacy+ // `log.md`, the rotated `log-YYYY-MM.md`, and `bootstrap.md`).+ // Single-word unique tokens so FTS5 (which parses hyphens as+ // operators) can match them.+ std::fs::write(proj_dir.join("real.md"), "real content\n").unwrap();+ std::fs::write(proj_dir.join("log.md"), "sessionstarted logtoken unique\n").unwrap();+ std::fs::write(+ proj_dir.join("log-2026-05.md"),+ "sessionstarted rotatedlogtoken unique\n",+ )+ .unwrap();+ std::fs::write(+ proj_dir.join("bootstrap.md"),+ "bootstrapmanifest boottoken unique\n",+ )+ .unwrap();++ let handle = WatcherHandle::start(wiki.clone()).unwrap();+ // Trigger the reconciliation pass directly.+ reconcile(&wiki).await.unwrap();++ // Only `real.md` should land in the index.+ let hits = store+ .reader+ .search_pages("real content".into(), 5)+ .await+ .unwrap();+ assert_eq!(hits.len(), 1, "only the real page should be indexed");+ assert_eq!(hits[0].path.as_str(), "real.md");++ // Neither reserved file should be searchable.+ let log_hits = store+ .reader+ .search_pages("logtoken".into(), 5)+ .await+ .unwrap();+ assert!(log_hits.is_empty(), "log.md must not be indexed");++ let rotated_hits = store+ .reader+ .search_pages("rotatedlogtoken".into(), 5)+ .await+ .unwrap();+ assert!(+ rotated_hits.is_empty(),+ "log-YYYY-MM.md (rotated) must not be indexed"+ );++ let boot_hits = store+ .reader+ .search_pages("boottoken".into(), 5)+ .await+ .unwrap();+ assert!(boot_hits.is_empty(), "bootstrap.md must not be indexed");++ handle.shutdown().await;+ drop(store);+ }+/// Defence: an attacker who can write to wiki/ shouldn't be able/// to make the watcher index arbitrary files via symlinks.#[tokio::test(flavor = "multi_thread", worker_threads = 2)]diff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rsindex 586082dc..70c43394 100644--- a/crates/ai-memory-wiki/src/wiki.rs+++ b/crates/ai-memory-wiki/src/wiki.rs@@ -19,6 +19,13 @@ use crate::markdown::{Markdown, derive_title, emit, parse};/// file *and* sends a `WriteCmd::UpsertPage` to the store in a single/// call — no background-task indexing-after-return (basic-memory #763/// lesson).+///+/// ## On-disk layout+///+/// Pages are stored at `<wiki_root>/<workspace_id>/<project_id>/<page-path>`.+/// Each of `workspace_id` and `project_id` is a UUID string. This layout is+/// the single canonical namespace; all path construction must go through+/// [`Wiki::project_root`] or [`Wiki::abs_path`] — never hand-rolled joins.#[derive(Clone)]pub struct Wiki {root: PathBuf,@@ -272,7 +279,8 @@ impl Wiki {}/// Write `body` (with optional `frontmatter`) atomically to- /// `<wiki_root>/<path>` and upsert the matching page row in the store.+ /// `<wiki_root>/<workspace_id>/<project_id>/<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`.@@ -387,6 +395,22 @@ mod tests {use ai_memory_store::Store;use tempfile::TempDir;+ #[tokio::test]+ async fn project_root_is_wiki_root_joined_with_ws_and_proj() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();+ let ws = WorkspaceId::new();+ let proj = ProjectId::new();+ assert_eq!(+ wiki.project_root(ws, proj),+ tmp.path()+ .join("wiki")+ .join(ws.to_string())+ .join(proj.to_string()),+ );+ }+fn req(ws: WorkspaceId,proj: ProjectId,@@ -435,13 +459,11 @@ mod tests {let _ = id; // any non-zero PageId is sufficient// 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"),- )+ let on_disk = std::fs::read_to_string(wiki.abs_path(+ ws,+ proj,+ &PagePath::new("notes/karpathy.md").unwrap(),+ )).unwrap();assert!(on_disk.starts_with("---\n"));assert!(on_disk.contains("title: Karpathy LLM Wiki"));@@ -491,13 +513,11 @@ mod tests {.await.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"),- )+ let on_disk = std::fs::read_to_string(wiki.abs_path(+ ws,+ proj,+ &PagePath::new("notes/leaky.md").unwrap(),+ )).unwrap();// The on-disk page must not contain any of the planted// secrets; each should have been replaced with [REDACTED].@@ -560,12 +580,7 @@ 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("wiki")- .join(ws.to_string())- .join(proj.to_string())- .join(format!("batch/{i}.md"));+ let path = wiki.abs_path(ws, proj, &PagePath::new(format!("batch/{i}.md")).unwrap());assert!(path.is_file(), "missing file {i}");let body = std::fs::read_to_string(&path).unwrap();assert!(body.contains(&format!("Page {i}")));@@ -625,18 +640,9 @@ mod tests {.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");+ let page = PagePath::new("decisions/foo.md").unwrap();+ let path_a = wiki.abs_path(ws, proj_a, &page);+ let path_b = wiki.abs_path(ws, proj_b, &page);assert!(path_a.is_file(), "alpha file must exist");assert!(path_b.is_file(), "beta file must exist");diff --git a/docs/install.md b/docs/install.mdindex 50e6c4fc..d993e55a 100644--- a/docs/install.md+++ b/docs/install.md@@ -386,10 +386,11 @@ docker run --rm \- 1-2k generated tokens → ~$0.007 output- Total: well under $0.20 per run.-**Idempotency.** The first run produces `wiki/bootstrap.md`-listing every page generated + a one-paragraph rationale. Re-running-without `--force` errors out. Delete the manifest (and the generated-pages) if you want a clean re-bootstrap.+**Idempotency.** The first run produces a per-project `bootstrap.md`+manifest (at `<wiki>/<workspace>/<project>/bootstrap.md`) listing every+page generated + a one-paragraph rationale. Re-running without `--force`+errors out. Delete the manifest (and the generated pages) if you want a+clean re-bootstrap.**Dry-run first.** Always worth doing before the real call to seewhich sources would actually be sent + how many tokens thatdiff --git a/docs/lifecycle-ops.md b/docs/lifecycle-ops.mdindex 265caade..3daee233 100644--- a/docs/lifecycle-ops.md+++ b/docs/lifecycle-ops.md@@ -33,7 +33,7 @@ Every project's data lives under an isolated, UUID-keyed root on disk:│ ├── gotchas/│ ├── sessions/│ ├── _rules/-│ ├── log.md+│ ├── log-YYYY-MM.md # rolling event log, one file per month│ └── bootstrap.md└── <other_workspace_id>/└── <other_project_id>/@@ -107,7 +107,7 @@ What happens:whitespace. 422 on bad input.3. `UPDATE projects SET name = ? WHERE id = ?`. UNIQUE-violation onthe `(workspace_id, name)` index → 422 with "name taken".-4. Return `{label, from, to, pages}`.+4. Return `{workspace, from, to, pages}`.Zero files move on disk because the disk path is keyed by`project_id`, not name. The web UI URL `/web/w/<ws>/<proj-name>/…`