Skip to content

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.md
index 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) for
the full flag reference + per-source priority order.
diff --git a/crates/ai-memory-consolidate/src/bootstrap.rs b/crates/ai-memory-consolidate/src/bootstrap.rs
index 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.rs
index 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.rs
index 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.rs
index 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 and
diff --git a/crates/ai-memory-mcp/tests/admin_backup.rs b/crates/ai-memory-mcp/tests/admin_backup.rs
index 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.rs
index 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.rs
index 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.rs
index 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.md
index 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 see
which sources would actually be sent + how many tokens that
diff --git a/docs/lifecycle-ops.md b/docs/lifecycle-ops.md
index 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 on
the `(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>/…`