use std::path::{Path, PathBuf};
pub const BEGIN: &str =
"<!-- memfork:begin (managed by `memfork init --project`; edits between these markers are replaced) -->";
pub const END: &str = "<!-- memfork:end -->";
const BEGIN_TAG: &str = "<!-- memfork:begin";
pub const AGENTS_FILE: &str = "AGENTS.md";
const BODY: &str = "\
## Shared memory: MemFork
This repository's working memory lives in MemFork, which every AI tool used \
here can reach through its MCP tools. Other agents, from any vendor, read what \
you record and continue from it, so record as you go rather than at the end.
- When you start, call `memfork_resume`, saying in `task` what you are about \
to do.
- Before asking the user something memory may already know, call \
`memfork_search` with `text`.
- Before starting a task on the board, claim it with `memfork_task`; mark it \
done when it is.
- Store each decision with its reason using `memfork_put` under \
`<project>:decision:<topic>`, where `<project>` is the namespace MemFork names \
when you connect. After exploring code, store what you found with `sources` \
naming the files.
- Before you stop or hand over, call `memfork_handoff` with what is done, what \
comes next and what is blocking.
- Before anything risky, call `memfork_fork`. If it worked, `memfork_merge`; if \
it did not, `memfork_discard` with a one-line `lesson`.";
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Change {
Create,
Append,
Update,
Unchanged,
Remove,
Absent,
}
impl Change {
pub fn writes(self) -> bool {
matches!(
self,
Change::Create | Change::Append | Change::Update | Change::Remove
)
}
pub fn verb(self) -> &'static str {
match self {
Change::Create => "create",
Change::Append => "add block",
Change::Update => "update block",
Change::Unchanged => "up to date",
Change::Remove => "remove block",
Change::Absent => "no block",
}
}
pub fn done(self) -> &'static str {
match self {
Change::Create => "created",
Change::Append => "added block",
Change::Update => "updated block",
Change::Remove => "removed block",
other => other.verb(),
}
}
}
#[derive(Debug, Clone)]
pub struct FilePlan {
pub relative: String,
pub path: PathBuf,
pub clients: Vec<String>,
pub change: Change,
pub before: Option<String>,
pub after: String,
}
impl FilePlan {
pub fn diff(&self) -> String {
if !self.change.writes() {
return String::new();
}
let before = self.before.as_deref().unwrap_or("");
let old_name = match self.before {
Some(_) => format!("a/{}", self.relative),
None => "/dev/null".to_owned(),
};
similar::TextDiff::from_lines(before, &self.after)
.unified_diff()
.context_radius(3)
.header(&old_name, &format!("b/{}", self.relative))
.to_string()
}
pub fn left_empty(&self) -> bool {
self.change == Change::Remove && self.after.trim().is_empty()
}
}
pub fn plan(
root: &Path,
files: &[(String, Vec<String>)],
remove: bool,
) -> Result<Vec<FilePlan>, String> {
files
.iter()
.map(|(relative, clients)| {
let path = relative
.split('/')
.fold(root.to_path_buf(), |p, part| p.join(part));
let before = match std::fs::read(&path) {
Ok(bytes) => Some(String::from_utf8(bytes).map_err(|_| {
format!("{relative} is not UTF-8 text, so MemFork will not edit it")
})?),
Err(e) if e.kind() == std::io::ErrorKind::NotFound => None,
Err(e) => return Err(format!("cannot read {relative}: {e}")),
};
let (change, after) = match &before {
None if remove => (Change::Absent, String::new()),
None => (Change::Create, format!("{}\n", block("\n"))),
Some(text) => edit(text, remove).map_err(|why| format!("{relative}: {why}"))?,
};
Ok(FilePlan {
relative: relative.clone(),
path,
clients: clients.clone(),
change,
before,
after,
})
})
.collect()
}
pub fn apply(plan: &FilePlan) -> Result<(), String> {
if !plan.change.writes() {
return Ok(());
}
if let Some(parent) = plan.path.parent() {
std::fs::create_dir_all(parent)
.map_err(|e| format!("cannot create {}: {e}", parent.display()))?;
}
let tmp = plan.path.with_extension("memfork-tmp");
std::fs::write(&tmp, &plan.after)
.map_err(|e| format!("cannot write {}: {e}", tmp.display()))?;
std::fs::rename(&tmp, &plan.path).map_err(|e| {
let _ = std::fs::remove_file(&tmp);
format!("cannot replace {}: {e}", plan.path.display())
})
}
fn block(nl: &str) -> String {
let mut out = String::new();
out.push_str(BEGIN);
out.push_str(nl);
for line in BODY.lines() {
out.push_str(line);
out.push_str(nl);
}
out.push_str(END);
out
}
fn locate(text: &str) -> Result<Option<(usize, usize)>, String> {
let mut begin = None;
let mut found = None;
let mut offset = 0;
for line in text.split_inclusive('\n') {
let bare = line.trim_end_matches(['\r', '\n']).trim();
if bare.starts_with(BEGIN_TAG) {
if begin.is_some() || found.is_some() {
return Err(
"it has more than one MemFork block; leave one and run this again".to_owned(),
);
}
begin = Some(offset);
} else if bare == END {
match begin.take() {
Some(start) => found = Some((start, offset + line.len())),
None => {
return Err(
"it has a MemFork end marker with no begin marker; fix it by hand"
.to_owned(),
)
}
}
}
offset += line.len();
}
if begin.is_some() {
return Err("it has a MemFork begin marker with no end marker; fix it by hand".to_owned());
}
Ok(found)
}
fn edit(text: &str, remove: bool) -> Result<(Change, String), String> {
let (bom, body) = match text.strip_prefix('\u{feff}') {
Some(rest) => ("\u{feff}", rest),
None => ("", text),
};
let nl = if body.contains("\r\n") { "\r\n" } else { "\n" };
let fresh = block(nl);
match (locate(body)?, remove) {
(Some((start, end)), false) => {
let old = &body[start..end];
let ending = if old.ends_with('\n') { nl } else { "" };
let replacement = format!("{fresh}{ending}");
if old == replacement {
return Ok((Change::Unchanged, text.to_owned()));
}
Ok((
Change::Update,
format!("{bom}{}{replacement}{}", &body[..start], &body[end..]),
))
}
(Some((start, end)), true) => {
let mut head = &body[..start];
let tail = &body[end..];
if tail.is_empty() {
let doubled = format!("{nl}{nl}");
if head.ends_with(&doubled) {
head = &head[..head.len() - nl.len()];
}
}
Ok((Change::Remove, format!("{bom}{head}{tail}")))
}
(None, true) => Ok((Change::Absent, text.to_owned())),
(None, false) => {
let separator = if body.is_empty() {
""
} else if body.ends_with('\n') {
nl
} else {
if nl == "\r\n" {
"\r\n\r\n"
} else {
"\n\n"
}
};
Ok((Change::Append, format!("{bom}{body}{separator}{fresh}{nl}")))
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn a_new_block_follows_what_is_there() {
let (change, after) = edit("# Project\n\nOur rules.\n", false).unwrap();
assert_eq!(change, Change::Append);
assert!(after.starts_with("# Project\n\nOur rules.\n\n<!-- memfork:begin"));
assert!(after.ends_with("<!-- memfork:end -->\n"));
}
#[test]
fn running_again_changes_nothing() {
let (_, once) = edit("# Project\n", false).unwrap();
let (change, twice) = edit(&once, false).unwrap();
assert_eq!(change, Change::Unchanged);
assert_eq!(once, twice);
}
#[test]
fn only_the_block_is_replaced() {
let outdated = format!(
"intro\n\n<!-- memfork:begin (an older wording) -->\nold words\n{END}\n\noutro\n"
);
let (change, after) = edit(&outdated, false).unwrap();
assert_eq!(change, Change::Update);
assert!(after.starts_with("intro\n\n<!-- memfork:begin (managed"));
assert!(after.ends_with(&format!("{END}\n\noutro\n")));
assert!(!after.contains("old words"));
}
#[test]
fn adding_then_removing_gives_back_the_original() {
for original in ["# Rules\n\nBe kind.\n", "", "one line\n", "a\r\nb\r\n"] {
let (_, added) = edit(original, false).unwrap();
let (change, removed) = edit(&added, true).unwrap();
assert_eq!(change, Change::Remove);
assert_eq!(removed, original, "round trip of {original:?}");
}
}
#[test]
fn crlf_files_stay_crlf_and_a_bom_stays() {
let (_, after) = edit("\u{feff}# Rules\r\n", false).unwrap();
assert!(after.starts_with("\u{feff}# Rules\r\n\r\n<!-- memfork:begin"));
let bare_lf = after.replace("\r\n", "");
assert!(!bare_lf.contains('\n'), "a bare LF crept in");
}
#[test]
fn a_file_with_no_final_newline_gets_one_before_the_block() {
let (_, after) = edit("last line", false).unwrap();
assert!(after.starts_with("last line\n\n<!-- memfork:begin"));
}
#[test]
fn a_block_in_the_middle_is_removed_without_touching_either_side() {
let text = format!("top\n\n{}\n\nbottom\n", block("\n"));
let (_, after) = edit(&text, true).unwrap();
assert_eq!(after, "top\n\n\nbottom\n");
}
#[test]
fn broken_markers_are_refused_not_guessed_at() {
assert!(edit("<!-- memfork:begin -->\nno end\n", false)
.unwrap_err()
.contains("no end marker"));
assert!(edit(&format!("{END}\n"), false)
.unwrap_err()
.contains("no begin marker"));
let two = format!("{}\n{}\n", block("\n"), block("\n"));
assert!(edit(&two, false).unwrap_err().contains("more than one"));
}
#[test]
fn removing_from_a_file_without_a_block_changes_nothing() {
let (change, after) = edit("mine\n", true).unwrap();
assert_eq!(change, Change::Absent);
assert_eq!(after, "mine\n");
}
#[test]
fn the_block_says_the_routine_and_names_no_vendor() {
let text = block("\n").to_ascii_lowercase();
for step in [
"memfork_resume",
"memfork_search",
"memfork_task",
"memfork_put",
"sources",
"lesson",
"memfork_handoff",
"memfork_fork",
"memfork_merge",
"memfork_discard",
":decision:",
] {
assert!(text.contains(step), "no `{step}`");
}
for vendor in [
"claude",
"anthropic",
"openai",
"codex",
"cursor",
"gemini",
"google",
"grok",
"xai",
] {
assert!(!text.contains(vendor), "mentions `{vendor}`");
}
}
#[test]
fn the_diff_shows_exactly_the_change() {
let tmp = tempfile::tempdir().unwrap();
std::fs::write(tmp.path().join("NOTES.md"), "keep me\n").unwrap();
let plans = plan(
tmp.path(),
&[
("NOTES.md".to_owned(), vec!["A".to_owned()]),
("sub/NEW.md".to_owned(), vec!["B".to_owned()]),
],
false,
)
.unwrap();
let existing = plans[0].diff();
assert!(
existing.starts_with("--- a/NOTES.md\n+++ b/NOTES.md\n"),
"{existing}"
);
assert!(existing.contains(" keep me\n"), "{existing}");
assert!(existing.contains("+<!-- memfork:begin"), "{existing}");
assert!(!existing.contains("-keep me"), "{existing}");
let created = plans[1].diff();
assert!(
created.starts_with("--- /dev/null\n+++ b/sub/NEW.md\n"),
"{created}"
);
for p in &plans {
apply(p).unwrap();
}
assert_eq!(
std::fs::read_to_string(tmp.path().join("sub").join("NEW.md")).unwrap(),
plans[1].after
);
assert!(!tmp.path().join("NOTES.memfork-tmp").exists());
}
}