Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

feat(wikisync): two-way sync through the MCP write tool (#986 slice 3)

geeksilva9708ddbcfabad2
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5d5d23fd..5bc82299 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Added
+- Added two-way sync to the `ai-memory-wikisync` companion (#986, slice 3):
+ `sync` imports repository edits and new pages through the public
+ `memory_write_page` MCP tool and exports server edits, comparing each
+ page with the last sync. A page changed on both sides is a conflict until
+ `--prefer repo` or `--prefer server`; deletes are reported, not synced.
+ It is a dry-run without `--apply`, refuses files without frontmatter,
+ refuses to overwrite server pages whose metadata a write would clear, and
+ re-reads each page right before writing it. (#TBD)
+
+### Changed
+- Changed `ai-memory-wikisync` files to carry a small frontmatter (`title`,
+ plus `tags`, `pinned` and a non-default `tier` when set) above the body,
+ so metadata survives a round trip. The first run after upgrading rewrites
+ unedited files of an earlier export in place. (#TBD)
+
### Fixed
- Fixed `ai-memory-wikisync` committing its per-clone export state: the
`git add` of the destination that `export --apply` prints also staged
diff --git a/companions/ai-memory-wikisync/README.md b/companions/ai-memory-wikisync/README.md
index 17650d20..eee27e40 100644
--- a/companions/ai-memory-wikisync/README.md
+++ b/companions/ai-memory-wikisync/README.md
@@ -1,11 +1,14 @@
# ai-memory-wikisync
-Read-only **team-wiki export** companion for
-[ai-memory](https://github.com/akitaonrails/ai-memory) (issue #986,
-slice 1). It pulls explicitly allowlisted page families from a running
-ai-memory server through the public, read-only `/api/v1` surface into a
-directory inside a project repository, so a team's shared memory can live
-as reviewable markdown in git.
+**Team-wiki sync** companion for
+[ai-memory](https://github.com/akitaonrails/ai-memory) (issue #986, slices
+1 and 3). It keeps explicitly allowlisted page families of a running
+ai-memory server in step with a directory inside a project repository, so a
+team's shared memory can live as reviewable markdown in git:
+
+- `export` copies server pages into the repository (one way).
+- `sync` also sends repository edits back to the server, through the public
+ `memory_write_page` MCP tool.
It is a standalone Cargo package (own workspace, own lockfile); the root
ai-memory workspace does not build or test it:
@@ -28,6 +31,12 @@ ai-memory-wikisync plan \
# Same listing, then write — export without --apply is still a dry-run.
ai-memory-wikisync export ... --apply
+
+# Two-way: dry-run plan of imports and exports, then apply it.
+ai-memory-wikisync sync ...
+ai-memory-wikisync sync ... --apply
+# A page changed on both sides is a conflict until a side is chosen.
+ai-memory-wikisync sync ... --apply --prefer repo # or --prefer server
```
- `plan` never writes, not even the state file.
@@ -43,10 +52,24 @@ ai-memory-wikisync export ... --apply
## What it writes
-Exactly the server's canonical page projection: `path`, `title`, `body`.
-The page body (which carries its own `# H1` title) is transported
-verbatim. The tool never forges attribution, generated, or sync
-frontmatter into page files.
+Each file is a small frontmatter, then the server body verbatim:
+
+```markdown
+---
+title: "Commit rules"
+tags: ["git"]
+pinned: true
+---
+# Commit rules
+...
+```
+
+Only the fields `memory_write_page` accepts and this tool round-trips appear:
+`title`, `tags` (when there are any), `pinned` (when true), and `tier` (when
+it is not the default `semantic`). The values are JSON strings and lists,
+which are also valid YAML. A sync sends these fields back with every import,
+because the tool clears whatever a write omits. Server-generated keys
+(`type`, `generated`, `last_modified_by`) never reach the repository.
All local bookkeeping lives in **one** state file,
`.ai-memory-wikisync/state.json` (mode 0600, atomically replaced after
@@ -63,12 +86,15 @@ state; untrack it once with
## Safety model
+This section describes `plan` and `export`; `sync` adds the rules under
+[Two-way sync](#two-way-sync).
+
- **API-only.** Documented read-only `/api/v1` endpoints (incremental
`recent` listing with cursor paging, single-page reads with
`ETag`/`If-None-Match` revalidation; the legacy array listing is
- accepted as a fallback). No MCP, no admin routes, no writes to the
- server. `401`/`403`/`404` become clear errors; page count and body size
- are bounded per run.
+ accepted as a fallback). No admin routes, and `plan` and `export` never
+ write to the server. `401`/`403`/`404` become clear errors; page count
+ and body size are bounded per run.
- **Path safety.** Every server-reported path is validated into a
portable shape (ASCII, no traversal, no dotfiles, no reserved Windows
names, `.md` leaf, bounded depth/length) before it is joined onto
@@ -80,19 +106,57 @@ state; untrack it once with
diverged from both is reported with a diff summary and **refused**; the
whole batch is refused, nothing is written. `--force` overwrites the
divergent files with server content.
-- **Never deletes.** Local files — including brand-new local files inside
- an allowlisted family — are never deleted. Deletes are slice 4.
+- **Never deletes.** Local files and server pages are never deleted,
+ including brand-new local files inside an allowlisted family. Deletes
+ are slice 4.
- **Untrusted content.** Page bodies are data: transported verbatim,
never executed, never rendered, never interpreted. Paths that would
escape `--dest` are refused.
-## Roadmap (#986)
+## Two-way sync
+
+`sync` classifies every page in the allowlisted families from three
+versions: the repository file, the state entry (what the last sync wrote),
+and the server page rendered into file bytes.
+
+| Repository | Server | Action |
+|---|---|---|
+| unchanged | changed | export the server page |
+| changed | unchanged | import the file with `memory_write_page` |
+| new file | no page | import (create) |
+| changed | changed | conflict: nothing is written until `--prefer repo` or `--prefer server` |
+| deleted | present | reported; the server page is kept |
+| present | deleted | reported; the file is kept |
+
+Safety rules:
+
+- **Writes only through MCP.** No wiki file or SQLite access; the server's
+ sanitizer, admission and attribution apply to every import.
+- **Dry-run by default.** `--apply` is required, and any refused page
+ (a conflict, an invalid file) blocks the whole batch.
+- **Frontmatter is required to import.** A file without it would clear the
+ page's title, tags and pin on the server, so it is refused.
+- **Metadata the write cannot carry is protected.** A server page with any
+ frontmatter key other than `title`, `tier`, `pinned`, `tags`, `type`,
+ `generated` and `last_modified_by` (a consolidated page's `summary` or
+ `sources`, an MCP write's `kind` or `abstract`) is never overwritten by an
+ import; the refusal names the keys. Such pages still export.
+- **Re-read before each write.** Right before an import the server page is
+ read again and must still render to the bytes it was classified against.
+ The MCP write has no compare-and-write, so a write that lands between that
+ read and the import is the one race left (the case for slice 2).
+- **The server's version wins after an import.** If the server stores
+ something other than the file (the sanitizer redacting a secret), the file
+ is rewritten with the server's rendering.
+- **Deletes are not synced yet** (slice 4). Pages gone from both sides drop
+ out of the state.
-This is slice 1 of the accepted team-wiki sync plan:
+## Roadmap (#986)
-1. **This release — read-only export** into a project repository.
+1. Read-only export into a project repository (`export`).
2. Conditional mutation seam (compare-and-write) in core, if independently
justified.
-3. Bidirectional apply (repo edits flow back through public write tools).
+3. **This release — two-way sync** (`sync`): repository edits flow back
+ through the public MCP write tool.
4. Deletes and conflict reporting.
5. Post-merge hook / CI integration.
diff --git a/companions/ai-memory-wikisync/src/bidi.rs b/companions/ai-memory-wikisync/src/bidi.rs
new file mode 100644
index 00000000..d0462620
--- /dev/null
+++ b/companions/ai-memory-wikisync/src/bidi.rs
@@ -0,0 +1,734 @@
+//! Two-way sync (#986, slice 3): repository edits flow back to the server
+//! through the public `memory_write_page` tool, server edits flow out as in
+//! `export`.
+//!
+//! Every page in an allowlisted family is classified from three versions:
+//! the repository file, the state entry (what the last sync wrote), and the
+//! server page rendered into file bytes. A change on one side is applied to
+//! the other; a change on both sides is a conflict that only `--prefer`
+//! resolves. Deletes on either side are reported and left alone (slice 4).
+//!
+//! Nothing is written unless `--apply` is passed and nothing in the plan is
+//! refused. Before each import the server page is read again and must still
+//! render to the bytes it was classified against: the MCP write has no
+//! compare-and-write, so that re-read narrows the race to the gap between
+//! one read and one write (the case for slice 2).
+
+use std::collections::{BTreeMap, BTreeSet};
+use std::fs;
+use std::path::Path;
+
+use anyhow::{Context, Result, bail};
+use serde_json::Value;
+
+use crate::client::{ApiClient, ApiPage};
+use crate::mcp::McpClient;
+use crate::page_file::{self, PageMeta};
+use crate::state::{self, PageState, SyncState};
+use crate::sync::{self, Mode, RunArgs};
+use crate::{MAX_BODY_BYTES, MAX_PAGES, paths};
+
+/// Server frontmatter keys a `memory_write_page` import writes back, or
+/// the server regenerates on every write. A page carrying any other key
+/// (a consolidated page's `summary`, `sources`, `kind`, …) would lose it,
+/// because the tool clears what the call omits.
+const RECREATED_KEYS: &[&str] = &[
+ "title",
+ "tier",
+ "pinned",
+ "tags",
+ "type",
+ "generated",
+ "last_modified_by",
+];
+
+/// Which side wins a page changed on both sides.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Prefer {
+ Repo,
+ Server,
+}
+
+/// What the server holds for one path.
+#[derive(Debug, Clone, Copy)]
+pub enum ServerSide<'a> {
+ /// Not in the listing: never created, or deleted.
+ Absent,
+ /// `304`: unchanged since the ETag recorded with the base.
+ NotModified,
+ /// The page rendered into file bytes.
+ Rendered(&'a [u8]),
+}
+
+/// The decision for one page.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Action {
+ Unchanged,
+ /// Server to repository.
+ Export {
+ create: bool,
+ },
+ /// Repository to server.
+ Import {
+ create: bool,
+ },
+ /// Changed on both sides, and no `--prefer`.
+ Conflict,
+ /// The server no longer has a page the last sync saw (slice 4).
+ DeletedOnServer,
+ /// The repository no longer has a file the last sync wrote (slice 4).
+ DeletedInRepo,
+ /// Gone from both sides: only the state entry remains, and it is dropped.
+ GoneOnBothSides,
+}
+
+/// Decide one page from its three versions. Pure, so the matrix is testable
+/// without a server.
+pub fn decide(
+ disk: Option<&[u8]>,
+ base: Option<&PageState>,
+ server: ServerSide<'_>,
+ prefer: Option<Prefer>,
+) -> Action {
+ let disk_hash = disk.map(state::sha256_hex);
+ let disk_is_base = matches!((&disk_hash, base), (Some(disk), Some(base)) if *disk == base.hash);
+ match server {
+ ServerSide::Absent => match (disk.is_some(), base.is_some()) {
+ (true, false) => Action::Import { create: true },
+ (true, true) => Action::DeletedOnServer,
+ (false, true) => Action::GoneOnBothSides,
+ (false, false) => Action::Unchanged,
+ },
+ ServerSide::NotModified => match (disk.is_some(), base.is_some()) {
+ (false, true) => Action::DeletedInRepo,
+ (false, false) => Action::Unchanged,
+ (true, _) if disk_is_base => Action::Unchanged,
+ (true, _) => Action::Import { create: false },
+ },
+ ServerSide::Rendered(server) => {
+ let server_hash = state::sha256_hex(server);
+ match disk_hash {
+ None if base.is_some() => Action::DeletedInRepo,
+ None => Action::Export { create: true },
+ Some(disk) if disk == server_hash => Action::Unchanged,
+ Some(_) if disk_is_base => Action::Export { create: false },
+ Some(_) if base.is_some_and(|base| base.hash == server_hash) => {
+ Action::Import { create: false }
+ }
+ Some(_) => match prefer {
+ Some(Prefer::Repo) => Action::Import { create: false },
+ Some(Prefer::Server) => Action::Export { create: false },
+ None => Action::Conflict,
+ },
+ }
+ }
+ }
+}
+
+/// Server frontmatter keys an import would clear, sorted.
+pub fn keys_an_import_would_clear(frontmatter: &Value) -> Vec<String> {
+ let Some(map) = frontmatter.as_object() else {
+ return Vec::new();
+ };
+ let mut keys: Vec<String> = map
+ .keys()
+ .filter(|key| !RECREATED_KEYS.contains(&key.as_str()))
+ .cloned()
+ .collect();
+ keys.sort();
+ keys
+}
+
+/// Arguments of `sync`.
+#[derive(Debug, Clone)]
+pub struct SyncArgs {
+ pub run: RunArgs,
+ pub prefer: Option<Prefer>,
+}
+
+struct Import {
+ path: String,
+ create: bool,
+ meta: PageMeta,
+ body: String,
+ disk: Vec<u8>,
+ /// Hash of the server page's rendering at classification, which must
+ /// still hold right before the write; `None` for a create.
+ expected_server: Option<String>,
+}
+
+struct Export {
+ path: String,
+ create: bool,
+ bytes: String,
+ etag: Option<String>,
+}
+
+/// A page the plan refuses to touch; any of these blocks `--apply`.
+struct Refusal {
+ path: String,
+ reason: String,
+}
+
+#[derive(Default)]
+struct Plan {
+ imports: Vec<Import>,
+ exports: Vec<Export>,
+ unchanged: Vec<String>,
+ refused: Vec<Refusal>,
+ notices: Vec<(String, &'static str)>,
+ /// State to keep for pages this run leaves alone or adopts.
+ adopted: BTreeMap<String, PageState>,
+ forget: Vec<String>,
+}
+
+/// Entry point behind `sync`.
+pub async fn run(args: &SyncArgs, apply: bool) -> Result<()> {
+ let run_args = &args.run;
+ let families = sync::validate_allowlist(&run_args.include)?;
+ let mode = if apply { Mode::Apply } else { Mode::DryRun };
+ let dest_root = sync::resolve_dest(&run_args.dest, mode)?;
+ let old_state = state::load(&dest_root)?;
+ let api = ApiClient::new(&run_args.server, run_args.token.clone())?;
+
+ let plan = build_plan(&api, args, &families, &dest_root, &old_state).await?;
+ print_plan(run_args, &families, &plan, apply);
+
+ if !apply {
+ return Ok(());
+ }
+ if !plan.refused.is_empty() {
+ bail!(
+ "{} page(s) refused; nothing was written. Resolve them (or pass --prefer for \
+ conflicts) and run again",
+ plan.refused.len()
+ );
+ }
+ let mcp = McpClient::new(&run_args.server, run_args.token.clone())?;
+ let wrote_files = apply_plan(&api, &mcp, run_args, &dest_root, &old_state, plan).await?;
+ if wrote_files {
+ sync::print_git_hints(run_args);
+ }
+ Ok(())
+}
+
+async fn build_plan(
+ api: &ApiClient,
+ args: &SyncArgs,
+ families: &[String],
+ dest_root: &Path,
+ old_state: &SyncState,
+) -> Result<Plan> {
+ let run_args = &args.run;
+ let mut plan = Plan::default();
+ let listed = api
+ .list_pages(&run_args.workspace, &run_args.project)
+ .await?;
+ let on_server: BTreeSet<String> = sync::select_pages(listed, families)?
+ .into_iter()
+ .map(|page| page.path)
+ .collect();
+ let in_repo = local_pages(dest_root, families, &mut plan.refused)?;
+ let in_state = old_state
+ .pages
+ .keys()
+ .filter(|path| {
+ families
+ .iter()
+ .any(|family| paths::family_of(path) == family)
+ })
+ .cloned();
+ let all: BTreeSet<String> = on_server
+ .iter()
+ .cloned()
+ .chain(in_repo)
+ .chain(in_state)
+ .collect();
+ if all.len() > MAX_PAGES {
+ bail!(
+ "{} pages exceed the per-run ceiling of {MAX_PAGES}; narrow --include",
+ all.len()
+ );
+ }
+ paths::ensure_no_case_fold_collisions(&all.iter().cloned().collect::<Vec<_>>())?;
+
+ for path in all {
+ let disk = sync::read_disk(dest_root, &path)?;
+ if disk
+ .as_ref()
+ .is_some_and(|disk| disk.len() > MAX_BODY_BYTES)
+ {
+ plan.refused.push(Refusal {
+ path,
+ reason: format!("file is larger than {MAX_BODY_BYTES} bytes"),
+ });
+ continue;
+ }
+ let base = old_state.pages.get(&path);
+ let mut current: Option<ApiPage> = None;
+ let mut etag = None;
+ let mut rendered = None;
+ if on_server.contains(&path) {
+ let hint = disk
+ .as_ref()
+ .and(base.and_then(|base| base.etag.as_deref()));
+ let read = api
+ .read_page(&run_args.workspace, &run_args.project, &path, hint)
+ .await?;
+ etag = read.etag;
+ if let Some(page) = read.page {
+ rendered = Some(sync::render_page(&page)?);
+ current = Some(page);
+ }
+ }
+ let server = match (&rendered, on_server.contains(&path)) {
+ (Some(bytes), _) => ServerSide::Rendered(bytes.as_bytes()),
+ (None, true) => ServerSide::NotModified,
+ (None, false) => ServerSide::Absent,
+ };
+ match decide(disk.as_deref(), base, server, args.prefer) {
+ Action::Unchanged => {
+ if let Some(bytes) = &rendered {
+ plan.adopted.insert(
+ path.clone(),
+ PageState {
+ hash: state::sha256_hex(bytes.as_bytes()),
+ etag,
+ },
+ );
+ }
+ plan.unchanged.push(path);
+ }
+ Action::Export { create } => {
+ let Some(bytes) = rendered else {
+ bail!("server returned 304 for {path} with no local file to compare");
+ };
+ plan.exports.push(Export {
+ path,
+ create,
+ bytes,
+ etag,
+ });
+ }
+ Action::Import { create } => {
+ let disk = disk.unwrap_or_default();
+ if !create && current.is_none() {
+ // A 304 proved the server unchanged, but the import
+ // still needs the page's metadata keys and rendering.
+ let page = api
+ .read_page(&run_args.workspace, &run_args.project, &path, None)
+ .await?
+ .page
+ .with_context(|| {
+ format!("server returned 304 for {path} without an ETag")
+ })?;
+ current = Some(page);
+ }
+ plan_import(&mut plan, path, create, disk, current.as_ref())?;
+ }
+ Action::Conflict => {
+ let summary =
+ sync::diff_summary(disk.as_deref(), rendered.as_deref().map(str::as_bytes));
+ plan.refused.push(Refusal {
+ path,
+ reason: format!(
+ "changed in the repository and on the server since the last sync \
+ ({summary}); pass --prefer repo or --prefer server"
+ ),
+ });
+ }
+ Action::DeletedOnServer => plan.notices.push((
+ path,
+ "deleted on the server; the file is kept (deletes are not synced yet)",
+ )),
+ Action::DeletedInRepo => plan.notices.push((
+ path,
+ "deleted in the repository; the server page is kept (deletes are not synced yet)",
+ )),
+ Action::GoneOnBothSides => plan.forget.push(path),
+ }
+ }
+ Ok(plan)
+}
+
+fn plan_import(
+ plan: &mut Plan,
+ path: String,
+ create: bool,
+ disk: Vec<u8>,
+ current: Option<&ApiPage>,
+) -> Result<()> {
+ let (meta, body) = match page_file::parse(&disk) {
+ Ok(parsed) => parsed,
+ Err(error) => {
+ plan.refused.push(Refusal {
+ path,
+ reason: format!("cannot import: {error:#}"),
+ });
+ return Ok(());
+ }
+ };
+ let expected_server = match current {
+ Some(page) => {
+ let lost = keys_an_import_would_clear(&page.frontmatter);
+ if !lost.is_empty() {
+ plan.refused.push(Refusal {
+ path,
+ reason: format!(
+ "cannot import: the server page carries metadata a write would clear \
+ ({}); edit it through ai-memory instead",
+ lost.join(", ")
+ ),
+ });
+ return Ok(());
+ }
+ Some(state::sha256_hex(sync::render_page(page)?.as_bytes()))
+ }
+ None => None,
+ };
+ plan.imports.push(Import {
+ path,
+ create,
+ meta,
+ body,
+ disk,
+ expected_server,
+ });
+ Ok(())
+}
+
+/// Every `.md` file under the allowlisted families. A symlink or a path the
+/// server could not hold is refused, never followed or guessed at.
+fn local_pages(
+ dest_root: &Path,
+ families: &[String],
+ refused: &mut Vec<Refusal>,
+) -> Result<Vec<String>> {
+ let mut found = Vec::new();
+ for family in families {
+ let mut pending = vec![(dest_root.join(family), family.clone())];
+ while let Some((dir, rel)) = pending.pop() {
+ let meta = match fs::symlink_metadata(&dir) {
+ Ok(meta) => meta,
+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue,
+ Err(e) => {
+ return Err(anyhow::Error::new(e))
+ .context(format!("cannot inspect {}", dir.display()));
+ }
+ };
+ if meta.file_type().is_symlink() {
+ refused.push(Refusal {
+ path: rel,
+ reason: "is a symlink; wikisync never follows one".to_string(),
+ });
+ continue;
+ }
+ if !meta.is_dir() {
+ continue;
+ }
+ for entry in
+ fs::read_dir(&dir).with_context(|| format!("cannot read {}", dir.display()))?
+ {
+ let entry = entry?;
+ let name = entry.file_name().to_string_lossy().into_owned();
+ // Hidden entries include this tool's own tmp files.
+ if name.starts_with('.') {
+ continue;
+ }
+ let child_rel = format!("{rel}/{name}");
+ let kind = entry.file_type()?;
+ if kind.is_symlink() {
+ refused.push(Refusal {
+ path: child_rel,
+ reason: "is a symlink; wikisync never follows one".to_string(),
+ });
+ } else if kind.is_dir() {
+ pending.push((entry.path(), child_rel));
+ } else if name.ends_with(".md") {
+ match paths::validate_page_path(&child_rel) {
+ Ok(()) => found.push(child_rel),
+ Err(error) => refused.push(Refusal {
+ path: child_rel,
+ reason: format!("cannot import: {error:#}"),
+ }),
+ }
+ }
+ if found.len() > MAX_PAGES {
+ bail!("more than {MAX_PAGES} local pages; narrow --include");
+ }
+ }
+ }
+ }
+ Ok(found)
+}
+
+/// Perform the imports, then the exports, then save the state once. The
+/// state is also saved when an import fails partway, so the pages already
+/// written are not re-classified as conflicts on the next run.
+async fn apply_plan(
+ api: &ApiClient,
+ mcp: &McpClient,
+ args: &RunArgs,
+ dest_root: &Path,
+ old_state: &SyncState,
+ plan: Plan,
+) -> Result<bool> {
+ let mut new_state = old_state.clone();
+ new_state.pages.extend(plan.adopted);
+ for path in &plan.forget {
+ new_state.pages.remove(path);
+ }
+ let mut wrote_files = false;
+ for import in &plan.imports {
+ match import_one(api, mcp, args, dest_root, import).await {
+ Ok((entry, normalised)) => {
+ wrote_files |= normalised;
+ new_state.pages.insert(import.path.clone(), entry);
+ }
+ Err(error) => {
+ state::save(dest_root, &new_state)?;
+ return Err(error.context(format!(
+ "import of {} failed; the pages imported before it are recorded",
+ import.path
+ )));
+ }
+ }
+ }
+ for export in &plan.exports {
+ sync::atomic_write(dest_root, &export.path, export.bytes.as_bytes())?;
+ wrote_files = true;
+ new_state.pages.insert(
+ export.path.clone(),
+ PageState {
+ hash: state::sha256_hex(export.bytes.as_bytes()),
+ etag: export.etag.clone(),
+ },
+ );
+ }
+ state::save(dest_root, &new_state)?;
+ Ok(wrote_files)
+}
+
+/// Re-check, write, read back. Returns the new state entry and whether the
+/// file was rewritten because the server stored something other than the
+/// file's bytes (the sanitizer redacting a secret, for example).
+async fn import_one(
+ api: &ApiClient,
+ mcp: &McpClient,
+ args: &RunArgs,
+ dest_root: &Path,
+ import: &Import,
+) -> Result<(PageState, bool)> {
+ let now = api
+ .read_page_if_exists(&args.workspace, &args.project, &import.path)
+ .await?;
+ match (&now, &import.expected_server) {
+ (Some(_), None) => bail!("{} was created on the server during this run", import.path),
+ (None, Some(_)) => bail!("{} was deleted on the server during this run", import.path),
+ (Some(page), Some(expected)) => {
+ if state::sha256_hex(sync::render_page(page)?.as_bytes()) != *expected {
+ bail!("{} changed on the server during this run", import.path);
+ }
+ let lost = keys_an_import_would_clear(&page.frontmatter);
+ if !lost.is_empty() {
+ bail!(
+ "{} gained metadata a write would clear during this run ({})",
+ import.path,
+ lost.join(", ")
+ );
+ }
+ }
+ (None, None) => {}
+ }
+ mcp.write_page(
+ &args.workspace,
+ &args.project,
+ &import.path,
+ &import.meta,
+ &import.body,
+ )
+ .await?;
+ let read = api
+ .read_page(&args.workspace, &args.project, &import.path, None)
+ .await?;
+ let page = read.page.with_context(|| {
+ format!(
+ "server returned no body for {} after the write",
+ import.path
+ )
+ })?;
+ let rendered = sync::render_page(&page)?;
+ let normalised = rendered.as_bytes() != import.disk.as_slice();
+ if normalised {
+ sync::atomic_write(dest_root, &import.path, rendered.as_bytes())?;
+ }
+ Ok((
+ PageState {
+ hash: state::sha256_hex(rendered.as_bytes()),
+ etag: read.etag,
+ },
+ normalised,
+ ))
+}
+
+fn print_plan(args: &RunArgs, families: &[String], plan: &Plan, apply: bool) {
+ println!(
+ "ai-memory-wikisync sync: {}/{} <-> {}",
+ args.workspace,
+ args.project,
+ args.dest.display()
+ );
+ println!(" allowlist: {}", families.join(", "));
+ for import in &plan.imports {
+ let kind = if import.create { "create" } else { "update" };
+ println!(" {:<9} {} (repo -> server, {kind})", "import", import.path);
+ }
+ for export in &plan.exports {
+ let kind = if export.create { "create" } else { "update" };
+ println!(" {:<9} {} (server -> repo, {kind})", "export", export.path);
+ }
+ for path in &plan.unchanged {
+ println!(" {:<9} {path}", "unchanged");
+ }
+ for (path, notice) in &plan.notices {
+ println!(" {:<9} {path} — {notice}", "notice");
+ }
+ for refusal in &plan.refused {
+ println!(" {:<9} {} — {}", "REFUSED", refusal.path, refusal.reason);
+ }
+ println!(
+ " sync: {} import, {} export, {} unchanged, {} notice, {} refused",
+ plan.imports.len(),
+ plan.exports.len(),
+ plan.unchanged.len(),
+ plan.notices.len(),
+ plan.refused.len()
+ );
+ if !apply {
+ println!(" dry run: nothing was written (pass --apply to sync)");
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use serde_json::json;
+
+ fn base(bytes: &[u8]) -> PageState {
+ PageState {
+ hash: state::sha256_hex(bytes),
+ etag: Some("\"e\"".to_string()),
+ }
+ }
+
+ #[test]
+ fn decide_three_way_matrix() {
+ let old = b"old".as_slice();
+ let repo = b"repo edit".as_slice();
+ let server = b"server edit".as_slice();
+ let rendered = ServerSide::Rendered;
+
+ // One side changed: the other side follows.
+ assert_eq!(
+ decide(Some(old), Some(&base(old)), rendered(server), None),
+ Action::Export { create: false }
+ );
+ assert_eq!(
+ decide(Some(repo), Some(&base(old)), rendered(old), None),
+ Action::Import { create: false }
+ );
+ assert_eq!(
+ decide(Some(repo), Some(&base(old)), ServerSide::NotModified, None),
+ Action::Import { create: false }
+ );
+ assert_eq!(
+ decide(Some(old), Some(&base(old)), ServerSide::NotModified, None),
+ Action::Unchanged
+ );
+
+ // Both changed: a conflict, unless --prefer picks a side.
+ assert_eq!(
+ decide(Some(repo), Some(&base(old)), rendered(server), None),
+ Action::Conflict
+ );
+ assert_eq!(
+ decide(
+ Some(repo),
+ Some(&base(old)),
+ rendered(server),
+ Some(Prefer::Repo)
+ ),
+ Action::Import { create: false }
+ );
+ assert_eq!(
+ decide(
+ Some(repo),
+ Some(&base(old)),
+ rendered(server),
+ Some(Prefer::Server)
+ ),
+ Action::Export { create: false }
+ );
+ // Both changed to the same bytes: nothing to do.
+ assert_eq!(
+ decide(Some(server), Some(&base(old)), rendered(server), None),
+ Action::Unchanged
+ );
+
+ // A file with no base that differs from the server is a conflict
+ // too: nothing says which side is newer.
+ assert_eq!(
+ decide(Some(repo), None, rendered(server), None),
+ Action::Conflict
+ );
+ assert_eq!(
+ decide(Some(server), None, rendered(server), None),
+ Action::Unchanged
+ );
+
+ // Creates come from whichever side has the page.
+ assert_eq!(
+ decide(None, None, rendered(server), None),
+ Action::Export { create: true }
+ );
+ assert_eq!(
+ decide(Some(repo), None, ServerSide::Absent, None),
+ Action::Import { create: true }
+ );
+
+ // Deletes are reported, never propagated, whatever --prefer says.
+ for prefer in [None, Some(Prefer::Repo), Some(Prefer::Server)] {
+ assert_eq!(
+ decide(Some(old), Some(&base(old)), ServerSide::Absent, prefer),
+ Action::DeletedOnServer
+ );
+ assert_eq!(
+ decide(None, Some(&base(old)), rendered(server), prefer),
+ Action::DeletedInRepo
+ );
+ assert_eq!(
+ decide(None, Some(&base(old)), ServerSide::NotModified, prefer),
+ Action::DeletedInRepo
+ );
+ assert_eq!(
+ decide(None, Some(&base(old)), ServerSide::Absent, prefer),
+ Action::GoneOnBothSides
+ );
+ }
+ }
+
+ #[test]
+ fn metadata_an_import_would_clear_is_named() {
+ let written_by_mcp = json!({
+ "title": "T", "tier": "semantic", "pinned": true, "tags": ["a"],
+ "type": "Rule", "generated": {"by": "x"}, "last_modified_by": "u"
+ });
+ assert!(keys_an_import_would_clear(&written_by_mcp).is_empty());
+ let consolidated = json!({"title": "T", "summary": "s", "sources": [], "kind": "k"});
+ assert_eq!(
+ keys_an_import_would_clear(&consolidated),
+ vec!["kind", "sources", "summary"]
+ );
+ assert!(keys_an_import_would_clear(&json!(null)).is_empty());
+ }
+}
diff --git a/companions/ai-memory-wikisync/src/client.rs b/companions/ai-memory-wikisync/src/client.rs
index 5e70d227..4099ed4e 100644
--- a/companions/ai-memory-wikisync/src/client.rs
+++ b/companions/ai-memory-wikisync/src/client.rs
@@ -38,12 +38,23 @@ pub struct PageSummary {
}
/// The canonical single-page projection. Only the fields this tool
-/// transports are decoded; everything else the server returns is ignored
-/// rather than stored, and nothing is forged locally.
+/// transports, or checks before an import, are decoded; everything else the
+/// server returns is ignored rather than stored, and nothing is forged
+/// locally.
#[derive(Debug, Clone, Deserialize)]
pub struct ApiPage {
pub path: String,
pub body_markdown: String,
+ #[serde(default)]
+ pub title: String,
+ #[serde(default)]
+ pub tier: String,
+ #[serde(default)]
+ pub pinned: bool,
+ /// The page's parsed frontmatter: `tags` live here, and so does any
+ /// metadata an import would clear.
+ #[serde(default)]
+ pub frontmatter: serde_json::Value,
}
/// Result of one page read: the body on `200`, or `None` on `304 Not
@@ -145,24 +156,47 @@ impl ApiClient {
.send()
.await
.map_err(|e| anyhow!("request to {} failed: {e}", url.as_str()))?;
- match response.status() {
- StatusCode::OK | StatusCode::NOT_MODIFIED => Ok(response),
- StatusCode::UNAUTHORIZED => bail!(
- "GET {} returned 401 Unauthorized — the server requires a bearer token \
- (pass --token or set AI_MEMORY_AUTH_TOKEN)",
- url.as_str()
- ),
- StatusCode::FORBIDDEN => bail!(
- "GET {} returned 403 Forbidden — the token was rejected, the caller lacks \
- access to this scope, or the server's host allowlist refused the request",
- url.as_str()
- ),
- StatusCode::NOT_FOUND => bail!(
- "GET {} returned 404 Not Found — {not_found_hint}",
+ check_status(response, url, not_found_hint)
+ }
+
+ /// Read one full page, or `None` when the server has no such page. Used
+ /// right before an import, where absence is an answer, not an error.
+ pub async fn read_page_if_exists(
+ &self,
+ workspace: &str,
+ project: &str,
+ path: &str,
+ ) -> Result<Option<ApiPage>> {
+ let tail: Vec<&str> = path.split('/').collect();
+ let url = self.build_page_url(workspace, project, &tail)?;
+ let mut request = self
+ .http
+ .get(url.clone())
+ .header(reqwest::header::ACCEPT, "application/json");
+ if let Some(token) = &self.token {
+ request = request.bearer_auth(token);
+ }
+ let response = request
+ .send()
+ .await
+ .map_err(|e| anyhow!("request to {} failed: {e}", url.as_str()))?;
+ if response.status() == StatusCode::NOT_FOUND {
+ return Ok(None);
+ }
+ let response = check_status(response, &url, "")?;
+ let page: ApiPage = response.json().await.map_err(|e| {
+ anyhow!(
+ "page read from {} returned malformed JSON: {e}",
url.as_str()
- ),
- status => bail!("GET {} returned unexpected status {status}", url.as_str()),
+ )
+ })?;
+ if page.path != path {
+ bail!(
+ "server answered a read of {path:?} with page {:?}; refusing the mismatch",
+ page.path
+ );
}
+ Ok(Some(page))
}
/// List the project's latest pages via incremental `recent` paging from
@@ -292,6 +326,31 @@ impl ApiClient {
}
}
+fn check_status(
+ response: reqwest::Response,
+ url: &Url,
+ not_found_hint: &str,
+) -> Result<reqwest::Response> {
+ match response.status() {
+ StatusCode::OK | StatusCode::NOT_MODIFIED => Ok(response),
+ StatusCode::UNAUTHORIZED => bail!(
+ "GET {} returned 401 Unauthorized — the server requires a bearer token \
+ (pass --token or set AI_MEMORY_AUTH_TOKEN)",
+ url.as_str()
+ ),
+ StatusCode::FORBIDDEN => bail!(
+ "GET {} returned 403 Forbidden — the token was rejected, the caller lacks \
+ access to this scope, or the server's host allowlist refused the request",
+ url.as_str()
+ ),
+ StatusCode::NOT_FOUND => bail!(
+ "GET {} returned 404 Not Found — {not_found_hint}",
+ url.as_str()
+ ),
+ status => bail!("GET {} returned unexpected status {status}", url.as_str()),
+ }
+}
+
/// Small helper so the client builder error reads like the others.
trait ContextBuild {
fn context_build(self) -> Result<reqwest::Client>;
diff --git a/companions/ai-memory-wikisync/src/lib.rs b/companions/ai-memory-wikisync/src/lib.rs
index 27f478d6..edca1785 100644
--- a/companions/ai-memory-wikisync/src/lib.rs
+++ b/companions/ai-memory-wikisync/src/lib.rs
@@ -1,16 +1,20 @@
-//! `ai-memory-wikisync`: read-only team-wiki export companion (#986, slice 1).
+//! `ai-memory-wikisync`: team-wiki sync companion (#986, slices 1 and 3).
//!
-//! Pulls explicitly allowlisted page families from a running ai-memory server
-//! through the public, read-only `/api/v1` surface into a directory inside a
-//! project repository. The tool never mutates the server, never deletes local
-//! files (deletes are slice 4), never forges page frontmatter, and never runs
-//! git on the operator's behalf.
+//! Keeps explicitly allowlisted page families of a running ai-memory server
+//! in step with a directory inside a project repository. Reads go through
+//! the public, read-only `/api/v1` surface; the only write to the server is
+//! the public `memory_write_page` MCP tool, used by `sync`. The tool never
+//! opens the wiki directory or SQLite, never deletes (deletes are slice 4),
+//! and never runs git on the operator's behalf.
//!
//! Page bodies are untrusted data: they are transported verbatim into files
//! whose validated paths cannot escape the destination directory, and are
//! never executed or rendered.
+pub mod bidi;
pub mod client;
+pub mod mcp;
+pub mod page_file;
pub mod paths;
pub mod state;
pub mod sync;
diff --git a/companions/ai-memory-wikisync/src/main.rs b/companions/ai-memory-wikisync/src/main.rs
index ea6bb2ba..d0ade109 100644
--- a/companions/ai-memory-wikisync/src/main.rs
+++ b/companions/ai-memory-wikisync/src/main.rs
@@ -2,15 +2,16 @@
use std::path::PathBuf;
+use ai_memory_wikisync::bidi::{self, Prefer, SyncArgs};
use ai_memory_wikisync::client::DEFAULT_SERVER_URL;
use ai_memory_wikisync::sync::{Mode, RunArgs, run};
-use clap::{Parser, Subcommand};
+use clap::{Parser, Subcommand, ValueEnum};
#[derive(Parser, Debug)]
#[command(
author,
version,
- about = "Read-only team-wiki export companion for ai-memory (#986, slice 1)"
+ about = "Team-wiki sync companion for ai-memory (#986): export and two-way sync"
)]
struct Cli {
#[command(subcommand)]
@@ -24,6 +25,28 @@ enum Commands {
Plan(CommonArgs),
/// Export pages into --dest. Dry-run unless --apply is passed.
Export(ExportArgs),
+ /// Sync both ways: repository edits go to the server through MCP,
+ /// server edits come to --dest. Dry-run unless --apply is passed.
+ Sync(SyncCliArgs),
+}
+
+#[derive(Parser, Debug, Clone)]
+struct SyncCliArgs {
+ /// Perform the writes. Without it, sync stays a dry-run.
+ #[arg(long)]
+ apply: bool,
+ /// Which side wins a page changed in the repository and on the server.
+ /// Without it, such a page is a conflict and nothing is written.
+ #[arg(long, value_enum)]
+ prefer: Option<PreferArg>,
+ #[command(flatten)]
+ common: CommonArgs,
+}
+
+#[derive(ValueEnum, Debug, Clone, Copy)]
+enum PreferArg {
+ Repo,
+ Server,
}
#[derive(Parser, Debug, Clone)]
@@ -89,6 +112,18 @@ impl From<CommonArgs> for RunArgs {
}
}
+impl From<SyncCliArgs> for SyncArgs {
+ fn from(args: SyncCliArgs) -> Self {
+ Self {
+ run: RunArgs::from(args.common),
+ prefer: args.prefer.map(|prefer| match prefer {
+ PreferArg::Repo => Prefer::Repo,
+ PreferArg::Server => Prefer::Server,
+ }),
+ }
+ }
+}
+
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let cli = Cli::parse();
@@ -102,6 +137,10 @@ async fn main() -> anyhow::Result<()> {
};
run(&RunArgs::from(args), mode).await
}
+ Commands::Sync(args) => {
+ let apply = args.apply;
+ bidi::run(&SyncArgs::from(args), apply).await
+ }
}
}
diff --git a/companions/ai-memory-wikisync/src/mcp.rs b/companions/ai-memory-wikisync/src/mcp.rs
new file mode 100644
index 00000000..870ef797
--- /dev/null
+++ b/companions/ai-memory-wikisync/src/mcp.rs
@@ -0,0 +1,160 @@
+//! The only write seam: the public `memory_write_page` MCP tool.
+//!
+//! Imports never touch the wiki directory or SQLite. They call the same tool
+//! an agent calls, so sanitization, admission, attribution and scope
+//! resolution all apply. The request carries `workspace` and `project`
+//! explicitly on every call; this companion has no session to route by.
+
+use std::time::Duration;
+
+use anyhow::{Result, anyhow, bail};
+use serde_json::{Value, json};
+use url::Url;
+
+use crate::page_file::PageMeta;
+
+const REQUEST_TIMEOUT: Duration = Duration::from_secs(30);
+/// Bound on a tool error echoed to the terminal.
+const ERROR_PREVIEW: usize = 300;
+
+pub struct McpClient {
+ http: reqwest::Client,
+ url: Url,
+ token: Option<String>,
+}
+
+impl McpClient {
+ /// `server` is the origin `ApiClient::new` already validated.
+ pub fn new(server: &str, token: Option<String>) -> Result<Self> {
+ let mut url =
+ Url::parse(server).map_err(|e| anyhow!("invalid --server {server:?}: {e}"))?;
+ url.set_path("/mcp");
+ let http = reqwest::Client::builder()
+ .timeout(REQUEST_TIMEOUT)
+ .build()
+ .map_err(|e| anyhow!("cannot build HTTP client: {e}"))?;
+ Ok(Self { http, url, token })
+ }
+
+ /// Replace (or create) one page with exactly `meta` and `body`. The
+ /// tool clears whatever the call omits, which is why every field the
+ /// file carries is sent, defaults included.
+ pub async fn write_page(
+ &self,
+ workspace: &str,
+ project: &str,
+ path: &str,
+ meta: &PageMeta,
+ body: &str,
+ ) -> Result<()> {
+ let mut arguments = json!({
+ "workspace": workspace,
+ "project": project,
+ "path": path,
+ "body": body,
+ "tags": meta.tags,
+ "pinned": meta.pinned,
+ });
+ if let Some(title) = &meta.title {
+ arguments["title"] = json!(title);
+ }
+ if let Some(tier) = &meta.tier {
+ arguments["tier"] = json!(tier);
+ }
+ self.call_tool("memory_write_page", arguments).await
+ }
+
+ async fn call_tool(&self, name: &str, arguments: Value) -> Result<()> {
+ let request = json!({
+ "jsonrpc": "2.0",
+ "id": 1,
+ "method": "tools/call",
+ "params": {"name": name, "arguments": arguments},
+ });
+ let mut builder = self
+ .http
+ .post(self.url.clone())
+ // The streamable HTTP transport refuses a request that does not
+ // accept both; it answers plain JSON in its default stateless
+ // mode and SSE frames in stateful mode.
+ .header(
+ reqwest::header::ACCEPT,
+ "application/json, text/event-stream",
+ )
+ .json(&request);
+ if let Some(token) = &self.token {
+ builder = builder.bearer_auth(token);
+ }
+ let response = builder
+ .send()
+ .await
+ .map_err(|e| anyhow!("MCP {name} request to {} failed: {e}", self.url))?;
+ let status = response.status();
+ let text = response
+ .text()
+ .await
+ .map_err(|e| anyhow!("reading the MCP {name} response failed: {e}"))?;
+ if !status.is_success() {
+ bail!("MCP {name} returned HTTP {status}: {}", preview(&text));
+ }
+ let message = json_rpc_message(&text)
+ .ok_or_else(|| anyhow!("MCP {name} answered with no JSON-RPC message"))?;
+ if let Some(error) = message.get("error") {
+ bail!("MCP {name} failed: {}", preview(&error.to_string()));
+ }
+ let result = message
+ .get("result")
+ .ok_or_else(|| anyhow!("MCP {name} answered with no result"))?;
+ if result.get("isError").and_then(Value::as_bool) == Some(true) {
+ let detail = result
+ .pointer("/content/0/text")
+ .and_then(Value::as_str)
+ .unwrap_or("no detail");
+ bail!("MCP {name} refused the write: {}", preview(detail));
+ }
+ Ok(())
+ }
+}
+
+/// The JSON-RPC message in a response body: the body itself, or the last
+/// `data:` frame of an SSE stream.
+fn json_rpc_message(text: &str) -> Option<Value> {
+ if let Ok(value) = serde_json::from_str::<Value>(text) {
+ return Some(value);
+ }
+ text.lines()
+ .filter_map(|line| line.strip_prefix("data:"))
+ .filter_map(|data| serde_json::from_str::<Value>(data.trim()).ok())
+ .next_back()
+}
+
+/// Server text is untrusted: bound it and neutralise control characters so
+/// it cannot drive the terminal.
+fn preview(text: &str) -> String {
+ text.chars()
+ .take(ERROR_PREVIEW)
+ .map(|c| if c.is_control() { '?' } else { c })
+ .collect()
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn reads_plain_json_and_sse_frames() {
+ let plain = r#"{"jsonrpc":"2.0","id":1,"result":{"isError":false}}"#;
+ assert_eq!(json_rpc_message(plain).unwrap()["id"], 1);
+ let sse = "event: message\ndata: {\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{}}\n\n";
+ assert!(json_rpc_message(sse).unwrap().get("result").is_some());
+ assert!(json_rpc_message("event: ping\n\n").is_none());
+ }
+
+ #[test]
+ fn previews_are_bounded_and_inert() {
+ let hostile = format!("\u{1b}[31m{}", "x".repeat(1_000));
+ let shown = preview(&hostile);
+ assert!(!shown.contains('\u{1b}'));
+ assert_eq!(shown.chars().count(), ERROR_PREVIEW);
+ }
+}
diff --git a/companions/ai-memory-wikisync/src/page_file.rs b/companions/ai-memory-wikisync/src/page_file.rs
new file mode 100644
index 00000000..863ca536
--- /dev/null
+++ b/companions/ai-memory-wikisync/src/page_file.rs
@@ -0,0 +1,263 @@
+//! The on-disk page format: a small, fixed frontmatter plus the verbatim
+//! server body.
+//!
+//! `memory_write_page` replaces a whole page and clears every field the call
+//! omits, so a file must carry the metadata an import sends back. Only the
+//! fields that write accepts and this tool round-trips appear: `title`,
+//! `tags`, `pinned`, and `tier` when it is not the server default. Values
+//! are JSON scalars and arrays, which are also valid YAML, so a reviewer
+//! reads plain YAML and the parser stays strict and dependency-free.
+
+use anyhow::{Result, bail};
+use serde_json::Value;
+
+/// The tier `memory_write_page` assigns when the call omits one.
+pub const DEFAULT_TIER: &str = "semantic";
+const FENCE: &str = "---";
+
+/// Page metadata a file carries and an import sends back.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct PageMeta {
+ pub title: Option<String>,
+ pub tags: Vec<String>,
+ pub pinned: bool,
+ /// `None` means the server default ([`DEFAULT_TIER`]).
+ pub tier: Option<String>,
+}
+
+impl PageMeta {
+ /// Metadata of a server page, normalised so a default tier and an empty
+ /// title are omitted rather than written.
+ pub fn from_server(title: &str, tier: &str, pinned: bool, frontmatter: &Value) -> Self {
+ let tags = frontmatter
+ .get("tags")
+ .and_then(Value::as_array)
+ .map(|tags| {
+ tags.iter()
+ .filter_map(Value::as_str)
+ .map(str::to_owned)
+ .collect()
+ })
+ .unwrap_or_default();
+ Self {
+ title: (!title.is_empty()).then(|| title.to_owned()),
+ tags,
+ pinned,
+ tier: (!tier.is_empty() && tier != DEFAULT_TIER).then(|| tier.to_owned()),
+ }
+ }
+}
+
+/// Render the file for a page: frontmatter, then the body byte for byte.
+pub fn render(meta: &PageMeta, body: &str) -> String {
+ let mut out = String::with_capacity(body.len() + 128);
+ out.push_str(FENCE);
+ out.push('\n');
+ if let Some(title) = &meta.title {
+ out.push_str("title: ");
+ out.push_str(&json_string(title));
+ out.push('\n');
+ }
+ if !meta.tags.is_empty() {
+ let tags: Vec<String> = meta.tags.iter().map(|tag| json_string(tag)).collect();
+ out.push_str("tags: [");
+ out.push_str(&tags.join(", "));
+ out.push_str("]\n");
+ }
+ if meta.pinned {
+ out.push_str("pinned: true\n");
+ }
+ if let Some(tier) = &meta.tier {
+ out.push_str("tier: ");
+ out.push_str(&json_string(tier));
+ out.push('\n');
+ }
+ out.push_str(FENCE);
+ out.push('\n');
+ out.push_str(body);
+ out
+}
+
+fn json_string(value: &str) -> String {
+ Value::String(value.to_owned()).to_string()
+}
+
+/// Parse a file this tool wrote, or a reviewer edited, back into metadata
+/// and body. Strict on purpose: an import replaces the whole server page,
+/// so a key this tool does not understand is refused rather than dropped.
+/// Plain (unquoted) scalars are accepted for `title` and `tier`, the shape a
+/// person editing YAML by hand most often writes.
+pub fn parse(bytes: &[u8]) -> Result<(PageMeta, String)> {
+ let Ok(text) = std::str::from_utf8(bytes) else {
+ bail!("file is not valid UTF-8");
+ };
+ let mut lines = text.split_inclusive('\n');
+ let opening = lines.next().unwrap_or_default();
+ if trim_eol(opening) != FENCE {
+ bail!(
+ "file has no frontmatter; an import needs it, because the server clears \
+ any title, tags or pin the write omits"
+ );
+ }
+ let mut consumed = opening.len();
+ let mut meta = PageMeta::default();
+ let mut seen: Vec<&str> = Vec::new();
+ let mut closed = false;
+ for line in lines {
+ consumed += line.len();
+ let line = trim_eol(line);
+ if line == FENCE {
+ closed = true;
+ break;
+ }
+ if line.trim().is_empty() {
+ continue;
+ }
+ let Some((key, value)) = line.split_once(':') else {
+ bail!("frontmatter line {line:?} is not `key: value`");
+ };
+ let key = key.trim();
+ let value = value.trim();
+ if seen.contains(&key) {
+ bail!("frontmatter key {key:?} appears twice");
+ }
+ match key {
+ "title" => meta.title = Some(scalar(key, value)?),
+ "tier" => meta.tier = Some(scalar(key, value)?).filter(|tier| tier != DEFAULT_TIER),
+ "pinned" => {
+ meta.pinned = match value {
+ "true" => true,
+ "false" => false,
+ _ => bail!("frontmatter `pinned` must be true or false, not {value:?}"),
+ }
+ }
+ "tags" => meta.tags = tags(value)?,
+ _ => bail!(
+ "frontmatter key {key:?} is not one wikisync round-trips \
+ (title, tags, pinned, tier); remove it before importing"
+ ),
+ }
+ seen.push(key);
+ }
+ if !closed {
+ bail!("frontmatter is not closed by a `---` line");
+ }
+ Ok((meta, text[consumed..].to_owned()))
+}
+
+fn trim_eol(line: &str) -> &str {
+ line.strip_suffix('\n')
+ .map(|line| line.strip_suffix('\r').unwrap_or(line))
+ .unwrap_or(line)
+}
+
+fn scalar(key: &str, value: &str) -> Result<String> {
+ let parsed = if value.starts_with('"') {
+ match serde_json::from_str::<Value>(value) {
+ Ok(Value::String(text)) => text,
+ _ => bail!("frontmatter `{key}` is not a valid double-quoted string: {value}"),
+ }
+ } else if value.starts_with(['\'', '[', '{', '|', '>', '&', '*', '!']) {
+ bail!("frontmatter `{key}` must be plain text or a double-quoted string");
+ } else {
+ value.to_owned()
+ };
+ if parsed.trim().is_empty() || parsed.contains(['\n', '\r']) {
+ bail!("frontmatter `{key}` must be one non-empty line");
+ }
+ Ok(parsed)
+}
+
+fn tags(value: &str) -> Result<Vec<String>> {
+ let Ok(Value::Array(items)) = serde_json::from_str::<Value>(value) else {
+ bail!("frontmatter `tags` must be a list of double-quoted strings, like [\"db\", \"ops\"]");
+ };
+ items
+ .into_iter()
+ .map(|item| match item {
+ Value::String(tag) if !tag.trim().is_empty() => Ok(tag),
+ other => bail!("frontmatter tag {other} is not a non-empty string"),
+ })
+ .collect()
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use serde_json::json;
+
+ fn meta() -> PageMeta {
+ PageMeta {
+ title: Some("Use \"Postgres\": ação".to_string()),
+ tags: vec!["db".to_string(), "ops".to_string()],
+ pinned: true,
+ tier: Some("episodic".to_string()),
+ }
+ }
+
+ #[test]
+ fn render_then_parse_round_trips_metadata_and_body() {
+ let body = "# Use Postgres\n\n---\nA rule line inside the body.\n";
+ let rendered = render(&meta(), body);
+ assert!(rendered.starts_with("---\ntitle: "), "{rendered}");
+ let (parsed, parsed_body) = parse(rendered.as_bytes()).unwrap();
+ assert_eq!(parsed, meta());
+ assert_eq!(parsed_body, body);
+ }
+
+ #[test]
+ fn defaults_are_omitted_from_the_file() {
+ let plain = PageMeta {
+ title: Some("T".to_string()),
+ ..PageMeta::default()
+ };
+ assert_eq!(render(&plain, "# T\n"), "---\ntitle: \"T\"\n---\n# T\n");
+ let server = PageMeta::from_server("T", DEFAULT_TIER, false, &json!({"tier": "semantic"}));
+ assert_eq!(server, plain);
+ let tagged = PageMeta::from_server("T", "episodic", true, &json!({"tags": ["a", 1, "b"]}));
+ assert_eq!(tagged.tags, vec!["a".to_string(), "b".to_string()]);
+ assert_eq!(tagged.tier.as_deref(), Some("episodic"));
+ }
+
+ #[test]
+ fn hand_edited_yaml_is_accepted_when_unambiguous() {
+ let file = "---\r\ntitle: Plain title\r\n\r\ntier: semantic\r\npinned: false\r\ntags: []\r\n---\r\nbody\r\n";
+ let (meta, body) = parse(file.as_bytes()).unwrap();
+ assert_eq!(meta.title.as_deref(), Some("Plain title"));
+ assert_eq!(meta.tier, None, "the default tier normalises away");
+ assert!(meta.tags.is_empty() && !meta.pinned);
+ assert_eq!(body, "body\r\n");
+ }
+
+ #[test]
+ fn anything_an_import_could_lose_is_refused() {
+ for (file, needle) in [
+ ("# no frontmatter\n", "no frontmatter"),
+ (
+ "---\ntitle: \"T\"\nbody without a closing fence\n",
+ "not `key: value`",
+ ),
+ ("---\ntitle: \"T\"\n", "not closed"),
+ ("---\nsummary: \"x\"\n---\n", "not one wikisync round-trips"),
+ ("---\ntitle: \"a\"\ntitle: \"b\"\n---\n", "twice"),
+ ("---\npinned: yes\n---\n", "true or false"),
+ ("---\ntags: db, ops\n---\n", "list of double-quoted"),
+ ("---\ntags: [\"\"]\n---\n", "non-empty string"),
+ (
+ "---\ntitle: 'single'\n---\n",
+ "plain text or a double-quoted",
+ ),
+ ("---\ntitle: \"\"\n---\n", "non-empty line"),
+ ("---\ntitle: \"a\\nb\"\n---\n", "non-empty line"),
+ ] {
+ let err = parse(file.as_bytes()).unwrap_err().to_string();
+ assert!(err.contains(needle), "{file:?}: {err}");
+ }
+ assert!(
+ parse(&[0xff, 0xfe])
+ .unwrap_err()
+ .to_string()
+ .contains("UTF-8")
+ );
+ }
+}
diff --git a/companions/ai-memory-wikisync/src/paths.rs b/companions/ai-memory-wikisync/src/paths.rs
index 0f0d0cbf..5bad7db8 100644
--- a/companions/ai-memory-wikisync/src/paths.rs
+++ b/companions/ai-memory-wikisync/src/paths.rs
@@ -1,4 +1,4 @@
-//! Destination-path safety for the read-only export.
+//! Destination-path safety for export and sync.
//!
//! Page paths arrive from the server as untrusted data. Every relative wiki
//! path is validated into a portable shape before it is ever joined onto the
diff --git a/companions/ai-memory-wikisync/src/sync.rs b/companions/ai-memory-wikisync/src/sync.rs
index 5b526744..e0a1b479 100644
--- a/companions/ai-memory-wikisync/src/sync.rs
+++ b/companions/ai-memory-wikisync/src/sync.rs
@@ -14,7 +14,8 @@ use std::path::{Path, PathBuf};
use anyhow::{Context, Result, bail};
-use crate::client::{ApiClient, PageSummary};
+use crate::client::{ApiClient, ApiPage, PageSummary};
+use crate::page_file::{self, PageMeta};
use crate::paths;
use crate::state::{self, PageState, SyncState};
use crate::{MAX_BODY_BYTES, MAX_PAGES};
@@ -47,8 +48,6 @@ pub enum DivergentReason {
LocalEdit,
/// Present on disk but never written by this tool.
UnknownFile,
- /// Begins with a YAML frontmatter delimiter this tool never writes.
- LocalFrontmatter,
}
impl DivergentReason {
@@ -56,10 +55,6 @@ impl DivergentReason {
match self {
Self::LocalEdit => "edited locally since the last export",
Self::UnknownFile => "exists on disk but was never written by wikisync",
- Self::LocalFrontmatter => {
- "edited locally since the last export (file begins with a YAML \
- frontmatter delimiter; wikisync never writes frontmatter)"
- }
}
}
}
@@ -166,14 +161,23 @@ pub fn classify(
Some(_) => Classification::Write(WriteKind::Update),
},
(Some(_), None) => Classification::Divergent(DivergentReason::UnknownFile),
- (Some(disk), Some(_)) => {
- if disk.starts_with(b"---") {
- Classification::Divergent(DivergentReason::LocalFrontmatter)
- } else {
- Classification::Divergent(DivergentReason::LocalEdit)
- }
- }
+ (Some(_), Some(_)) => Classification::Divergent(DivergentReason::LocalEdit),
+ }
+}
+
+/// The file bytes for a server page: its round-trippable metadata as
+/// frontmatter, then the body verbatim. Export and sync write the same
+/// bytes, so the two never disagree about whether a file is current.
+pub fn render_page(page: &ApiPage) -> Result<String> {
+ if page.body_markdown.len() > MAX_BODY_BYTES {
+ bail!(
+ "page {} is {} bytes; refusing bodies over {MAX_BODY_BYTES} bytes",
+ page.path,
+ page.body_markdown.len()
+ );
}
+ let meta = PageMeta::from_server(&page.title, &page.tier, page.pinned, &page.frontmatter);
+ Ok(page_file::render(&meta, &page.body_markdown))
}
/// Bounded, printable diff summary for a divergent file: sizes, line counts
@@ -303,7 +307,7 @@ pub fn select_pages(summaries: Vec<PageSummary>, families: &[String]) -> Result<
Ok(selected)
}
-fn read_disk(dest_root: &Path, path: &str) -> Result<Option<Vec<u8>>> {
+pub(crate) fn read_disk(dest_root: &Path, path: &str) -> Result<Option<Vec<u8>>> {
let target = paths::secure_join(dest_root, path)?;
match fs::read(&target) {
Ok(bytes) => Ok(Some(bytes)),
@@ -346,16 +350,7 @@ async fn run_batch(
let read = client
.read_page(&args.workspace, &args.project, &page.path, etag_hint)
.await?;
- let mut body = read.page.map(|api_page| api_page.body_markdown);
- if let Some(body) = body.as_ref()
- && body.len() > MAX_BODY_BYTES
- {
- bail!(
- "page {} is {} bytes; refusing bodies over {MAX_BODY_BYTES} bytes",
- page.path,
- body.len()
- );
- }
+ let mut body = read.page.as_ref().map(render_page).transpose()?;
let mut decision = classify(
disk.as_deref(),
base,
@@ -367,16 +362,7 @@ async fn run_batch(
let refetch = client
.read_page(&args.workspace, &args.project, &page.path, None)
.await?;
- body = refetch.page.map(|api_page| api_page.body_markdown);
- if let Some(body) = body.as_ref()
- && body.len() > MAX_BODY_BYTES
- {
- bail!(
- "page {} is {} bytes; refusing bodies over {MAX_BODY_BYTES} bytes",
- page.path,
- body.len()
- );
- }
+ body = refetch.page.as_ref().map(render_page).transpose()?;
decision = classify(
disk.as_deref(),
base,
@@ -545,7 +531,7 @@ fn print_report(args: &RunArgs, report: &Report, mode: Mode, families: &[String]
}
}
-fn print_git_hints(args: &RunArgs) {
+pub(crate) fn print_git_hints(args: &RunArgs) {
println!(
"this tool never runs git; to commit the export you may run:\
\n git add -- {}\
@@ -560,7 +546,7 @@ fn print_git_hints(args: &RunArgs) {
/// Validate the destination root. `Apply` creates a missing directory;
/// dry-run modes never touch the filesystem, so for them a missing
/// destination is simply an empty destination (validated only lexically).
-fn resolve_dest(dest: &Path, mode: Mode) -> Result<PathBuf> {
+pub(crate) fn resolve_dest(dest: &Path, mode: Mode) -> Result<PathBuf> {
match mode {
Mode::Apply => paths::prepare_dest(dest),
Mode::Plan | Mode::DryRun => {
@@ -659,13 +645,6 @@ mod tests {
classify(Some(edited), None, Some(server)),
Classification::Divergent(DivergentReason::UnknownFile)
);
- // Frontmatter this tool never wrote reads as a local edit with a
- // specific reason.
- let with_fm = b"---\ntitle: forged\n---\n# page\n";
- assert_eq!(
- classify(Some(with_fm), Some(&base(&disk_hash, None)), Some(server)),
- Classification::Divergent(DivergentReason::LocalFrontmatter)
- );
}
#[test]
diff --git a/companions/ai-memory-wikisync/tests/api_server.rs b/companions/ai-memory-wikisync/tests/api_server.rs
index fdd06942..9124cf9e 100644
--- a/companions/ai-memory-wikisync/tests/api_server.rs
+++ b/companions/ai-memory-wikisync/tests/api_server.rs
@@ -6,43 +6,89 @@ use std::collections::BTreeMap;
use std::fs;
use std::net::SocketAddr;
use std::path::PathBuf;
-use std::sync::Arc;
use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::{Arc, Mutex};
+use ai_memory_wikisync::bidi::{self, Prefer, SyncArgs};
use ai_memory_wikisync::state::{self, SyncState};
use ai_memory_wikisync::sync::{Mode, RunArgs, run};
use axum::extract::{Path, Query, State};
use axum::http::{HeaderMap, StatusCode, header};
use axum::response::IntoResponse;
-use axum::routing::get;
+use axum::routing::{get, post};
use axum::{Json, Router};
use serde_json::json;
use tokio::net::TcpListener;
+/// One fixture page: what the real server's page read returns, reduced to
+/// the fields wikisync reads.
+#[derive(Clone)]
+struct FixturePage {
+ path: String,
+ body: String,
+ title: String,
+ tier: String,
+ pinned: bool,
+ frontmatter: serde_json::Value,
+}
+
+impl FixturePage {
+ fn new(path: &str, body: &str) -> Self {
+ Self {
+ path: path.to_string(),
+ body: body.to_string(),
+ title: format!("title {path}"),
+ tier: "semantic".to_string(),
+ pinned: false,
+ frontmatter: json!({}),
+ }
+ }
+}
+
/// Fixture server state: pages, optional bearer token, call counters.
struct Fixture {
- /// (path, body) in listing order.
- pages: Vec<(String, String)>,
+ /// Pages in listing order.
+ pages: Mutex<Vec<FixturePage>>,
token: Option<&'static str>,
project_exists: bool,
/// Page advertised by the listing but missing on read, to simulate a
/// delete/expiry racing the run.
unreachable: Option<&'static str>,
+ /// Rewrite this page's body on its Nth read (1-based), to simulate an
+ /// edit landing between a sync's classification and its write.
+ edit_on_read: Option<(&'static str, usize)>,
+ /// Text the fixture's write path redacts, like the server's sanitizer.
+ redact: Option<&'static str>,
+ reads_by_path: Mutex<BTreeMap<String, usize>>,
recent_calls: AtomicUsize,
page_reads_200: AtomicUsize,
page_reads_304: AtomicUsize,
+ mcp_writes: AtomicUsize,
}
impl Fixture {
fn new(pages: Vec<(String, String)>) -> Self {
+ Self::with_pages(
+ pages
+ .iter()
+ .map(|(path, body)| FixturePage::new(path, body))
+ .collect(),
+ )
+ }
+
+ fn with_pages(pages: Vec<FixturePage>) -> Self {
Self {
- pages,
+ pages: Mutex::new(pages),
token: None,
project_exists: true,
unreachable: None,
+ edit_on_read: None,
+ redact: None,
+ reads_by_path: Mutex::new(BTreeMap::new()),
recent_calls: AtomicUsize::new(0),
page_reads_200: AtomicUsize::new(0),
page_reads_304: AtomicUsize::new(0),
+ mcp_writes: AtomicUsize::new(0),
}
}
@@ -61,11 +107,26 @@ impl Fixture {
self
}
- fn body_of(&self, path: &str) -> Option<&str> {
+ fn page(&self, path: &str) -> Option<FixturePage> {
self.pages
+ .lock()
+ .unwrap()
.iter()
- .find(|(candidate, _)| candidate == path)
- .map(|(_, body)| body.as_str())
+ .find(|page| page.path == path)
+ .cloned()
+ }
+
+ fn update(&self, path: &str, edit: impl FnOnce(&mut FixturePage)) {
+ let mut pages = self.pages.lock().unwrap();
+ let page = pages
+ .iter_mut()
+ .find(|page| page.path == path)
+ .expect("fixture page");
+ edit(page);
+ }
+
+ fn remove(&self, path: &str) {
+ self.pages.lock().unwrap().retain(|page| page.path != path);
}
fn authorize(&self, headers: &HeaderMap) -> Result<(), Box<axum::response::Response>> {
@@ -111,21 +172,22 @@ async fn recent_handler(
.and_then(|value| value.strip_prefix("idx:"))
.and_then(|value| value.parse().ok())
.unwrap_or(0);
- let end = (start + 2).min(fixture.pages.len());
- let pages: Vec<serde_json::Value> = fixture.pages[start..end]
+ let all = fixture.pages.lock().unwrap().clone();
+ let end = (start + 2).min(all.len());
+ let pages: Vec<serde_json::Value> = all[start..end]
.iter()
.enumerate()
- .map(|(offset, (path, _))| {
+ .map(|(offset, page)| {
json!({
- "path": path,
- "title": format!("title {path}"),
+ "path": page.path,
+ "title": page.title,
"kind": "note",
"tier": "semantic",
"updated_at": format!("2026-10-0{}T00:00:00Z", start + offset + 1),
})
})
.collect();
- let next_cursor = if end < fixture.pages.len() {
+ let next_cursor = if end < all.len() {
json!(format!("idx:{end}"))
} else {
json!(null)
@@ -152,10 +214,45 @@ async fn page_handler(
if fixture.unreachable == Some(path.as_str()) {
return error_json(StatusCode::NOT_FOUND, "page not found");
}
- let Some(body) = fixture.body_of(&path) else {
+ let read_count = {
+ let mut reads = fixture.reads_by_path.lock().unwrap();
+ let count = reads.entry(path.clone()).or_insert(0);
+ *count += 1;
+ *count
+ };
+ if let Some((target, nth)) = fixture.edit_on_read
+ && target == path
+ && nth == read_count
+ {
+ fixture.update(&path, |page| page.body.push_str("edited concurrently\n"));
+ }
+ let Some(page) = fixture.page(&path) else {
return error_json(StatusCode::NOT_FOUND, "page not found");
};
- let etag = format!("\"{}\"", state::sha256_hex(body.as_bytes()));
+ let mut frontmatter = page.frontmatter.clone();
+ frontmatter["tier"] = json!(page.tier);
+ if page.pinned {
+ frontmatter["pinned"] = json!(true);
+ }
+ let document = json!({
+ "project": project,
+ "workspace": workspace,
+ "path": path,
+ "title": page.title,
+ "kind": "note",
+ "tier": page.tier,
+ "pinned": page.pinned,
+ "created_at": "2026-10-01T00:00:00Z",
+ "updated_at": "2026-10-01T00:00:00Z",
+ "supersedes": null,
+ "frontmatter": frontmatter,
+ "body_markdown": page.body,
+ "links": [],
+ "backlinks": [],
+ });
+ // Like the server: the ETag covers the whole projection, so a change to
+ // metadata alone also changes it.
+ let etag = format!("\"{}\"", state::sha256_hex(document.to_string().as_bytes()));
if let Some(if_none_match) = headers
.get(header::IF_NONE_MATCH)
.and_then(|v| v.to_str().ok())
@@ -176,26 +273,65 @@ async fn page_handler(
(header::ETAG, etag),
(header::CONTENT_TYPE, "application/json".to_string()),
],
- Json(json!({
- "project": project,
- "workspace": workspace,
- "path": path,
- "title": format!("title {path}"),
- "kind": "note",
- "tier": "semantic",
- "pinned": false,
- "created_at": "2026-10-01T00:00:00Z",
- "updated_at": "2026-10-01T00:00:00Z",
- "supersedes": null,
- "frontmatter": {},
- "body_markdown": body,
- "links": [],
- "backlinks": [],
- })),
+ Json(document),
)
.into_response()
}
+/// `POST /mcp` `tools/call memory_write_page` with the server's replace
+/// semantics: every field the call omits is cleared, and the stored body
+/// passes a redaction step like the server's sanitizer.
+async fn mcp_handler(
+ State(fixture): State<Arc<Fixture>>,
+ headers: HeaderMap,
+ Json(request): Json<serde_json::Value>,
+) -> axum::response::Response {
+ if let Err(response) = fixture.authorize(&headers) {
+ return *response;
+ }
+ let accept = headers
+ .get(header::ACCEPT)
+ .and_then(|value| value.to_str().ok())
+ .unwrap_or_default();
+ if !(accept.contains("application/json") && accept.contains("text/event-stream")) {
+ return StatusCode::NOT_ACCEPTABLE.into_response();
+ }
+ let args = &request["params"]["arguments"];
+ if request["params"]["name"] != "memory_write_page"
+ || args["workspace"] != "demo"
+ || args["project"] != "app"
+ {
+ return Json(json!({"jsonrpc": "2.0", "id": request["id"],
+ "result": {"isError": true, "content": [{"type": "text", "text": "bad call"}]}}))
+ .into_response();
+ }
+ fixture.mcp_writes.fetch_add(1, Ordering::SeqCst);
+ let path = args["path"].as_str().unwrap_or_default().to_string();
+ let mut body = args["body"].as_str().unwrap_or_default().to_string();
+ if let Some(secret) = fixture.redact {
+ body = body.replace(secret, "[REDACTED]");
+ }
+ let mut written = FixturePage::new(&path, &body);
+ if let Some(title) = args["title"].as_str() {
+ written.title = title.to_string();
+ }
+ if let Some(tier) = args["tier"].as_str() {
+ written.tier = tier.to_string();
+ }
+ written.pinned = args["pinned"].as_bool().unwrap_or(false);
+ if let Some(tags) = args["tags"].as_array().filter(|tags| !tags.is_empty()) {
+ written.frontmatter = json!({ "tags": tags });
+ }
+ {
+ let mut pages = fixture.pages.lock().unwrap();
+ pages.retain(|page| page.path != path);
+ pages.push(written);
+ }
+ Json(json!({"jsonrpc": "2.0", "id": request["id"],
+ "result": {"isError": false, "content": [{"type": "text", "text": "{}"}]}}))
+ .into_response()
+}
+
async fn serve(fixture: Fixture) -> (SocketAddr, Arc<Fixture>) {
let shared = Arc::new(fixture);
let app = Router::new()
@@ -207,6 +343,7 @@ async fn serve(fixture: Fixture) -> (SocketAddr, Arc<Fixture>) {
"/api/v1/workspaces/{workspace}/projects/{project}/pages/{*path}",
get(page_handler),
)
+ .route("/mcp", post(mcp_handler))
.with_state(shared.clone());
let listener = TcpListener::bind("127.0.0.1:0")
.await
@@ -246,6 +383,12 @@ fn fixture_pages() -> Vec<(String, String)> {
]
}
+/// The file export writes for a fixture page: the fixture's title as
+/// frontmatter, then the body verbatim.
+fn file(path: &str, body: &str) -> Vec<u8> {
+ format!("---\ntitle: \"title {path}\"\n---\n{body}").into_bytes()
+}
+
fn temp_dest() -> (tempfile::TempDir, PathBuf) {
let tmp = tempfile::tempdir().expect("tempdir");
// Canonicalize so the symlink-free destination guard passes on every OS.
@@ -272,10 +415,13 @@ async fn export_apply_writes_files_and_state() {
.await
.expect("first export");
- assert_eq!(fs::read(dest.join("notes/a.md")).unwrap(), b"# A\nalpha\n");
+ assert_eq!(
+ fs::read(dest.join("notes/a.md")).unwrap(),
+ file("notes/a.md", "# A\nalpha\n")
+ );
assert_eq!(
fs::read(dest.join("_rules/postgres.md")).unwrap(),
- b"# Postgres only\nUse Postgres.\n"
+ file("_rules/postgres.md", "# Postgres only\nUse Postgres.\n")
);
// Only allowlisted families land on disk.
assert!(!dest.join("decisions/0001-db.md").exists());
@@ -341,7 +487,10 @@ async fn local_edits_are_refused_until_forced() {
b"# B\nlocally edited\n",
"diverged file is untouched"
);
- assert_eq!(fs::read(dest.join("notes/a.md")).unwrap(), b"# A\nalpha\n");
+ assert_eq!(
+ fs::read(dest.join("notes/a.md")).unwrap(),
+ file("notes/a.md", "# A\nalpha\n")
+ );
assert_eq!(
fs::read(dest.join("notes/zz-new.md")).unwrap(),
b"# local\n",
@@ -353,7 +502,10 @@ async fn local_edits_are_refused_until_forced() {
run(&force_args, Mode::Apply)
.await
.expect("--force exports");
- assert_eq!(fs::read(dest.join("notes/b.md")).unwrap(), b"# B\nbeta\n");
+ assert_eq!(
+ fs::read(dest.join("notes/b.md")).unwrap(),
+ file("notes/b.md", "# B\nbeta\n")
+ );
assert_eq!(
fs::read(dest.join("notes/zz-new.md")).unwrap(),
b"# local\n",
@@ -363,7 +515,7 @@ async fn local_edits_are_refused_until_forced() {
let state = state::load(&dest).unwrap();
assert_eq!(
state.pages["notes/b.md"].hash,
- state::sha256_hex(b"# B\nbeta\n")
+ state::sha256_hex(&file("notes/b.md", "# B\nbeta\n"))
);
}
@@ -500,7 +652,316 @@ async fn empty_state_after_user_deletes_local_file_recreates_it() {
run(&args(addr, &dest, &["notes"]), Mode::Apply)
.await
.expect("recreate");
- assert_eq!(fs::read(dest.join("notes/b.md")).unwrap(), b"# B\nbeta\n");
+ assert_eq!(
+ fs::read(dest.join("notes/b.md")).unwrap(),
+ file("notes/b.md", "# B\nbeta\n")
+ );
let state: SyncState = state::load(&dest).unwrap();
assert!(state.pages.contains_key("notes/b.md"));
}
+
+fn sync_args(addr: SocketAddr, dest: &std::path::Path, prefer: Option<Prefer>) -> SyncArgs {
+ SyncArgs {
+ run: args(addr, dest, &["decisions"]),
+ prefer,
+ }
+}
+
+async fn sync(addr: SocketAddr, dest: &std::path::Path) -> anyhow::Result<()> {
+ bidi::run(&sync_args(addr, dest, None), true).await
+}
+
+fn decision() -> FixturePage {
+ let mut page = FixturePage::new("decisions/db.md", "# DB\nUse Postgres.\n");
+ page.title = "DB".to_string();
+ page.frontmatter = json!({"tags": ["db"]});
+ page.pinned = true;
+ page
+}
+
+const DECISION_FILE: &str =
+ "---\ntitle: \"DB\"\ntags: [\"db\"]\npinned: true\n---\n# DB\nUse Postgres.\n";
+
+#[tokio::test]
+async fn sync_exports_metadata_and_round_trips_without_writes() {
+ let (addr, fixture) = serve(Fixture::with_pages(vec![decision()])).await;
+ let (_tmp, dest) = temp_dest();
+ sync(addr, &dest).await.expect("first sync");
+ assert_eq!(
+ fs::read_to_string(dest.join("decisions/db.md")).unwrap(),
+ DECISION_FILE
+ );
+
+ sync(addr, &dest).await.expect("second sync");
+ assert_eq!(
+ fixture.mcp_writes.load(Ordering::SeqCst),
+ 0,
+ "nothing to import"
+ );
+ assert_eq!(
+ fs::read_to_string(dest.join("decisions/db.md")).unwrap(),
+ DECISION_FILE
+ );
+}
+
+#[tokio::test]
+async fn sync_imports_a_repo_edit_with_its_metadata() {
+ let (addr, fixture) = serve(Fixture::with_pages(vec![decision()])).await;
+ let (_tmp, dest) = temp_dest();
+ sync(addr, &dest).await.expect("first sync");
+
+ let edited =
+ "---\ntitle: \"DB\"\ntags: [\"db\", \"ops\"]\npinned: true\n---\n# DB\nUse Postgres 17.\n";
+ fs::write(dest.join("decisions/db.md"), edited).unwrap();
+ // Dry-run first: nothing reaches the server.
+ bidi::run(&sync_args(addr, &dest, None), false)
+ .await
+ .expect("dry run");
+ assert_eq!(fixture.mcp_writes.load(Ordering::SeqCst), 0);
+
+ sync(addr, &dest).await.expect("import");
+ let page = fixture.page("decisions/db.md").unwrap();
+ assert_eq!(page.body, "# DB\nUse Postgres 17.\n");
+ assert!(
+ page.pinned,
+ "the write re-sent pinned, so the replace kept it"
+ );
+ assert_eq!(page.frontmatter["tags"], json!(["db", "ops"]));
+ assert_eq!(
+ fs::read_to_string(dest.join("decisions/db.md")).unwrap(),
+ edited
+ );
+
+ sync(addr, &dest).await.expect("settled");
+ assert_eq!(
+ fixture.mcp_writes.load(Ordering::SeqCst),
+ 1,
+ "a settled page is not written again"
+ );
+}
+
+#[tokio::test]
+async fn sync_creates_new_repo_pages_only_with_frontmatter() {
+ let (addr, fixture) = serve(Fixture::with_pages(vec![decision()])).await;
+ let (_tmp, dest) = temp_dest();
+ sync(addr, &dest).await.expect("first sync");
+
+ fs::write(dest.join("decisions/cache.md"), "# Cache\nUse Redis.\n").unwrap();
+ let err = sync(addr, &dest)
+ .await
+ .expect_err("a file without frontmatter is refused");
+ assert!(err.to_string().contains("refused"), "{err}");
+ assert!(fixture.page("decisions/cache.md").is_none());
+ assert_eq!(
+ fixture.mcp_writes.load(Ordering::SeqCst),
+ 0,
+ "a refusal blocks the whole batch"
+ );
+
+ fs::write(
+ dest.join("decisions/cache.md"),
+ "---\ntitle: \"Cache\"\n---\n# Cache\nUse Redis.\n",
+ )
+ .unwrap();
+ sync(addr, &dest).await.expect("create");
+ let page = fixture
+ .page("decisions/cache.md")
+ .expect("created on the server");
+ assert_eq!(page.title, "Cache");
+ assert_eq!(page.body, "# Cache\nUse Redis.\n");
+ // Pages outside the allowlist never travel.
+ fs::create_dir_all(dest.join("notes")).unwrap();
+ fs::write(dest.join("notes/x.md"), "---\ntitle: \"X\"\n---\nx\n").unwrap();
+ sync(addr, &dest).await.expect("notes ignored");
+ assert!(fixture.page("notes/x.md").is_none());
+}
+
+#[tokio::test]
+async fn sync_conflicts_until_a_side_is_preferred() {
+ let (addr, fixture) = serve(Fixture::with_pages(vec![decision()])).await;
+ let (_tmp, dest) = temp_dest();
+ sync(addr, &dest).await.expect("first sync");
+
+ let repo_edit = DECISION_FILE.replace("Use Postgres.", "Use Postgres in the repo.");
+ fs::write(dest.join("decisions/db.md"), &repo_edit).unwrap();
+ fixture.update("decisions/db.md", |page| {
+ page.body = "# DB\nUse Postgres on the server.\n".into()
+ });
+
+ let err = sync(addr, &dest).await.expect_err("conflict");
+ assert!(err.to_string().contains("refused"), "{err}");
+ assert_eq!(
+ fs::read_to_string(dest.join("decisions/db.md")).unwrap(),
+ repo_edit
+ );
+ assert_eq!(fixture.mcp_writes.load(Ordering::SeqCst), 0);
+
+ bidi::run(&sync_args(addr, &dest, Some(Prefer::Server)), true)
+ .await
+ .expect("prefer server");
+ assert!(
+ fs::read_to_string(dest.join("decisions/db.md"))
+ .unwrap()
+ .contains("on the server")
+ );
+
+ fs::write(dest.join("decisions/db.md"), &repo_edit).unwrap();
+ fixture.update("decisions/db.md", |page| {
+ page.body = "# DB\nAgain on the server.\n".into()
+ });
+ bidi::run(&sync_args(addr, &dest, Some(Prefer::Repo)), true)
+ .await
+ .expect("prefer repo");
+ assert!(
+ fixture
+ .page("decisions/db.md")
+ .unwrap()
+ .body
+ .contains("in the repo")
+ );
+}
+
+#[tokio::test]
+async fn sync_refuses_to_clear_metadata_it_cannot_round_trip() {
+ let mut consolidated = decision();
+ consolidated.frontmatter = json!({"tags": ["db"], "summary": "s", "sources": ["x"]});
+ let (addr, fixture) = serve(Fixture::with_pages(vec![consolidated])).await;
+ let (_tmp, dest) = temp_dest();
+ sync(addr, &dest).await.expect("export still works");
+
+ let edited = fs::read_to_string(dest.join("decisions/db.md"))
+ .unwrap()
+ .replace("Use Postgres.", "Edited.");
+ fs::write(dest.join("decisions/db.md"), edited).unwrap();
+ let err = sync(addr, &dest).await.expect_err("import refused");
+ assert!(err.to_string().contains("refused"), "{err}");
+ assert_eq!(fixture.mcp_writes.load(Ordering::SeqCst), 0);
+ assert_eq!(
+ fixture.page("decisions/db.md").unwrap().frontmatter["summary"],
+ "s"
+ );
+}
+
+#[tokio::test]
+async fn sync_stops_when_the_server_page_changes_before_the_write() {
+ let (addr, fixture) = serve(Fixture::with_pages(vec![decision()])).await;
+ let (_tmp, dest) = temp_dest();
+ sync(addr, &dest).await.expect("first sync");
+ fs::write(
+ dest.join("decisions/db.md"),
+ DECISION_FILE.replace("Use Postgres.", "Repo edit."),
+ )
+ .unwrap();
+
+ // Reads so far: 1 by the first sync. The second sync classifies with
+ // read 2 (a 304) and 3 (the full page for the import); read 4 is the
+ // re-check right before the write, and lands after an edit.
+ let fixture_with_race = Fixture {
+ edit_on_read: Some(("decisions/db.md", 4)),
+ ..Fixture::with_pages(vec![fixture.page("decisions/db.md").unwrap()])
+ };
+ let (race_addr, raced) = serve(fixture_with_race).await;
+ // Seed the race server's read counter like the first server's.
+ raced
+ .reads_by_path
+ .lock()
+ .unwrap()
+ .insert("decisions/db.md".into(), 1);
+ let err = sync(race_addr, &dest).await.expect_err("race detected");
+ assert!(
+ format!("{err:#}").contains("changed on the server during this run"),
+ "{err:#}"
+ );
+ assert_eq!(
+ raced.mcp_writes.load(Ordering::SeqCst),
+ 0,
+ "the write never happened"
+ );
+}
+
+#[tokio::test]
+async fn sync_reports_deletes_and_never_propagates_them() {
+ let mut other = decision();
+ other.path = "decisions/other.md".to_string();
+ let (addr, fixture) = serve(Fixture::with_pages(vec![decision(), other])).await;
+ let (_tmp, dest) = temp_dest();
+ sync(addr, &dest).await.expect("first sync");
+
+ fixture.remove("decisions/db.md");
+ fs::remove_file(dest.join("decisions/other.md")).unwrap();
+ sync(addr, &dest)
+ .await
+ .expect("deletes are notices, not refusals");
+ assert!(
+ dest.join("decisions/db.md").exists(),
+ "server delete not propagated"
+ );
+ assert!(
+ fixture.page("decisions/other.md").is_some(),
+ "repo delete not propagated"
+ );
+ assert_eq!(fixture.mcp_writes.load(Ordering::SeqCst), 0);
+
+ fs::remove_file(dest.join("decisions/db.md")).unwrap();
+ sync(addr, &dest).await.expect("gone on both sides");
+ assert!(
+ !state::load(&dest)
+ .unwrap()
+ .pages
+ .contains_key("decisions/db.md")
+ );
+}
+
+#[tokio::test]
+async fn sync_adopts_the_server_rendering_after_an_import() {
+ let fixture = Fixture {
+ redact: Some("hunter2"),
+ ..Fixture::with_pages(vec![decision()])
+ };
+ let (addr, fixture) = serve(fixture).await;
+ let (_tmp, dest) = temp_dest();
+ sync(addr, &dest).await.expect("first sync");
+ fs::write(
+ dest.join("decisions/db.md"),
+ DECISION_FILE.replace("Use Postgres.", "password hunter2"),
+ )
+ .unwrap();
+ sync(addr, &dest).await.expect("import");
+ let file = fs::read_to_string(dest.join("decisions/db.md")).unwrap();
+ assert!(
+ file.contains("[REDACTED]") && !file.contains("hunter2"),
+ "{file}"
+ );
+
+ sync(addr, &dest).await.expect("settled");
+ assert_eq!(fixture.mcp_writes.load(Ordering::SeqCst), 1);
+}
+
+#[tokio::test]
+async fn sync_upgrades_a_slice_one_export_without_importing() {
+ let (addr, fixture) = serve(Fixture::with_pages(vec![decision()])).await;
+ let (_tmp, dest) = temp_dest();
+ // What slice 1 left behind: the bare body, and its hash as the base.
+ fs::create_dir_all(dest.join("decisions")).unwrap();
+ fs::write(dest.join("decisions/db.md"), "# DB\nUse Postgres.\n").unwrap();
+ let mut old = SyncState::default();
+ old.pages.insert(
+ "decisions/db.md".into(),
+ state::PageState {
+ hash: state::sha256_hex(b"# DB\nUse Postgres.\n"),
+ etag: None,
+ },
+ );
+ state::save(&dest, &old).unwrap();
+
+ sync(addr, &dest).await.expect("upgrade");
+ assert_eq!(
+ fixture.mcp_writes.load(Ordering::SeqCst),
+ 0,
+ "an unedited file is not imported"
+ );
+ assert_eq!(
+ fs::read_to_string(dest.join("decisions/db.md")).unwrap(),
+ DECISION_FILE
+ );
+}
diff --git a/docs/companion-crates.md b/docs/companion-crates.md
index a48d1251..9c1c15f6 100644
--- a/docs/companion-crates.md
+++ b/docs/companion-crates.md
@@ -79,8 +79,9 @@ the public MCP write/delete tools. It must never open the wiki directory or
SQLite directly. The core read seam is `/api/v1` in API-only mode; the supported
MCP page arguments are documented in [programmatic memory](programmatic-memory.md).
-Slice 1 (read-only export) shipped as
-[`ai-memory-wikisync`](#ai-memory-wikisync-read-only-team-wiki-export)
+Slice 1 (read-only export) and slice 3 (two-way sync through the MCP write
+tool) ship as
+[`ai-memory-wikisync`](#ai-memory-wikisync-team-wiki-export-and-sync)
below; the remaining slices are tracked in #986.
## `ai-memory-client`: shared private capture privacy
@@ -234,9 +235,9 @@ Re-home by kind:
6. Only after repeated usage, consider whether ai-memory core lacks a small,
generic API seam; do not start by patching core endpoints.
-## `ai-memory-wikisync`: read-only team-wiki export
+## `ai-memory-wikisync`: team-wiki export and sync
-Slice 1 of the accepted [team-wiki sync](#proposed-team-wiki-sync-986)
+Slices 1 and 3 of the accepted [team-wiki sync](#proposed-team-wiki-sync-986)
shape, implemented at [`companions/ai-memory-wikisync`](../companions/ai-memory-wikisync)
as a standalone Cargo package with its own `[workspace]` (mirroring the
importer): it is not a member of the root workspace and is not covered by
@@ -246,21 +247,26 @@ root `cargo test --workspace`.
Mirror a team's shared ai-memory pages into a project repository as
reviewable markdown, so the wiki a team actually maintains can travel with
-the code it documents — read-only, family-scoped, and dry-run by default.
+the code it documents, and let reviewed repository edits flow back —
+family-scoped and dry-run by default.
### How it talks to ai-memory
- `plan` (always dry-run) and `export` (dry-run unless `--apply`) against
the documented read-only `/api/v1` surface: incremental `recent` listing
with cursor paging (legacy array accepted) plus single-page reads with
- `ETag` / `If-None-Match` revalidation. No MCP, no admin routes, no
- writes to the server.
+ `ETag` / `If-None-Match` revalidation. No admin routes.
+- `sync` (dry-run unless `--apply`) also writes to the server, and only
+ through the public `memory_write_page` MCP tool with explicit `workspace`
+ and `project`, so sanitization, admission and attribution apply. It never
+ opens the wiki directory or SQLite.
- `--include FAMILY` is an explicit, repeatable allowlist of top-level
wiki directories; at least one is required and a bare `*` is refused.
- Auth is a bearer token via `--token` or `AI_MEMORY_AUTH_TOKEN` only;
tokens are never logged or persisted.
-- Writes exactly the server's canonical projection (path, title, body)
- with no forged attribution/generated frontmatter. All local bookkeeping
+- Each file is the server body under a fixed frontmatter of the fields a
+ write round-trips (`title`, `tags`, `pinned`, and `tier` when not the
+ default), never server-generated or attribution keys. All local bookkeeping
lives in one state file under the destination
(`.ai-memory-wikisync/state.json`, 0600, atomically replaced after each
successful write batch). The directory ignores itself with a `.gitignore`
@@ -281,6 +287,15 @@ the code it documents — read-only, family-scoped, and dry-run by default.
(tmp + rename + fsync).
- Page bodies are untrusted data, transported verbatim and never executed
or rendered.
+- `sync` changes one side only when the other is unchanged since the last
+ sync; a page changed on both sides is refused until `--prefer repo` or
+ `--prefer server`. Deletes are reported, never propagated (slice 4).
+- An import requires the file's frontmatter (a write clears what it omits),
+ and is refused for a server page carrying any metadata the write cannot
+ carry (`summary`, `sources`, `kind`, …), naming the keys.
+- Right before each import the server page is re-read and must still render
+ to the classified bytes. MCP has no compare-and-write, so one read-to-write
+ race window remains; that is the documented case for slice 2.
### Validation
@@ -293,14 +308,18 @@ cargo clippy --manifest-path companions/ai-memory-wikisync/Cargo.toml --all-targ
Unit tests cover the path-safety matrix, the allowlist rules, state
hash/crash behavior and local-edit refusal; integration tests run the
full plan/export flow against a fixture axum server serving `/api/v1`
-responses (200/ETag/304/401/404 and cursor pagination).
+responses (200/ETag/304/401/404 and cursor pagination), and the sync flow
+against the same fixture's `POST /mcp` with the server's replace semantics:
+imports with metadata, creates, conflicts and `--prefer`, the
+metadata-loss refusal, the pre-write race check, delete notices, sanitizer
+rewrites and the upgrade of a slice 1 export.
### Roadmap (#986)
-1. This slice — read-only export into a project repository.
+1. Read-only export into a project repository (shipped).
2. Conditional mutation seam (compare-and-write) in core, if independently
justified.
-3. Bidirectional apply through public write tools.
+3. Bidirectional apply through public write tools (shipped as `sync`).
4. Deletes and conflict reporting.
5. Post-merge hook / CI integration.