Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
//! `ai-memory render-plugins` (hidden) — generate the marketplace plugins.
//!
//! Every file under `plugins/` and the marketplace catalogs at the repository
//! root (`.claude-plugin/marketplace.json`, `.agents/plugins/marketplace.json`)
//! come from here, built from the sources `install-hooks` and
//! `install-skills` already use: the event lists in [`super::render_shared`]
//! and the managed routing skills in `ai-memory-core`. Two callers keep the
//! committed tree honest: the CLI suite's drift test, which fails when the
//! committed files differ from this output, and `bin/release`, which re-renders
//! after the version bump so every manifest and catalog `ref` names the tag
//! being cut (#1166).
//!
//! The plugins stay thin: manifests, skills, and one POSIX launcher that hands
//! each lifecycle event to the installed binary's native `hook` command. No
//! build step, no bundled binary, no first-run download.
use std::path::Path;
use ai_memory_core::routing_skills::MANAGED_SKILLS;
use anyhow::{Context as _, Result};
use serde_json::{Value, json};
use super::render_shared::{CLAUDE_CODE_EVENTS, CODEX_EVENTS};
use crate::cli::RenderPluginsArgs;
/// The repository the catalogs point at.
const REPOSITORY_URL: &str = "https://github.com/akitaonrails/ai-memory";
/// The project's landing page, used for every manifest's `homepage`.
const HOMEPAGE_URL: &str = "https://aimemory.sh";
/// The marketplace name and the plugin name; installs as `ai-memory@ai-memory`.
pub(crate) const MARKETPLACE_NAME: &str = "ai-memory";
/// The plugin's name inside its marketplace.
pub(crate) const PLUGIN_NAME: &str = "ai-memory";
const LAUNCHER: &str = include_str!("../../templates/plugin/ai-memory-hook.sh");
const LICENSE: &str = include_str!("../../../../LICENSE");
const OVERVIEW_README: &str = include_str!("../../templates/plugin/README.md");
const CLAUDE_README: &str = include_str!("../../templates/plugin/claude-code-README.md");
const CODEX_README: &str = include_str!("../../templates/plugin/codex-README.md");
const STATUS_SKILL: &str = include_str!("../../templates/plugin/status-SKILL.md");
/// The launcher's path inside a plugin directory.
const LAUNCHER_PATH: &str = "scripts/ai-memory-hook";
const CLAUDE_DESCRIPTION: &str = "Long-term memory across sessions and harnesses. Hands each \
lifecycle event to the installed ai-memory binary, which applies your capture exclusions and \
sends a sanitized record only to your ai-memory server (default http://127.0.0.1:49374). Adds \
the ai-memory MCP tools. No telemetry. Requires the ai-memory binary, 3.0 or later. In \
Cowork, capture runs on your computer and needs ai-memory installed there; the memory tools \
still work.";
const CODEX_DESCRIPTION: &str = "Long-term memory across sessions and harnesses, backed by the \
installed ai-memory binary (3.0 or later) and your ai-memory server. No telemetry. Codex runs \
the hooks only \
after you trust them in /hooks.";
/// One generated file, relative to the repository root.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PluginFile {
/// Path relative to the repository root, `/`-separated.
pub path: String,
/// Exact file contents.
pub contents: String,
/// Whether the file is executable (the launcher).
pub executable: bool,
}
impl PluginFile {
/// Every constructor goes through here. The templates and LICENSE are
/// `include_str!`ed, so a CRLF checkout (Windows `core.autocrlf`) would
/// otherwise ship `/bin/sh^M` launchers and break the drift test.
fn text(path: impl Into<String>, contents: impl Into<String>) -> Self {
Self {
path: path.into(),
contents: contents.into().replace("\r\n", "\n"),
executable: false,
}
}
fn script(path: impl Into<String>, contents: impl Into<String>) -> Self {
Self {
executable: true,
..Self::text(path, contents)
}
}
fn json(path: impl Into<String>, value: &Value) -> Self {
let mut contents = serde_json::to_string_pretty(value).unwrap_or_default();
contents.push('\n');
Self::text(path, contents)
}
}
/// Every generated file for `version` (the workspace version, without `v`).
#[must_use]
pub fn render(version: &str) -> Vec<PluginFile> {
let mut files = vec![
PluginFile::json(".claude-plugin/marketplace.json", &claude_catalog(version)),
PluginFile::json(".agents/plugins/marketplace.json", &codex_catalog(version)),
PluginFile::text("plugins/README.md", OVERVIEW_README),
];
files.extend(claude_code_plugin(version));
files.extend(codex_plugin(version));
files
}
fn author() -> Value {
json!({ "name": "AkitaOnRails", "url": "https://github.com/akitaonrails" })
}
fn git_subdir(path: &str, version: &str) -> Value {
json!({
"source": "git-subdir",
"url": format!("{REPOSITORY_URL}.git"),
"path": path,
"ref": format!("v{version}"),
})
}
fn claude_catalog(version: &str) -> Value {
json!({
"name": MARKETPLACE_NAME,
"owner": author(),
"description": "ai-memory plugins: lifecycle capture and memory tools for coding agents, \
backed by your own ai-memory server.",
"plugins": [{
"name": PLUGIN_NAME,
"description": "Long-term memory across sessions and harnesses.",
"version": version,
"source": git_subdir("plugins/claude-code", version),
}],
})
}
fn codex_catalog(version: &str) -> Value {
json!({
"name": MARKETPLACE_NAME,
"interface": { "displayName": "ai-memory" },
"plugins": [{
"name": PLUGIN_NAME,
"source": git_subdir("plugins/codex", version),
"policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
"category": "Productivity",
}],
})
}
/// The files every plugin directory carries: launcher, routing skills, the
/// status skill and the license.
fn common_files(dir: &str) -> Vec<PluginFile> {
let mut files = vec![
PluginFile::script(format!("{dir}/{LAUNCHER_PATH}"), LAUNCHER),
PluginFile::text(format!("{dir}/LICENSE"), LICENSE),
PluginFile::text(format!("{dir}/skills/status/SKILL.md"), STATUS_SKILL),
];
files.extend(MANAGED_SKILLS.iter().map(|skill| {
PluginFile::text(
format!("{dir}/skills/{}", skill.relative_path),
skill.content,
)
}));
files
}
fn claude_code_plugin(version: &str) -> Vec<PluginFile> {
const DIR: &str = "plugins/claude-code";
let option = |title: &str, description: &str, default: &str| json!({ "type": "string", "title": title, "description": description, "default": default });
let manifest = json!({
"name": PLUGIN_NAME,
"displayName": "ai-memory",
"version": version,
"description": CLAUDE_DESCRIPTION,
"author": author(),
"homepage": HOMEPAGE_URL,
"repository": REPOSITORY_URL,
"license": "MIT",
"keywords": ["memory", "mcp", "hooks", "handoff", "context"],
"userConfig": {
"server_url": option(
"ai-memory server URL",
"Base URL of the ai-memory server. Leave empty to use the server_url from your \
ai-memory config (http://127.0.0.1:49374 for a local install).",
"",
),
"ai_memory_bin": option(
"ai-memory executable",
"Absolute path to the ai-memory binary, only needed when it is not on PATH. A \
relative path is ignored.",
"ai-memory",
),
"data_dir": option(
"ai-memory data directory",
"Only for an install that uses a non-default data directory.",
"",
),
},
});
// Run through `sh`, as the Codex plugin does, rather than executing the
// launcher: a plugin uploaded as a desktop zip can lose the exec bit, and
// Windows Git Bash does not honour it at all.
let mut hooks = serde_json::Map::new();
for (name, script) in CLAUDE_CODE_EVENTS {
let event = script.trim_end_matches(".sh");
hooks.insert(
name.to_owned(),
json!([{ "matcher": "", "hooks": [{
"type": "command",
"command": format!("sh \"${{CLAUDE_PLUGIN_ROOT}}/{LAUNCHER_PATH}\" claude-code {event}"),
}]}]),
);
}
let hooks = json!({
"description": "ai-memory lifecycle capture through the installed ai-memory binary",
"hooks": hooks,
});
// The session-aware bridge, as `install-mcp --client claude-code`
// registers it: the plugin MCP process receives CLAUDE_CODE_SESSION_ID.
// An unset server_url option arrives as "" and means "use the config".
let mcp = json!({
"mcpServers": {
"ai-memory": {
"command": "${user_config.ai_memory_bin}",
"args": ["mcp-bridge", "--server-url", "${user_config.server_url}"],
}
}
});
let mut files = vec![
PluginFile::json(format!("{DIR}/.claude-plugin/plugin.json"), &manifest),
PluginFile::json(format!("{DIR}/hooks/hooks.json"), &hooks),
PluginFile::json(format!("{DIR}/.mcp.json"), &mcp),
PluginFile::text(format!("{DIR}/README.md"), CLAUDE_README),
];
files.extend(common_files(DIR));
files
}
fn codex_plugin(version: &str) -> Vec<PluginFile> {
const DIR: &str = "plugins/codex";
// Codex's own manifest location. Codex 0.162.1 installs a plugin whose
// only manifest is the Agent Plugins root `plugin.json` but discovers no
// hooks in it, so the native `.codex-plugin/plugin.json` is the one that
// works; `mcpServers` has to name the MCP file there.
let manifest = json!({
"name": PLUGIN_NAME,
"version": version,
"description": CODEX_DESCRIPTION,
"author": author(),
"homepage": HOMEPAGE_URL,
"repository": REPOSITORY_URL,
"license": "MIT",
"mcpServers": "./mcp.json",
});
// Session-less: Codex forwards no lifecycle session id to MCP servers.
let mcp = json!({
"$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers": {
"ai-memory": { "type": "stdio", "command": "ai-memory", "args": ["mcp-bridge", "--no-session-id"] }
}
});
// The commands reference ${PLUGIN_ROOT}, never a versioned path, and
// stay byte-identical across releases: Codex keys hook trust on a hash of
// the unexpanded command, so a plugin upgrade keeps it.
let mut hooks = serde_json::Map::new();
for (name, script) in CODEX_EVENTS {
let event = script.trim_end_matches(".sh");
hooks.insert(
name.to_owned(),
json!([{ "hooks": [{
"type": "command",
"command": format!("sh \"${{PLUGIN_ROOT}}/{LAUNCHER_PATH}\" codex {event}"),
"commandWindows": format!("ai-memory hook --event {event} --agent codex"),
}]}]),
);
}
let hooks = json!({ "hooks": hooks });
let mut files = vec![
PluginFile::json(format!("{DIR}/.codex-plugin/plugin.json"), &manifest),
PluginFile::json(format!("{DIR}/mcp.json"), &mcp),
PluginFile::json(format!("{DIR}/hooks/hooks.json"), &hooks),
PluginFile::text(format!("{DIR}/README.md"), CODEX_README),
];
files.extend(common_files(DIR));
files
}
/// Write every generated file below `out`.
///
/// # Errors
/// When a directory or file cannot be written.
pub fn run(args: RenderPluginsArgs) -> Result<()> {
write_all(&args.out, &render(env!("CARGO_PKG_VERSION")))
}
fn write_all(out: &Path, files: &[PluginFile]) -> Result<()> {
for file in files {
let path = out.join(&file.path);
if let Some(parent) = path.parent() {
std::fs::create_dir_all(parent)
.with_context(|| format!("creating {}", parent.display()))?;
}
std::fs::write(&path, &file.contents)
.with_context(|| format!("writing {}", path.display()))?;
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt as _;
let mode = if file.executable { 0o755 } else { 0o644 };
std::fs::set_permissions(&path, std::fs::Permissions::from_mode(mode))
.with_context(|| format!("setting the mode of {}", path.display()))?;
}
}
println!(
"rendered {} plugin file(s) under {}",
files.len(),
out.display()
);
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
fn file<'a>(files: &'a [PluginFile], path: &str) -> &'a PluginFile {
files
.iter()
.find(|f| f.path == path)
.unwrap_or_else(|| panic!("{path} not rendered"))
}
fn json_of(files: &[PluginFile], path: &str) -> Value {
serde_json::from_str(&file(files, path).contents).unwrap()
}
#[test]
fn every_manifest_and_catalog_names_the_version_and_its_tag() {
let files = render("9.8.7");
let claude = json_of(&files, "plugins/claude-code/.claude-plugin/plugin.json");
assert_eq!(claude["version"], "9.8.7");
let codex = json_of(&files, "plugins/codex/.codex-plugin/plugin.json");
assert_eq!(codex["version"], "9.8.7");
let catalog = json_of(&files, ".claude-plugin/marketplace.json");
assert_eq!(catalog["plugins"][0]["source"]["ref"], "v9.8.7");
assert_eq!(catalog["plugins"][0]["version"], "9.8.7");
let catalog = json_of(&files, ".agents/plugins/marketplace.json");
assert_eq!(catalog["plugins"][0]["source"]["ref"], "v9.8.7");
}
/// The plugin wires exactly the events `install-hooks` wires, through the
/// launcher, with the agent each harness's native hook expects.
#[test]
fn hooks_cover_the_install_hooks_events_through_the_launcher() {
let files = render("1.0.0");
let claude = json_of(&files, "plugins/claude-code/hooks/hooks.json");
let names: Vec<&String> = claude["hooks"].as_object().unwrap().keys().collect();
assert_eq!(names.len(), CLAUDE_CODE_EVENTS.len());
for (name, script) in CLAUDE_CODE_EVENTS {
let command = claude["hooks"][name][0]["hooks"][0]["command"]
.as_str()
.unwrap();
assert_eq!(
command,
format!(
"sh \"${{CLAUDE_PLUGIN_ROOT}}/scripts/ai-memory-hook\" claude-code {}",
script.trim_end_matches(".sh")
)
);
}
let codex = json_of(&files, "plugins/codex/hooks/hooks.json");
assert_eq!(
codex["hooks"].as_object().unwrap().len(),
CODEX_EVENTS.len()
);
for (name, _) in CODEX_EVENTS {
let command = codex["hooks"][name][0]["hooks"][0]["command"]
.as_str()
.unwrap();
assert!(command.contains("${PLUGIN_ROOT}") && command.contains(" codex "));
}
}
/// The plugins never call the curl script bundle, which sits outside
/// capture-policy v1, and never carry a credential.
#[test]
fn plugins_use_only_the_native_hook_and_carry_no_credential() {
for file in render("1.0.0") {
let lower = file.contents.to_ascii_lowercase();
if file.path.ends_with(".json") {
// The homepage URL ends in `.sh"`; a script path must not.
let without_homepage = lower.replace(HOMEPAGE_URL, "");
assert!(!lower.contains("hooks/claude-code/"), "{}", file.path);
assert!(!without_homepage.contains(".sh\""), "{}", file.path);
assert!(!lower.contains("authorization"), "{}", file.path);
assert!(!lower.contains("auth_token"), "{}", file.path);
assert!(!lower.contains("auth-token"), "{}", file.path);
}
}
let files = render("1.0.0");
let launcher = &file(&files, "plugins/claude-code/scripts/ai-memory-hook").contents;
assert!(launcher.contains("exec \"$bin\" \"$@\""));
assert!(!launcher.contains("curl"));
assert!(!launcher.contains("wget"));
}
#[test]
fn mcp_entries_match_the_install_mcp_bridge_shapes() {
let files = render("1.0.0");
let claude = json_of(&files, "plugins/claude-code/.mcp.json");
let args = claude["mcpServers"]["ai-memory"]["args"]
.as_array()
.unwrap();
assert!(!args.iter().any(|a| a == "--no-session-id"));
let codex = json_of(&files, "plugins/codex/mcp.json");
let args = codex["mcpServers"]["ai-memory"]["args"].as_array().unwrap();
assert!(args.iter().any(|a| a == "--no-session-id"));
}
#[test]
fn skills_are_the_managed_routing_skills_plus_status() {
let files = render("1.0.0");
for dir in ["plugins/claude-code", "plugins/codex"] {
for skill in MANAGED_SKILLS {
assert_eq!(
file(&files, &format!("{dir}/skills/{}", skill.relative_path)).contents,
skill.content
);
}
assert!(
file(&files, &format!("{dir}/skills/status/SKILL.md"))
.contents
.contains("ai-memory doctor")
);
assert!(file(&files, &format!("{dir}/scripts/ai-memory-hook")).executable);
}
}
#[test]
fn rendered_files_are_lf_even_from_a_crlf_checkout() {
let launcher = PluginFile::script("x", "#!/bin/sh\r\nexec \"$bin\"\r\n");
assert_eq!(launcher.contents, "#!/bin/sh\nexec \"$bin\"\n");
assert!(launcher.executable);
assert_eq!(PluginFile::text("y", "a\r\nb").contents, "a\nb");
for file in render("1.0.0") {
assert!(!file.contents.contains('\r'), "{}", file.path);
}
}
#[test]
fn render_writes_the_tree_with_an_executable_launcher() {
let temp = tempfile::tempdir().unwrap();
let files = render("1.0.0");
write_all(temp.path(), &files).unwrap();
for file in &files {
assert_eq!(
std::fs::read_to_string(temp.path().join(&file.path)).unwrap(),
file.contents
);
}
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt as _;
let mode = std::fs::metadata(
temp.path()
.join("plugins/claude-code/scripts/ai-memory-hook"),
)
.unwrap()
.permissions()
.mode();
assert_eq!(mode & 0o111, 0o111);
}
}
}