use std::process::ExitCode;
#[path = "mnemo/export.rs"]
mod export;
#[path = "mnemo/hook.rs"]
mod hook;
#[path = "mnemo/inspect.rs"]
mod inspect;
#[path = "mnemo/mcp_install.rs"]
mod mcp_install;
#[path = "mnemo/onboard.rs"]
mod onboard;
#[path = "mnemo/project.rs"]
mod project;
use clap::{Parser, Subcommand, ValueEnum};
use mnemo_engine::{
Memory, MemoryType, Metric, Mnemo, MnemoConfig, RecallRequest, RecallResult, Result, Ulid,
};
#[derive(Parser)]
#[command(name = "mnemo", version, about, long_about = None)]
struct Cli {
#[arg(long, global = true, value_name = "DURATION", default_value = "10s",
value_parser = parse_wait)]
wait: std::time::Duration,
#[arg(long, global = true, value_name = "DIR")]
model_dir: Option<std::path::PathBuf>,
#[arg(short = 'C', global = true, value_name = "DIR")]
dir: Option<std::path::PathBuf>,
#[command(subcommand)]
command: Command,
}
fn brain_arg(cmd: &mut Command) -> Option<&mut String> {
match cmd {
Command::Init { path, .. }
| Command::Unlock { path }
| Command::RecoveryCode { path }
| Command::Rekey { path, .. }
| Command::Info { path, .. }
| Command::Verify { path, .. }
| Command::Remember { path, .. }
| Command::About { path, .. }
| Command::List { path, .. }
| Command::Export { path, .. }
| Command::Inspect { path, .. }
| Command::Recall { path, .. }
| Command::Get { path, .. }
| Command::Update { path, .. }
| Command::DefaultAgent { path, .. }
| Command::Inbox { path, .. }
| Command::Stale { path, .. }
| Command::Ack { path, .. }
| Command::Post { brain: path, .. }
| Command::Claim { brain: path, .. }
| Command::Finding { brain: path, .. }
| Command::Task { brain: path, .. }
| Command::Wake { brain: path, .. }
| Command::Search { path, .. }
| Command::Snapshots { path, .. }
| Command::History { path, .. }
| Command::Serve { path, .. }
| Command::Mcp {
cmd: McpCmd::Install { path, .. },
}
| Command::Cache {
op:
CacheOp::Get { path, .. }
| CacheOp::Put { path, .. }
| CacheOp::Delete { path, .. }
| CacheOp::Stats { path, .. }
| CacheOp::Purge { path, .. },
}
| Command::Thread {
cmd:
ThreadCmd::Ingest { path, .. }
| ThreadCmd::Export { path, .. }
| ThreadCmd::Forget { path, .. }
| ThreadCmd::Start { path, .. },
}
| Command::Essence {
cmd:
EssenceCmd::Render { path, .. }
| EssenceCmd::Add { path, .. }
| EssenceCmd::Append { path, .. }
| EssenceCmd::Update { path, .. }
| EssenceCmd::Resolve { path, .. }
| EssenceCmd::Remove { path, .. },
} => Some(path),
_ => None,
}
}
fn shift_get_args(cmd: &mut Command) -> std::result::Result<(), String> {
let (name, path, id, ulid) = match cmd {
Command::Get { path, id, .. } => ("get", path, id, true),
Command::Update { path, id, .. } => ("update", path, id, true),
Command::Ack { path, id, .. } => ("ack", path, id, true),
Command::Essence {
cmd:
EssenceCmd::Update { path, id, .. }
| EssenceCmd::Resolve { path, id, .. }
| EssenceCmd::Remove { path, id, .. },
} => ("essence", path, id, true),
Command::Thread {
cmd: ThreadCmd::Start { path, new, .. },
} => ("thread start", path, new, false),
_ => return Ok(()),
};
if id.is_some() {
return Ok(());
}
if ulid && parse_ulid(path).is_err() {
return Err(format!(
"`{name}` takes `[PATH] <ID>`: with one argument it's the memory's id, and \
{path:?} isn't one"
));
}
if !ulid && (path.ends_with(".mnemo") || std::path::Path::new(path.as_str()).is_file()) {
return Err(format!(
"`{name}` takes `[PATH] <NEW>`: with one argument it's the new thread id, and \
{path:?} looks like a brain's path; give the thread id too"
));
}
*id = Some(std::mem::take(path));
Ok(())
}
fn resolve_brain_arg(cmd: &mut Command, moved: bool) -> std::result::Result<bool, String> {
let creating = matches!(cmd, Command::Init { .. });
let Some(path) = brain_arg(cmd) else {
return Ok(false);
};
if !path.is_empty() {
return Ok(false);
}
let brain = project::find(moved, false)?;
if creating {
project::create_dir(&brain)?;
} else if !brain.is_file() {
return Err(format!(
"no project brain at {} yet; create it with `mnemo init` in this repository",
brain.display()
));
}
*path = brain
.to_str()
.ok_or_else(|| format!("{}: the path isn't UTF-8", brain.display()))?
.to_string();
Ok(true)
}
#[derive(Subcommand)]
enum Command {
Init {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long, default_value_t = 384)]
dimensions: usize,
#[arg(long)]
no_manifest: bool,
#[arg(long, conflicts_with_all = ["ask_passphrase", "key_file"])]
passphrase: Option<String>,
#[arg(long, conflicts_with = "key_file")]
ask_passphrase: bool,
#[arg(long, value_name = "PATH")]
key_file: Option<String>,
},
Unlock {
#[arg(default_value = "", hide_default_value = true)]
path: String,
},
RecoveryCode {
#[arg(default_value = "", hide_default_value = true)]
path: String,
},
Info {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long, value_name = "PATH", conflicts_with = "passphrase")]
key_file: Option<String>,
#[arg(long)]
passphrase: Option<String>,
},
Rekey {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long, value_name = "PATH", conflicts_with = "passphrase")]
key_file: Option<String>,
#[arg(long)]
passphrase: Option<String>,
#[arg(long, conflicts_with = "new_key")]
new_passphrase: Option<String>,
#[arg(long)]
new_key: bool,
#[arg(long, conflicts_with = "new_key")]
store: bool,
#[arg(long, value_name = "PATH", requires = "new_key")]
new_key_file: Option<String>,
#[arg(long)]
rotate: bool,
},
Compact {
path: String,
#[arg(long, value_name = "PATH", conflicts_with = "passphrase")]
key_file: Option<String>,
#[arg(long)]
passphrase: Option<String>,
},
Reembed {
path: String,
#[arg(long, requires = "embed_name")]
embed_cmd: Option<String>,
#[arg(long, requires = "embed_cmd")]
embed_name: Option<String>,
#[arg(long, default_value_t = true, action = clap::ArgAction::Set)]
embed_normalize: bool,
#[arg(long)]
embed_query: Option<String>,
#[arg(long)]
embed_dims: Option<usize>,
#[arg(long, default_value_t = 60)]
embed_timeout: u64,
#[arg(long, value_name = "PATH", conflicts_with = "passphrase")]
key_file: Option<String>,
#[arg(long)]
passphrase: Option<String>,
},
Verify {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long, value_name = "PATH", conflicts_with = "passphrase")]
key_file: Option<String>,
#[arg(long)]
passphrase: Option<String>,
},
Import {
path: String,
file: String,
#[arg(long)]
passphrase: Option<String>,
},
Remember {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long)]
text: String,
#[arg(long, default_value = "semantic")]
r#type: String,
#[arg(long)]
importance: Option<f32>,
#[arg(long)]
agent: Option<String>,
#[arg(long)]
metadata: Option<String>,
#[command(flatten)]
fresh: FreshArgs,
#[arg(long)]
key: Option<String>,
#[arg(long, requires = "key", value_name = "ID")]
supersedes: Option<String>,
#[arg(long, requires = "embed_name")]
embed_cmd: Option<String>,
#[arg(long, requires = "embed_cmd")]
embed_name: Option<String>,
#[arg(long, default_value_t = true, action = clap::ArgAction::Set)]
embed_normalize: bool,
#[arg(long)]
embed_query: Option<String>,
#[arg(long, default_value_t = 60)]
embed_timeout: u64,
#[arg(long)]
passphrase: Option<String>,
},
Index {
path: String,
#[arg(long)]
passphrase: Option<String>,
#[arg(long, conflicts_with = "rebuild")]
drop: bool,
#[arg(long, conflicts_with = "drop")]
rebuild: bool,
#[arg(long, default_value_t = 0)]
partitions: usize,
#[arg(long, default_value_t = 0)]
subspaces: usize,
#[arg(long, default_value_t = 0)]
n_probe: usize,
#[arg(long, default_value_t = 0)]
n_rerank: usize,
},
Search {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long, conflicts_with = "query_file")]
query: Option<String>,
#[arg(long, conflicts_with = "query")]
query_file: Option<String>,
#[arg(long, default_value_t = 5)]
top_k: usize,
#[arg(long, value_name = "LEVELS", value_delimiter = ',')]
visibility: Vec<String>,
#[arg(long)]
passphrase: Option<String>,
},
About {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long, value_enum, default_value_t = OutputFormat::Table)]
format: OutputFormat,
#[arg(long)]
manifest_only: bool,
#[arg(long, value_name = "LEVELS", value_delimiter = ',')]
visibility: Vec<String>,
#[arg(long, value_name = "PATH", conflicts_with = "passphrase")]
key_file: Option<String>,
#[arg(long)]
passphrase: Option<String>,
},
Get {
#[arg(value_name = "PATH")]
path: String,
#[arg(value_name = "ID")]
id: Option<String>,
#[arg(long, value_enum, default_value_t = OutputFormat::Table)]
format: OutputFormat,
#[arg(long)]
verbose: bool,
#[arg(long)]
vector: bool,
#[arg(long)]
passphrase: Option<String>,
},
Post {
to: String,
subject: String,
#[arg(long, default_value = "")]
body: String,
#[arg(long, value_delimiter = ',')]
refs: Vec<String>,
#[arg(long)]
conversation: Option<String>,
#[command(flatten)]
who: AsArgs,
#[arg(
long,
value_name = "PATH",
default_value = "",
hide_default_value = true
)]
brain: String,
#[arg(long)]
passphrase: Option<String>,
},
Inbox {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long)]
all: bool,
#[arg(long, value_name = "LEVELS", value_delimiter = ',')]
visibility: Vec<String>,
#[arg(long)]
prune: bool,
#[arg(long, default_value_t = 30, requires = "prune")]
days: u32,
#[arg(long, value_enum, default_value_t = OutputFormat::Table)]
format: OutputFormat,
#[command(flatten)]
who: AsArgs,
#[arg(long)]
passphrase: Option<String>,
},
Ack {
#[arg(value_name = "PATH")]
path: String,
#[arg(value_name = "ID")]
id: Option<String>,
#[arg(long)]
note: Option<String>,
#[command(flatten)]
who: AsArgs,
#[arg(long)]
passphrase: Option<String>,
},
Stale {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long)]
mine: bool,
#[arg(long, value_name = "LEVELS", value_delimiter = ',')]
visibility: Vec<String>,
#[arg(long, value_enum, default_value_t = OutputFormat::Table)]
format: OutputFormat,
#[command(flatten)]
who: AsArgs,
#[arg(long)]
passphrase: Option<String>,
},
Wake {
#[command(subcommand)]
cmd: WakeCmd,
#[command(flatten)]
who: AsArgs,
#[arg(
long,
global = true,
value_name = "PATH",
default_value = "",
hide_default_value = true
)]
brain: String,
#[arg(long, global = true)]
passphrase: Option<String>,
},
Task {
#[command(subcommand)]
cmd: TaskCmd,
#[command(flatten)]
who: AsArgs,
#[arg(
long,
global = true,
value_name = "PATH",
default_value = "",
hide_default_value = true
)]
brain: String,
#[arg(long, global = true)]
passphrase: Option<String>,
},
Claim {
#[command(subcommand)]
cmd: ClaimCmd,
#[command(flatten)]
who: AsArgs,
#[arg(
long,
global = true,
value_name = "PATH",
default_value = "",
hide_default_value = true
)]
brain: String,
#[arg(long, global = true)]
passphrase: Option<String>,
},
Finding {
#[command(subcommand)]
cmd: FindingCmd,
#[command(flatten)]
who: AsArgs,
#[arg(
long,
global = true,
value_name = "PATH",
default_value = "",
hide_default_value = true
)]
brain: String,
#[arg(long, global = true)]
passphrase: Option<String>,
},
DefaultAgent {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long, conflicts_with = "clear")]
set: Option<String>,
#[arg(long)]
clear: bool,
#[arg(long)]
passphrase: Option<String>,
},
List {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long, value_enum, default_value_t = OutputFormat::Table)]
format: OutputFormat,
#[arg(long, value_name = "T[,T...]")]
r#type: Option<String>,
#[arg(long)]
agent: Option<String>,
#[arg(long)]
limit: Option<usize>,
#[arg(long, default_value_t = 0)]
offset: usize,
#[arg(long, value_name = "LEVELS", value_delimiter = ',')]
visibility: Vec<String>,
#[arg(long, default_value = "created")]
sort: String,
#[arg(long)]
vector: bool,
#[arg(long, value_name = "PATH", conflicts_with = "passphrase")]
key_file: Option<String>,
#[arg(long)]
passphrase: Option<String>,
},
Export {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long, value_enum, default_value_t = export::ExportFormat::Markdown)]
format: export::ExportFormat,
#[arg(long, value_name = "T[,T...]")]
r#type: Option<String>,
#[arg(long)]
agent: Option<String>,
#[arg(long)]
git: bool,
#[arg(long, value_name = "LEVELS", value_delimiter = ',')]
visibility: Vec<String>,
#[arg(long, short = 'o')]
output: Option<String>,
#[arg(long, value_name = "PATH", conflicts_with = "passphrase")]
key_file: Option<String>,
#[arg(long)]
passphrase: Option<String>,
},
Inspect {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long)]
port: Option<u16>,
#[arg(long)]
open: bool,
#[arg(long, default_value = "30m", value_name = "DURATION")]
idle_timeout: String,
#[arg(long, value_name = "PATH", conflicts_with = "passphrase")]
key_file: Option<String>,
#[arg(long)]
passphrase: Option<String>,
},
Recall {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long, conflicts_with_all = ["query_file", "text"])]
query: Option<String>,
#[arg(long, conflicts_with_all = ["query", "text"])]
query_file: Option<String>,
#[arg(long, conflicts_with_all = ["query", "query_file"])]
text: Option<String>,
#[arg(long)]
keywords: Option<String>,
#[arg(long, conflicts_with = "keywords")]
no_keywords: bool,
#[arg(long, default_value_t = 10)]
top_k: usize,
#[arg(long, value_name = "LEVELS", value_delimiter = ',')]
visibility: Vec<String>,
#[arg(long, value_enum, default_value_t = OutputFormat::Table)]
format: OutputFormat,
#[arg(long, value_name = "T[,T...]")]
r#type: Option<String>,
#[arg(long)]
agent: Option<String>,
#[arg(long, default_value = "cosine")]
metric: String,
#[arg(long)]
n_probe: Option<usize>,
#[arg(long)]
n_rerank: Option<usize>,
#[arg(long)]
no_track: bool,
#[arg(long)]
session: Option<String>,
#[arg(long = "filter", value_name = "EXPR")]
filter: Vec<String>,
#[arg(long)]
max_bytes: Option<usize>,
#[arg(long, requires = "text")]
embed_cmd: Option<String>,
#[arg(long, requires = "text")]
embed_name: Option<String>,
#[arg(long, default_value_t = true, action = clap::ArgAction::Set)]
embed_normalize: bool,
#[arg(long, requires = "embed_cmd")]
embed_query: Option<String>,
#[arg(long, default_value_t = 60)]
embed_timeout: u64,
#[arg(long, value_name = "PATH", conflicts_with = "passphrase")]
key_file: Option<String>,
#[arg(long)]
passphrase: Option<String>,
},
Demo {
#[arg(long, default_value = "demo.mnemo")]
path: String,
},
Update {
#[arg(value_name = "PATH")]
path: String,
#[arg(value_name = "ID")]
id: Option<String>,
#[arg(long)]
text: Option<String>,
#[command(flatten)]
fresh: FreshArgs,
#[arg(long)]
importance: Option<f32>,
#[arg(long)]
metadata: Option<String>,
#[arg(long, conflicts_with = "clear_ttl")]
ttl_secs: Option<i64>,
#[arg(long)]
clear_ttl: bool,
#[arg(long, requires = "text")]
embed_cmd: Option<String>,
#[arg(long, requires = "text")]
embed_name: Option<String>,
#[arg(long, default_value_t = true, action = clap::ArgAction::Set)]
embed_normalize: bool,
#[arg(long, requires = "embed_cmd")]
embed_query: Option<String>,
#[arg(long, default_value_t = 60)]
embed_timeout: u64,
#[arg(long)]
passphrase: Option<String>,
},
History {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long)]
key: String,
#[arg(long, conflicts_with = "shared")]
agent: Option<String>,
#[arg(long, conflicts_with = "agent")]
shared: bool,
#[arg(long, value_enum, default_value_t = OutputFormat::Table)]
format: OutputFormat,
#[arg(long, value_name = "LEVELS", value_delimiter = ',')]
visibility: Vec<String>,
#[arg(long)]
passphrase: Option<String>,
},
Thread {
#[command(subcommand)]
cmd: ThreadCmd,
},
Essence {
#[command(subcommand)]
cmd: EssenceCmd,
},
Snapshots {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long)]
passphrase: Option<String>,
},
Restore {
path: String,
#[arg(long, conflicts_with = "to_time")]
to_txn: Option<u64>,
#[arg(long)]
to_time: Option<i64>,
#[arg(long)]
passphrase: Option<String>,
},
Onboard {
#[arg(long)]
guide: bool,
#[arg(long, value_enum, value_delimiter = ',')]
client: Vec<hook::Client>,
#[arg(long, value_enum, default_value = "local")]
scope: onboard::Scope,
#[arg(long, value_name = "BYTES")]
hook_budget: Option<usize>,
#[arg(long, conflicts_with = "print")]
yes: bool,
#[arg(long)]
print: bool,
#[arg(long)]
no_model: bool,
#[arg(long)]
undo: bool,
#[arg(long, value_enum)]
wake: Option<onboard::Wake>,
#[arg(long)]
plugin: bool,
#[arg(long, value_enum, default_value = "markdown", requires = "guide")]
format: GuideFormat,
},
Hook {
#[arg(value_enum)]
event: hook::Event,
#[arg(long, value_enum)]
client: hook::Client,
#[arg(long)]
budget: Option<usize>,
},
Mcp {
#[command(subcommand)]
cmd: McpCmd,
},
Serve {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long)]
mcp: bool,
#[arg(long, requires = "embed_name")]
embed_cmd: Option<String>,
#[arg(long, requires = "embed_cmd")]
embed_name: Option<String>,
#[arg(long, default_value_t = true, action = clap::ArgAction::Set)]
embed_normalize: bool,
#[arg(long, requires = "embed_cmd")]
embed_query: Option<String>,
#[arg(long, default_value_t = 60)]
embed_timeout: u64,
#[arg(long)]
shared: bool,
#[arg(long, requires = "shared")]
allow_network_fs: bool,
},
Embedder {
#[command(subcommand)]
cmd: EmbedderCmd,
},
Cache {
#[command(subcommand)]
op: CacheOp,
},
}
#[derive(Subcommand)]
enum WakeCmd {
Pause,
Resume,
Status,
}
fn cross_session_inbound(dir: &std::path::Path) -> Vec<(String, String)> {
fn find(v: &serde_json::Value) -> Option<String> {
match v {
serde_json::Value::Object(o) => o
.get("crossSessionInbound")
.and_then(|x| x.as_str().map(str::to_string))
.or_else(|| o.values().find_map(find)),
_ => None,
}
}
let mut files = Vec::new();
if let Some(h) = std::env::var_os("HOME") {
files.push(std::path::PathBuf::from(h).join(".claude/settings.json"));
}
files.push(dir.join(".claude/settings.json"));
files.push(dir.join(".claude/settings.local.json"));
files
.into_iter()
.filter_map(|f| {
let text = std::fs::read_to_string(&f).ok()?;
let v: serde_json::Value = serde_json::from_str(&text).ok()?;
Some((f.display().to_string(), find(&v)?))
})
.collect()
}
#[derive(Subcommand)]
enum TaskCmd {
Add {
title: String,
#[arg(long, default_value = "")]
body: String,
#[arg(long = "for", value_name = "ROLE")]
for_role: Option<String>,
#[arg(long, value_delimiter = ',')]
after: Vec<String>,
#[arg(long)]
pre_approved: bool,
#[arg(long)]
slug: Option<String>,
},
Next,
Update {
slug: String,
#[arg(long)]
status: Option<String>,
#[arg(long)]
note: Option<String>,
#[arg(long)]
token: Option<String>,
},
List {
#[arg(long)]
status: Option<String>,
#[arg(long = "for", value_name = "ROLE")]
for_role: Option<String>,
#[arg(long, value_enum, default_value_t = OutputFormat::Table)]
format: OutputFormat,
},
Get {
slug: String,
#[arg(long, value_enum, default_value_t = OutputFormat::Table)]
format: OutputFormat,
},
}
#[derive(Subcommand)]
enum FindingCmd {
Add {
id: String,
#[arg(long)]
category: String,
#[arg(long)]
priority: String,
#[arg(long)]
title: String,
#[arg(long, default_value = "")]
body: String,
#[arg(long = "ref", value_name = "REF")]
refs: Vec<String>,
},
Triage {
id: String,
#[arg(long)]
status: String,
#[arg(long)]
text: String,
},
Verify {
id: String,
#[arg(long = "ref", value_name = "REF")]
verified_ref: String,
},
List {
#[arg(long)]
status: Option<String>,
#[arg(long)]
batch: Option<String>,
#[arg(long)]
category: Option<String>,
#[arg(long)]
priority: Option<String>,
#[arg(long, value_enum, default_value_t = OutputFormat::Table)]
format: OutputFormat,
},
Get {
id: String,
#[arg(long, value_enum, default_value_t = OutputFormat::Table)]
format: OutputFormat,
},
}
fn finding_json(f: &mnemo_engine::Finding) -> serde_json::Value {
serde_json::json!({
"id": f.id, "record_id": f.record_id.to_string(), "batch": f.batch, "category": f.category, "priority": f.priority,
"title": f.title, "body": f.body, "refs": f.refs, "author": f.author,
"status": f.status, "triage": f.triage, "triaged_by": f.triaged_by,
"verified_ref": f.verified_ref, "verified_by": f.verified_by,
"created_at": f.created_at, "history": f.history,
})
}
#[derive(Subcommand)]
enum ClaimCmd {
Take {
topic: String,
#[arg(long)]
ttl: Option<String>,
},
Renew {
topic: String,
token: String,
#[arg(long)]
ttl: Option<String>,
},
Release { topic: String, token: String },
Check { topic: String, token: String },
Who {
#[arg(long, value_enum, default_value_t = OutputFormat::Table)]
format: OutputFormat,
},
}
#[derive(Subcommand)]
enum EmbedderCmd {
Install,
Status,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, ValueEnum)]
enum ToolResultsArg {
Full,
Omit,
}
impl From<ToolResultsArg> for mnemo_engine::ToolResults {
fn from(t: ToolResultsArg) -> Self {
match t {
ToolResultsArg::Full => mnemo_engine::ToolResults::Full,
ToolResultsArg::Omit => mnemo_engine::ToolResults::Omit,
}
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, ValueEnum)]
enum GuideFormat {
Markdown,
LlmsTxt,
LlmsFull,
#[value(hide = true)]
PluginSkill,
}
#[derive(Subcommand)]
enum McpCmd {
Install {
#[arg(long, value_enum)]
client: mcp_install::Client,
#[arg(long, value_enum)]
scope: Option<mcp_install::Scope>,
#[arg(long, default_value = "mnemo")]
name: String,
#[arg(long)]
print: bool,
#[arg(long, conflicts_with = "print")]
yes: bool,
#[arg(default_value = "", hide_default_value = true)]
path: String,
},
}
#[derive(Subcommand)]
enum ThreadCmd {
Ingest {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long)]
thread: String,
#[arg(long)]
transcript: String,
#[arg(long, default_value = "jsonl")]
format: String,
#[arg(long, value_enum, default_value = "full")]
tool_results: ToolResultsArg,
#[arg(long)]
redact: bool,
#[arg(long, requires = "embed_name")]
embed_cmd: Option<String>,
#[arg(long, requires = "embed_cmd")]
embed_name: Option<String>,
#[arg(long, default_value_t = true, action = clap::ArgAction::Set)]
embed_normalize: bool,
#[arg(long)]
embed_query: Option<String>,
#[arg(long, default_value_t = 60)]
embed_timeout: u64,
#[arg(long)]
passphrase: Option<String>,
},
Export {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long)]
thread: String,
#[arg(long, short = 'o')]
output: Option<String>,
#[arg(long)]
passphrase: Option<String>,
},
Forget {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long)]
thread: String,
#[arg(long)]
passphrase: Option<String>,
},
Start {
#[arg(value_name = "PATH")]
path: String,
#[arg(value_name = "NEW")]
new: Option<String>,
#[arg(long)]
from: String,
#[arg(long)]
passphrase: Option<String>,
},
}
#[derive(Subcommand)]
enum EssenceCmd {
Render {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long, conflicts_with = "project")]
thread: Option<String>,
#[arg(long, conflicts_with = "thread")]
project: bool,
#[arg(long, default_value_t = 6144)]
budget: usize,
#[arg(long)]
passphrase: Option<String>,
},
Add {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long)]
section: String,
#[arg(long)]
text: String,
#[arg(long, conflicts_with = "project")]
thread: Option<String>,
#[arg(long, conflicts_with = "thread")]
project: bool,
#[arg(long)]
refs: Option<String>,
#[arg(long)]
passphrase: Option<String>,
},
Append {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long)]
text: String,
#[arg(long, conflicts_with = "project")]
thread: Option<String>,
#[arg(long, conflicts_with = "thread")]
project: bool,
#[arg(long)]
refs: Option<String>,
#[arg(long)]
passphrase: Option<String>,
},
Update {
#[arg(value_name = "PATH")]
path: String,
#[arg(value_name = "ID")]
id: Option<String>,
#[arg(long)]
text: String,
#[arg(long)]
refs: Option<String>,
#[arg(long)]
passphrase: Option<String>,
},
Resolve {
#[arg(value_name = "PATH")]
path: String,
#[arg(value_name = "ID")]
id: Option<String>,
#[arg(long)]
passphrase: Option<String>,
},
Remove {
#[arg(value_name = "PATH")]
path: String,
#[arg(value_name = "ID")]
id: Option<String>,
#[arg(long)]
passphrase: Option<String>,
},
}
#[derive(Subcommand)]
enum CacheOp {
Get {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long)]
ns: String,
#[arg(long)]
key: String,
#[arg(long)]
passphrase: Option<String>,
},
Put {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long)]
ns: String,
#[arg(long)]
key: String,
#[arg(long, conflicts_with = "file")]
value: Option<String>,
#[arg(long, conflicts_with = "value")]
file: Option<String>,
#[arg(long, default_value = "text")]
content_type: String,
#[arg(long)]
ttl: Option<u64>,
#[arg(long)]
passphrase: Option<String>,
},
Delete {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long)]
ns: String,
#[arg(long)]
key: String,
#[arg(long)]
passphrase: Option<String>,
},
Stats {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long)]
ns: Option<String>,
#[arg(long)]
passphrase: Option<String>,
},
Purge {
#[arg(default_value = "", hide_default_value = true)]
path: String,
#[arg(long)]
ns: Option<String>,
#[arg(long)]
expired: bool,
#[arg(long)]
passphrase: Option<String>,
},
}
fn tokenizer_note(path: &str, k: mnemo_engine::KeywordTokenizer) -> Option<String> {
match k {
mnemo_engine::KeywordTokenizer::V2 => None,
mnemo_engine::KeywordTokenizer::V1 => Some(format!(
"keywords match whole words as written; `mnemo compact {path}` rebuilds the \
index so parts of dotted names and possessives match too"
)),
mnemo_engine::KeywordTokenizer::Mixed => Some(format!(
"a build before v0.15 wrote to the keyword index, so parts of words match only \
some memories; `mnemo compact {path}` rebuilds it"
)),
}
}
fn upgrade_hint(path: &str, format_version: u16) -> Option<String> {
(format_version < 9).then(|| {
format!(
"v{format_version} file: run `mnemo compact {path}` to upgrade to v9 \
(upgrade every tool that reads it first)"
)
})
}
fn passphrase(arg: &Option<String>) -> std::result::Result<String, String> {
if let Some(p) = arg {
eprintln!(
"warning: passing the passphrase as `--passphrase` is insecure; \
it lands in shell history and process listings. Prefer the \
MNEMO_PASSPHRASE env var, or omit both to be prompted."
);
return Ok(p.clone());
}
if let Ok(p) = std::env::var("MNEMO_PASSPHRASE") {
return Ok(p);
}
if !std::io::IsTerminal::is_terminal(&std::io::stdin()) {
return Err("no passphrase: pass --passphrase or set MNEMO_PASSPHRASE".to_string());
}
rpassword::prompt_password("Passphrase: ")
.map_err(|e| format!("failed to read passphrase: {e}"))
}
static WAIT: std::sync::OnceLock<std::time::Duration> = std::sync::OnceLock::new();
fn wait_opts() -> mnemo_engine::SharedOptions {
let mut o = mnemo_engine::SharedOptions::default();
if let Some(w) = WAIT.get() {
o.deadline = *w;
}
o
}
fn parse_wait(s: &str) -> std::result::Result<std::time::Duration, String> {
let s = s.trim();
let (num, unit) = match s.find(|c: char| c.is_ascii_alphabetic()) {
Some(i) => s.split_at(i),
None => (s, "s"),
};
let n: f64 = num
.trim()
.parse()
.map_err(|_| format!("not a duration: {s:?} (try 10s, 500ms or 2m)"))?;
let secs = match unit.trim() {
"ms" => n / 1000.0,
"s" => n,
"m" => n * 60.0,
other => return Err(format!("unknown unit {other:?} in {s:?} (use ms, s or m)")),
};
if !secs.is_finite() || secs < 0.0 {
return Err(format!("not a duration: {s:?}"));
}
Ok(std::time::Duration::from_secs_f64(secs.min(1e9)))
}
fn open_r(path: &str, s: &inspect::Secret) -> mnemo_engine::Result<Mnemo> {
open_ro(path, s)
}
fn open_w(path: &str, s: &inspect::Secret, op: &str) -> mnemo_engine::Result<Mnemo> {
open_rw(path, s, op)
}
type Embedded = (Box<dyn mnemo_engine::Embedder>, Vec<Vec<f32>>);
fn embed_first(
path: &str,
cmd: Option<&str>,
name: Option<&str>,
normalize: bool,
timeout: u64,
query: &str,
texts: &[&str],
) -> std::result::Result<Option<Embedded>, String> {
let Ok(dimensions) = Mnemo::peek_dimensions(path) else {
return Ok(None);
};
let embedder = new_embedder(cmd, name, normalize, timeout, query, Some(dimensions))?;
let vectors = embedder.embed(texts).map_err(fmt)?;
Ok(Some((embedder, vectors)))
}
static MODEL_DIR: std::sync::OnceLock<Option<std::path::PathBuf>> = std::sync::OnceLock::new();
fn new_embedder(
cmd: Option<&str>,
name: Option<&str>,
normalize: bool,
timeout: u64,
query: &str,
dimensions: Option<usize>,
) -> std::result::Result<Box<dyn mnemo_engine::Embedder>, String> {
let Some(cmd) = cmd else {
if name.is_some() {
return Err("--embed-name needs --embed-cmd".into());
}
let builtin = builtin_embedder()?;
if let Some(d) = dimensions {
let width = builtin.identity().dimensions;
if d != width {
return Err(format!(
"this file is {d}-dimensional and the built-in embedder is {width}: pass \
the file's own embedder (--embed-cmd and --embed-name), or move the file \
to the built-in with `mnemo reembed <file> --embed-dims {width}`"
));
}
}
return Ok(builtin);
};
let name = name.ok_or_else(|| "--embed-cmd needs --embed-name".to_string())?;
let identity = mnemo_engine::EmbedderIdentity {
name: name.to_string(),
dimensions: dimensions.unwrap_or_default(),
normalize,
query_convention: query.to_string(),
};
Ok(Box::new(
mnemo_engine::EmbedCmd::new(cmd, identity)
.map_err(fmt)?
.with_timeout(std::time::Duration::from_secs(timeout)),
))
}
#[cfg(feature = "embed-candle")]
fn builtin_embedder() -> std::result::Result<Box<dyn mnemo_engine::Embedder>, String> {
let e = match MODEL_DIR.get().and_then(Option::as_deref) {
Some(dir) => mnemo_engine::BuiltinEmbedder::from_dir(dir),
None => mnemo_engine::BuiltinEmbedder::load_or_install(&mut |m| eprintln!("{m}")),
}
.map_err(fmt)?;
Ok(Box::new(e))
}
#[cfg(not(feature = "embed-candle"))]
fn builtin_embedder() -> std::result::Result<Box<dyn mnemo_engine::Embedder>, String> {
Err("this build of mnemo has no built-in embedder: pass --embed-cmd and --embed-name".into())
}
#[cfg(feature = "embed-candle")]
fn run_embedder(cmd: EmbedderCmd) -> std::result::Result<(), String> {
use mnemo_engine::builtin;
use mnemo_engine::Embedder;
let dir = builtin::model_dir().map_err(fmt)?;
let size = builtin::human_size(builtin::download_size());
match cmd {
EmbedderCmd::Install => {
if MODEL_DIR.get().is_some_and(Option::is_some) {
return Err(
"--model-dir loads a model of your own; there's nothing to install".into(),
);
}
println!(
"the built-in embedder: {}@{} ({size}), into {}",
builtin::MODEL,
builtin::REVISION,
dir.display()
);
let mut fetched = false;
builtin::install(&mut |m| {
fetched = true;
eprintln!("{m}")
})
.map_err(fmt)?;
builtin::BuiltinEmbedder::load().map_err(fmt)?;
println!(
"{}",
if fetched {
"installed"
} else {
"already installed"
}
);
}
EmbedderCmd::Status => {
println!("model: {}", builtin::MODEL);
println!("revision: {}", builtin::REVISION);
match MODEL_DIR.get().and_then(Option::as_deref) {
Some(d) => {
let e = builtin::BuiltinEmbedder::from_dir(d).map_err(fmt)?;
println!("model dir: {} (--model-dir)", d.display());
println!(
"files: {}",
if e.is_builtin() {
"the pinned files (the built-in embedder)"
} else {
"not the pinned files (an identity of their own)"
}
);
println!("identity: {}", e.identity().name);
}
None => {
println!("identity: {}", builtin::identity().name);
println!("cache: {}", dir.display());
println!(
"installed: {}",
if !builtin::is_installed() {
format!(
"no ({size} to fetch on first use, or `mnemo embedder install`)"
)
} else {
match builtin::verify_installed() {
Ok(()) => "yes (every file matches its pinned SHA-256)".into(),
Err(mnemo_engine::MnemoError::Invalid(why)) => {
format!("no ({why})")
}
Err(e) => format!("no ({e})"),
}
}
);
}
}
}
}
Ok(())
}
#[cfg(not(feature = "embed-candle"))]
fn run_embedder(_: EmbedderCmd) -> std::result::Result<(), String> {
Err("this build of mnemo has no built-in embedder (pass --embed-cmd and --embed-name)".into())
}
fn serve_builtin(
p: &std::path::Path,
shared: Option<mnemo_engine::SharedOptions>,
) -> mnemo_engine::Result<()> {
#[cfg(feature = "embed-candle")]
{
let dir = MODEL_DIR.get().and_then(Option::as_deref);
mnemo_engine::mcp::serve_stdio_with_builtin(p, dir, shared)
}
#[cfg(not(feature = "embed-candle"))]
{
mnemo_engine::mcp::serve_stdio_with_spec(p, None, shared)
}
}
fn builtin_ready() -> bool {
#[cfg(feature = "embed-candle")]
{
MODEL_DIR.get().is_some_and(Option::is_some) || mnemo_engine::builtin::is_installed()
}
#[cfg(not(feature = "embed-candle"))]
{
false
}
}
fn builtin_identity() -> Option<mnemo_engine::EmbedderIdentity> {
#[cfg(feature = "embed-candle")]
{
Some(mnemo_engine::builtin::identity())
}
#[cfg(not(feature = "embed-candle"))]
{
None
}
}
fn open_ro(path: &str, s: &inspect::Secret) -> mnemo_engine::Result<Mnemo> {
match s {
inspect::Secret::Passphrase(p) => Mnemo::open_read_only_waiting(path, p, wait_opts()),
inspect::Secret::Key(k) => Mnemo::open_read_only_waiting_with_key(path, k, wait_opts()),
}
.map(warn_notices)
}
fn warn_notices(db: Mnemo) -> Mnemo {
for n in db.notices() {
eprintln!("warning: {n}");
}
db
}
static SOURCE: std::sync::OnceLock<(String, Option<String>)> = std::sync::OnceLock::new();
fn secret_for(
path: &str,
pp: &Option<String>,
key_file: &Option<String>,
) -> std::result::Result<inspect::Secret, String> {
use mnemo_engine::keys::{self, Resolution, SecretKind};
if let Some(k) = key_file {
let _ = SOURCE.set((format!("--key-file ({k})"), None));
return Ok(inspect::Secret::Key(inspect::read_key_file(k)?));
}
if pp.is_some() {
let _ = SOURCE.set(("--passphrase".into(), None));
return Ok(inspect::Secret::Passphrase(zeroize::Zeroizing::new(
passphrase(pp)?,
)));
}
let store = keys::default_store();
match keys::resolve(path, store.as_deref(), keys::CLI_COMMAND_TIMEOUT).map_err(fmt)? {
Resolution::Found(r) => {
for n in &r.notes {
eprintln!("note: {n}");
}
let _ = SOURCE.set((r.source.to_string(), r.next.map(|s| s.to_string())));
Ok(r.secret)
}
Resolution::NoSource { kind, notes } => {
for n in ¬es {
eprintln!("note: {n}");
}
match kind {
SecretKind::Passphrase => {
let p = passphrase(&None)?;
let _ = SOURCE.set(("the prompt".into(), None));
Ok(inspect::Secret::Passphrase(zeroize::Zeroizing::new(p)))
}
SecretKind::Key => Err(format!(
"no key for {path}: it uses a key, and none of MNEMO_KEY, MNEMO_KEY_FILE, \
MNEMO_KEY_COMMAND or {} has one; pass --key-file, or --passphrase if it \
was given a passphrase",
store
.as_deref()
.map(|s| s.describe())
.unwrap_or_else(|| "a key store (none in this build yet)".into())
)),
}
}
}
}
fn open_rw(path: &str, s: &inspect::Secret, op: &str) -> mnemo_engine::Result<Mnemo> {
match s {
inspect::Secret::Passphrase(p) => Mnemo::open_exclusive(path, p, op, wait_opts()),
inspect::Secret::Key(k) => Mnemo::open_exclusive_with_key(path, k, op, wait_opts()),
}
.map(warn_notices)
.map(|mut db| {
db.set_author(env_identity().0);
db
})
}
pub(crate) fn env_identity() -> (Option<String>, Option<String>) {
static NOTED: std::sync::Once = std::sync::Once::new();
let read = |name: &str| -> Option<String> {
let v = std::env::var(name).ok()?;
let v = v.trim().to_string();
if v.is_empty() {
return None;
}
if mnemo_engine::valid_agent_id(&v) {
Some(v)
} else {
NOTED.call_once(|| {
eprintln!(
"mnemo: note: {name} isn't 1 to 64 of letters, digits, '.', '_' and '-'; \
it's ignored"
)
});
None
}
};
(read("MNEMO_AGENT"), read("MNEMO_ROLE"))
}
#[derive(clap::Args, Debug, Default)]
struct AsArgs {
#[arg(long = "as", value_name = "AGENT", global = true)]
agent: Option<String>,
#[arg(long, value_name = "ROLE", global = true)]
role: Option<String>,
}
impl AsArgs {
fn resolve_for_write(&self) -> std::result::Result<(Option<String>, Option<String>), String> {
for (name, given) in [("MNEMO_AGENT", &self.agent), ("MNEMO_ROLE", &self.role)] {
if given.is_some() {
continue;
}
if let Ok(v) = std::env::var(name) {
let v = v.trim();
if !v.is_empty() && !mnemo_engine::valid_agent_id(v) {
return Err(format!(
"{name} isn't 1 to 64 of letters, digits, '.', '_' and '-'; fix it, or \
give --as/--role"
));
}
}
}
self.resolve()
}
fn resolve(&self) -> std::result::Result<(Option<String>, Option<String>), String> {
let (env_agent, env_role) = env_identity();
let check = |flag: &str, v: &Option<String>| -> std::result::Result<(), String> {
match v {
Some(x) if !mnemo_engine::valid_agent_id(x) => Err(format!(
"{flag} {x:?}: 1 to 64 of letters, digits, '.', '_' and '-'"
)),
_ => Ok(()),
}
};
check("--as", &self.agent)?;
check("--role", &self.role)?;
Ok((
self.agent.clone().or(env_agent),
self.role.clone().or(env_role),
))
}
}
fn mistagged_line(db: &mut mnemo_engine::Mnemo) -> Option<String> {
let n = db.mistagged_coordination().ok()?;
(n > 0).then(|| {
format!(
"{n} coordination record{} tagged as facts (an older mnemo rewrote this brain); \
`mnemo compact` fixes it",
if n == 1 { " is" } else { "s are" }
)
})
}
fn note_mistagged(db: &mut mnemo_engine::Mnemo) {
static ONCE: std::sync::Once = std::sync::Once::new();
if let Some(line) = mistagged_line(db) {
ONCE.call_once(|| eprintln!("mnemo: warning: {line}"));
}
}
fn parse_ttl(s: &str) -> std::result::Result<i64, String> {
let s = s.trim();
let bad = || format!("--ttl {s:?}: seconds, or 90s, 15m, 2h");
let (n, mult) = match s.char_indices().last() {
Some((i, 's')) => (&s[..i], 1),
Some((i, 'm')) => (&s[..i], 60),
Some((i, 'h')) => (&s[..i], 3_600),
Some((i, 'd')) => (&s[..i], 86_400),
_ => (s, 1),
};
n.parse::<i64>()
.ok()
.and_then(|n| n.checked_mul(mult))
.ok_or_else(bad)
}
fn print_message(m: &mnemo_engine::Message) {
println!(
"{} {} -> {} [{}{}] {}",
m.id,
m.from,
m.to,
m.status,
if m.hops > 0 {
format!(", hop {}", m.hops)
} else {
String::new()
},
m.subject
);
for l in m.body.lines() {
println!(" {l}");
}
if !m.refs.is_empty() {
println!(" refs: {}", m.refs.join(", "));
}
}
fn message_json(m: &mnemo_engine::Message) -> serde_json::Value {
serde_json::json!({
"id": m.id.to_string(), "to": m.to, "from": m.from, "subject": m.subject,
"body": m.body, "refs": m.refs, "conversation": m.conversation, "hops": m.hops,
"status": m.status, "delivery": m.delivery, "created_at": m.created_at,
"acked_at": m.acked_at,
})
}
#[derive(clap::Args, Debug, Default)]
struct FreshArgs {
#[arg(long, value_parser = ["public", "team", "private"])]
visibility: Option<String>,
#[arg(long, value_name = "WHEN")]
review_by: Option<String>,
#[arg(long, value_name = "WHEN")]
as_of: Option<String>,
}
impl FreshArgs {
fn keys(&self) -> std::result::Result<serde_json::Map<String, serde_json::Value>, String> {
let mut m = serde_json::Map::new();
if let Some(v) = &self.visibility {
m.insert(mnemo_engine::MNEMO_META_VISIBILITY.into(), v.clone().into());
}
if let Some(w) = &self.review_by {
m.insert(
mnemo_engine::MNEMO_META_REVIEW_BY.into(),
parse_when(w, true)
.map_err(|e| format!("--review-by: {e}"))?
.into(),
);
}
if let Some(w) = &self.as_of {
m.insert(
mnemo_engine::MNEMO_META_AS_OF.into(),
parse_when(w, false)
.map_err(|e| format!("--as-of: {e}"))?
.into(),
);
}
Ok(m)
}
}
fn parse_when(s: &str, ahead: bool) -> std::result::Result<i64, String> {
let s = s.trim();
if let Ok(n) = s.parse::<i64>() {
return if n >= 0 {
Ok(n)
} else {
Err(format!("{s:?} is before 1970"))
};
}
let bad = || format!("{s:?} isn't a duration (30d, 12h), a date (2026-12-01) or unix seconds");
if let Some((_, mult)) = [
('w', 604_800),
('d', 86_400),
('h', 3_600),
('m', 60),
('s', 1),
]
.iter()
.find(|(u, _)| s.ends_with(*u))
{
let n: i64 = s[..s.len() - 1].parse().map_err(|_| bad())?;
let now = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map_or(0, |d| d.as_secs() as i64);
let d = n.checked_mul(*mult).ok_or_else(bad)?;
return Ok(if ahead { now + d } else { (now - d).max(0) });
}
let parts: Vec<&str> = s.split('-').collect();
if let [y, m, d] = parts[..] {
let (y, m, d): (i64, i64, i64) = (
y.parse().map_err(|_| bad())?,
m.parse().map_err(|_| bad())?,
d.parse().map_err(|_| bad())?,
);
if !(1..=12).contains(&m) || !(1..=31).contains(&d) || y < 1970 {
return Err(bad());
}
let (yy, mm) = if m <= 2 { (y - 1, m + 9) } else { (y, m - 3) };
let era = yy.div_euclid(400);
let yoe = yy - era * 400;
let doy = (153 * mm + 2) / 5 + d - 1;
let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
let days = era * 146_097 + doe - 719_468;
return Ok(days * 86_400);
}
Err(bad())
}
fn new_passphrase(arg: &Option<String>, env_var: &str) -> std::result::Result<String, String> {
if let Some(p) = arg {
eprintln!(
"warning: passing the passphrase as a flag is insecure; it lands \
in shell history and process listings. Prefer the {env_var} env \
var, or omit both to be prompted twice."
);
return Ok(p.clone());
}
if let Ok(p) = std::env::var(env_var) {
return Ok(p);
}
if !std::io::IsTerminal::is_terminal(&std::io::stdin()) {
return Err(format!("no passphrase: pass the flag or set {env_var}"));
}
prompt_new_passphrase()
}
fn serve_path(path: &str) -> std::result::Result<std::path::PathBuf, String> {
let given = std::path::Path::new(path);
let project = std::env::var_os("CLAUDE_PROJECT_DIR")
.map(std::path::PathBuf::from)
.filter(|d| d.is_absolute());
let resolved = match (&project, given.is_relative()) {
(Some(dir), true) => {
let r = dir.join(given);
eprintln!(
"mnemo mcp: {path} is relative to CLAUDE_PROJECT_DIR: {}",
r.display()
);
r
}
_ => given.to_path_buf(),
};
if !resolved.is_file() {
return Err(format!(
"no brain at {}; the MCP server never creates one (make one with `mnemo init`)",
resolved.display()
));
}
Ok(resolved)
}
fn prompt_new_passphrase() -> std::result::Result<String, String> {
let first = rpassword::prompt_password("New passphrase: ")
.map_err(|e| format!("failed to read passphrase: {e}"))?;
let second = rpassword::prompt_password("Confirm passphrase: ")
.map_err(|e| format!("failed to read passphrase: {e}"))?;
if first != second {
return Err("passphrases do not match".to_string());
}
Ok(first)
}
fn show_recovery_code(path: &str, key: &[u8; 32]) {
use mnemo_engine::keys;
match keys::display::refusal_reason() {
None => {
if let Err(e) = keys::display::show(&keys::recovery::encode(key)) {
eprintln!(
"note: the recovery code couldn't be shown ({e}); run `mnemo recovery-code \
{path}` in a terminal of your own"
);
}
}
Some(why) => eprintln!(
"note: {} ({why})",
keys::display::REFUSAL.replace("<file>", path)
),
}
}
fn resolve_query(
inline: Option<String>,
file: Option<String>,
) -> std::result::Result<Vec<f32>, String> {
let text = match (inline, file) {
(Some(s), None) => s,
(None, Some(p)) => {
if p == "-" {
use std::io::Read;
let mut buf = String::new();
std::io::stdin()
.read_to_string(&mut buf)
.map_err(|e| format!("reading stdin: {e}"))?;
buf
} else {
std::fs::read_to_string(&p).map_err(|e| format!("reading {p}: {e}"))?
}
}
(Some(_), Some(_)) => {
return Err("pass only one of --query or --query-file".into());
}
(None, None) => {
return Err("missing query: pass --query <floats> or --query-file <path|->".into());
}
};
parse_query_text(&text)
}
fn parse_query_text(text: &str) -> std::result::Result<Vec<f32>, String> {
let trimmed = text.trim();
if trimmed.is_empty() {
return Err("query text was empty".into());
}
if trimmed.starts_with('[') {
return serde_json::from_str::<Vec<f32>>(trimmed)
.map_err(|e| format!("invalid JSON array of floats: {e}"));
}
trimmed
.split(|c: char| c == ',' || c.is_whitespace())
.filter(|s| !s.is_empty())
.map(|t| {
t.parse::<f32>()
.map_err(|e| format!("bad float '{t}': {e}"))
})
.collect()
}
fn parse_ulid(s: &str) -> std::result::Result<Ulid, String> {
Ulid::from_string(s.trim()).map_err(|e| format!("bad ULID '{s}': {e}"))
}
fn parse_filter_expr(
expr: &str,
f: mnemo_engine::Filter,
) -> std::result::Result<mnemo_engine::Filter, String> {
if let Some(key) = expr.strip_suffix(":exists") {
if key.is_empty() {
return Err(format!("empty key in --filter '{expr}'"));
}
return Ok(f.metadata_exists(key.to_string()));
}
let (lhs, rhs) = expr
.split_once('=')
.ok_or_else(|| format!("bad --filter '{expr}': expected key=value or key:op=value"))?;
let (key, op) = match lhs.split_once(':') {
Some((k, o)) => (k, Some(o)),
None => (lhs, None),
};
if key.is_empty() {
return Err(format!("empty key in --filter '{expr}'"));
}
match op {
Some("in") => {
let values: Vec<serde_json::Value> = rhs
.split(',')
.map(|s| parse_filter_value(s.trim()))
.collect();
Ok(f.metadata_in(key.to_string(), values))
}
Some("gte") => {
let n: f64 = rhs
.parse()
.map_err(|e| format!("bad :gte number in --filter '{expr}': {e}"))?;
Ok(f.metadata_range(key.to_string(), Some(n), None))
}
Some("lte") => {
let n: f64 = rhs
.parse()
.map_err(|e| format!("bad :lte number in --filter '{expr}': {e}"))?;
Ok(f.metadata_range(key.to_string(), None, Some(n)))
}
Some(other) => Err(format!(
"unknown operator ':{other}' in --filter '{expr}' (want :exists, :in, :gte, :lte)"
)),
None => Ok(f.metadata_eq(key.to_string(), parse_filter_value(rhs))),
}
}
fn parse_filter_value(s: &str) -> serde_json::Value {
if let Ok(v) = serde_json::from_str::<serde_json::Value>(s) {
v
} else {
serde_json::Value::String(s.to_string())
}
}
fn parse_memory_types(s: &str) -> std::result::Result<Vec<MemoryType>, String> {
s.split(',')
.map(|t| t.trim())
.filter(|t| !t.is_empty())
.map(|t| MemoryType::parse(t).ok_or_else(|| format!("unknown memory type '{t}'")))
.collect()
}
fn parse_metric(s: &str) -> std::result::Result<Metric, String> {
match s.trim().to_ascii_lowercase().as_str() {
"cosine" | "cos" => Ok(Metric::Cosine),
"l2" | "euclidean" => Ok(Metric::L2),
"dot" | "ip" => Ok(Metric::Dot),
other => Err(format!("unknown metric '{other}' (use cosine, l2, or dot)")),
}
}
#[derive(Copy, Clone, Debug, PartialEq, Eq, ValueEnum)]
#[clap(rename_all = "lowercase")]
enum OutputFormat {
Table,
Json,
Jsonl,
}
impl std::fmt::Display for OutputFormat {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(match self {
OutputFormat::Table => "table",
OutputFormat::Json => "json",
OutputFormat::Jsonl => "jsonl",
})
}
}
fn truncate(s: &str, max: usize) -> String {
if s.chars().count() <= max {
return s.to_string();
}
let mut out: String = s.chars().take(max.saturating_sub(1)).collect();
out.push('…');
out
}
fn memory_to_json(m: &Memory, include_vector: bool) -> serde_json::Value {
let mut v = serde_json::to_value(m).unwrap_or_else(|_| serde_json::json!({}));
if !include_vector {
if let Some(obj) = v.as_object_mut() {
obj.remove("vector");
}
}
v
}
fn print_memory(
m: &Memory,
format: OutputFormat,
verbose: bool,
include_vector: bool,
whole: bool,
) {
match format {
OutputFormat::Table => {
let id = m.id.to_string();
let imp = format!("imp={:.2}", m.importance);
if verbose {
println!(
"{} [{}] agent={} {}",
id,
m.memory_type.as_str(),
m.agent_id,
imp
);
println!(" content : {}", m.content);
if let Some(sid) = &m.session_id {
println!(" session : {sid}");
}
println!(
" scope : {}",
match m.scope {
mnemo_engine::Scope::Private => "private",
mnemo_engine::Scope::Shared => "shared",
}
);
println!(
" times : created={} accessed={} access_count={}",
m.created_at, m.accessed_at, m.access_count
);
if let Some(ttl) = m.ttl_secs {
println!(" ttl_secs: {ttl}");
}
if !m.metadata.is_empty() {
let meta = serde_json::Value::Object(m.metadata.clone());
println!(" meta : {meta}");
}
} else {
println!(
"{} [{}] agent={} {} {}",
id,
m.memory_type.as_str(),
m.agent_id,
imp,
if whole {
m.content.clone()
} else {
truncate(&m.content, 80)
},
);
}
}
OutputFormat::Json => {
let v = memory_to_json(m, include_vector);
println!(
"{}",
serde_json::to_string_pretty(&v).unwrap_or_else(|_| "{}".into())
);
}
OutputFormat::Jsonl => {
let v = memory_to_json(m, include_vector);
println!(
"{}",
serde_json::to_string(&v).unwrap_or_else(|_| "{}".into())
);
}
}
}
fn print_memories(items: &[Memory], total: usize, format: OutputFormat, include_vector: bool) {
match format {
OutputFormat::Table => {
if items.is_empty() {
println!("no memories");
return;
}
println!("showing {} of {} memories", items.len(), total);
for m in items {
print_memory(m, OutputFormat::Table, false, false, false);
}
}
OutputFormat::Json => {
let arr: Vec<_> = items
.iter()
.map(|m| memory_to_json(m, include_vector))
.collect();
let doc = serde_json::json!({ "total": total, "count": arr.len(), "memories": arr });
println!(
"{}",
serde_json::to_string_pretty(&doc).unwrap_or_else(|_| "{}".into())
);
}
OutputFormat::Jsonl => {
for m in items {
println!(
"{}",
serde_json::to_string(&memory_to_json(m, include_vector))
.unwrap_or_else(|_| "{}".into())
);
}
}
}
}
fn print_recall_hits(hits: &[RecallResult], format: OutputFormat) {
match format {
OutputFormat::Table => {
if hits.is_empty() {
println!("no results");
return;
}
for h in hits {
println!(
"score={:.3} sim={:.3} [{}] {} {}",
h.score,
h.similarity,
h.memory.memory_type.as_str(),
h.memory.id,
truncate(&h.memory.content, 80),
);
}
}
OutputFormat::Json => {
let arr: Vec<_> = hits
.iter()
.map(|h| {
serde_json::json!({
"score": h.score,
"similarity": h.similarity,
"memory": memory_to_json(&h.memory, false),
})
})
.collect();
let doc = serde_json::json!({ "count": arr.len(), "hits": arr });
println!(
"{}",
serde_json::to_string_pretty(&doc).unwrap_or_else(|_| "{}".into())
);
}
OutputFormat::Jsonl => {
for h in hits {
let line = serde_json::json!({
"score": h.score,
"similarity": h.similarity,
"memory": memory_to_json(&h.memory, false),
});
println!(
"{}",
serde_json::to_string(&line).unwrap_or_else(|_| "{}".into())
);
}
}
}
}
fn run() -> std::result::Result<(), String> {
let argv: Vec<std::ffi::OsString> = std::env::args_os().collect();
if let Some(a) = hook::parse_args(&argv) {
match a.wait.as_deref().map(parse_wait) {
Some(Ok(w)) => {
let _ = WAIT.set(w);
}
Some(Err(e)) => eprintln!("mnemo: hook: --wait: {e}; the default was used"),
None => {}
}
let _ = MODEL_DIR.set(a.model_dir.clone());
hook::run_args(a);
return Ok(());
}
let mut cli = Cli::parse();
let _ = WAIT.set(cli.wait);
let _ = MODEL_DIR.set(cli.model_dir.clone());
if let Some(dir) = &cli.dir {
std::env::set_current_dir(dir).map_err(|e| format!("-C {}: {e}", dir.display()))?;
}
shift_get_args(&mut cli.command)?;
let project_brain = resolve_brain_arg(&mut cli.command, cli.dir.is_some())?;
let moved = cli.dir.is_some();
match cli.command {
Command::Init {
path,
dimensions,
no_manifest,
passphrase: pp,
ask_passphrase,
key_file,
} => {
use mnemo_engine::keys;
let cfg = MnemoConfig {
dimensions,
..Default::default()
};
let mut write_manifest = |db: &mut Mnemo| -> Result<()> {
if !no_manifest {
db.remember(Memory::scaffold_manifest(dimensions))?;
db.flush()?;
}
Ok(())
};
let env_pp = std::env::var("MNEMO_PASSPHRASE").is_ok_and(|v| !v.is_empty());
let how = if pp.is_some() || ask_passphrase || env_pp {
let pp = if ask_passphrase {
prompt_new_passphrase()?
} else {
new_passphrase(&pp, "MNEMO_PASSPHRASE")?
};
let mut db = Mnemo::create(&path, &pp, cfg).map_err(fmt)?;
write_manifest(&mut db).map_err(fmt)?;
db.close().map_err(fmt)?;
"encrypted with a passphrase".to_string()
} else if let Some(kf) = &key_file {
if std::fs::symlink_metadata(kf).is_ok() {
return Err(format!("{kf} already exists; nothing was created"));
}
let mut persist =
|_salt: &[u8; 16], key: &[u8; 32]| keys::write_new_key_file(kf, key);
keys::create_generated(&path, cfg, &mut write_manifest, &mut persist)
.map_err(fmt)?;
format!("encrypted with a generated key, written to {kf} (mode 0600)")
} else {
let no_keychain = |why: String| {
format!(
"no keychain is available here{why}, so `mnemo init` can't keep a \
generated key, and nothing was created. To protect {path} with a \
passphrase, as v0.14 did: `mnemo init --ask-passphrase {path}` (or set \
MNEMO_PASSPHRASE). To write a generated key to a new file (mode 0600): \
`mnemo init --key-file <PATH> {path}`"
)
};
let Some(store) = keys::default_store() else {
return Err(no_keychain(String::new()));
};
store
.check_available()
.map_err(|e| no_keychain(format!(" ({e})")))?;
let label = path.clone();
let mut persist = |salt: &[u8; 16], key: &[u8; 32]| {
let entry = keys::StoredSecret::Key(zeroize::Zeroizing::new(*key));
keys::store_and_check(&*store, salt, &entry, &label)
};
let key = keys::create_generated(&path, cfg, &mut write_manifest, &mut persist)
.map_err(fmt)?;
println!(
"created {path} ({dimensions} dimensions), encrypted with a generated key"
);
println!(" → the key is in {}", store.describe());
show_recovery_code(&path, &key);
if !no_manifest {
println!(" → run `mnemo about {path}` to view its scaffold manifest");
}
return Ok(());
};
if no_manifest {
println!("created {path} ({dimensions} dimensions, {how}, no manifest)");
} else {
println!("created {path} ({dimensions} dimensions, {how}) with scaffold manifest");
println!(" → run `mnemo about {path}` to view it");
println!(" → replace it with one that records your embedder and conventions");
}
}
Command::Unlock { path } => {
use mnemo_engine::keys::{self, StoredSecret};
let nowhere = "there's nowhere to keep the key, so set MNEMO_KEY to the recovery \
code, or use --key-file";
let store = keys::default_store()
.ok_or_else(|| format!("no keychain is available here; {nowhere}"))?;
store
.check_available()
.map_err(|e| format!("{e}; {nowhere}"))?;
let info = keys::file_info(&path).map_err(fmt)?;
let typed =
zeroize::Zeroizing::new(if std::io::IsTerminal::is_terminal(&std::io::stdin()) {
rpassword::prompt_password("Recovery code: ")
.map_err(|e| format!("reading the recovery code: {e}"))?
} else {
let mut line = String::new();
std::io::Read::read_to_string(
&mut std::io::Read::take(std::io::stdin(), 256),
&mut line,
)
.map_err(|e| format!("reading the recovery code: {e}"))?;
line.lines().next().unwrap_or("").to_string()
});
let key = keys::recovery::parse(&typed).map_err(|e| e.to_string())?;
if !info.kdf.below_passphrase_floor() {
return Err(format!(
"{path} is protected by a passphrase, not a key, so a recovery code can't \
open it; nothing was stored"
));
}
if !Mnemo::key_opens(&path, &key).map_err(fmt)? {
return Err(format!(
"that recovery code is well formed but doesn't open {path}; nothing was \
stored"
));
}
match store.get(&info.salt).map_err(fmt)? {
Some(StoredSecret::Key(k)) if *k == *key => {
println!(
"{path} is already unlocked on this machine ({})",
store.describe()
);
return Ok(());
}
Some(_) => eprintln!(
"note: {} had another entry for {path}, which doesn't open it; replacing it",
store.describe()
),
None => {}
}
keys::store_and_check(&*store, &info.salt, &StoredSecret::Key(key), &path)
.map_err(fmt)?;
println!("unlocked {path}: its key is in {}", store.describe());
}
Command::RecoveryCode { path } => {
use mnemo_engine::keys::{self, StoredSecret};
let store = keys::default_store().ok_or_else(|| {
"no keychain is available here, so there's no stored key to show".to_string()
})?;
let info = keys::file_info(&path).map_err(fmt)?;
let entry = store
.get(&info.salt)
.map_err(fmt)?
.ok_or_else(|| format!("{} has no entry for {path}", store.describe()))?;
let key = match entry {
StoredSecret::Key(k) => k,
StoredSecret::Passphrase(_) => {
return Err(format!(
"{path} uses a passphrase; there's no recovery code"
))
}
};
if !Mnemo::key_opens(&path, &key).map_err(fmt)? {
return Err(format!(
"the key {} holds for {path} doesn't open it, so its code isn't shown",
store.describe()
));
}
if let Some(why) = keys::display::refusal_reason() {
return Err(format!(
"{} ({why})",
keys::display::REFUSAL.replace("<file>", &path)
));
}
keys::display::show(&keys::recovery::encode(&key))
.map_err(|e| format!("showing the recovery code: {e}"))?;
}
Command::Info {
path,
key_file,
passphrase: pp,
} => {
let bi = mnemo_engine::build_info();
println!("mnemo: v{} ({})", bi.version, bi.target);
println!("aes: {}", bi.aes_backend);
println!("polyval: {}", bi.polyval_backend);
let secret = secret_for(&path, &pp, &key_file)?;
let mut db = open_ro(&path, &secret).map_err(fmt)?;
let s = db.stats().map_err(fmt)?;
println!("path: {path}");
if let Some((src, _)) = SOURCE.get() {
println!("key source: {src}");
}
if let Some(note) = mnemo_engine::keys::kdf_grade_note(db.kdf_params(), secret.kind()) {
println!("kdf: {note}");
}
println!("format: v{}", s.format_version);
if let Some(hint) = upgrade_hint(&path, s.format_version) {
println!(" {hint}");
}
println!("memories: {}", s.memories);
println!("tombstoned: {}", s.deleted);
println!("dimensions: {}", s.dimensions);
println!("file bytes: {}", s.file_bytes);
println!("encrypted: {}", s.encrypted);
println!(
"wal region: {} pages ({} KiB)",
s.wal_pages,
s.wal_pages * 8
);
println!("recall: {}", s.recall_mode.as_str());
if let Some(k) = s.keyword_tokenizer {
println!("keywords: tokenizer {}", k.as_str());
if let Some(note) = tokenizer_note(&path, k) {
println!(" {note}");
}
}
println!("created at: {}", s.created_at);
println!("agents: {}", s.agents.join(", "));
match s.oldest_restorable_at {
Some(t) => println!(
"snapshots: {} retained, oldest {} ({} bytes pinned)",
s.snapshots_retained,
export::rfc3339(t),
s.snapshot_pinned_bytes
),
None => println!("snapshots: none"),
}
if s.fsyncs_last_flush == 0 {
println!("fsyncs/flush: — (no flush seen on this handle)");
} else {
println!("fsyncs/flush: {}", s.fsyncs_last_flush);
}
{
let cs = db.cache_stats(None);
println!(
"cache: {} entries, {} bytes (hits {}, misses {}, evict {})",
cs.entries, cs.bytes, cs.hits, cs.misses, cs.evictions
);
}
match s.index {
Some(ix) => {
println!(
"ann index: {} vectors, {} partitions, {} PQ subspaces",
ix.vectors, ix.partitions, ix.subspaces
);
println!(
" defaults: n_probe={}, n_rerank={}",
ix.n_probe, ix.n_rerank
);
}
None => println!("ann index: none (recall uses exact scan)"),
}
}
Command::Rekey {
path,
key_file,
passphrase: pp,
new_passphrase: new,
new_key,
store: keep,
new_key_file,
rotate,
} => {
use mnemo_engine::keys::{self, Secret};
let old = secret_for(&path, &pp, &key_file)?;
let new: Secret = if new_key {
Secret::Key(zeroize::Zeroizing::new(Mnemo::generate_key()))
} else {
Secret::Passphrase(zeroize::Zeroizing::new(new_passphrase(
&new,
"MNEMO_NEW_PASSPHRASE",
)?))
};
let mut db = open_rw(&path, &old, "rekey").map_err(fmt)?;
let old_word = match old.kind() {
keys::SecretKind::Passphrase => "passphrase",
keys::SecretKind::Key => "key",
};
let not_changed = |msg: String| {
if msg.contains("may open with either secret") {
msg
} else {
format!("{msg}; the {old_word} was not changed")
}
};
let mut stored_note = None;
if new_key || keep {
let Some(store) = keys::default_store() else {
return Err(
"--new-key and --store keep the new secret in a keychain, and none \
is available here; nothing was changed"
.into(),
);
};
store
.check_available()
.map_err(|e| format!("{e}; nothing was changed"))?;
let refused = keys::display::refusal_reason();
if new_key && !store.durable() && refused.is_some() && new_key_file.is_none() {
return Err(format!(
"{} doesn't promise its write is on disk before the rekey commits, and \
the new key's recovery code can't be shown here ({}); a power cut \
could leave the key nowhere. Run it at a terminal of your own, or add \
--new-key-file <PATH> to write the key to a new file too. Nothing was \
changed",
store.describe(),
refused.unwrap_or_default()
));
}
if let Some(f) = &new_key_file {
if std::fs::symlink_metadata(f).is_ok() {
return Err(format!("{f} already exists; nothing was changed"));
}
}
let mut before_commit = || -> Result<()> {
if let Secret::Key(k) = &new {
show_recovery_code(&path, k);
if let Some(f) = &new_key_file {
keys::write_new_key_file(f, k)?;
}
}
Ok(())
};
match keys::rekey_stored(&mut db, &new, &*store, &path, &mut before_commit) {
Ok(note) => stored_note = Some(note),
Err(e) => {
if e.new_secret_dropped {
if let Some(f) = &new_key_file {
let _ = std::fs::remove_file(f);
}
}
return Err(format!("{}; {}", not_changed(fmt(e.error)), e.entries));
}
}
} else if let Secret::Passphrase(p) = &new {
let kdf = db.kdf_params().for_passphrase();
db.rekey(p, kdf).map_err(|e| not_changed(fmt(e)))?;
}
let left = db.rekey_cleanup_error().map(str::to_owned);
db.close().map_err(fmt)?;
if let (Some(left), false) = (&left, rotate) {
eprintln!(
"warning: the new secret is in force, but part of the old key \
wrap's cleanup failed ({left}); run `mnemo rekey --rotate` to be sure \
the old secret opens nothing"
);
}
if let Some(note) = stored_note {
println!(" → {note}");
}
if rotate {
let r = match &new {
Secret::Passphrase(p) => Mnemo::compact_file_waiting(&path, p, wait_opts()),
Secret::Key(k) => Mnemo::compact_file_waiting_with_key(&path, k, wait_opts()),
}
.map_err(fmt)?;
println!(
"rekeyed and rotated {path}: a fresh data key, {} memories kept",
r.after
);
} else {
println!("rekeyed {path}");
println!(
"note: the data key is unchanged; after a leak, run \
`mnemo rekey --rotate` to revoke the old secret"
);
}
}
Command::Compact {
path,
key_file,
passphrase: pp,
} => {
let secret = secret_for(&path, &pp, &key_file)?;
let report = match &secret {
inspect::Secret::Passphrase(p) => {
Mnemo::compact_file_waiting(&path, p, wait_opts())
}
inspect::Secret::Key(k) => {
Mnemo::compact_file_waiting_with_key(&path, k, wait_opts())
}
}
.map_err(fmt)?;
println!(
"compacted {path} (v9): {} -> {} live memories",
report.before, report.after
);
if report.zero_vector_manifests + report.zero_vector_memories > 0 {
println!(
" all-zero vectors: {} legacy manifest memories given the sentinel \
vector, {} other memories carried unchanged",
report.zero_vector_manifests, report.zero_vector_memories
);
}
}
Command::Reembed {
path,
embed_cmd,
embed_name,
embed_normalize,
embed_query,
embed_dims,
embed_timeout,
key_file,
passphrase: pp,
} => {
let secret = secret_for(&path, &pp, &key_file)?;
let dims = match (&embed_cmd, embed_dims) {
(_, Some(d)) => Some(d),
(Some(_), None) => Some(Mnemo::peek_dimensions(&path).map_err(fmt)?),
(None, None) => None,
};
let embedder = new_embedder(
embed_cmd.as_deref(),
embed_name.as_deref(),
embed_normalize,
embed_timeout,
embed_query.as_deref().unwrap_or_default(),
dims,
)?;
let report = match &secret {
inspect::Secret::Passphrase(p) => {
Mnemo::reembed_file_waiting(&path, p, &embedder, wait_opts())
}
inspect::Secret::Key(k) => {
Mnemo::reembed_file_waiting_with_key(&path, k, &embedder, wait_opts())
}
}
.map_err(fmt)?;
let from = report
.from
.as_ref()
.map_or_else(|| "no recorded embedder".to_string(), |i| i.name.clone());
println!(
"re-embedded {path}: {} memories, {from} -> {} ({} dimensions)",
report.memories, report.to.name, report.to.dimensions
);
println!(
" (facts, superseded versions, essence and thread turns; {} manifest and {} \
thread links kept on their sentinel vector)",
report.manifests, report.thread_links
);
if report.cache_dropped > 0 {
println!(
" {} semantic cache entries dropped (their vectors have the old width)",
report.cache_dropped
);
}
}
Command::Verify {
path,
key_file,
passphrase: pp,
} => {
let secret = secret_for(&path, &pp, &key_file)?;
let mut db = open_ro(&path, &secret).map_err(fmt)?;
let report = db.verify_report().map_err(fmt)?;
println!(
"verified {} records — all pages decrypt and decode",
report.records
);
if report.zero_vector_memories > 0 {
eprintln!(
"warning: {} memories have an all-zero vector (written before v0.5's \
zero-vector rule); they score 0.0 on every vector query. `mnemo compact` \
carries them and gives a legacy manifest the sentinel vector.",
report.zero_vector_memories
);
}
if let Some(note) = report
.keyword_tokenizer
.filter(|k| *k == mnemo_engine::KeywordTokenizer::Mixed)
.and_then(|k| tokenizer_note(&path, k))
{
eprintln!("note: {note}");
}
if let Some(line) = mistagged_line(&mut db) {
eprintln!("warning: {line}");
}
}
Command::Import {
path,
file,
passphrase: pp,
} => {
let pp = secret_for(&path, &pp, &None)?;
let text =
std::fs::read_to_string(&file).map_err(|e| format!("cannot read {file}: {e}"))?;
let mut db = open_w(&path, &pp, "import").map_err(fmt)?;
let mut count = 0usize;
for (lineno, line) in text.lines().enumerate() {
let line = line.trim();
if line.is_empty() {
continue;
}
let m = memory_from_json(line).map_err(|e| format!("line {}: {e}", lineno + 1))?;
db.remember(m).map_err(fmt)?;
count += 1;
}
db.flush().map_err(fmt)?;
println!("imported {count} memories into {path}");
}
Command::Remember {
path,
text,
r#type,
importance,
agent,
metadata,
fresh,
key,
supersedes,
embed_cmd,
embed_name,
embed_normalize,
embed_query,
embed_timeout,
passphrase: pp,
} => {
if let Some(a) = &agent {
if !mnemo_engine::valid_agent_id(a) {
return Err(format!(
"--agent {a:?}: 1 to 64 of letters, digits, '.', '_' and '-'"
));
}
}
let pp = secret_for(&path, &pp, &None)?;
let mt = parse_memory_types(&r#type)?
.pop()
.ok_or_else(|| format!("unknown memory type: {type:?}", r#type = r#type))?;
let (mut db, vector) = match embed_first(
&path,
embed_cmd.as_deref(),
embed_name.as_deref(),
embed_normalize,
embed_timeout,
embed_query.as_deref().unwrap_or_default(),
&[text.as_str()],
)? {
Some((embedder, mut vectors)) => {
let vector = vectors
.pop()
.ok_or_else(|| "embedder returned no vector".to_string())?;
let mut db = open_w(&path, &pp, "remember").map_err(fmt)?;
db.set_embedder(embedder).map_err(fmt)?;
(db, vector)
}
None => {
let mut db = open_w(&path, &pp, "remember").map_err(fmt)?;
let embedder = new_embedder(
embed_cmd.as_deref(),
embed_name.as_deref(),
embed_normalize,
embed_timeout,
embed_query.as_deref().unwrap_or_default(),
Some(db.dimensions()),
)?;
db.set_embedder(embedder).map_err(fmt)?;
let vector = {
let embedder_ref = db
.embedder()
.ok_or_else(|| "no embedder registered".to_string())?;
let mut vectors = embedder_ref.embed(&[text.as_str()]).map_err(fmt)?;
vectors
.pop()
.ok_or_else(|| "embedder returned no vector".to_string())?
};
(db, vector)
}
};
let mut memory = Memory::new(text, mt, vector);
if let Some(i) = importance {
memory = memory.with_importance(i);
}
let agent = match agent {
Some(a) => Some(a),
None => db.default_agent().map_err(fmt)?,
};
if let Some(a) = agent {
memory = memory.with_agent(a);
}
if let Some(meta_str) = metadata {
let parsed: serde_json::Value = serde_json::from_str(&meta_str)
.map_err(|e| format!("invalid --metadata JSON: {e}"))?;
let obj = parsed
.as_object()
.ok_or_else(|| "--metadata must be a JSON object".to_string())?;
for (k, v) in obj {
memory.metadata.insert(k.clone(), v.clone());
}
}
memory.metadata.extend(fresh.keys()?);
match key {
None => {
let id = db.remember(memory).map_err(fmt)?;
db.flush().map_err(fmt)?;
println!("{id}");
}
Some(k) => {
let (id, outcome) = match &supersedes {
Some(old) => {
let old = parse_ulid(old)?;
db.remember_keyed_superseding(memory, &k, &old)
}
None => db.remember_keyed(memory, &k),
}
.map_err(fmt)?;
db.flush().map_err(fmt)?;
let outcome_str = match outcome {
mnemo_engine::WriteOutcome::Added => "added",
mnemo_engine::WriteOutcome::Superseded => "superseded",
mnemo_engine::WriteOutcome::Unchanged => "unchanged",
mnemo_engine::WriteOutcome::Updated => "updated",
};
let change = match outcome {
mnemo_engine::WriteOutcome::Superseded => db
.superseded_level_change(&id)
.map_err(fmt)?
.map(|(a, b)| format!(" ({a} → {b})"))
.unwrap_or_default(),
_ => String::new(),
};
println!("{id}\t{outcome_str}{change}");
}
}
}
Command::Index {
path,
passphrase: pp,
drop,
rebuild,
partitions,
subspaces,
n_probe,
n_rerank,
} => {
let pp = secret_for(&path, &pp, &None)?;
let mut db = open_w(&path, &pp, "index").map_err(fmt)?;
if drop {
db.drop_index();
db.flush().map_err(fmt)?;
println!("dropped ANN index on {path}");
} else if rebuild {
if partitions != 0 || subspaces != 0 || n_probe != 0 || n_rerank != 0 {
return Err(fmt(mnemo_engine::MnemoError::Invalid(
"--rebuild uses the auto-defaults; drop \
--partitions / --subspaces / --n-probe / \
--n-rerank, or build without --rebuild to pin \
explicit values"
.into(),
)));
}
let info = db.rebuild_index().map_err(fmt)?;
db.flush().map_err(fmt)?;
println!(
"rebuilt ANN index on {path}: {} vectors, {} partitions, {} PQ subspaces",
info.vectors, info.partitions, info.subspaces
);
} else {
let cfg = mnemo_engine::IndexConfig {
n_partitions: partitions,
pq_subspaces: subspaces,
n_probe,
n_rerank,
..Default::default()
};
let info = db.build_index_with(cfg).map_err(fmt)?;
db.flush().map_err(fmt)?;
println!(
"built ANN index on {path}: {} vectors, {} partitions, {} PQ subspaces",
info.vectors, info.partitions, info.subspaces
);
}
}
Command::Search {
path,
query,
query_file,
top_k,
visibility,
passphrase: pp,
} => {
let vis = mnemo_engine::VisibilitySet::parse(&visibility).map_err(fmt)?;
let pp = secret_for(&path, &pp, &None)?;
let q = resolve_query(query, query_file)?;
let mut db = open_r(&path, &pp).map_err(fmt)?;
let hits = db
.search_in(&q, top_k, mnemo_engine::Metric::Cosine, vis)
.map_err(fmt)?;
if hits.is_empty() {
println!("no results");
}
for (m, sim) in hits {
println!("{sim:.4} [{}] {}", m.memory_type.as_str(), m.content);
}
}
Command::About {
path,
format,
manifest_only,
visibility,
key_file,
passphrase: pp,
} => {
let vis = mnemo_engine::VisibilitySet::parse(&visibility).map_err(fmt)?;
let secret = secret_for(&path, &pp, &key_file)?;
let mut db = open_ro(&path, &secret).map_err(fmt)?;
let stats = db.stats().map_err(fmt)?;
let snapshots = db.snapshots().len();
let counts = db.kind_counts();
let now = db.coordination_now();
let mut entries = db.about_in(vis).map_err(fmt)?;
let essence = if manifest_only {
None
} else {
db.about_essence().map_err(fmt)?
};
let print_essence = || {
if let Some(render) = &essence {
println!();
println!("## Project essence");
println!();
print!("{render}");
}
};
if manifest_only {
entries.retain(|m| {
m.metadata
.get("topic")
.and_then(|v| v.as_str())
.map(|s| s.eq_ignore_ascii_case("manifest"))
.unwrap_or(false)
});
}
match format {
OutputFormat::Json | OutputFormat::Jsonl => {
let manifest = entries.iter().find(|m| {
m.metadata
.get("topic")
.and_then(|v| v.as_str())
.map(|s| s.eq_ignore_ascii_case("manifest"))
.unwrap_or(false)
});
let doc = serde_json::json!({
"path": path,
"stats": {
"format_version": stats.format_version,
"upgrade_hint": upgrade_hint(&path, stats.format_version),
"memories": stats.memories,
"counts": {
"facts": counts.facts,
"turns": counts.turns,
"essence": counts.essence,
"coordination": counts.coordination,
},
"dimensions": stats.dimensions,
"file_bytes": stats.file_bytes,
"encrypted": stats.encrypted,
"snapshots": snapshots,
"has_index": stats.index.is_some(),
},
"manifest": manifest.map(|m| memory_to_json(m, false)),
"onboarding": entries
.iter()
.map(|m| memory_to_json(m, false))
.collect::<Vec<_>>(),
"essence": essence.as_deref(),
});
println!(
"{}",
serde_json::to_string_pretty(&doc).unwrap_or_else(|_| "{}".into())
);
}
OutputFormat::Table => {
println!(
"# {} ({} memories: {} facts, {} turns, {} essence, {} coordination · {}-dim · {} · {} snapshots{})",
path,
stats.memories,
counts.facts,
counts.turns,
counts.essence,
counts.coordination,
stats.dimensions,
if stats.encrypted {
"encrypted"
} else {
"plaintext"
},
snapshots,
if stats.index.is_some() {
" · ANN index built"
} else {
""
},
);
if let Some(line) = mistagged_line(&mut db) {
println!("# {line}");
}
if let Some(hint) = upgrade_hint(&path, stats.format_version) {
println!("# {hint}");
}
if entries.is_empty() {
println!();
println!(
"(no onboarding memories — this database has no self-description.)"
);
println!("To make a database self-describing, store a memory with");
println!(
" metadata = {{\"area\": \"onboarding\", \"topic\": \"manifest\"}}"
);
println!("that introduces the project, embedder, and conventions.");
print_essence();
} else {
println!();
println!(
"## Onboarding briefing ({} entries, most important first)",
entries.len()
);
for m in &entries {
let topic = m
.metadata
.get("topic")
.and_then(|v| v.as_str())
.unwrap_or("");
let is_scaffold = m
.metadata
.get("scaffold")
.and_then(|v| v.as_bool())
.unwrap_or(false);
let head = if topic.eq_ignore_ascii_case("manifest") {
if is_scaffold {
format!(
"MANIFEST (scaffold — please replace) (importance={:.2})",
m.importance
)
} else {
format!("MANIFEST (importance={:.2})", m.importance)
}
} else if topic.is_empty() {
format!("(importance={:.2})", m.importance)
} else {
format!("[{}] (importance={:.2})", topic, m.importance)
};
let head = match mnemo_engine::stale_since(m, now) {
Some(t) => {
format!("{head} [stale since {}]", mnemo_engine::date_of(t))
}
None => head,
};
println!();
println!("### {head}");
println!("{}", m.content);
}
print_essence();
println!();
println!("## Quick start");
println!(
" mnemo list {path} # browse all live memories"
);
println!(" mnemo recall {path} --query VEC # multi-signal recall");
println!(" mnemo get {path} <ulid> --verbose # fetch one memory");
}
}
}
}
Command::Get {
path,
id,
format,
verbose,
vector,
passphrase: pp,
} => {
let pp = secret_for(&path, &pp, &None)?;
let ulid = parse_ulid(id.as_deref().unwrap_or_default())?;
let mut db = open_r(&path, &pp).map_err(fmt)?;
let m = db.get(&ulid).map_err(fmt)?;
print_memory(&m, format, verbose, vector, true);
}
Command::List {
path,
format,
r#type,
agent,
limit,
offset,
sort,
vector,
visibility,
key_file,
passphrase: pp,
} => {
let vis = mnemo_engine::VisibilitySet::parse(&visibility).map_err(fmt)?;
let secret = secret_for(&path, &pp, &key_file)?;
let types = match r#type {
Some(s) => Some(parse_memory_types(&s)?),
None => None,
};
let sort = sort.trim().to_ascii_lowercase();
if !matches!(sort.as_str(), "created" | "importance" | "id") {
return Err(format!(
"unknown sort '{sort}' (use created, importance, or id)"
));
}
let mut db = open_ro(&path, &secret).map_err(fmt)?;
let mut all = db.memories().map_err(fmt)?;
all.retain(|m| vis.shows(m));
if let Some(ts) = &types {
all.retain(|m| ts.contains(&m.memory_type));
}
if let Some(a) = &agent {
all.retain(|m| &m.agent_id == a);
}
let total_after_filter = all.len();
if limit.is_none() && total_after_filter > 10_000 {
eprintln!(
"warning: {} memories — consider --limit; printing all anyway",
total_after_filter
);
}
match sort.as_str() {
"created" => all.sort_by_key(|m| m.created_at),
"importance" => {
all.sort_by(|a, b| b.importance.total_cmp(&a.importance));
}
"id" => all.sort_by_key(|m| m.id),
_ => unreachable!(),
}
let start = offset.min(all.len());
let end = match limit {
Some(n) => (start + n).min(all.len()),
None => all.len(),
};
let mut page: Vec<Memory> = all[start..end].to_vec();
if vis.private && matches!(format, OutputFormat::Table) {
for m in page.iter_mut() {
if mnemo_engine::visibility_of(m) == "private" {
m.content = format!("[private] {}", m.content);
}
}
}
print_memories(&page, total_after_filter, format, vector);
}
Command::Export {
path,
format,
r#type,
agent,
git,
visibility,
output,
key_file,
passphrase: pp,
} => {
let secret = secret_for(&path, &pp, &key_file)?;
let types = match r#type {
Some(s) => Some(parse_memory_types(&s)?),
None => None,
};
if let Some(o) = &output {
if let (Ok(a), Ok(b)) = (std::fs::canonicalize(o), std::fs::canonicalize(&path)) {
if a == b {
return Err(format!("refusing to write the export over {path} itself"));
}
}
}
let mut db = open_ro(&path, &secret).map_err(fmt)?;
let summary = db.stats_summary();
let facts = export::FileFacts {
format_version: summary.format_version,
dimensions: summary.dimensions,
};
let mut all = db.memories().map_err(fmt)?;
drop(db);
let vis = mnemo_engine::VisibilitySet::parse(&visibility).map_err(fmt)?;
let vis = if git {
mnemo_engine::VisibilitySet {
private: false,
..vis
}
} else {
vis
};
let before = all.len();
let private = all
.iter()
.filter(|m| mnemo_engine::visibility_of(m) == "private")
.count();
all.retain(|m| vis.shows(m));
if vis.private && private > 0 {
eprintln!(
"mnemo: the export includes {private} private record{}",
if private == 1 { "" } else { "s" }
);
} else if private > 0 && before != all.len() {
eprintln!(
"mnemo: {private} private record{} left out{}",
if private == 1 { " was" } else { "s were" },
if git {
" (`--git` never writes them)"
} else {
" (`--visibility all` includes them)"
}
);
}
let opts = export::ExportOptions {
format,
git,
types,
agent,
};
let selected = export::select(all, &opts);
let body = export::render(&selected, &opts, &facts);
if git {
eprintln!(
"note: the export is plaintext, written by mnemo {} with `--git` to be \
committed; read the diff first",
env!("CARGO_PKG_VERSION")
);
} else {
eprintln!(
"warning: the export is plaintext, not encrypted; keep it as safe as \
the file's passphrase"
);
}
match output {
Some(p) => {
export::write_private(&p, &body)?;
eprintln!("exported {} memories to {p}", selected.len());
}
None => {
use std::io::Write;
let _ = std::io::stdout().lock().write_all(body.as_bytes());
}
}
}
Command::Inspect {
path,
port,
open,
idle_timeout,
key_file,
passphrase: pp,
} => {
let idle = inspect::parse_idle(&idle_timeout)?;
let secret = secret_for(&path, &pp, &key_file)?;
let loaded = inspect::load(&path, &secret)?;
let listener = inspect::bind(port).map_err(|e| format!("binding 127.0.0.1: {e}"))?;
let port = listener
.local_addr()
.map_err(|e| format!("binding 127.0.0.1: {e}"))?
.port();
let token = inspect::new_token();
let code = inspect::new_token();
let url = format!("http://127.0.0.1:{port}/?c={code}");
println!("inspecting {path} (read-only; the file is read once and closed)");
println!("{url}");
println!("the link opens one tab (it works once); press Ctrl-C to stop");
{
use std::io::Write;
let _ = std::io::stdout().flush();
}
let watch = inspect::Watch::new();
if open {
if let Err(e) = inspect::open_browser(&url, watch.clone()) {
eprintln!("warning: couldn't open a browser ({e}); open the URL above");
} else if cfg!(target_os = "linux") {
eprintln!(
"note: if the browser says the file can't be found (a snap or \
flatpak browser can't read /tmp), copy the link above instead"
);
}
}
let state = std::sync::Arc::new(std::sync::Mutex::new(inspect::State::new(
path, secret, loaded,
)));
inspect::serve(listener, token, code, state, watch, idle)
.map_err(|e| format!("serving: {e}"))?;
}
Command::Recall {
path,
query,
query_file,
text,
keywords,
no_keywords,
top_k,
visibility,
format,
r#type,
agent,
metric,
n_probe,
n_rerank,
no_track,
session,
filter,
max_bytes,
embed_cmd,
embed_name,
embed_normalize,
embed_query,
embed_timeout,
key_file,
passphrase: pp,
} => {
let secret = secret_for(&path, &pp, &key_file)?;
if query.is_none() && query_file.is_none() && text.is_none() && keywords.is_none() {
return Err(
"recall requires one of --query / --query-file / --text / --keywords".into(),
);
}
let open_recall =
|path: &str,
secret: &inspect::Secret,
no_track: bool|
-> std::result::Result<(Mnemo, bool), mnemo_engine::MnemoError> {
if no_track {
return open_ro(path, secret).map(|db| (db, true));
}
match open_rw(path, secret, "recall") {
Ok(db) => Ok((db, false)),
Err(mnemo_engine::MnemoError::Locked { .. }) => {
let db = match secret {
inspect::Secret::Passphrase(p) => Mnemo::open_read_only(path, p),
inspect::Secret::Key(k) => Mnemo::open_read_only_with_key(path, k),
}?;
eprintln!(
"mnemo: another process holds the lock on {path}; \
running recall read-only with --no-track"
);
Ok((db, true))
}
Err(mnemo_engine::MnemoError::FormatTooOld { version: 8 }) => {
let db = open_ro(path, secret)?;
eprintln!(
"mnemo: {path} is a v8 file, which opens read-only; running \
recall with --no-track (`mnemo compact` converts it to v9)"
);
Ok((db, true))
}
Err(e) => Err(e),
}
};
let mut keyword: Option<String> = if no_keywords {
Some(String::new())
} else {
keywords
};
let mut query_text: Option<String> = None;
let (q, mut db_opt, mut effective_no_track) = match text {
Some(text) => {
let mut builtin =
(embed_cmd.is_none() && builtin_ready()).then(builtin_embedder);
let (mut db, mut effective_no_track) =
open_recall(&path, &secret, no_track).map_err(fmt)?;
if embed_cmd.is_none() && builtin.is_none() {
let recorded = db.embedder_identity().map_err(fmt)?;
if recorded.is_some() && recorded == builtin_identity() {
drop(db);
builtin = Some(builtin_embedder());
(db, effective_no_track) =
open_recall(&path, &secret, no_track).map_err(fmt)?;
}
}
let embedder = if embed_cmd.is_some() {
Ok(new_embedder(
embed_cmd.as_deref(),
embed_name.as_deref(),
embed_normalize,
embed_timeout,
embed_query.as_deref().unwrap_or_default(),
Some(db.dimensions()),
)?)
} else {
let recorded = db.embedder_identity().map_err(fmt)?;
match builtin {
Some(Ok(b)) if recorded.as_ref() == Some(&b.identity()) => Ok(b),
Some(Err(e)) => Err(e),
_ => Err(match recorded {
Some(r) => format!(
"this file's embedder is {:?}, not the built-in (pass \
--embed-cmd and --embed-name for it)",
r.name
),
None if builtin_identity().is_none() => {
"this build has no built-in embedder".to_string()
}
None => "this file records no embedder yet".to_string(),
}),
}
};
match embedder {
Ok(embedder) => {
db.set_embedder(embedder).map_err(fmt)?;
let vector = {
let embedder_ref = db.embedder().ok_or_else(|| {
"embedder vanished after set_embedder".to_string()
})?;
let mut vs =
embedder_ref.embed_query(&[text.as_str()]).map_err(fmt)?;
vs.pop()
.ok_or_else(|| "embedder returned no vector".to_string())?
};
query_text = Some(text);
(vector, Some(db), effective_no_track)
}
Err(why) => {
if no_keywords {
return Err(format!(
"--no-keywords with --text needs an embedder: {why}"
));
}
if db.stats_summary().format_version < 9 {
return Err(format!(
"--text needs an embedder on a v8 file (or a v9 file, \
which can recall by keyword): {why}"
));
}
eprintln!("mnemo: recalling by keywords only: {why}");
if keyword.is_none() {
keyword = Some(text);
}
(Vec::new(), Some(db), effective_no_track)
}
}
}
None if query.is_none() && query_file.is_none() => (Vec::new(), None, no_track),
None => (resolve_query(query, query_file)?, None, no_track),
};
let metric = parse_metric(&metric)?;
let mut req = RecallRequest::new(q)
.top_k(top_k)
.metric(metric)
.visibility(mnemo_engine::VisibilitySet::parse(&visibility).map_err(fmt)?);
if let Some(k) = keyword {
req = req.keywords(k);
}
if let Some(t) = query_text {
req = req.text(t);
}
if let Some(s) = r#type {
req = req.types(parse_memory_types(&s)?);
}
if let Some(a) = agent {
req = req.agent(a);
}
if let Some(n) = n_probe {
req = req.n_probe(n);
}
if let Some(n) = n_rerank {
req = req.n_rerank(n);
}
let mut f = mnemo_engine::Filter::default();
if let Some(s) = session {
f = f.with_session(s);
}
for expr in filter {
f = parse_filter_expr(&expr, f)?;
}
req = req.filter(f);
if let Some(b) = max_bytes {
req = req.max_bytes(b);
}
let mut db = match db_opt.take() {
Some(db) => db,
None => {
let (db, eff_no_track) = open_recall(&path, &secret, no_track).map_err(fmt)?;
effective_no_track = eff_no_track;
db
}
};
if effective_no_track {
req = req.track_access(false);
}
let resp = db.recall_budgeted(&req).map_err(fmt)?;
if !effective_no_track {
db.flush().map_err(fmt)?;
}
print_recall_hits(&resp.hits, format);
if resp.truncated {
eprintln!(
"(truncated: hits dropped by --max-bytes; rerun with a larger \
budget or smaller --top-k to see more)"
);
}
}
Command::Stale {
path,
mine,
visibility,
format,
who,
passphrase: pp,
} => {
let vis = mnemo_engine::VisibilitySet::parse(&visibility).map_err(fmt)?;
let (agent, _) = who.resolve()?;
if mine && agent.is_none() {
return Err("--mine needs --as or MNEMO_AGENT".into());
}
let pp = secret_for(&path, &pp, &None)?;
let mut db = open_ro(&path, &pp).map_err(fmt)?;
note_mistagged(&mut db);
let mut rows = db.stale().map_err(fmt)?;
if mine {
rows.retain(|r| r.whose == agent);
}
rows.retain(|r| vis.shows_level(&r.visibility));
let json = |r: &mnemo_engine::Stale| {
serde_json::json!({
"id": r.id.to_string(), "what": r.what, "since": r.since,
"text": r.text, "whose": r.whose,
})
};
match format {
OutputFormat::Json => println!(
"{}",
serde_json::Value::Array(rows.iter().map(json).collect())
),
OutputFormat::Jsonl => rows.iter().for_each(|r| println!("{}", json(r))),
OutputFormat::Table => {
if rows.is_empty() {
println!("nothing stale");
}
for r in &rows {
println!(
"{} {} stale since {}{} {}",
r.id,
r.what,
mnemo_engine::date_of(r.since),
r.whose
.as_deref()
.map(|w| format!(" ({w})"))
.unwrap_or_default(),
r.text
);
}
}
}
}
Command::Wake {
cmd,
who,
brain: path,
passphrase: pp,
} => {
let (agent, _) = who.resolve()?;
let pp = secret_for(&path, &pp, &None)?;
let mut db = open_w(&path, &pp, "wake").map_err(fmt)?;
if agent.is_some() {
db.set_author(agent);
}
match cmd {
WakeCmd::Pause | WakeCmd::Resume => {
let pause = matches!(cmd, WakeCmd::Pause);
let o = db.set_wake_paused(pause).map_err(fmt)?;
db.flush().map_err(fmt)?;
let word = if pause { "paused" } else { "resumed" };
match o {
mnemo_engine::WriteOutcome::Unchanged => {
println!("wake-ups were already {word}")
}
_ => println!("wake-ups {word} for every session of this brain"),
}
}
WakeCmd::Status => {
match db.wake_paused().map_err(fmt)? {
Some((by, at)) => {
println!("wake-ups: paused (by {by}, {})", export::rfc3339(at))
}
None => println!("wake-ups: on"),
}
if std::env::var("MNEMO_WAKE").is_ok_and(|v| v.eq_ignore_ascii_case("off")) {
println!("MNEMO_WAKE=off: this session wakes for nothing");
}
let cwd = std::env::current_dir().unwrap_or_default();
let dir = project::toplevel(&cwd).unwrap_or(cwd);
let found = cross_session_inbound(&dir);
if found.is_empty() {
println!(
"crossSessionInbound: not set in the settings files found (keep it \
`accept` for this project's sessions)"
);
}
for (f, v) in found {
let note = if v == "accept" {
""
} else {
" (wake-ups through a session's socket need `accept`)"
};
println!("crossSessionInbound: {v} in {f}{note}");
}
}
}
}
Command::Task {
cmd,
who,
brain: path,
passphrase: pp,
} => {
let (agent, role) = if matches!(cmd, TaskCmd::Add { .. }) {
who.resolve_for_write()?
} else {
who.resolve()?
};
let pp = secret_for(&path, &pp, &None)?;
let mut db = open_w(&path, &pp, "task").map_err(fmt)?;
note_mistagged(&mut db);
if agent.is_some() {
db.set_author(agent.clone());
}
if agent.is_some()
&& matches!(
cmd,
TaskCmd::Add { .. } | TaskCmd::Next | TaskCmd::Update { .. }
)
{
let _ = db.touch_presence(role.as_deref(), Some("cli"));
}
let task_json = |t: &mnemo_engine::Task| {
serde_json::json!({
"slug": t.slug, "title": t.title, "body": t.body, "role": t.role,
"status": t.status, "owner": t.owner, "creator": t.creator,
"after": t.after, "pre_approved": t.pre_approved,
"created_at": t.created_at, "history": t.history,
})
};
let row = |t: &mnemo_engine::Task| {
format!(
"{} [{}{}] {}{}",
t.slug,
t.status,
t.owner
.as_deref()
.map(|o| format!(", {o}"))
.unwrap_or_default(),
t.title,
t.role
.as_deref()
.map(|r| format!(" (for {r})"))
.unwrap_or_default()
)
};
let out: std::result::Result<(), String> = match &cmd {
TaskCmd::Add {
title,
body,
for_role,
after,
pre_approved,
slug,
} => {
let spec = mnemo_engine::TaskSpec {
title: title.clone(),
body: body.clone(),
role: for_role.clone(),
after: after.clone(),
pre_approved: *pre_approved,
slug: slug.clone(),
};
let (t, o) = db.task_add(&spec).map_err(fmt)?;
let o = match o {
mnemo_engine::WriteOutcome::Added => "added",
mnemo_engine::WriteOutcome::Unchanged => "unchanged",
_ => "updated",
};
println!("{}\t{o}\t{}", t.slug, t.status);
Ok(())
}
TaskCmd::Next => match db.task_next(role.as_deref()).map_err(fmt)? {
Some(t) => {
println!(
"{}\t{}\t{}\t{}",
t.task.slug,
t.token,
export::rfc3339(t.expires_at),
t.task.title
);
if let Some(o) = &t.reclaimed_from {
eprintln!("mnemo: taken back from {o}, whose claim lapsed");
}
Ok(())
}
None => Err(format!(
"nothing to take for {}",
role.as_deref()
.map(|r| format!("role {r}"))
.unwrap_or("no role".into())
)),
},
TaskCmd::Update {
slug,
status,
note,
token,
} => {
match db
.task_update(slug, status.as_deref(), note.as_deref(), token.as_deref())
.map_err(fmt)?
{
mnemo_engine::TaskOutcome::Updated(t, claim) => {
match claim {
Some(c) => {
println!(
"{}\t{}\t{}\t{}",
t.slug,
t.status,
c.token,
export::rfc3339(c.expires_at)
);
if c.retaken {
eprintln!(
"mnemo: your claim had lapsed and nobody took {}, so \
it's yours again, with a new token",
t.slug
);
}
}
None => println!("{}\t{}", t.slug, t.status),
}
Ok(())
}
mnemo_engine::TaskOutcome::Lost(mnemo_engine::TaskLost::TakenBack) => {
Err(format!(
"lost: another agent took {slug} back after your claim lapsed; \
nothing changed"
))
}
mnemo_engine::TaskOutcome::Lost(mnemo_engine::TaskLost::OtherToken) => {
Err(format!(
"lost: that token isn't {slug}'s claim's (another session of \
yours may hold it); nothing changed"
))
}
}
}
TaskCmd::List {
status,
for_role,
format,
} => {
let ts = db
.tasks(status.as_deref(), for_role.as_deref())
.map_err(fmt)?;
match format {
OutputFormat::Json => println!(
"{}",
serde_json::Value::Array(ts.iter().map(task_json).collect())
),
OutputFormat::Jsonl => ts.iter().for_each(|t| println!("{}", task_json(t))),
OutputFormat::Table => {
if ts.is_empty() {
println!("no tasks");
}
ts.iter().for_each(|t| println!("{}", row(t)));
}
}
Ok(())
}
TaskCmd::Get { slug, format } => match db.task(slug).map_err(fmt)? {
None => Err(format!("no task {slug:?}")),
Some(t) => {
match format {
OutputFormat::Table => {
println!("{}", row(&t));
for l in t.body.lines() {
println!(" {l}");
}
if !t.after.is_empty() {
println!(" after: {}", t.after.join(", "));
}
for h in &t.history {
println!(
" {} {} -> {} by {}{}",
export::rfc3339(h["at"].as_i64().unwrap_or(0)),
h["from"].as_str().unwrap_or(""),
h["to"].as_str().unwrap_or(""),
h["by"].as_str().unwrap_or(""),
h["note"]
.as_str()
.map(|n| format!(": {n}"))
.unwrap_or_default()
);
}
}
_ => println!("{}", task_json(&t)),
}
Ok(())
}
},
};
db.flush().map_err(fmt)?;
out?;
}
Command::Finding {
cmd,
who,
brain: path,
passphrase: pp,
} => {
let writes = !matches!(cmd, FindingCmd::List { .. } | FindingCmd::Get { .. });
let (agent, role) = if writes {
who.resolve_for_write()?
} else {
who.resolve()?
};
let pp = secret_for(&path, &pp, &None)?;
let mut db = if writes {
open_w(&path, &pp, "finding").map_err(fmt)?
} else {
open_ro(&path, &pp).map_err(fmt)?
};
if agent.is_some() {
db.set_author(agent.clone());
}
if writes && agent.is_some() {
let _ = db.touch_presence(role.as_deref(), Some("cli"));
}
let row = |f: &mnemo_engine::Finding| {
format!(
"{} [{}] {} {} {}",
f.id, f.status, f.category, f.priority, f.title
)
};
let out: std::result::Result<(), String> = match &cmd {
FindingCmd::Add {
id,
category,
priority,
title,
body,
refs,
} => {
let spec = mnemo_engine::FindingSpec {
id: id.clone(),
category: category.clone(),
priority: priority.clone(),
title: title.clone(),
body: body.clone(),
refs: refs.clone(),
};
let f = db.finding_add(&spec).map_err(fmt)?;
println!("{}\t{}", f.id, f.status);
Ok(())
}
FindingCmd::Triage { id, status, text } => {
let f = db.finding_triage(id, status, text).map_err(fmt)?;
println!("{}\t{}", f.id, f.status);
Ok(())
}
FindingCmd::Verify { id, verified_ref } => {
let f = db.finding_verify(id, verified_ref).map_err(fmt)?;
println!("{}\t{}", f.id, f.status);
Ok(())
}
FindingCmd::List {
status,
batch,
category,
priority,
format,
} => {
let filter = mnemo_engine::FindingFilter {
status: status.clone(),
batch: batch.clone(),
category: category.clone(),
priority: priority.clone(),
};
let fs = db.findings(&filter).map_err(fmt)?;
match format {
OutputFormat::Json => println!(
"{}",
serde_json::Value::Array(fs.iter().map(finding_json).collect())
),
OutputFormat::Jsonl => {
fs.iter().for_each(|f| println!("{}", finding_json(f)))
}
OutputFormat::Table => {
if fs.is_empty() {
println!("no findings");
}
fs.iter().for_each(|f| println!("{}", row(f)));
}
}
Ok(())
}
FindingCmd::Get { id, format } => match db.finding(id).map_err(fmt)? {
None => Err(format!("no finding {id:?}")),
Some(f) => {
match format {
OutputFormat::Table => {
println!("{}", row(&f));
for l in f.body.lines() {
println!(" {l}");
}
if !f.refs.is_empty() {
println!(" refs: {}", f.refs.join(", "));
}
for h in &f.history {
println!(
" {} {} -> {} by {}{}",
export::rfc3339(h["at"].as_i64().unwrap_or(0)),
h["from"].as_str().unwrap_or(""),
h["to"].as_str().unwrap_or(""),
h["by"].as_str().unwrap_or(""),
h["note"]
.as_str()
.map(|n| format!(": {n}"))
.unwrap_or_default()
);
}
}
_ => println!("{}", finding_json(&f)),
}
Ok(())
}
},
};
if writes {
db.flush().map_err(fmt)?;
}
out?;
}
Command::Claim {
cmd,
who,
brain: path,
passphrase: pp,
} => {
let (agent, role) = if matches!(
cmd,
ClaimCmd::Take { .. } | ClaimCmd::Renew { .. } | ClaimCmd::Release { .. }
) {
who.resolve_for_write()?
} else {
who.resolve()?
};
let pp = secret_for(&path, &pp, &None)?;
let mut db = open_w(&path, &pp, "claim").map_err(fmt)?;
note_mistagged(&mut db);
if agent.is_some() {
db.set_author(agent.clone());
}
let writes = matches!(
cmd,
ClaimCmd::Take { .. } | ClaimCmd::Renew { .. } | ClaimCmd::Release { .. }
);
if writes {
let _ = db.touch_presence(role.as_deref(), Some("cli"));
}
let ttl = |t: &Option<String>| t.as_deref().map(parse_ttl).transpose();
let lost = |topic: &str| {
format!(
"lost: the claim on {topic:?} lapsed or another agent holds it; don't take an irreversible step on it"
)
};
let when = |t: i64| export::rfc3339(t);
let out: std::result::Result<(), String> = match &cmd {
ClaimCmd::Take { topic, ttl: t } => match db.claim(topic, ttl(t)?).map_err(fmt)? {
mnemo_engine::ClaimOutcome::Claimed { token, expires_at } => {
println!("claimed\t{token}\t{}", when(expires_at));
Ok(())
}
mnemo_engine::ClaimOutcome::HeldBy {
agent: a,
expires_at,
} => Err(format!(
"{topic:?} is held by {a} until {}",
when(expires_at)
)),
},
ClaimCmd::Renew {
topic,
token,
ttl: t,
} => match db.renew(topic, token, ttl(t)?).map_err(fmt)? {
mnemo_engine::ClaimStatus::Held { expires_at } => {
println!("held until {}", when(expires_at));
Ok(())
}
_ => Err(lost(topic)),
},
ClaimCmd::Release { topic, token } => {
match db.release(topic, token).map_err(fmt)? {
mnemo_engine::ClaimStatus::Released => {
println!("released");
Ok(())
}
_ => Err(lost(topic)),
}
}
ClaimCmd::Check { topic, token } => {
match db.check_claim(topic, token).map_err(fmt)? {
mnemo_engine::ClaimStatus::Held { expires_at } => {
println!("held until {}", when(expires_at));
Ok(())
}
_ => Err(lost(topic)),
}
}
ClaimCmd::Who { format } => {
let rows = db.who().map_err(fmt)?;
let alive = |a: mnemo_engine::Alive| match a {
mnemo_engine::Alive::Yes => "yes",
mnemo_engine::Alive::No => "no",
mnemo_engine::Alive::Unknown => "unknown",
};
let json = |p: &mnemo_engine::Presence| {
serde_json::json!({
"agent": p.agent, "role": p.role, "tool": p.tool,
"last_active": p.last_active, "alive": alive(p.alive),
"claims": p.claims,
})
};
match format {
OutputFormat::Json => println!(
"{}",
serde_json::Value::Array(rows.iter().map(json).collect())
),
OutputFormat::Jsonl => {
for p in &rows {
println!("{}", json(p));
}
}
OutputFormat::Table => {
if rows.is_empty() {
println!("no agents yet");
}
for p in &rows {
println!(
"{} role {} {} alive {} last active {}{}",
p.agent,
p.role.as_deref().unwrap_or("-"),
p.tool.as_deref().unwrap_or("-"),
alive(p.alive),
when(p.last_active),
if p.claims.is_empty() {
String::new()
} else {
format!(" holds {}", p.claims.join(", "))
}
);
}
}
}
Ok(())
}
};
db.flush().map_err(fmt)?;
out?;
}
Command::Post {
to,
subject,
body,
refs,
conversation,
who,
brain: path,
passphrase: pp,
} => {
let (agent, role) = who.resolve_for_write()?;
let pp = secret_for(&path, &pp, &None)?;
let mut db = open_w(&path, &pp, "post").map_err(fmt)?;
note_mistagged(&mut db);
if agent.is_some() {
db.set_author(agent.clone());
let _ = db.touch_presence(role.as_deref(), Some("cli"));
}
let m = db
.post(
&to,
&subject,
&body,
&refs,
conversation.as_deref(),
agent.as_deref(),
role.as_deref(),
)
.map_err(fmt)?;
db.flush().map_err(fmt)?;
println!("{}\thop {}", m.id, m.hops);
}
Command::Inbox {
path,
all,
visibility,
prune,
days,
format,
who,
passphrase: pp,
} => {
let (agent, role) = who.resolve()?;
let pp = secret_for(&path, &pp, &None)?;
let mut db = open_w(&path, &pp, "inbox").map_err(fmt)?;
note_mistagged(&mut db);
if agent.is_some() {
db.set_author(agent.clone());
let _ = db.touch_presence(role.as_deref(), Some("cli"));
}
if prune {
let n = db.prune_messages(i64::from(days) * 86_400).map_err(fmt)?;
db.flush().map_err(fmt)?;
println!("pruned {n} acked message{}", if n == 1 { "" } else { "s" });
return Ok(());
}
if agent.is_none() && role.is_none() {
eprintln!("mnemo: no MNEMO_AGENT or --as: showing only messages to `all`");
}
let msgs = db
.inbox_in(
agent.as_deref(),
role.as_deref(),
!all,
mnemo_engine::VisibilitySet::parse(&visibility).map_err(fmt)?,
)
.map_err(fmt)?;
let unseen: Vec<mnemo_engine::Ulid> = msgs.iter().map(|m| m.id).collect();
db.mark_seen(&unseen).map_err(fmt)?;
db.flush().map_err(fmt)?;
match format {
OutputFormat::Json => println!(
"{}",
serde_json::Value::Array(msgs.iter().map(message_json).collect())
),
OutputFormat::Jsonl => {
for m in &msgs {
println!("{}", message_json(m));
}
}
OutputFormat::Table => {
if msgs.is_empty() {
println!("no messages");
}
for m in &msgs {
print_message(m);
}
}
}
}
Command::Ack {
path,
id,
note,
who,
passphrase: pp,
} => {
let (agent, role) = who.resolve()?;
let id = id.unwrap_or_default();
let ulid = parse_ulid(&id)?;
let pp = secret_for(&path, &pp, &None)?;
let mut db = open_w(&path, &pp, "ack").map_err(fmt)?;
note_mistagged(&mut db);
if agent.is_some() {
db.set_author(agent.clone());
let _ = db.touch_presence(role.as_deref(), Some("cli"));
}
let outcome = db
.ack(&ulid, note.as_deref(), agent.as_deref())
.map_err(fmt)?;
db.flush().map_err(fmt)?;
let s = match outcome {
mnemo_engine::WriteOutcome::Unchanged => "unchanged",
_ => "acked",
};
println!("{id}\t{s}");
}
Command::DefaultAgent {
path,
set,
clear,
passphrase: pp,
} => {
let pp = secret_for(&path, &pp, &None)?;
if set.is_none() && !clear {
let mut db = open_r(&path, &pp).map_err(fmt)?;
match db.default_agent().map_err(fmt)? {
Some(a) => println!("{a}"),
None => println!("(none: writes that name no agent go to `default`)"),
}
} else {
let mut db = open_w(&path, &pp, "default-agent").map_err(fmt)?;
let outcome = db.set_default_agent(set.as_deref()).map_err(fmt)?;
db.flush().map_err(fmt)?;
let what = set.as_deref().unwrap_or("(none)");
match outcome {
mnemo_engine::WriteOutcome::Unchanged => println!("{what}\tunchanged"),
_ => println!("{what}\tupdated"),
}
}
}
Command::Demo { path } => demo(&path).map_err(fmt)?,
Command::Update {
path,
id,
text,
fresh,
importance,
metadata,
ttl_secs,
clear_ttl,
embed_cmd,
embed_name,
embed_normalize,
embed_query,
embed_timeout,
passphrase: pp,
} => {
use mnemo_engine::{MemoryPatch, WriteOutcome};
let pp = secret_for(&path, &pp, &None)?;
let id = id.unwrap_or_default();
let ulid = parse_ulid(&id)?;
let mut patch = MemoryPatch::default();
if let Some(i) = importance {
patch.importance = Some(i);
}
let keys = fresh.keys()?;
if !keys.is_empty() {
patch.caller_keys = Some(keys);
}
if let Some(meta_str) = metadata {
let parsed: serde_json::Value = serde_json::from_str(&meta_str)
.map_err(|e| format!("invalid --metadata JSON: {e}"))?;
let obj = parsed
.as_object()
.ok_or_else(|| "--metadata must be a JSON object".to_string())?;
patch.metadata = Some(obj.clone());
}
if clear_ttl {
patch.ttl_secs = Some(None);
} else if let Some(ttl) = ttl_secs {
patch.ttl_secs = Some(Some(ttl));
}
let (mut db, outcome) = match text {
Some(t) => {
match embed_first(
&path,
embed_cmd.as_deref(),
embed_name.as_deref(),
embed_normalize,
embed_timeout,
embed_query.as_deref().unwrap_or_default(),
&[t.as_str()],
)? {
Some((embedder, mut vectors)) => {
let vector = vectors.pop().ok_or_else(|| {
"embedder returned no vector for the input text".to_string()
})?;
let mut db = open_w(&path, &pp, "update").map_err(fmt)?;
db.set_embedder(embedder).map_err(fmt)?;
if vector.len() != db.dimensions() {
return Err(fmt(mnemo_engine::MnemoError::DimensionMismatch {
expected: db.dimensions(),
got: vector.len(),
}));
}
patch.content = Some(t);
patch.vector = Some(vector);
let outcome = db.update(&ulid, patch).map_err(fmt)?;
(db, outcome)
}
None => {
let mut db = open_w(&path, &pp, "update").map_err(fmt)?;
let embedder = new_embedder(
embed_cmd.as_deref(),
embed_name.as_deref(),
embed_normalize,
embed_timeout,
embed_query.as_deref().unwrap_or_default(),
Some(db.dimensions()),
)?;
db.set_embedder(embedder).map_err(fmt)?;
let outcome = db.update_text(&ulid, &t, patch).map_err(fmt)?;
(db, outcome)
}
}
}
None => {
let mut db = open_w(&path, &pp, "update").map_err(fmt)?;
let outcome = db.update(&ulid, patch).map_err(fmt)?;
(db, outcome)
}
};
db.flush().map_err(fmt)?;
let outcome_str = match outcome {
WriteOutcome::Updated => "updated",
WriteOutcome::Unchanged => "unchanged",
WriteOutcome::Added => "updated",
WriteOutcome::Superseded => "updated",
};
println!("{id}\t{outcome_str}");
}
Command::History {
path,
key,
agent,
shared,
format,
visibility,
passphrase: pp,
} => {
let vis = mnemo_engine::VisibilitySet::parse(&visibility).map_err(fmt)?;
use mnemo_engine::KeyScope;
let pp = secret_for(&path, &pp, &None)?;
let mut db = open_r(&path, &pp).map_err(fmt)?;
let scope = if shared {
KeyScope::Shared
} else {
match agent.or(db.default_agent().map_err(fmt)?) {
Some(a) => KeyScope::Private(a),
None => KeyScope::private_default(),
}
};
let chain: Vec<(&str, Memory)> = db
.history_in(&key, scope)
.map_err(fmt)?
.into_iter()
.enumerate()
.map(|(i, m)| (if i == 0 { "live" } else { "superseded" }, m))
.filter(|(_, m)| vis.shows(m))
.collect();
match format {
OutputFormat::Table => {
if chain.is_empty() {
println!("no history for key={key}");
} else {
for (state, m) in chain.iter() {
println!(
"{state:<10} {id} created_at={ct} {content}",
id = m.id,
ct = m.created_at,
content = truncate(&m.content, 80),
);
}
}
}
OutputFormat::Json => {
let arr: Vec<_> = chain
.iter()
.map(|(state, m)| {
let mut v = memory_to_json(m, false);
if let Some(obj) = v.as_object_mut() {
obj.insert(
"state".into(),
serde_json::Value::String((*state).into()),
);
}
v
})
.collect();
println!(
"{}",
serde_json::to_string_pretty(
&serde_json::json!({ "count": arr.len(), "chain": arr }),
)
.unwrap_or_else(|_| "{}".into())
);
}
OutputFormat::Jsonl => {
for (state, m) in chain.iter() {
let mut v = memory_to_json(m, false);
if let Some(obj) = v.as_object_mut() {
obj.insert("state".into(), serde_json::Value::String((*state).into()));
}
println!(
"{}",
serde_json::to_string(&v).unwrap_or_else(|_| "{}".into())
);
}
}
}
}
Command::Thread { cmd } => handle_thread_cmd(cmd)?,
Command::Essence { cmd } => handle_essence_cmd(cmd)?,
Command::Snapshots {
path,
passphrase: pp,
} => {
let pp = secret_for(&path, &pp, &None)?;
let db = open_r(&path, &pp).map_err(fmt)?;
let snaps = db.snapshots();
if snaps.is_empty() {
println!("no snapshots yet (nothing has been flushed)");
} else {
println!("{:<8} {:<12} committed (unix)", "txn", "memories");
for s in snaps {
println!("{:<8} {:<12} {}", s.txn_id, s.memory_count, s.created_at);
}
}
}
Command::Restore {
path,
to_txn,
to_time,
passphrase: pp,
} => {
let pp = secret_for(&path, &pp, &None)?;
let mut db = open_w(&path, &pp, "restore").map_err(fmt)?;
let info = match (to_txn, to_time) {
(Some(txn), _) => db.restore_to(txn).map_err(fmt)?,
(None, Some(t)) => db.restore_to_time(t).map_err(fmt)?,
(None, None) => return Err("restore needs --to-txn or --to-time".to_string()),
};
println!(
"restored {path} to snapshot txn {} ({} memories)",
info.txn_id, info.memory_count
);
}
Command::Serve {
path,
mcp,
embed_cmd,
embed_name,
embed_normalize,
embed_query,
embed_timeout,
shared,
allow_network_fs,
} => {
if !mcp {
return Err("serve requires --mcp today (other transports may come later)".into());
}
let resolved = serve_path(&path)?;
let p = resolved.as_path();
let shared = shared.then(|| {
let mut o = wait_opts();
o.allow_network_fs = allow_network_fs;
o
});
match (embed_cmd, embed_name) {
(Some(c), Some(n)) => {
let spec = mnemo_engine::mcp::EmbedSpec {
command: c,
name: n,
normalize: embed_normalize,
timeout: std::time::Duration::from_secs(embed_timeout),
query_convention: embed_query.unwrap_or_default(),
};
mnemo_engine::mcp::serve_stdio_with_spec(p, Some(spec), shared)
}
(None, None) => serve_builtin(p, shared),
_ => return Err("--embed-cmd and --embed-name go together".into()),
}
.map_err(fmt)?;
}
Command::Onboard {
guide,
format,
client,
scope,
hook_budget,
yes,
print,
no_model,
undo,
plugin,
wake,
} => {
if !guide {
return onboard::run(onboard::Opts {
clients: client,
scope,
hook_budget,
yes,
print,
no_model,
undo,
plugin,
moved,
wake,
});
}
let text = match format {
GuideFormat::Markdown => mnemo_engine::guide::markdown(),
GuideFormat::LlmsTxt => mnemo_engine::guide::llms_txt(),
GuideFormat::LlmsFull => mnemo_engine::guide::llms_full(),
GuideFormat::PluginSkill => mnemo_engine::guide::plugin_skill_md(),
};
print!("{text}");
}
Command::Hook {
event,
client,
budget,
} => hook::run(hook::Opts {
event,
client,
budget,
moved,
}),
Command::Embedder { cmd } => run_embedder(cmd)?,
Command::Cache { op } => run_cache_op(op)?,
Command::Mcp {
cmd:
McpCmd::Install {
client,
scope,
name,
print,
yes,
path,
},
} => mcp_install::run(mcp_install::Install {
client,
file: path,
project: project_brain,
scope,
name,
print,
yes,
})?,
}
Ok(())
}
fn run_cache_op(op: CacheOp) -> std::result::Result<(), String> {
use mnemo_engine::CachePutOpts;
match op {
CacheOp::Get {
path,
ns,
key,
passphrase: pp,
} => {
let pp = secret_for(&path, &pp, &None)?;
let mut db = match open_w(&path, &pp, "cache get") {
Err(mnemo_engine::MnemoError::FormatTooOld { version: 8 }) => {
open_r(&path, &pp).map_err(fmt)?
}
other => other.map_err(fmt)?,
};
match db.cache_get(&ns, &key).map_err(fmt)? {
Some(v) => {
use std::io::Write;
std::io::stdout()
.write_all(&v.value)
.map_err(|e| e.to_string())?;
if !v.value.ends_with(b"\n") {
println!();
}
db.flush().map_err(fmt)?;
}
None => {
return Err(format!("cache miss on ({ns}, {key})"));
}
}
}
CacheOp::Put {
path,
ns,
key,
value,
file,
content_type,
ttl,
passphrase: pp,
} => {
let pp = secret_for(&path, &pp, &None)?;
let bytes = match (value, file) {
(Some(v), None) => v.into_bytes(),
(None, Some(f)) => std::fs::read(&f).map_err(|e| format!("read {f}: {e}"))?,
(Some(_), Some(_)) => {
return Err("--value and --file are mutually exclusive".into())
}
(None, None) => {
return Err("cache put needs --value <string> or --file <path>".into())
}
};
let opts = CachePutOpts {
content_type,
ttl_secs: ttl,
cost_hint_ms: None,
};
let mut db = open_w(&path, &pp, "cache put").map_err(fmt)?;
db.cache_put(&ns, &key, &bytes, opts).map_err(fmt)?;
db.flush().map_err(fmt)?;
println!("cached {} bytes at ({ns}, {key})", bytes.len());
}
CacheOp::Delete {
path,
ns,
key,
passphrase: pp,
} => {
let pp = secret_for(&path, &pp, &None)?;
let mut db = open_w(&path, &pp, "cache delete").map_err(fmt)?;
db.cache_delete(&ns, &key).map_err(fmt)?;
db.flush().map_err(fmt)?;
println!("deleted ({ns}, {key}) (space reclaimed on next compact)");
}
CacheOp::Stats {
path,
ns,
passphrase: pp,
} => {
let pp = secret_for(&path, &pp, &None)?;
let db = open_r(&path, &pp).map_err(fmt)?;
let s = db.cache_stats(ns.as_deref());
let obj = serde_json::json!({
"namespace": ns,
"entries": s.entries,
"bytes": s.bytes,
"hits": s.hits,
"misses": s.misses,
"hit_rate": s.hit_rate,
"evictions": s.evictions,
});
println!("{}", serde_json::to_string_pretty(&obj).unwrap());
}
CacheOp::Purge {
path,
ns,
expired,
passphrase: pp,
} => {
let pp = secret_for(&path, &pp, &None)?;
let mut db = open_w(&path, &pp, "cache purge").map_err(fmt)?;
let n = db.cache_purge(ns.as_deref(), expired).map_err(fmt)?;
db.flush().map_err(fmt)?;
println!("purged {n} entr{}", if n == 1 { "y" } else { "ies" });
}
}
Ok(())
}
fn memory_from_json(line: &str) -> std::result::Result<Memory, String> {
use serde_json::Value;
let v: Value = serde_json::from_str(line).map_err(|e| e.to_string())?;
let content = v
.get("content")
.and_then(Value::as_str)
.ok_or("missing string field 'content'")?;
let vec_json = v
.get("vector")
.and_then(Value::as_array)
.ok_or("missing array field 'vector'")?;
let vector: Vec<f32> = vec_json
.iter()
.map(|x| {
x.as_f64()
.map(|f| f as f32)
.ok_or("vector element not a number")
})
.collect::<std::result::Result<_, _>>()?;
let mt = v
.get("memory_type")
.and_then(Value::as_str)
.and_then(MemoryType::parse)
.unwrap_or(MemoryType::Semantic);
let mut m = Memory::new(content, mt, vector);
if let Some(a) = v.get("agent_id").and_then(Value::as_str) {
m = m.with_agent(a);
}
if let Some(i) = v.get("importance").and_then(Value::as_f64) {
m = m.with_importance(i as f32);
}
Ok(m)
}
fn fmt(e: mnemo_engine::MnemoError) -> String {
if matches!(e, mnemo_engine::MnemoError::WrongPassphrase) {
if let Some((src, next)) = SOURCE.get() {
return match next {
Some(n) => format!("{e} (the secret came from {src}; without it, {n} comes next)"),
None => format!("{e} (the secret came from {src})"),
};
}
}
e.to_string()
}
fn ingest_turns(
path: &str,
pp: &inspect::Secret,
thread: &str,
turns: &[mnemo_engine::ThreadTurn],
op: &str,
make_embedder: impl FnOnce(usize) -> std::result::Result<Box<dyn mnemo_engine::Embedder>, String>,
) -> std::result::Result<mnemo_engine::IngestReport, String> {
let (texts, dimensions) = {
let mut db = open_r(path, pp).map_err(fmt)?;
(
db.ingest_thread_texts(thread, turns).map_err(fmt)?,
db.dimensions(),
)
};
let embedder = make_embedder(dimensions)?;
let pre: Vec<Vec<f32>> = if texts.is_empty() {
Vec::new()
} else {
use mnemo_engine::Embedder;
let refs: Vec<&str> = texts.iter().map(String::as_str).collect();
embedder.embed(&refs).map_err(fmt)?
};
let mut db = open_w(path, pp, op).map_err(fmt)?;
db.set_embedder(embedder).map_err(fmt)?;
let now = db.ingest_thread_texts(thread, turns).map_err(fmt)?;
let report = if now == texts {
db.ingest_thread_with_vectors(thread, turns, &pre)
.map_err(fmt)?
} else {
let mut have: std::collections::HashMap<&str, &Vec<f32>> =
texts.iter().map(String::as_str).zip(pre.iter()).collect();
let missing: Vec<&str> = now
.iter()
.map(String::as_str)
.filter(|t| !have.contains_key(t))
.collect();
let extra = if missing.is_empty() {
Vec::new()
} else {
db.embedder()
.ok_or_else(|| "no embedder registered".to_string())?
.embed(&missing)
.map_err(fmt)?
};
for (t, v) in missing.iter().zip(extra.iter()) {
have.insert(t, v);
}
let vectors = now
.iter()
.map(|t| have.get(t.as_str()).map(|v| (*v).clone()))
.collect::<Option<Vec<_>>>()
.ok_or_else(|| "embedder returned too few vectors".to_string())?;
db.ingest_thread_with_vectors(thread, turns, &vectors)
.map_err(fmt)?
};
db.flush().map_err(fmt)?;
Ok(report)
}
fn handle_thread_cmd(cmd: ThreadCmd) -> std::result::Result<(), String> {
use mnemo_engine::{read_transcript_with, TranscriptFormat};
use std::io::{Read, Write};
match cmd {
ThreadCmd::Ingest {
path,
thread,
transcript,
format,
tool_results,
redact,
embed_cmd,
embed_name,
embed_normalize,
embed_query,
embed_timeout,
passphrase: pp,
} => {
let pp = secret_for(&path, &pp, &None)?;
let fmt_enum = TranscriptFormat::parse(&format).ok_or_else(|| {
format!("unknown --format '{format}' (want 'jsonl' or 'claude-code-jsonl')")
})?;
let opts = mnemo_engine::TranscriptOptions {
tool_results: tool_results.into(),
lenient: false,
};
let mut turns = if transcript == "-" {
let mut buf = Vec::new();
std::io::stdin()
.read_to_end(&mut buf)
.map_err(|e| format!("reading stdin: {e}"))?;
read_transcript_with(&buf[..], fmt_enum, opts).map_err(fmt)?
} else {
let file = std::fs::File::open(&transcript)
.map_err(|e| format!("opening {transcript}: {e}"))?;
read_transcript_with(file, fmt_enum, opts).map_err(fmt)?
};
if redact {
let counts = hook::redact_turns(&mut turns);
if let Some(line) = hook::redaction_note(&counts) {
eprintln!("{line}");
}
}
let report =
ingest_turns(&path, &pp, &thread, &turns, "thread ingest", |dimensions| {
new_embedder(
embed_cmd.as_deref(),
embed_name.as_deref(),
embed_normalize,
embed_timeout,
embed_query.as_deref().unwrap_or_default(),
Some(dimensions),
)
})?;
println!(
"thread {thread}: added {added} record(s) ({chunked} chunked, {truncated} truncated); \
skipped {skipped} already-stored turn(s)",
added = report.added_records,
chunked = report.chunked_turns,
truncated = report.truncated_turns,
skipped = report.skipped_existing_turns,
);
Ok(())
}
ThreadCmd::Export {
path,
thread,
output,
passphrase: pp,
} => {
let pp = secret_for(&path, &pp, &None)?;
let mut db = open_r(&path, &pp).map_err(fmt)?;
let turns = db.thread_export_turns(&thread).map_err(fmt)?;
let lines: Vec<String> = turns
.iter()
.map(|t| serde_json::to_string(&t.to_json()).unwrap_or_else(|_| "{}".into()))
.collect();
let body = lines.join("\n") + "\n";
match output {
Some(p) => {
let mut f =
std::fs::File::create(&p).map_err(|e| format!("opening {p}: {e}"))?;
f.write_all(body.as_bytes())
.map_err(|e| format!("writing {p}: {e}"))?;
println!(
"exported {} turn(s) from thread '{thread}' to {p}",
turns.len()
);
}
None => {
print!("{body}");
}
}
Ok(())
}
ThreadCmd::Forget {
path,
thread,
passphrase: pp,
} => {
let pp = secret_for(&path, &pp, &None)?;
let mut db = open_w(&path, &pp, "thread forget").map_err(fmt)?;
let n = db.thread_forget(&thread).map_err(fmt)?;
db.flush().map_err(fmt)?;
println!(
"forgot {n} record(s) in thread '{thread}' (run `mnemo compact {path}` to reclaim space)"
);
Ok(())
}
ThreadCmd::Start {
path,
new,
from,
passphrase: pp,
} => {
let new = new.unwrap_or_default();
let pp = secret_for(&path, &pp, &None)?;
let mut db = open_w(&path, &pp, "thread start").map_err(fmt)?;
let id = db.thread_start(&new, &from).map_err(fmt)?;
db.flush().map_err(fmt)?;
println!(
"thread '{new}' continues from '{from}' (link record {id}; try `mnemo essence {path} --thread {new}`)"
);
Ok(())
}
}
}
fn handle_essence_cmd(cmd: EssenceCmd) -> std::result::Result<(), String> {
use mnemo_engine::{EssenceScope, EssenceSection};
let parse_refs = |s: Option<String>| -> Option<Vec<String>> {
s.map(|raw| {
raw.split(',')
.map(|p| p.trim().to_string())
.filter(|p| !p.is_empty())
.collect::<Vec<_>>()
})
};
let resolve_scope =
|thread: Option<String>, project: bool| -> std::result::Result<EssenceScope, String> {
match (thread, project) {
(Some(t), false) => Ok(EssenceScope::Thread(t)),
(None, true) => Ok(EssenceScope::Project),
(None, false) => {
Err("pass either --thread <id> or --project (clap also enforces this).".into())
}
(Some(_), true) => Err("--thread and --project are mutually exclusive.".into()),
}
};
match cmd {
EssenceCmd::Render {
path,
thread,
project,
budget,
passphrase: pp,
} => {
let pp = secret_for(&path, &pp, &None)?;
let scope = resolve_scope(thread, project)?;
let mut db = open_r(&path, &pp).map_err(fmt)?;
let out = db.essence(scope, budget).map_err(fmt)?;
print!("{out}");
Ok(())
}
EssenceCmd::Add {
path,
section,
text,
thread,
project,
refs,
passphrase: pp,
} => {
let pp = secret_for(&path, &pp, &None)?;
let section = EssenceSection::parse(§ion).ok_or_else(|| {
format!(
"unknown section '{section}' (want intent, conventions, decisions, state, open, next, lessons)"
)
})?;
if section == EssenceSection::Timeline {
return Err("use `mnemo essence append` for timeline entries".into());
}
let scope = resolve_scope(thread, project)?;
let mut db = open_w(&path, &pp, "essence add").map_err(fmt)?;
let id = db
.essence_add(scope, section, &text, parse_refs(refs))
.map_err(fmt)?;
db.flush().map_err(fmt)?;
println!("{id}\tadded");
Ok(())
}
EssenceCmd::Append {
path,
text,
thread,
project,
refs,
passphrase: pp,
} => {
let pp = secret_for(&path, &pp, &None)?;
let scope = resolve_scope(thread, project)?;
let mut db = open_w(&path, &pp, "essence append").map_err(fmt)?;
let id = db
.essence_append_timeline(scope, &text, parse_refs(refs))
.map_err(fmt)?;
db.flush().map_err(fmt)?;
println!("{id}\tappended");
Ok(())
}
EssenceCmd::Update {
path,
id,
text,
refs,
passphrase: pp,
} => {
let pp = secret_for(&path, &pp, &None)?;
let id = id.unwrap_or_default();
let ulid = parse_ulid(&id)?;
let mut db = open_w(&path, &pp, "essence update").map_err(fmt)?;
let outcome = db
.essence_update(&ulid, &text, parse_refs(refs))
.map_err(fmt)?;
db.flush().map_err(fmt)?;
let s = match outcome {
mnemo_engine::WriteOutcome::Updated => "updated",
mnemo_engine::WriteOutcome::Unchanged => "unchanged",
_ => "updated",
};
println!("{id}\t{s}");
Ok(())
}
EssenceCmd::Resolve {
path,
id,
passphrase: pp,
} => {
let pp = secret_for(&path, &pp, &None)?;
let id = id.unwrap_or_default();
let ulid = parse_ulid(&id)?;
let mut db = open_w(&path, &pp, "essence resolve").map_err(fmt)?;
let outcome = db.essence_resolve(&ulid).map_err(fmt)?;
db.flush().map_err(fmt)?;
let s = match outcome {
mnemo_engine::WriteOutcome::Updated => "resolved",
mnemo_engine::WriteOutcome::Unchanged => "already-resolved",
_ => "resolved",
};
println!("{id}\t{s}");
Ok(())
}
EssenceCmd::Remove {
path,
id,
passphrase: pp,
} => {
let pp = secret_for(&path, &pp, &None)?;
let id = id.unwrap_or_default();
let ulid = parse_ulid(&id)?;
let mut db = open_w(&path, &pp, "essence remove").map_err(fmt)?;
db.essence_remove(&ulid).map_err(fmt)?;
db.flush().map_err(fmt)?;
println!("{id}\tremoved");
Ok(())
}
}
}
fn demo(path: &str) -> Result<()> {
let _ = std::fs::remove_file(path);
let pp = "demo-passphrase";
let cfg = MnemoConfig {
dimensions: 4,
..Default::default()
};
println!("creating encrypted database at {path} ...");
let mut db = Mnemo::create(path, pp, cfg)?;
let seeds = [
(
"user prefers concise answers",
MemoryType::Semantic,
[0.9, 0.1, 0.0, 0.1],
0.9,
),
(
"user is based in Berlin",
MemoryType::Semantic,
[0.8, 0.2, 0.1, 0.0],
0.7,
),
(
"ran the deploy script at 14:00",
MemoryType::Episodic,
[0.1, 0.9, 0.1, 0.0],
0.4,
),
(
"to reset state, call clear() then reload",
MemoryType::Procedural,
[0.0, 0.1, 0.9, 0.2],
0.6,
),
(
"scratch: temp calculation result",
MemoryType::Working,
[0.2, 0.2, 0.2, 0.9],
0.2,
),
];
for (content, mt, v, imp) in seeds {
db.remember(
Memory::new(content, mt, v.to_vec())
.with_agent("assistant")
.with_importance(imp),
)?;
}
db.flush()?;
println!("stored {} memories, flushed to disk\n", db.len());
let info = db.build_index()?;
db.flush()?;
println!(
"built ANN index: {} vectors, {} partitions, {} PQ subspaces",
info.vectors, info.partitions, info.subspaces
);
println!("\nrecall for a query close to 'user preferences' (index-accelerated):");
let req = RecallRequest::new(vec![0.85, 0.15, 0.05, 0.05]).top_k(3);
for h in db.recall(&req)? {
println!(
" score={:.3} sim={:.3} [{}] {}",
h.score,
h.similarity,
h.memory.memory_type.as_str(),
h.memory.content
);
}
println!("\nreopening to confirm persistence and encryption ...");
db.close()?;
let db = Mnemo::open(path, pp)?;
println!("reopened: {} memories survive the round-trip", db.len());
let raw = std::fs::read(path).unwrap_or_default();
let needle = b"user prefers concise answers";
let leaked = raw.windows(needle.len()).any(|w| w == needle);
println!("plaintext 'user prefers concise answers' present in file bytes: {leaked}");
println!("\ndemo complete.");
Ok(())
}
#[cfg(unix)]
const EXIT_BROKEN_PIPE: i32 = 141;
#[cfg(not(unix))]
const EXIT_BROKEN_PIPE: i32 = 1;
fn quiet_broken_pipe() {
let default = std::panic::take_hook();
std::panic::set_hook(Box::new(move |info| {
let msg = info
.payload()
.downcast_ref::<String>()
.map(String::as_str)
.or_else(|| info.payload().downcast_ref::<&str>().copied())
.unwrap_or("");
let pipe = msg.contains("Broken pipe")
|| msg.contains("os error 32)")
|| msg.contains("os error 232)")
|| msg.contains("pipe is being closed");
if msg.starts_with("failed printing to stdout") && pipe {
std::process::exit(EXIT_BROKEN_PIPE);
}
default(info);
}));
}
fn main() -> ExitCode {
quiet_broken_pipe();
const RUN_STACK: usize = 8 * 1024 * 1024;
let handle = match std::thread::Builder::new()
.name("mnemo-cli".into())
.stack_size(RUN_STACK)
.spawn(run)
{
Ok(h) => h,
Err(e) => {
eprintln!("error: could not start cli worker thread: {e}");
return ExitCode::FAILURE;
}
};
let result = match handle.join() {
Ok(r) => r,
Err(_) => {
eprintln!("error: cli worker thread panicked");
return ExitCode::FAILURE;
}
};
match result {
Ok(()) => ExitCode::SUCCESS,
Err(e) => {
eprintln!("error: {e}");
ExitCode::FAILURE
}
}
}