Skip to content

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

Rust

M5: wiki git versioning + auto-commit on session end

AkitaOnRailsab1df0faa5ef
diff --git a/Cargo.lock b/Cargo.lock
index 65d96268..d3db3e9b 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -147,6 +147,7 @@ dependencies = [
"ai-memory-core",
"ai-memory-store",
"anyhow",
+ "git2",
"jiff",
"notify",
"notify-debouncer-full",
@@ -354,6 +355,8 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a1dce859f0832a7d088c4f1119888ab94ef4b5d6795d1ce05afb7fe159d79f98"
dependencies = [
"find-msvc-tools",
+ "jobserver",
+ "libc",
"shlex",
]
@@ -822,6 +825,18 @@ dependencies = [
"wasi",
]
+[[package]]
+name = "getrandom"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi 5.3.0",
+ "wasip2",
+]
+
[[package]]
name = "getrandom"
version = "0.4.2"
@@ -830,12 +845,25 @@ checksum = "0de51e6874e94e7bf76d726fc5d13ba782deca734ff60d5bb2fb2607c7406555"
dependencies = [
"cfg-if",
"libc",
- "r-efi",
+ "r-efi 6.0.0",
"rand_core",
"wasip2",
"wasip3",
]
+[[package]]
+name = "git2"
+version = "0.20.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b88256088d75a56f8ecfa070513a775dd9107f6530ef14919dac831af9cfe2b"
+dependencies = [
+ "bitflags",
+ "libc",
+ "libgit2-sys",
+ "log",
+ "url",
+]
+
[[package]]
name = "hashbrown"
version = "0.14.5"
@@ -1185,6 +1213,16 @@ dependencies = [
"jiff-tzdb",
]
+[[package]]
+name = "jobserver"
+version = "0.1.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9afb3de4395d6b3e67a780b6de64b51c978ecf11cb9a462c66be7d4ca9039d33"
+dependencies = [
+ "getrandom 0.3.4",
+ "libc",
+]
+
[[package]]
name = "js-sys"
version = "0.3.98"
@@ -1235,6 +1273,18 @@ version = "0.2.186"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+[[package]]
+name = "libgit2-sys"
+version = "0.18.4+1.9.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b26f66f35e1871b22efcf7191564123d2a446ca0538cde63c23adfefa9b15b7"
+dependencies = [
+ "cc",
+ "libc",
+ "libz-sys",
+ "pkg-config",
+]
+
[[package]]
name = "libredox"
version = "0.1.16"
@@ -1255,6 +1305,18 @@ dependencies = [
"vcpkg",
]
+[[package]]
+name = "libz-sys"
+version = "1.1.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc3a226e576f50782b3305c5ccf458698f92798987f551c6a02efe8276721e22"
+dependencies = [
+ "cc",
+ "libc",
+ "pkg-config",
+ "vcpkg",
+]
+
[[package]]
name = "linux-raw-sys"
version = "0.12.1"
@@ -1563,6 +1625,12 @@ dependencies = [
"proc-macro2",
]
+[[package]]
+name = "r-efi"
+version = "5.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
+
[[package]]
name = "r-efi"
version = "6.0.0"
diff --git a/Cargo.toml b/Cargo.toml
index f6c18640..ac7ea64a 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -84,6 +84,9 @@ flate2 = "1"
# Text munging / hook payload sanitisation.
regex = "1"
+# Wiki git versioning.
+git2 = { version = "0.20", default-features = false, features = ["vendored-libgit2"] }
+
# Testing.
tempfile = "3"
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index e75962aa..8bd1bfce 100644
--- a/crates/ai-memory-cli/src/cli.rs
+++ b/crates/ai-memory-cli/src/cli.rs
@@ -47,6 +47,8 @@ pub enum Command {
Restore(RestoreArgs),
/// Print (or apply) lifecycle-hook configuration for an agent CLI.
InstallHooks(InstallHooksArgs),
+ /// Stage + commit the wiki tree under git.
+ Commit(CommitArgs),
}
/// Arguments for `init`.
@@ -127,6 +129,14 @@ pub enum AgentChoice {
OpenCode,
}
+/// Arguments for `commit`.
+#[derive(Debug, Args)]
+pub struct CommitArgs {
+ /// Commit message.
+ #[arg(long, short = 'm', default_value = "manual commit")]
+ pub message: String,
+}
+
/// Arguments for `install-hooks`.
#[derive(Debug, Args)]
pub struct InstallHooksArgs {
diff --git a/crates/ai-memory-cli/src/commands/commit.rs b/crates/ai-memory-cli/src/commands/commit.rs
new file mode 100644
index 00000000..cf106e07
--- /dev/null
+++ b/crates/ai-memory-cli/src/commands/commit.rs
@@ -0,0 +1,23 @@
+//! `ai-memory commit` — manual wiki git commit.
+
+use ai_memory_store::Store;
+use ai_memory_wiki::Wiki;
+use anyhow::{Context, Result};
+
+use crate::cli::CommitArgs;
+use crate::config::Config;
+
+/// Run the `commit` subcommand.
+///
+/// # Errors
+/// Returns an error if the wiki/git layer fails.
+pub fn run(config: &Config, args: CommitArgs) -> Result<()> {
+ let store = Store::open(&config.data_dir)
+ .with_context(|| format!("opening store at {}", config.data_dir.display()))?;
+ let wiki = Wiki::new(&config.data_dir, store.writer.clone())?;
+ match wiki.commit_all(&args.message)? {
+ Some(oid) => println!("committed: {oid}"),
+ None => println!("nothing to commit (working tree clean)"),
+ }
+ Ok(())
+}
diff --git a/crates/ai-memory-cli/src/commands/mod.rs b/crates/ai-memory-cli/src/commands/mod.rs
index 94745773..e1712cb9 100644
--- a/crates/ai-memory-cli/src/commands/mod.rs
+++ b/crates/ai-memory-cli/src/commands/mod.rs
@@ -1,6 +1,7 @@
//! Subcommand implementations.
pub mod backup;
+pub mod commit;
pub mod init;
pub mod install_hooks;
pub mod reset;
diff --git a/crates/ai-memory-cli/src/main.rs b/crates/ai-memory-cli/src/main.rs
index e70835cb..3eec040e 100644
--- a/crates/ai-memory-cli/src/main.rs
+++ b/crates/ai-memory-cli/src/main.rs
@@ -47,5 +47,6 @@ async fn main() -> Result<()> {
Command::Backup(args) => commands::backup::run(&config, args).await,
Command::Restore(args) => commands::restore::run(&config, args),
Command::InstallHooks(args) => commands::install_hooks::run(&config, args),
+ Command::Commit(args) => commands::commit::run(&config, args),
}
}
diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rs
index b42ca274..b43057de 100644
--- a/crates/ai-memory-hooks/src/router.rs
+++ b/crates/ai-memory-hooks/src/router.rs
@@ -23,7 +23,7 @@ use axum::http::StatusCode;
use axum::response::IntoResponse;
use axum::routing::post;
use jiff::Timestamp;
-use tracing::{info, warn};
+use tracing::{debug, info, warn};
use uuid::Uuid;
use crate::log;
@@ -144,6 +144,18 @@ async fn process(state: &HookState, env: HookEnvelope) -> anyhow::Result<()> {
let handoff =
build_auto_handoff(state, env.agent, session_id, env.cwd.clone(), &observations);
let handoff_id = state.writer.insert_handoff(handoff).await?;
+ // Auto-commit the wiki tree so the session/handoff/log.md
+ // changes land in git in one atomic snapshot.
+ let commit_msg = format!(
+ "session {}: {}",
+ short_id(&session_id.to_string()),
+ new_page.title.chars().take(60).collect::<String>(),
+ );
+ match state.wiki.commit_all(&commit_msg) {
+ Ok(Some(oid)) => debug!(commit = %oid, "wiki auto-commit"),
+ Ok(None) => debug!("wiki clean; no auto-commit"),
+ Err(e) => warn!(error = %e, "auto-commit failed"),
+ }
info!(
session = %session_id,
page = %new_page.path,
@@ -231,6 +243,10 @@ fn build_auto_handoff(
}
}
+fn short_id(s: &str) -> String {
+ s.chars().take(8).collect()
+}
+
const fn importance_for(event: HookEvent) -> u8 {
match event {
HookEvent::SessionStart | HookEvent::SessionEnd => 7,
diff --git a/crates/ai-memory-wiki/Cargo.toml b/crates/ai-memory-wiki/Cargo.toml
index 1fb1d5db..bc32bb37 100644
--- a/crates/ai-memory-wiki/Cargo.toml
+++ b/crates/ai-memory-wiki/Cargo.toml
@@ -22,6 +22,7 @@ tracing.workspace = true
tokio.workspace = true
notify.workspace = true
notify-debouncer-full.workspace = true
+git2.workspace = true
[dev-dependencies]
diff --git a/crates/ai-memory-wiki/src/git.rs b/crates/ai-memory-wiki/src/git.rs
new file mode 100644
index 00000000..9b7e27c5
--- /dev/null
+++ b/crates/ai-memory-wiki/src/git.rs
@@ -0,0 +1,164 @@
+//! Git versioning for the wiki tree.
+//!
+//! On `Wiki::new`, we lazily `git init` the wiki root if it isn't already
+//! a repo. Auto-commits fire from the hook router on `SessionEnd` and
+//! from the M7 consolidator. Author/email are fixed so the wiki history
+//! can't accidentally leak the maintainer's git identity.
+
+use std::path::{Path, PathBuf};
+
+use git2::{IndexAddOption, Repository, Signature};
+use tracing::{debug, warn};
+
+use crate::error::{WikiError, WikiResult};
+
+/// Author identity used for ai-memory's own commits. The user can
+/// rewrite history with their own identity later if they care.
+pub const COMMIT_AUTHOR_NAME: &str = "ai-memory";
+/// Author email used for ai-memory's own commits.
+pub const COMMIT_AUTHOR_EMAIL: &str = "ai-memory@local";
+
+/// Thin handle over the wiki repo. Cheap to clone — internally a `PathBuf`.
+#[derive(Clone)]
+pub struct GitAdapter {
+ root: PathBuf,
+}
+
+impl GitAdapter {
+ /// Open or initialise the repo at `root`. Idempotent: if the
+ /// directory is already a git repo, leaves it alone.
+ ///
+ /// # Errors
+ /// Propagates any underlying libgit2 error.
+ pub fn open_or_init(root: &Path) -> WikiResult<Self> {
+ std::fs::create_dir_all(root)?;
+ match Repository::open(root) {
+ Ok(_) => debug!(root = %root.display(), "wiki repo already initialised"),
+ Err(_) => {
+ debug!(root = %root.display(), "initialising wiki repo");
+ Repository::init(root).map_err(map_git_err)?;
+ }
+ }
+ Ok(Self {
+ root: root.to_path_buf(),
+ })
+ }
+
+ /// Path of the wiki root.
+ #[must_use]
+ pub fn root(&self) -> &Path {
+ &self.root
+ }
+
+ /// Stage *everything* in the wiki root, then commit with `message`.
+ /// Returns `Ok(None)` if there were no changes to commit (working
+ /// tree clean), or `Ok(Some(commit_oid))` on a successful commit.
+ ///
+ /// # Errors
+ /// Propagates any underlying libgit2 error.
+ pub fn commit_all(&self, message: &str) -> WikiResult<Option<git2::Oid>> {
+ let repo = Repository::open(&self.root).map_err(map_git_err)?;
+
+ // Stage everything (including deletions).
+ let mut index = repo.index().map_err(map_git_err)?;
+ index
+ .add_all(["*"].iter(), IndexAddOption::DEFAULT, None)
+ .map_err(map_git_err)?;
+ index.write().map_err(map_git_err)?;
+
+ // If the index matches HEAD, there is nothing to commit.
+ let tree_oid = index.write_tree().map_err(map_git_err)?;
+ if let Ok(head) = repo.head()
+ && let Some(target) = head.target()
+ && let Ok(parent_commit) = repo.find_commit(target)
+ && parent_commit.tree_id() == tree_oid
+ {
+ debug!("working tree clean; no commit");
+ return Ok(None);
+ }
+ let tree = repo.find_tree(tree_oid).map_err(map_git_err)?;
+ let sig = Signature::now(COMMIT_AUTHOR_NAME, COMMIT_AUTHOR_EMAIL).map_err(map_git_err)?;
+
+ let parents: Vec<git2::Commit<'_>> = match repo.head() {
+ Ok(head) => match head.target() {
+ Some(oid) => vec![repo.find_commit(oid).map_err(map_git_err)?],
+ None => Vec::new(),
+ },
+ Err(_) => Vec::new(),
+ };
+ let parent_refs: Vec<&git2::Commit<'_>> = parents.iter().collect();
+ let oid = repo
+ .commit(Some("HEAD"), &sig, &sig, message, &tree, &parent_refs)
+ .map_err(map_git_err)?;
+ debug!(oid = %oid, "wiki commit");
+ Ok(Some(oid))
+ }
+
+ /// Count commits reachable from HEAD. Returns 0 for an empty repo.
+ /// Useful for the test suite + for `ai-memory status`.
+ #[must_use]
+ pub fn commit_count(&self) -> usize {
+ let Ok(repo) = Repository::open(&self.root) else {
+ return 0;
+ };
+ let Ok(mut walk) = repo.revwalk() else {
+ return 0;
+ };
+ if walk.push_head().is_err() {
+ return 0;
+ }
+ walk.count()
+ }
+}
+
+fn map_git_err(e: git2::Error) -> WikiError {
+ warn!(error = %e, "libgit2 error");
+ WikiError::Io(std::io::Error::other(e.to_string()))
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use tempfile::TempDir;
+
+ #[test]
+ fn init_is_idempotent_and_creates_dotgit() {
+ let tmp = TempDir::new().unwrap();
+ let root = tmp.path().join("wiki");
+ let _adapter = GitAdapter::open_or_init(&root).unwrap();
+ assert!(root.join(".git").is_dir());
+ // Second open is a no-op.
+ let _adapter2 = GitAdapter::open_or_init(&root).unwrap();
+ }
+
+ #[test]
+ fn commit_all_returns_none_when_clean_some_when_dirty() {
+ let tmp = TempDir::new().unwrap();
+ let root = tmp.path().join("wiki");
+ let adapter = GitAdapter::open_or_init(&root).unwrap();
+ // No changes: returns None.
+ assert!(adapter.commit_all("initial").unwrap().is_none());
+
+ // Add a file -> commit -> Some(oid).
+ std::fs::write(root.join("foo.md"), "hello").unwrap();
+ let oid = adapter.commit_all("add foo").unwrap();
+ assert!(oid.is_some());
+
+ // Re-commit with no changes -> None again.
+ assert!(adapter.commit_all("no changes").unwrap().is_none());
+ assert_eq!(adapter.commit_count(), 1);
+ }
+
+ #[test]
+ fn commit_all_captures_deletes_too() {
+ let tmp = TempDir::new().unwrap();
+ let root = tmp.path().join("wiki");
+ let adapter = GitAdapter::open_or_init(&root).unwrap();
+ std::fs::write(root.join("a.md"), "first").unwrap();
+ adapter.commit_all("first").unwrap();
+ std::fs::remove_file(root.join("a.md")).unwrap();
+ let oid = adapter.commit_all("remove a").unwrap();
+ assert!(oid.is_some());
+ assert_eq!(adapter.commit_count(), 2);
+ }
+}
diff --git a/crates/ai-memory-wiki/src/lib.rs b/crates/ai-memory-wiki/src/lib.rs
index 9e28618a..1aceaf4b 100644
--- a/crates/ai-memory-wiki/src/lib.rs
+++ b/crates/ai-memory-wiki/src/lib.rs
@@ -7,11 +7,13 @@
mod atomic;
mod error;
+mod git;
mod markdown;
mod watcher;
mod wiki;
pub use error::{WikiError, WikiResult};
+pub use git::{COMMIT_AUTHOR_EMAIL, COMMIT_AUTHOR_NAME, GitAdapter};
pub use markdown::{Markdown, derive_title, emit, parse};
pub use watcher::{DEBOUNCE_WINDOW, RECONCILE_INTERVAL, WatcherHandle};
pub use wiki::{Wiki, WritePageRequest};
diff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rs
index beca4022..272e5bfd 100644
--- a/crates/ai-memory-wiki/src/wiki.rs
+++ b/crates/ai-memory-wiki/src/wiki.rs
@@ -7,6 +7,7 @@ use ai_memory_store::WriterHandle;
use crate::atomic;
use crate::error::WikiResult;
+use crate::git::GitAdapter;
use crate::markdown::{Markdown, derive_title, emit, parse};
/// Wiki filesystem handle.
@@ -20,18 +21,36 @@ use crate::markdown::{Markdown, derive_title, emit, parse};
pub struct Wiki {
root: PathBuf,
writer: WriterHandle,
+ git: GitAdapter,
}
impl Wiki {
/// Construct a wiki handle rooted at `<data_dir>/wiki/`. Creates the
- /// directory if absent.
+ /// directory if absent and initialises a git repo inside it.
///
/// # Errors
- /// Returns [`WikiError::Io`] if the wiki root cannot be created.
+ /// Returns [`WikiError::Io`] if the wiki root or git repo cannot be
+ /// created.
pub fn new(data_dir: &Path, writer: WriterHandle) -> WikiResult<Self> {
let root = data_dir.join("wiki");
std::fs::create_dir_all(&root)?;
- Ok(Self { root, writer })
+ let git = GitAdapter::open_or_init(&root)?;
+ Ok(Self { root, writer, git })
+ }
+
+ /// Borrow the git adapter (for callers wiring auto-commit).
+ #[must_use]
+ pub fn git(&self) -> &GitAdapter {
+ &self.git
+ }
+
+ /// Stage + commit the entire wiki tree. Returns `Ok(None)` if there
+ /// was nothing to commit.
+ ///
+ /// # Errors
+ /// Propagates [`WikiError`] from the git adapter.
+ pub fn commit_all(&self, message: &str) -> WikiResult<Option<git2::Oid>> {
+ self.git.commit_all(message)
}
/// Path of the wiki root on disk.