//! Hand-rolled Model Context Protocol (MCP) stdio server for MNemo.
//!
//! Exposes a `.mnemo` file as an MCP server so any MCP-compatible agent
//! (Claude Desktop, Cursor, mcp-server, custom clients) can drive it as a
//! tool. Framed as **JSON-RPC 2.0 with newline-delimited JSON** over
//! stdin/stdout, per the MCP spec. Stderr is used for human-readable
//! diagnostics only — never for protocol traffic.
//!
//! ## Why hand-rolled
//!
//! The official [`rmcp`](https://crates.io/crates/rmcp) SDK declares
//! `edition = "2024"` on its workspace, which requires Rust 1.85+; our
//! MSRV is 1.75 and locked (transitive deps pin us). `rmcp` also brings
//! in tokio + async, a big architectural shift for a sync-only core.
//! Hand-rolling stdio JSON-RPC is ~250 LoC and adds zero dependencies
//! beyond `serde_json` (already a dep). See CHANGELOG's Phase 4 entry
//! for the decision record.
//!
//! ## Protocol version
//!
//! We advertise MCP protocol `2025-06-18` on `initialize`. If a client
//! requests a different version we echo their version back — the standard
//! compatibility dance. The seven tools we expose are stable across
//! recent protocol revisions.
//!
//! ## Tools
//!
//! - `about` — read-only briefing (manifest + onboarding memories)
//! - `remember` — insert a memory (BYO vector; embedder integration deferred to Phase 3)
//! - `recall` — vector recall (BYO query vector)
//! - `forget` — delete by ULID
//! - `list` — enumerate live memories
//! - `snapshot_list` — enumerate PITR snapshots
//! - `stats` — database statistics
//!
//! Every mutation calls `Mnemo::flush()` before returning success — MCP
//! clients treat tool calls as atomic and expect on-disk durability.
//!
//! ## The secret
//!
//! 12.3 step 2: found through the key-source chain
//! ([`crate::keys::resolve`]), by the file's kind: `MNEMO_KEY`,
//! `MNEMO_KEY_FILE`, `MNEMO_KEY_COMMAND` (10 s at most) or the keychain for a
//! key; `MNEMO_PASSPHRASE` or the keychain for a passphrase. The server never
//! prompts (stdio carries JSON-RPC) and takes no key flag, so what a client's
//! config holds carries no secret. It logs where the secret came from to
//! stderr at start, never the secret.
use std::io::{BufRead, BufReader, Read, Write};
use std::path::Path;
use serde::{Deserialize, Serialize};
use serde_json::{json, Map, Value};
use crate::error::{MnemoError, Result};
use crate::memory::{Memory, MemoryType, Metric, Scope};
use crate::result_cache::{CachePutOpts, SemanticCachePutOpts, DEFAULT_SEMANTIC_THRESHOLD};
use crate::shared::SharedOptions;
use crate::store::{Mnemo, RecallRequest, SharedMnemo};
mod context;
/// MCP protocol version we advertise on `initialize`.
const PROTOCOL_VERSION: &str = "2025-06-18";
/// Fuzz-target helper: parse a single JSON-RPC line as a `Request` and
/// discard. Panic-free — malformed input returns `Err(String)`, valid
/// requests return `Ok(())`. Exposed only via `crate::__fuzz`; not part
/// of the stable public API.
#[doc(hidden)]
pub fn __fuzz_parse_request_line(line: &str) -> std::result::Result<(), String> {
serde_json::from_str::<Request>(line)
.map(|_| ())
.map_err(|e| e.to_string())
}
// --- JSON-RPC 2.0 wire types ---------------------------------------------
/// Incoming JSON-RPC 2.0 request or notification (a notification is a
/// request with no `id`).
#[derive(Debug, Deserialize)]
struct Request {
#[serde(default)]
jsonrpc: String,
#[serde(default)]
id: Option<Value>,
method: String,
#[serde(default)]
params: Value,
}
/// Outgoing JSON-RPC 2.0 response envelope.
#[derive(Debug, Serialize)]
struct Response {
jsonrpc: &'static str,
id: Value,
#[serde(skip_serializing_if = "Option::is_none")]
result: Option<Value>,
#[serde(skip_serializing_if = "Option::is_none")]
error: Option<RpcError>,
}
/// JSON-RPC 2.0 error object.
#[derive(Debug, Serialize)]
struct RpcError {
code: i32,
message: String,
#[serde(skip_serializing_if = "Option::is_none")]
data: Option<Value>,
}
impl RpcError {
fn new(code: i32, message: impl Into<String>) -> Self {
Self {
code,
message: message.into(),
data: None,
}
}
}
// Standard JSON-RPC error codes.
const PARSE_ERROR: i32 = -32700;
const INVALID_REQUEST: i32 = -32600;
const METHOD_NOT_FOUND: i32 = -32601;
const INVALID_PARAMS: i32 = -32602;
const INTERNAL_ERROR: i32 = -32603;
// --- Entry point ---------------------------------------------------------
/// Run the MCP stdio server over the provided `.mnemo` file.
///
/// Blocks the calling thread — reads JSON-RPC requests line-by-line from
/// stdin, dispatches to the tool implementations, writes responses to
/// stdout, and logs diagnostics to stderr. Returns when stdin closes
/// (typical MCP client shutdown) or on a fatal I/O error.
///
/// The secret comes from the key-source chain (see the module docs). With
/// no source, returns [`MnemoError::Invalid`] without opening the file.
pub fn serve_stdio(path: &Path) -> Result<()> {
serve_stdio_with_embedder(path, None)
}
/// Variant that optionally registers an [`crate::EmbedCmd`] embedder on
/// the handle at server start (Phase 3 PR 10b). The MCP `remember`,
/// `recall`, `cache_put_semantic` and `cache_get_semantic` tools then
/// accept a `text` param as an alternative to the explicit vector —
/// the embedder runs once per request against the persistent child
/// process. Pass `None` for the pre-Phase-3 vector-only behavior.
///
/// `embed_spec` tuple fields: `(command, name, normalize)`. See
/// [`crate::EmbedCmd::new`] for the command format.
pub fn serve_stdio_with_embedder(
path: &Path,
embed_spec: Option<(String, String, bool, std::time::Duration)>,
) -> Result<()> {
serve_stdio_with_options(path, embed_spec, None)
}
/// [`serve_stdio_with_embedder`], and with `shared` set, in **shared mode**
/// (12.4, `mnemo serve --mcp --shared`): the server holds no lock between
/// tool calls, and each call is one read or one write window on the file,
/// so other servers, the CLI and Python can use the brain meanwhile. The
/// options' deadline is how long one call waits for the lock.
pub fn serve_stdio_with_options(
path: &Path,
embed_spec: Option<(String, String, bool, std::time::Duration)>,
shared: Option<SharedOptions>,
) -> Result<()> {
serve_stdio_with_spec(path, embed_spec.map(EmbedSpec::from), shared)
}
/// The server's `--embed-cmd` embedder (12.3 step 4, v0.15): the tuple the
/// other `serve_*` functions take, plus the query convention.
#[derive(Clone, Debug)]
pub struct EmbedSpec {
/// The command ([`crate::EmbedCmd::new`]).
pub command: String,
/// The identity's name.
pub name: String,
/// The identity's `normalize`.
pub normalize: bool,
/// The per-request timeout.
pub timeout: std::time::Duration,
/// [`crate::EmbedderIdentity::query_convention`]: empty when queries
/// are embedded like documents. When set, the command gets each request
/// as `{"kind": …, "text": …}` (see [`crate::EmbedCmd`]).
pub query_convention: String,
}
impl From<(String, String, bool, std::time::Duration)> for EmbedSpec {
fn from(
(command, name, normalize, timeout): (String, String, bool, std::time::Duration),
) -> Self {
EmbedSpec {
command,
name,
normalize,
timeout,
query_convention: String::new(),
}
}
}
/// [`serve_stdio_with_options`] with an [`EmbedSpec`], so the embedder can
/// have a query convention (`mnemo serve --mcp --embed-query`).
pub fn serve_stdio_with_spec(
path: &Path,
embed_spec: Option<EmbedSpec>,
shared: Option<SharedOptions>,
) -> Result<()> {
let stdin = std::io::stdin();
let stdout = std::io::stdout();
serve_with_streams_spec(path, stdin.lock(), stdout.lock(), embed_spec, shared)
}
/// The server's handle: a plain read-write handle for its whole life, or
/// a shared-mode one (12.4). One per server, and the variants are close in
/// size, so neither is boxed.
#[allow(clippy::large_enum_variant)]
enum ServerDb {
Plain(Mnemo),
Shared(SharedMnemo),
}
impl ServerDb {
fn len(&mut self) -> Result<usize> {
match self {
ServerDb::Plain(db) => Ok(db.len()),
ServerDb::Shared(s) => s.read(|db| Ok(db.len())),
}
}
}
/// The tools that only read. In shared mode they run in a read window
/// (the shared lock, alongside other readers); every other tool runs in a
/// write window. `recall`'s access statistics ride the handle's next
/// write.
fn is_read_tool(name: &str) -> bool {
matches!(
name,
"about"
| "history"
| "thread_export"
| "recall"
| "list"
| "snapshot_list"
| "stats"
| "cache_get"
| "cache_stats"
| "cache_get_semantic"
)
}
/// Run the MCP loop against explicit reader/writer streams. Extracted so
/// integration tests can pipe scripted input without touching the real
/// stdin/stdout. `embed_spec` is as in [`serve_stdio_with_embedder`].
pub fn serve_with_streams<R: Read, W: Write>(
path: &Path,
reader: R,
writer: W,
embed_spec: Option<(String, String, bool, std::time::Duration)>,
) -> Result<()> {
serve_with_streams_opts(path, reader, writer, embed_spec, None)
}
/// [`serve_with_streams`], in shared mode when `shared` is set (see
/// [`serve_stdio_with_options`]).
pub fn serve_with_streams_opts<R: Read, W: Write>(
path: &Path,
reader: R,
writer: W,
embed_spec: Option<(String, String, bool, std::time::Duration)>,
shared: Option<SharedOptions>,
) -> Result<()> {
serve_with_streams_spec(
path,
reader,
writer,
embed_spec.map(EmbedSpec::from),
shared,
)
}
/// [`serve_with_streams_opts`] with an [`EmbedSpec`].
pub fn serve_with_streams_spec<R: Read, W: Write>(
path: &Path,
reader: R,
writer: W,
embed_spec: Option<EmbedSpec>,
shared: Option<SharedOptions>,
) -> Result<()> {
let choice = match embed_spec {
Some(spec) => ServerEmbedder::Command(spec),
None => ServerEmbedder::None,
};
serve_inner(path, reader, writer, choice, shared)
}
/// 12.3 step 5 (v0.15): [`serve_stdio_with_spec`] with the built-in
/// embedder (`mnemo serve --mcp` with no `--embed-cmd`), loaded before the
/// file is opened, or fetched first if it isn't in the cache (the size said
/// on stderr). It's registered when the file records the built-in's identity
/// or none yet (which it then records). A file that records another
/// embedder, or a model that can't be loaded (offline), gets a server
/// without one, said on stderr: `recall`'s `text` is then matched by keyword
/// only on a v9 file, and the other text tools refuse `text`.
/// `model_dir` is the CLI's `--model-dir`
/// ([`crate::BuiltinEmbedder::from_dir`]).
#[cfg(feature = "embed-candle")]
pub fn serve_stdio_with_builtin(
path: &Path,
model_dir: Option<&Path>,
shared: Option<SharedOptions>,
) -> Result<()> {
let stdin = std::io::stdin();
let stdout = std::io::stdout();
serve_with_streams_builtin(path, stdin.lock(), stdout.lock(), model_dir, shared)
}
/// [`serve_stdio_with_builtin`] over the given streams.
#[cfg(feature = "embed-candle")]
pub fn serve_with_streams_builtin<R: Read, W: Write>(
path: &Path,
reader: R,
writer: W,
model_dir: Option<&Path>,
shared: Option<SharedOptions>,
) -> Result<()> {
let choice = ServerEmbedder::Builtin(model_dir.map(Path::to_path_buf));
serve_inner(path, reader, writer, choice, shared)
}
/// RB-010.1: `serve --mcp` with no `--embed-cmd` never fails to start because
/// of the built-in. What it does, decided before the open and said on stderr:
/// - **a file whose width isn't the model's:** no embedder, and the model
/// isn't loaded or fetched;
/// - **the model can't be loaded** (offline, say): no embedder.
///
/// Recall's `text` is then matched by keyword only (v9 files), and a write
/// with `text` is refused, as with no embedder at all.
#[cfg(feature = "embed-candle")]
fn builtin_for(path: &Path, dir: Option<&Path>) -> Option<crate::BuiltinEmbedder> {
use crate::Embedder;
let not_its_width = |d: usize, width: usize| {
eprintln!(
"mnemo mcp: this file is {d}-dimensional and the built-in embedder is {width}: \
serving without one (pass the file's own embedder with --embed-cmd and \
--embed-name, or move the file to the built-in with `mnemo reembed <file> \
--embed-dims {width}`); recall's 'text' is matched by keyword only"
);
};
// An unreadable header is the open's to report.
let file_width = Mnemo::peek_dimensions(path).ok();
if dir.is_none() {
if let Some(d) = file_width.filter(|&d| d != crate::builtin::DIMENSIONS) {
not_its_width(d, crate::builtin::DIMENSIONS);
return None;
}
}
let loaded = match dir {
Some(d) => crate::BuiltinEmbedder::from_dir(d),
None => crate::BuiltinEmbedder::load_or_install(&mut |m| eprintln!("{m}")),
};
match loaded {
Ok(e) => match file_width {
Some(d) if d != e.identity().dimensions => {
not_its_width(d, e.identity().dimensions);
None
}
_ => Some(e),
},
Err(e) => {
eprintln!("mnemo mcp: no embedder ({e}); recall's 'text' is matched by keyword only");
None
}
}
}
/// RB-010.1: register the built-in on the open file, the way the CLI's recall
/// treats a file, with nothing written unless the file is new. Never an error:
/// each case that leaves the server without an embedder says why on stderr.
/// - **The file records the built-in:** registered.
/// - **It records another embedder:** none.
/// - **It records none, and has memories besides its onboarding scaffold**
/// (vectors from somewhere else): none, and nothing is written.
/// - **It records none, and has only its scaffold:** registered and recorded
/// (a fresh file).
#[cfg(feature = "embed-candle")]
fn attach_builtin(db: &mut ServerDb, e: crate::BuiltinEmbedder) {
use crate::Embedder;
let without = |why: String| {
eprintln!(
"mnemo mcp: {why}: serving without an embedder; recall's 'text' is matched by \
keyword only"
);
};
let recorded = match db {
ServerDb::Plain(db) => db.embedder_identity(),
ServerDb::Shared(s) => s.read(|db| db.embedder_identity()),
};
let fresh = |db: &mut Mnemo| -> Result<bool> {
let onboarding = db.about()?.len();
Ok(db.len() <= onboarding)
};
match recorded {
Err(err) => return without(format!("can't read this file's embedder ({err})")),
Ok(Some(r)) if r != e.identity() => {
return without(format!(
"this file's embedder is {:?}, not the built-in (start with --embed-cmd and \
--embed-name for it, or move the file with `mnemo reembed`)",
r.name
))
}
Ok(Some(_)) => {}
Ok(None) => {
let only_scaffold = match db {
ServerDb::Plain(db) => fresh(db),
ServerDb::Shared(s) => s.read(fresh),
};
match only_scaffold {
Ok(true) => {}
Ok(false) => {
return without(
"this file records no embedder, and its memories' vectors came from \
elsewhere, so the built-in isn't recorded and nothing is written \
(start with --embed-cmd and --embed-name for the file's embedder, or \
move it to the built-in with `mnemo reembed <file>`)"
.to_string(),
)
}
Err(err) => return without(format!("can't read this file's memories ({err})")),
}
}
}
let name = e.identity().name;
let attached = match db {
ServerDb::Plain(db) => db.set_embedder(e),
ServerDb::Shared(s) => s.set_embedder(e),
};
match attached {
Ok(()) => eprintln!("mnemo mcp: embedder ready (the built-in, {name})"),
Err(err) => without(format!("the built-in can't be used on this file ({err})")),
}
}
/// The server's embedder, as chosen at start.
enum ServerEmbedder {
/// None: vectors (and keywords) only.
None,
/// `--embed-cmd`.
Command(EmbedSpec),
/// 12.3 step 5: the built-in, from the cache or a `--model-dir`.
#[cfg(feature = "embed-candle")]
Builtin(Option<std::path::PathBuf>),
}
fn serve_inner<R: Read, W: Write>(
path: &Path,
reader: R,
mut writer: W,
choice: ServerEmbedder,
shared: Option<SharedOptions>,
) -> Result<()> {
use crate::keys::{Resolution, Secret};
let store = crate::keys::default_store();
let found =
match crate::keys::resolve(path, store.as_deref(), crate::keys::SERVER_COMMAND_TIMEOUT)? {
Resolution::Found(r) => r,
Resolution::NoSource { notes, .. } => {
for n in ¬es {
eprintln!("mnemo mcp: note: {n}");
}
return Err(MnemoError::Invalid(format!(
"no secret for {}: set MNEMO_PASSPHRASE, MNEMO_KEY, MNEMO_KEY_FILE or \
MNEMO_KEY_COMMAND in the server's environment, or keep its key in the keychain \
(`mnemo init`, `mnemo unlock`); the server never prompts",
path.display()
)));
}
};
for n in &found.notes {
eprintln!("mnemo mcp: note: {n}");
}
// A secret from the server's environment when the brain has its own
// entry in the key store: say so, naming the source, since a client's
// config (or a project's committed one) set it.
if !matches!(found.source, crate::keys::Source::Store(_)) {
if let (Some(st), Ok(info)) = (store.as_deref(), crate::keys::file_info(path)) {
if matches!(st.get(&info.salt), Ok(Some(_))) {
eprintln!(
"mnemo mcp: note: the secret comes from {} in this server's environment, \
though this brain has its own entry in {}; if you didn't set it, look at \
this server's entry in the client's config",
found.source,
st.describe()
);
}
}
}
// 12.3 step 5: the built-in model loads (or is fetched) before the file
// is opened, so the download never holds the file's lock; and only for a
// file of its width (RB-010.1), read from the header first.
#[cfg(feature = "embed-candle")]
let builtin = match &choice {
ServerEmbedder::Builtin(dir) => builtin_for(path, dir.as_deref()),
_ => None,
};
eprintln!(
"mnemo mcp: opening {} with the secret from {} (protocol {PROTOCOL_VERSION})",
path.display(),
found.source
);
let mut db = match shared {
None => {
let db = match &found.secret {
Secret::Passphrase(p) => Mnemo::open(path, p)?,
Secret::Key(k) => Mnemo::open_with_key(path, k)?,
};
for n in db.notices() {
eprintln!("mnemo mcp: note: {n}");
}
ServerDb::Plain(db)
}
Some(opts) => {
let s = match &found.secret {
Secret::Passphrase(p) => Mnemo::open_shared(path, p, opts)?,
Secret::Key(k) => Mnemo::open_shared_with_key(path, k, opts)?,
};
// The notices once, at start (RB-007.8 item 9).
for n in s.notices() {
eprintln!("mnemo mcp: note: {n}");
}
eprintln!(
"mnemo mcp: shared mode: each tool call takes the file's lock, \
nothing is held between calls"
);
ServerDb::Shared(s)
}
};
#[cfg(feature = "embed-candle")]
if let Some(e) = builtin {
attach_builtin(&mut db, e);
}
if let ServerEmbedder::Command(EmbedSpec {
command: cmd,
name,
normalize,
timeout,
query_convention,
}) = choice
{
let dimensions = match &mut db {
ServerDb::Plain(db) => db.dimensions(),
ServerDb::Shared(s) => s.read(|db| Ok(db.dimensions()))?,
};
let identity = crate::EmbedderIdentity {
name,
dimensions,
normalize,
query_convention,
};
let embedder = crate::EmbedCmd::new(&cmd, identity)?.with_timeout(timeout);
match &mut db {
ServerDb::Plain(db) => db.set_embedder(embedder)?,
ServerDb::Shared(s) => s.set_embedder(embedder)?,
}
eprintln!(
"mnemo mcp: embedder ready (text params accepted, timeout {}s)",
timeout.as_secs()
);
}
eprintln!("mnemo mcp: ready ({} live memories)", db.len()?);
let reader = BufReader::new(reader);
// RB-011.1: a panic inside one request answers that request with an
// internal error instead of ending the server. After one inside a tool
// call the handle may hold a half-made change, so the server stops
// using it: later requests get an error, and nothing is flushed at
// shutdown (the file keeps its last committed state).
let mut broken = false;
for line in reader.lines() {
let line = line.map_err(MnemoError::Io)?;
let trimmed = line.trim();
if trimmed.is_empty() {
continue;
}
let (id, out) = match serde_json::from_str::<Request>(trimmed) {
Ok(req) => {
let id = req.id.clone();
let is_notification = id.is_none();
let result = if broken {
Err(RpcError::new(
INTERNAL_ERROR,
"an earlier tool call hit an internal error in mnemo, so this server \
stopped using the file; restart it",
))
} else {
match std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
handle(&mut db, &req)
})) {
Ok(r) => r,
Err(_) => {
broken = req.method == "tools/call";
eprintln!(
"mnemo mcp: internal error in {}{}",
req.method,
if broken {
"; the server stops using the file"
} else {
"; the server goes on"
}
);
Err(RpcError::new(
INTERNAL_ERROR,
format!("internal error in mnemo while handling {}", req.method),
))
}
}
};
if is_notification {
// Per JSON-RPC 2.0: notifications get no response.
continue;
}
(id.unwrap_or(Value::Null), result)
}
Err(e) => (
Value::Null,
Err(RpcError::new(PARSE_ERROR, format!("parse error: {e}"))),
),
};
let resp = match out {
Ok(value) => Response {
jsonrpc: "2.0",
id,
result: Some(value),
error: None,
},
Err(err) => Response {
jsonrpc: "2.0",
id,
result: None,
error: Some(err),
},
};
let line =
serde_json::to_string(&resp).map_err(|e| MnemoError::Serialize(e.to_string()))?;
writeln!(writer, "{line}").map_err(MnemoError::Io)?;
writer.flush().map_err(MnemoError::Io)?;
}
// Scoring v2 (v0.7.0) flipped `tool_recall` to `track_access(true)`:
// every recall bumps `accessed_at` / `access_count` in the catalog
// in memory (no per-call fsync). The previous `db.flush()` only
// fired on each mutating tool call's exit path, so a session that
// issued only `recall` / `about` / `stats` / `list` /
// `cache_get_semantic`-on-hit calls (read-shaped) would exit with
// every one of its access-stat bumps still in RAM, discarded on
// shutdown. Flush at shutdown so a read-only session persists its
// access stats too — the write is cheap (catalog page only; the
// record bodies aren't dirty) and guarantees the usage-saturation
// signal survives across sessions.
// PERF-1 (R-004.3): `close()` also persists the ANN index, which plain
// flushes now write only every so often.
// A shared server holds nothing between calls; its last recalls'
// statistics went with their read windows (they ride the next write).
if broken {
eprintln!("mnemo mcp: stdin closed; nothing flushed after the internal error");
return Ok(());
}
if let ServerDb::Plain(db) = db {
if let Err(e) = db.close() {
eprintln!("mnemo mcp: flush on shutdown failed: {e}");
}
}
eprintln!("mnemo mcp: stdin closed, shutting down");
Ok(())
}
// --- Dispatch ------------------------------------------------------------
/// Route a request to a method handler. Returns either the `result`
/// payload for a JSON-RPC success or an [`RpcError`] for a failure.
fn handle(db: &mut ServerDb, req: &Request) -> std::result::Result<Value, RpcError> {
// A dev-hooks build can be told to panic in one method, to test the
// server's catch (RB-011.1).
#[cfg(feature = "dev-hooks")]
if std::env::var("MNEMO_DEV_MCP_PANIC").is_ok_and(|m| m == req.method) {
panic!("MNEMO_DEV_MCP_PANIC");
}
if req.jsonrpc != "2.0" {
return Err(RpcError::new(
INVALID_REQUEST,
format!("expected jsonrpc \"2.0\", got {:?}", req.jsonrpc),
));
}
match req.method.as_str() {
"initialize" => Ok(initialize_result(&req.params)),
"notifications/initialized" | "notifications/cancelled" => Ok(Value::Null),
"ping" => Ok(json!({})),
"tools/list" => Ok(tools_list()),
// 12.2 step 3: resources and prompts (`mcp/context.rs`).
"resources/list" => Ok(context::resources_list()),
"resources/templates/list" => Ok(context::resource_templates_list()),
"resources/read" => context::resources_read(db, &req.params),
"prompts/list" => Ok(context::prompts_list()),
"prompts/get" => context::prompts_get(db, &req.params),
"tools/call" => match db {
ServerDb::Plain(db) => tools_call(db, &req.params),
ServerDb::Shared(s) => shared_tools_call(s, &req.params),
},
other => Err(RpcError::new(
METHOD_NOT_FOUND,
format!("method '{other}' not implemented"),
)),
}
}
/// Echo the client's requested protocol version if present; fall back to
/// ours. Always advertise the same `serverInfo` and `capabilities` block.
fn initialize_result(params: &Value) -> Value {
let client_version = params
.get("protocolVersion")
.and_then(|v| v.as_str())
.unwrap_or(PROTOCOL_VERSION)
.to_string();
json!({
"protocolVersion": client_version,
"capabilities": {
"tools": { "listChanged": false },
// 12.2 step 3: read-only resources, with no subscriptions and a
// fixed list, and two prompts.
"resources": {},
"prompts": {},
},
// GUIDE-1: the guide's card, from the binary.
"instructions": crate::guide::card(),
"serverInfo": {
"name": "mnemo",
"version": env!("CARGO_PKG_VERSION"),
},
})
}
// --- Tools registry ------------------------------------------------------
/// The seven tools this server exposes. Kept as a hand-authored constant
/// (rather than macro-derived) so the JSON schemas stay auditable —
/// every field a client sees is visible right here.
fn tools_list() -> Value {
json!({
"tools": [
{
"name": "about",
"description": "Read-only briefing for this .mnemo file: manifest scaffold plus any memories tagged as onboarding, then the project essence (conventions, decisions, open items) as a final `{kind: \"essence\", render}` element when the file has one. Run this first to learn how the file expects to be used.",
"inputSchema": {
"type": "object",
"properties": {},
"additionalProperties": false
}
},
{
"name": "remember",
"description": "Insert, overwrite, or UPSERT a memory. The server embeds `content` with its embedder; pass `text` only when the embedded text should differ, or `vector` for an explicit embedding. Phase 12.1: when `key` is set, this becomes a keyed upsert — if a live memory already holds this `(agent + key)` slot the prior record is marked `_mnemo.superseded_by` and a new one is inserted, and an identical re-write is a no-op. **PREFER `key` for any fact that replaces an earlier one** (versions, current status, user preferences, plan outcomes). Persists to disk before returning. Returns `{id, outcome}` where `outcome` is `added`, `superseded`, `unchanged`, or (no key) `inserted`.",
"inputSchema": {
"type": "object",
"required": ["content", "memory_type"],
"properties": {
"content": { "type": "string" },
"memory_type": { "type": "string", "enum": ["episodic", "semantic", "procedural", "working"] },
"vector": { "type": "array", "items": { "type": "number" }, "description": "Explicit embedding; mutually exclusive with `text`." },
"text": { "type": "string", "description": "Optional: what's embedded, when it should differ from `content` (which is embedded by default). Mutually exclusive with `vector`. Needs the server's embedder (the built-in, or --embed-cmd)." },
"importance": { "type": "number", "minimum": 0, "maximum": 1 },
"agent_id": { "type": "string" },
"session_id": { "type": "string" },
"ttl_secs": { "type": "integer" },
"shared": { "type": "boolean" },
"metadata": { "type": "object" },
"key": { "type": "string", "description": "Phase 12.1 upsert slot name. A later `remember` with the same `key` + agent scope supersedes the prior record; an identical re-write is a no-op. Use this for any fact that replaces an earlier one." },
"supersedes": { "type": "string", "description": "With `key` only (v0.15): the id of a memory written without a key, which this write adopts as the key's first version and supersedes. It stops showing in recall and stays in the key's history. Use it to put an old unkeyed fact under a key." }
},
"additionalProperties": false
}
},
{
"name": "update",
"description": "Edit a memory in place (Phase 12.1). Preserves the ULID, `created_at` and access stats. Any of `content` (needs `vector` to avoid embedding drift), `text` (re-embeds via the server), `importance`, `metadata`, `ttl_secs` can change. An identical patch returns `{id, outcome: 'unchanged'}` without writing. Prefer `remember` with `key` for facts that replace earlier ones; use `update` for in-place corrections to one specific record.",
"inputSchema": {
"type": "object",
"required": ["id"],
"properties": {
"id": { "type": "string", "description": "ULID of the memory to update." },
"content": { "type": "string", "description": "New content. Requires a matching `vector` (use `text` to re-embed instead)." },
"vector": { "type": "array", "items": { "type": "number" } },
"text": { "type": "string", "description": "New content; the server embeds it through its registered embedder. Mutually exclusive with `content` + `vector`." },
"importance": { "type": "number", "minimum": 0, "maximum": 1 },
"metadata": { "type": "object", "description": "Replace the user-visible metadata. Reserved `_mnemo.*` keys on the record are preserved." },
"ttl_secs": { "type": "integer", "description": "Set the TTL to this many seconds. Use `clear_ttl: true` to drop any TTL." },
"clear_ttl": { "type": "boolean", "description": "Clear any TTL on the record." }
},
"additionalProperties": false
}
},
{
"name": "essence",
"description": "Phase 12.7b: edit or render the essence layer of a thread (or the project layer). ONE tool for every op — set `op` to `add` / `append` / `update` / `resolve` / `remove` / `render`. **Call it when the goal, a decision, an open problem, the next step or the user's way of working changes, and append a timeline entry at each milestone.** Section items (`intent`, `conventions`, `decisions`, `state`, `open`, `next`, `lessons`) are ≤ 280 bytes and have an `open → resolved` lifecycle; `append` adds an append-only `timeline` entry (≤ 600 bytes). Thread-scoped (`thread`) or project-scoped (`project: true`). `render` returns the deterministic markdown view, budgeted at `budget` bytes (default 6144).",
"inputSchema": {
"type": "object",
"required": ["op"],
"properties": {
"op": { "type": "string", "enum": ["add", "append", "update", "resolve", "remove", "render"] },
"thread": { "type": "string", "description": "Thread id. Omit with `project: true` for the project layer." },
"project": { "type": "boolean", "default": false, "description": "Project-scoped item (shows in every thread's render). Mutually exclusive with `thread`." },
"section": { "type": "string", "enum": ["intent", "conventions", "decisions", "state", "open", "next", "lessons"], "description": "Required for `op: add`. Timeline uses `op: append`, not add." },
"id": { "type": "string", "description": "ULID of the section item. Required for update / resolve / remove." },
"text": { "type": "string", "description": "Required for add / append / update." },
"refs": { "type": "array", "items": { "type": "string" }, "description": "Optional free-form reference strings (turn ids, memory ids, commits, paths)." },
"budget": { "type": "integer", "default": 6144, "description": "Byte budget for `op: render`." }
},
"additionalProperties": false
}
},
{
"name": "thread_start",
"description": "Phase 12.7c: start a new thread that continues from a previous one. `essence {op: render, thread: <new>}` then pulls the prior thread's open items, `next` and last-N timeline entries ahead of the new thread's own essence — the 'new thread, same experience' path. Returns `{id}` (the link-record ULID).",
"inputSchema": {
"type": "object",
"required": ["new", "from"],
"properties": {
"new": { "type": "string", "description": "New thread id." },
"from": { "type": "string", "description": "Previous thread id to continue from." }
},
"additionalProperties": false
}
},
{
"name": "commit_deltas",
"description": "Atomic batch write: facts, essence ops and thread archive turns in one call. Every item is checked before anything is written, so an invalid item writes nothing; one flush on success. Facts may omit `vector`: the server embeds every fact `content`, essence text and turn in one batched call with its embedder (`--embed-cmd` or builtin). Use at a session end to save a burst of updates in one round trip. `turn_policy` defaults to `archive`; `expire_after` takes a TTL in seconds; `drop` discards turns. Returns a counts summary.",
"inputSchema": {
"type": "object",
"properties": {
"facts": {
"type": "array",
"items": {
"type": "object",
"required": ["content", "memory_type"],
"properties": {
"content": { "type": "string" },
"memory_type": { "type": "string", "enum": ["episodic", "semantic", "procedural", "working"] },
"vector": { "type": "array", "items": { "type": "number" }, "description": "Optional. Omit it to have the server embed `content`." },
"importance": { "type": "number", "minimum": 0, "maximum": 1 },
"agent_id": { "type": "string" },
"session_id": { "type": "string" },
"shared": { "type": "boolean" },
"metadata": { "type": "object" },
"key": { "type": "string" }
}
}
},
"essence_ops": {
"type": "array",
"items": {
"type": "object",
"required": ["kind"],
"properties": {
"kind": { "type": "string", "enum": ["add", "append_timeline", "update", "resolve", "remove"] },
"thread": { "type": "string" },
"project": { "type": "boolean" },
"section": { "type": "string" },
"id": { "type": "string" },
"text": { "type": "string" },
"refs": { "type": "array", "items": { "type": "string" } }
}
}
},
"turns": {
"type": "array",
"items": {
"type": "object",
"required": ["turn_id", "role", "content"],
"properties": {
"turn_id": { "type": "string" },
"role": { "type": "string" },
"content": { "type": "string" },
"timestamp": { "type": "integer" }
}
}
},
"thread_id": { "type": "string", "description": "Required when `turns` is non-empty." },
"turn_policy": { "type": "string", "enum": ["archive", "expire_after", "drop"], "default": "archive" },
"turn_policy_ttl": { "type": "integer", "description": "TTL in seconds; required when `turn_policy = 'expire_after'`." }
},
"additionalProperties": false
}
},
{
"name": "thread_ingest",
"description": "Phase 12.7a: ingest a transcript file into a thread's archive layer. Idempotent per `turn_id` — re-running on a longer transcript appends only the new turns. Requires an embedder on the server (`--embed-cmd` at serve start) because every turn is embedded. Returns `{added_records, skipped_existing_turns, chunked_turns, truncated_turns}`.",
"inputSchema": {
"type": "object",
"required": ["thread", "transcript_path"],
"properties": {
"thread": { "type": "string", "description": "Thread id to append under." },
"transcript_path": { "type": "string", "description": "Local path to the transcript file." },
"format": { "type": "string", "enum": ["jsonl", "claude-code-jsonl"], "default": "jsonl" }
},
"additionalProperties": false
}
},
{
"name": "thread_export",
"description": "Return a thread's archive in the ingest shape: `[{turn_id, role, content, timestamp}]` in order, one entry per turn (long turns' chunks joined), plus `sha256` and `original_length` on a truncated tool result. Feeding it back to ingest for the same thread adds nothing.",
"inputSchema": {
"type": "object",
"required": ["thread"],
"properties": {
"thread": { "type": "string", "description": "Thread id to export." }
},
"additionalProperties": false
}
},
{
"name": "history",
"description": "Walk the full chain for a keyed slot (Phase 12.1), newest first. Entry 0 is the live record (or empty if the slot is empty); subsequent entries are the superseded history. Slot resolution matches keyed `remember`: with no `agent` and `shared=false`, walks the default agent's private slot (v0.8.1 bugfix — pre-v0.8.1 this walked the shared slot by accident and returned empty for the common case). Pass `shared: true` for the shared slot; `agent` + `shared=true` is rejected.",
"inputSchema": {
"type": "object",
"required": ["key"],
"properties": {
"key": { "type": "string" },
"agent": { "type": "string", "description": "Query the private slot for this agent. Mutually exclusive with `shared`." },
"shared": { "type": "boolean", "default": false, "description": "Query the shared slot (one per file). Mutually exclusive with `agent`." }
},
"additionalProperties": false
}
},
{
"name": "recall",
"description": "Score every live memory (or the ANN-narrowed candidate set) against a query and return the top-k. Pass EITHER `query` (explicit vector) OR `text` (embedded by the server; requires --embed-cmd at serve start). Phase 12.6: add a `filter` object to restrict candidates before scoring (`session_id` plus per-metadata-key conditions: equality, `$in`, `$exists`, `$gte`/`$lte`). Phase 12.1: superseded records never appear. Phase 12.8: set `max_bytes: N` to cap the total UTF-8 bytes of returned `content` fields; the response is then shaped as `{hits: [...], truncated: bool}` so the caller can tell whether the budget cut hits. Without `max_bytes`, the response is a bare JSON array of hits (unchanged). Keyword matching (v9 files): a recall by `text` also matches the text's words (hybrid by default, since v0.15); put identifiers the text doesn't contain (a version like v0.9.0, a PR number, a function name) in `keywords`, which then replace the text for keyword matching, or pass `keywords: \"\"` for vector-only recall. Parts of dotted names and possessives match too (`nosync` finds `mnemo.nosync`). `keywords` alone (no `query`/`text`) is keyword-only recall.",
"inputSchema": {
"type": "object",
"properties": {
"query": { "type": "array", "items": { "type": "number" }, "description": "Explicit query vector; mutually exclusive with `text`." },
"keywords": { "type": "string", "description": "Identifiers or exact terms to match (a version, a PR number, a function name). With `text`, they replace the text for keyword matching; \"\" turns keyword matching off. Needs a v9 file." },
"text": { "type": "string", "description": "Query text; embedded by the server's registered embedder. Mutually exclusive with `query`." },
"top_k": { "type": "integer", "default": 10 },
"types": { "type": "array", "items": { "type": "string" } },
"agent": { "type": "string" },
"metric": { "type": "string", "enum": ["cosine", "l2", "dot"], "default": "cosine" },
"max_bytes": { "type": "integer", "minimum": 1, "description": "Phase 12.8 budget: stop adding hits once the UTF-8 bytes of their `content` fields would exceed N. Always returns at least the top hit. When set, the response is `{hits, truncated}` instead of a bare array." },
"filter": {
"type": "object",
"description": "Phase 12.6 pre-scoring filter. All conditions AND together. Shape: `{\"session_id\": \"...\", \"metadata\": {key: value | {\"$in\": [...]} | {\"$exists\": true} | {\"$gte\": n, \"$lte\": n}}}`.",
"properties": {
"session_id": { "type": "string" },
"metadata": { "type": "object" }
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
{
"name": "forget",
"description": "Soft-delete a memory by ULID. Space is reclaimed on the next `mnemo compact`. Persists to disk before returning.",
"inputSchema": {
"type": "object",
"required": ["id"],
"properties": {
"id": { "type": "string", "description": "ULID of the memory to delete" }
},
"additionalProperties": false
}
},
{
"name": "list",
"description": "Return every live memory as JSON. Sorted by creation time, oldest first. Vectors are omitted by default to keep payloads small.",
"inputSchema": {
"type": "object",
"properties": {
"include_vectors": { "type": "boolean", "default": false }
},
"additionalProperties": false
}
},
{
"name": "snapshot_list",
"description": "List every restorable snapshot (one per committed flush). Each entry gives the transaction ID, creation timestamp, and memory count.",
"inputSchema": {
"type": "object",
"properties": {},
"additionalProperties": false
}
},
{
"name": "stats",
"description": "Summary statistics: memory count, deleted count, agents present, snapshot count, page cache occupancy.",
"inputSchema": {
"type": "object",
"properties": {},
"additionalProperties": false
}
},
{
"name": "cache_put",
"description": "Insert or overwrite an exact-key cache entry. Value is a UTF-8 string; use `content_type` to label the payload. Persists to disk before returning. Namespace and key are caller-chosen; the key is SHA-256 hashed by the engine.",
"inputSchema": {
"type": "object",
"required": ["namespace", "key", "value"],
"properties": {
"namespace": { "type": "string" },
"key": { "type": "string" },
"value": { "type": "string" },
"content_type": { "type": "string", "default": "text" },
"ttl_secs": { "type": "integer", "minimum": 0 }
},
"additionalProperties": false
}
},
{
"name": "cache_get",
"description": "Look up an exact-key cache entry. Returns `{value, content_type, hit}` on a hit, `{hit: false}` on miss (missing or TTL-expired). Bumps access stats catalog-only.",
"inputSchema": {
"type": "object",
"required": ["namespace", "key"],
"properties": {
"namespace": { "type": "string" },
"key": { "type": "string" }
},
"additionalProperties": false
}
},
{
"name": "cache_stats",
"description": "Cache statistics for a namespace (omit for the whole cache). Returns entries, bytes, hits, misses, hit_rate, evictions.",
"inputSchema": {
"type": "object",
"properties": {
"namespace": { "type": "string" }
},
"additionalProperties": false
}
},
{
"name": "cache_put_semantic",
"description": "Insert an entry with an embedding vector for semantic recall (Phase 10.2). Pass EITHER `vector` + `model` (explicit) OR `text` (embedded by the server; `model` defaults to the server embedder's identity name). Later cache_get_semantic calls under a different `model` won't see this entry (a different-model hit would be a semantics bug).",
"inputSchema": {
"type": "object",
"required": ["namespace", "key", "value"],
"properties": {
"namespace": { "type": "string" },
"key": { "type": "string" },
"vector": { "type": "array", "items": { "type": "number" }, "description": "Explicit embedding; mutually exclusive with `text`. Requires `model`." },
"text": { "type": "string", "description": "Content to embed via the server's registered embedder; mutually exclusive with `vector`." },
"value": { "type": "string" },
"model": { "type": "string", "description": "Required with `vector`; optional with `text` (defaults to the embedder's identity name)." },
"content_type": { "type": "string", "default": "text" },
"ttl_secs": { "type": "integer", "minimum": 0 }
},
"additionalProperties": false
}
},
{
"name": "cache_get_semantic",
"description": "Semantic recall over the cache: top-1 cosine over live vectored entries in the namespace whose `model` matches. Pass EITHER `query` + `model` OR `text` (which embeds via the server and defaults the model to the embedder's identity). Returns `{hit: true, value, similarity, ...}` iff similarity >= threshold, else `{hit: false}`. Threshold defaults to 0.97.",
"inputSchema": {
"type": "object",
"required": ["namespace"],
"properties": {
"namespace": { "type": "string" },
"query": { "type": "array", "items": { "type": "number" }, "description": "Explicit query vector; mutually exclusive with `text`. Requires `model`." },
"text": { "type": "string", "description": "Query text; embedded by the server. Mutually exclusive with `query`." },
"model": { "type": "string", "description": "Required with `query`; optional with `text`." },
"threshold": { "type": "number", "minimum": -1.0, "maximum": 1.0 }
},
"additionalProperties": false
}
}
]
})
}
// --- Tool dispatch -------------------------------------------------------
/// The MCP `tools/call` method: dispatches on the caller-supplied `name`
/// and returns the tool's `content` array wrapped in an MCP result.
fn tools_call(db: &mut Mnemo, params: &Value) -> std::result::Result<Value, RpcError> {
let name = params
.get("name")
.and_then(|v| v.as_str())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "missing tool name"))?;
let empty = json!({});
let args = params.get("arguments").unwrap_or(&empty);
let text = match name {
"about" => tool_about(db)?,
"remember" => tool_remember(db, args)?,
"update" => tool_update(db, args)?,
"history" => tool_history(db, args)?,
"thread_ingest" => tool_thread_ingest(db, args)?,
"thread_export" => tool_thread_export(db, args)?,
"thread_start" => tool_thread_start(db, args)?,
"commit_deltas" => tool_commit_deltas(db, args)?,
"essence" => tool_essence(db, args)?,
"recall" => tool_recall(db, args)?,
"forget" => tool_forget(db, args)?,
"list" => tool_list(db, args)?,
"snapshot_list" => tool_snapshot_list(db)?,
"stats" => tool_stats(db)?,
"cache_put" => tool_cache_put(db, args)?,
"cache_get" => tool_cache_get(db, args)?,
"cache_stats" => tool_cache_stats(db, args)?,
"cache_put_semantic" => tool_cache_put_semantic(db, args)?,
"cache_get_semantic" => tool_cache_get_semantic(db, args)?,
other => {
return Err(RpcError::new(
METHOD_NOT_FOUND,
format!("unknown tool '{other}'"),
))
}
};
Ok(json!({
"content": [ { "type": "text", "text": text } ],
"isError": false,
}))
}
/// 12.4: one tool call as one window (RB-007.5 rec. 3: one engine call per
/// window). A tool's own error aborts a write window, so nothing it did is
/// committed (unless it committed part of its work itself, which comes
/// back as `MaybeStored`).
fn shared_tools_call(s: &mut SharedMnemo, params: &Value) -> std::result::Result<Value, RpcError> {
let name = params.get("name").and_then(|v| v.as_str()).unwrap_or("");
pre_embed(s, params)?;
let mut tool_err: Option<RpcError> = None;
let run = |db: &mut Mnemo, tool_err: &mut Option<RpcError>| match tools_call(db, params) {
Ok(v) => Ok(v),
Err(e) => {
let msg = e.message.clone();
*tool_err = Some(e);
Err(MnemoError::Invalid(msg))
}
};
let r = if is_read_tool(name) {
s.read(|db| run(db, &mut tool_err))
} else {
s.write(|db| run(db, &mut tool_err))
};
// A vector the tool didn't use (it failed first) never reaches the next.
PRE_EMBEDDED.with(|p| p.borrow_mut().take());
match r {
Ok(v) => Ok(v),
// Part of the window is in the file: say so, whatever the tool said.
Err(e @ MnemoError::MaybeStored(_)) => Err(mnemo_err(e)),
Err(e) => match tool_err {
Some(t) => Err(t),
None => Err(mnemo_err(e)),
},
}
}
/// Convert a [`MnemoError`] to an [`RpcError`]. Every error becomes an
/// `INTERNAL_ERROR` with the human-readable message — MCP clients
/// display `error.message` verbatim to the user.
/// Resolve a text argument into a vector via the server's registered
/// embedder (Phase 3 PR 10b). Called by the four MCP tools that
/// accept `text` as an alternative to the explicit vector: `remember`,
/// `recall`, `cache_put_semantic`, `cache_get_semantic`. If no
/// embedder was configured at server start (`mnemo serve --mcp
/// --embed-cmd ...`) the error message tells the caller how to turn
/// it on.
fn embed_text_via_server(
db: &mut Mnemo,
tool: &str,
text: &str,
) -> std::result::Result<Vec<f32>, RpcError> {
// 12.4: a shared server embedded this text before it took the lock.
if let Some(v) = take_pre_embedded(text) {
return Ok(v);
}
let embedder = db.embedder().ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
format!(
"{tool}: 'text' requires an embedder on the server. \
`mnemo serve --mcp <file>` uses the built-in one (`mnemo embedder status` \
says whether it's installed), or start with --embed-cmd '<cmd>' \
--embed-name <name>"
),
)
})?;
let mut vs = embed_for_tool(embedder, tool, text)?;
vs.pop().ok_or_else(|| {
RpcError::new(
INTERNAL_ERROR,
format!("{tool}: embedder returned no vector for the input text"),
)
})
}
/// 12.3 step 4: `recall` embeds its text as a query; everything else
/// (`remember`, and both semantic-cache tools, whose two sides hold the
/// same kind of text) as a document.
fn embed_for_tool(
embedder: &dyn crate::Embedder,
tool: &str,
text: &str,
) -> std::result::Result<Vec<Vec<f32>>, RpcError> {
if tool == "recall" {
embedder.embed_query(&[text]).map_err(mnemo_err)
} else {
embedder.embed(&[text]).map_err(mnemo_err)
}
}
thread_local! {
/// 12.4: the vector a shared server computed for a tool's `text` before
/// its window, for [`embed_text_via_server`] to use inside it.
static PRE_EMBEDDED: std::cell::RefCell<Option<(String, Vec<f32>)>> =
const { std::cell::RefCell::new(None) };
}
fn take_pre_embedded(text: &str) -> Option<Vec<f32>> {
PRE_EMBEDDED.with(|p| {
let mut p = p.borrow_mut();
match p.as_ref() {
Some((t, _)) if t == text => p.take().map(|(_, v)| v),
_ => None,
}
})
}
/// The four tools that take `text` in place of a vector, and the name of
/// that vector's argument.
fn text_tool_vector_arg(name: &str) -> Option<&'static str> {
match name {
"remember" | "cache_put_semantic" => Some("vector"),
"recall" | "cache_get_semantic" => Some("query"),
_ => None,
}
}
/// 12.4 (the protocol's step 1, slow work first and unlocked): a shared
/// server embeds a tool's `text` before it takes the file's lock, so every
/// other session isn't kept waiting behind the embedder. The tool then
/// finds the vector through [`embed_text_via_server`], with its messages
/// unchanged. Nothing happens when the tool has no `text`, was also given a
/// vector (the tool reports that), or the server has no embedder (the tool
/// says how to add one).
fn pre_embed(s: &SharedMnemo, params: &Value) -> std::result::Result<(), RpcError> {
let name = params.get("name").and_then(|v| v.as_str()).unwrap_or("");
let Some(vector_arg) = text_tool_vector_arg(name) else {
return Ok(());
};
let Some(args) = params.get("arguments") else {
return Ok(());
};
// 12.2 step 3: `remember` with no `text` embeds its `content`.
let text = args.get("text").and_then(Value::as_str).or_else(|| {
(name == "remember")
.then(|| args.get("content").and_then(Value::as_str))
.flatten()
});
let (Some(text), None) = (text, args.get(vector_arg)) else {
return Ok(());
};
let Some(embedder) = s.embedder_arc() else {
return Ok(());
};
let mut vs = embed_for_tool(embedder.as_ref(), name, text)?;
let v = vs.pop().ok_or_else(|| {
RpcError::new(
INTERNAL_ERROR,
format!("{name}: embedder returned no vector for the input text"),
)
})?;
PRE_EMBEDDED.with(|p| *p.borrow_mut() = Some((text.to_string(), v)));
Ok(())
}
fn mnemo_err(e: MnemoError) -> RpcError {
RpcError::new(INTERNAL_ERROR, e.to_string())
}
fn tool_about(db: &mut Mnemo) -> std::result::Result<String, RpcError> {
let mems = db.about().map_err(mnemo_err)?;
let mut arr: Vec<Value> = mems.iter().map(memory_to_json).collect();
// Phase 12.7d: the project essence follows the manifest and the
// onboarding memories, as one tagged element.
if let Some(render) = db.about_essence().map_err(mnemo_err)? {
arr.push(json!({ "kind": "essence", "scope": "project", "render": render }));
}
Ok(serde_json::to_string_pretty(&arr).unwrap_or_else(|_| "[]".into()))
}
fn tool_thread_export(db: &mut Mnemo, args: &Value) -> std::result::Result<String, RpcError> {
let thread = args
.get("thread")
.and_then(|v| v.as_str())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "thread_export: missing 'thread'"))?;
let turns = db.thread_export_turns(thread).map_err(mnemo_err)?;
let arr: Vec<Value> = turns.iter().map(|t| t.to_json()).collect();
Ok(Value::Array(arr).to_string())
}
fn tool_remember(db: &mut Mnemo, args: &Value) -> std::result::Result<String, RpcError> {
let content = args
.get("content")
.and_then(|v| v.as_str())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "remember: missing 'content'"))?;
let mtype_str = args
.get("memory_type")
.and_then(|v| v.as_str())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "remember: missing 'memory_type'"))?;
let mtype = MemoryType::parse(mtype_str).ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
format!("remember: unknown memory_type '{mtype_str}'"),
)
})?;
// Accept either `vector` (explicit) or `text` (embedded via the
// server's registered embedder, Phase 3). Exactly one required.
let vector = match (args.get("vector"), args.get("text")) {
(Some(_), Some(_)) => {
return Err(RpcError::new(
INVALID_PARAMS,
"remember: pass EITHER 'vector' or 'text', not both",
));
}
(Some(v), None) => v
.as_array()
.ok_or_else(|| {
RpcError::new(INVALID_PARAMS, "remember: 'vector' must be a JSON array")
})?
.iter()
.map(|v| v.as_f64().map(|f| f as f32))
.collect::<Option<Vec<f32>>>()
.ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
"remember: 'vector' must be an array of numbers",
)
})?,
(None, Some(t)) => {
let text = t.as_str().ok_or_else(|| {
RpcError::new(INVALID_PARAMS, "remember: 'text' must be a string")
})?;
embed_text_via_server(db, "remember", text)?
}
// 12.2 step 3: with neither, the server embeds `content`.
(None, None) => embed_text_via_server(db, "remember", content)?,
};
let mut mem = Memory::new(content, mtype, vector);
if let Some(agent) = args.get("agent_id").and_then(|v| v.as_str()) {
mem = mem.with_agent(agent);
}
if let Some(sess) = args.get("session_id").and_then(|v| v.as_str()) {
mem = mem.with_session(sess);
}
if let Some(imp) = args.get("importance").and_then(|v| v.as_f64()) {
mem = mem.with_importance(imp as f32);
}
if let Some(ttl) = args.get("ttl_secs").and_then(|v| v.as_i64()) {
mem = mem.with_ttl(ttl);
}
if let Some(shared) = args.get("shared").and_then(|v| v.as_bool()) {
if shared {
mem = mem.with_scope(Scope::Shared);
}
}
if let Some(meta) = args.get("metadata").and_then(|v| v.as_object()) {
for (k, v) in meta {
mem.metadata.insert(k.clone(), v.clone());
}
}
// Phase 12.1: when `key` is set, take the keyed-upsert path
// (supersede / no-op / add); otherwise keep the pre-12.1
// single-id return shape (now carrying `outcome: "inserted"` so
// callers can distinguish it from the keyed outcomes).
// v0.15 (12.3 step 5b): `supersedes` names a memory written without a
// key, which the keyed write adopts as its first version.
let supersedes = match args.get("supersedes") {
None | Some(Value::Null) => None,
Some(v) => {
let s = v.as_str().ok_or_else(|| {
RpcError::new(INVALID_PARAMS, "remember: 'supersedes' must be a memory id")
})?;
Some(crate::Ulid::from_string(s).map_err(|_| {
RpcError::new(
INVALID_PARAMS,
format!("remember: 'supersedes' is not a memory id: {s}"),
)
})?)
}
};
match args.get("key").and_then(|v| v.as_str()) {
None if supersedes.is_some() => Err(RpcError::new(
INVALID_PARAMS,
"remember: 'supersedes' needs 'key'",
)),
None => {
let id = db.remember(mem).map_err(mnemo_err)?;
db.flush().map_err(mnemo_err)?;
Ok(json!({ "id": id.to_string(), "outcome": "inserted" }).to_string())
}
Some(k) => {
let (id, outcome) = match &supersedes {
Some(old) => db.remember_keyed_superseding(mem, k, old),
None => db.remember_keyed(mem, k),
}
.map_err(mnemo_err)?;
db.flush().map_err(mnemo_err)?;
let outcome_str = match outcome {
crate::WriteOutcome::Added => "added",
crate::WriteOutcome::Superseded => "superseded",
crate::WriteOutcome::Unchanged => "unchanged",
crate::WriteOutcome::Updated => "updated",
};
Ok(json!({ "id": id.to_string(), "outcome": outcome_str }).to_string())
}
}
}
fn tool_update(db: &mut Mnemo, args: &Value) -> std::result::Result<String, RpcError> {
use crate::Ulid;
use crate::{MemoryPatch, WriteOutcome};
let id_str = args
.get("id")
.and_then(|v| v.as_str())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "update: missing 'id'"))?;
let id = Ulid::from_string(id_str)
.map_err(|_| RpcError::new(INVALID_PARAMS, format!("update: invalid ULID '{id_str}'")))?;
// Mutually exclusive: `text` (server re-embeds) vs `content`+`vector`
// (explicit). Either path produces `(new_content, new_vector)` for
// the engine; both unset means no text/vector change.
let has_text = args.get("text").is_some();
let has_content = args.get("content").is_some();
let has_vector = args.get("vector").is_some();
if has_text && (has_content || has_vector) {
return Err(RpcError::new(
INVALID_PARAMS,
"update: pass EITHER 'text' or 'content'+'vector', not both",
));
}
let mut patch = MemoryPatch::default();
if has_content {
let c = args
.get("content")
.and_then(|v| v.as_str())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "update: 'content' must be a string"))?;
patch.content = Some(c.to_string());
}
if has_vector {
let v = args
.get("vector")
.and_then(|v| v.as_array())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "update: 'vector' must be a JSON array"))?
.iter()
.map(|v| v.as_f64().map(|f| f as f32))
.collect::<Option<Vec<f32>>>()
.ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
"update: 'vector' must be an array of numbers",
)
})?;
patch.vector = Some(v);
}
if let Some(imp) = args.get("importance").and_then(|v| v.as_f64()) {
patch.importance = Some(imp as f32);
}
if let Some(meta) = args.get("metadata").and_then(|v| v.as_object()) {
patch.metadata = Some(meta.clone());
}
let clear_ttl = args
.get("clear_ttl")
.and_then(|v| v.as_bool())
.unwrap_or(false);
if clear_ttl {
patch.ttl_secs = Some(None);
} else if let Some(ttl) = args.get("ttl_secs").and_then(|v| v.as_i64()) {
patch.ttl_secs = Some(Some(ttl));
}
let outcome = if has_text {
let t = args
.get("text")
.and_then(|v| v.as_str())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "update: 'text' must be a string"))?;
db.update_text(&id, t, patch).map_err(mnemo_err)?
} else {
db.update(&id, patch).map_err(mnemo_err)?
};
db.flush().map_err(mnemo_err)?;
let outcome_str = match outcome {
WriteOutcome::Updated => "updated",
WriteOutcome::Unchanged => "unchanged",
WriteOutcome::Added => "updated",
WriteOutcome::Superseded => "updated",
};
Ok(json!({ "id": id.to_string(), "outcome": outcome_str }).to_string())
}
fn tool_thread_start(db: &mut Mnemo, args: &Value) -> std::result::Result<String, RpcError> {
let new = args
.get("new")
.and_then(|v| v.as_str())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "thread_start: missing 'new'"))?;
let from = args
.get("from")
.and_then(|v| v.as_str())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "thread_start: missing 'from'"))?;
let id = db.thread_start(new, from).map_err(mnemo_err)?;
db.flush().map_err(mnemo_err)?;
Ok(json!({ "id": id.to_string() }).to_string())
}
fn tool_commit_deltas(db: &mut Mnemo, args: &Value) -> std::result::Result<String, RpcError> {
use crate::{
CommitBatch, EssenceOp, EssenceOpKind, EssenceScope, EssenceSection, KeyedMemory,
ThreadTurn, TurnPolicy, Ulid,
};
let mut batch = CommitBatch::default();
// facts
if let Some(arr) = args.get("facts").and_then(|v| v.as_array()) {
for (i, f) in arr.iter().enumerate() {
let obj = f.as_object().ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
format!("commit_deltas: facts[{i}] must be an object"),
)
})?;
let content = obj.get("content").and_then(|v| v.as_str()).ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
format!("commit_deltas: facts[{i}] missing 'content'"),
)
})?;
let mtype_str = obj
.get("memory_type")
.and_then(|v| v.as_str())
.ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
format!("commit_deltas: facts[{i}] missing 'memory_type'"),
)
})?;
let mtype = MemoryType::parse(mtype_str).ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
format!("commit_deltas: facts[{i}] unknown memory_type '{mtype_str}'"),
)
})?;
// 12.7d: `vector` is optional. Without one the engine embeds
// `content` with the server's embedder, batched with the rest
// of the call.
let vector = match obj.get("vector") {
None | Some(Value::Null) => Vec::new(),
Some(v) => v
.as_array()
.and_then(|a| {
a.iter()
.map(|x| x.as_f64().map(|f| f as f32))
.collect::<Option<Vec<f32>>>()
})
.ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
format!("commit_deltas: facts[{i}] vector must be an array of numbers"),
)
})?,
};
let mut mem = Memory::new(content, mtype, vector);
if let Some(a) = obj.get("agent_id").and_then(|v| v.as_str()) {
mem = mem.with_agent(a);
}
if let Some(s) = obj.get("session_id").and_then(|v| v.as_str()) {
mem = mem.with_session(s);
}
if let Some(imp) = obj.get("importance").and_then(|v| v.as_f64()) {
mem = mem.with_importance(imp as f32);
}
if let Some(shared) = obj.get("shared").and_then(|v| v.as_bool()) {
if shared {
mem = mem.with_scope(Scope::Shared);
}
}
if let Some(meta) = obj.get("metadata").and_then(|v| v.as_object()) {
for (k, v) in meta {
mem.metadata.insert(k.clone(), v.clone());
}
}
let key = obj.get("key").and_then(|v| v.as_str()).map(String::from);
batch.facts.push(KeyedMemory { memory: mem, key });
}
}
// essence_ops
if let Some(arr) = args.get("essence_ops").and_then(|v| v.as_array()) {
for (i, o) in arr.iter().enumerate() {
let obj = o.as_object().ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
format!("commit_deltas: essence_ops[{i}] must be an object"),
)
})?;
let kind_str = obj.get("kind").and_then(|v| v.as_str()).ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
format!("commit_deltas: essence_ops[{i}] missing 'kind'"),
)
})?;
let kind = match kind_str {
"add" => EssenceOpKind::Add,
"append_timeline" => EssenceOpKind::AppendTimeline,
"update" => EssenceOpKind::Update,
"resolve" => EssenceOpKind::Resolve,
"remove" => EssenceOpKind::Remove,
other => {
return Err(RpcError::new(
INVALID_PARAMS,
format!("commit_deltas: essence_ops[{i}] unknown kind '{other}'"),
));
}
};
let thread = obj.get("thread").and_then(|v| v.as_str()).map(String::from);
let project = obj
.get("project")
.and_then(|v| v.as_bool())
.unwrap_or(false);
let scope = match (thread, project) {
(Some(t), false) => Some(EssenceScope::Thread(t)),
(None, true) => Some(EssenceScope::Project),
(None, false) => None,
(Some(_), true) => {
return Err(RpcError::new(
INVALID_PARAMS,
format!(
"commit_deltas: essence_ops[{i}] can't set both 'thread' and 'project'"
),
));
}
};
let section = obj
.get("section")
.and_then(|v| v.as_str())
.and_then(EssenceSection::parse);
let id = obj
.get("id")
.and_then(|v| v.as_str())
.map(Ulid::from_string)
.transpose()
.map_err(|_| {
RpcError::new(
INVALID_PARAMS,
format!("commit_deltas: essence_ops[{i}] 'id' is not a valid ULID"),
)
})?;
let text = obj.get("text").and_then(|v| v.as_str()).map(String::from);
let refs = obj.get("refs").and_then(|v| v.as_array()).map(|a| {
a.iter()
.filter_map(|x| x.as_str().map(String::from))
.collect()
});
batch.essence_ops.push(EssenceOp {
kind,
scope,
section,
id,
text,
refs,
});
}
}
// turns
if let Some(arr) = args.get("turns").and_then(|v| v.as_array()) {
for (i, t) in arr.iter().enumerate() {
let obj = t.as_object().ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
format!("commit_deltas: turns[{i}] must be an object"),
)
})?;
let turn_id = obj
.get("turn_id")
.and_then(|v| v.as_str())
.ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
format!("commit_deltas: turns[{i}] missing 'turn_id'"),
)
})?
.to_string();
let role = obj
.get("role")
.and_then(|v| v.as_str())
.ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
format!("commit_deltas: turns[{i}] missing 'role'"),
)
})?
.to_string();
let content = obj
.get("content")
.and_then(|v| v.as_str())
.ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
format!("commit_deltas: turns[{i}] missing 'content'"),
)
})?
.to_string();
let timestamp = obj.get("timestamp").and_then(|v| v.as_i64());
batch.turns.push(ThreadTurn {
turn_id,
role,
content,
timestamp,
});
}
}
batch.thread_id = args
.get("thread_id")
.and_then(|v| v.as_str())
.map(String::from);
let policy_str = args
.get("turn_policy")
.and_then(|v| v.as_str())
.unwrap_or("archive");
batch.turn_policy = match policy_str {
"archive" => TurnPolicy::Archive,
"drop" => TurnPolicy::Drop,
"expire_after" => {
let ttl = args
.get("turn_policy_ttl")
.and_then(|v| v.as_i64())
.ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
"commit_deltas: turn_policy='expire_after' requires 'turn_policy_ttl' (seconds)",
)
})?;
TurnPolicy::ExpireAfter(ttl)
}
other => {
return Err(RpcError::new(
INVALID_PARAMS,
format!("commit_deltas: unknown turn_policy '{other}'"),
));
}
};
let report = db.commit_deltas(batch).map_err(mnemo_err)?;
Ok(json!({
"facts_added": report.facts_added,
"facts_superseded": report.facts_superseded,
"facts_unchanged": report.facts_unchanged,
"essence_ops_applied": report.essence_ops_applied,
"essence_ops_unchanged": report.essence_ops_unchanged,
"turns_added": report.turns_added,
"turns_skipped": report.turns_skipped,
"turns_truncated": report.turns_truncated,
"turns_chunked": report.turns_chunked,
})
.to_string())
}
fn tool_essence(db: &mut Mnemo, args: &Value) -> std::result::Result<String, RpcError> {
use crate::{EssenceScope, EssenceSection, Ulid, WriteOutcome};
let op = args
.get("op")
.and_then(|v| v.as_str())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "essence: missing 'op'"))?;
let thread = args
.get("thread")
.and_then(|v| v.as_str())
.map(String::from);
let project = args
.get("project")
.and_then(|v| v.as_bool())
.unwrap_or(false);
let scope_from = |t: Option<String>, p: bool| -> std::result::Result<EssenceScope, RpcError> {
match (t, p) {
(Some(s), false) => Ok(EssenceScope::Thread(s)),
(None, true) => Ok(EssenceScope::Project),
(None, false) => Err(RpcError::new(
INVALID_PARAMS,
"essence: pass either `thread` or `project: true`",
)),
(Some(_), true) => Err(RpcError::new(
INVALID_PARAMS,
"essence: `thread` and `project` are mutually exclusive",
)),
}
};
let refs: Option<Vec<String>> = args.get("refs").and_then(|v| v.as_array()).map(|arr| {
arr.iter()
.filter_map(|x| x.as_str().map(String::from))
.collect()
});
let text = args.get("text").and_then(|v| v.as_str()).map(String::from);
let id_str = args.get("id").and_then(|v| v.as_str());
let outcome_to_str = |o: WriteOutcome| -> &'static str {
match o {
WriteOutcome::Updated => "updated",
WriteOutcome::Unchanged => "unchanged",
WriteOutcome::Added => "updated",
WriteOutcome::Superseded => "updated",
}
};
match op {
"add" => {
let section_str = args
.get("section")
.and_then(|v| v.as_str())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "essence add: missing 'section'"))?;
let section = EssenceSection::parse(section_str).ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
format!("essence add: unknown section '{section_str}'"),
)
})?;
if section == EssenceSection::Timeline {
return Err(RpcError::new(
INVALID_PARAMS,
"essence add: timeline uses op: append, not add",
));
}
let text =
text.ok_or_else(|| RpcError::new(INVALID_PARAMS, "essence add: missing 'text'"))?;
let scope = scope_from(thread, project)?;
let id = db
.essence_add(scope, section, &text, refs)
.map_err(mnemo_err)?;
db.flush().map_err(mnemo_err)?;
Ok(json!({ "id": id.to_string(), "outcome": "added" }).to_string())
}
"append" => {
let text = text
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "essence append: missing 'text'"))?;
let scope = scope_from(thread, project)?;
let id = db
.essence_append_timeline(scope, &text, refs)
.map_err(mnemo_err)?;
db.flush().map_err(mnemo_err)?;
Ok(json!({ "id": id.to_string(), "outcome": "appended" }).to_string())
}
"update" => {
let id = id_str
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "essence update: missing 'id'"))?;
let ulid = Ulid::from_string(id).map_err(|_| {
RpcError::new(
INVALID_PARAMS,
format!("essence update: invalid ULID '{id}'"),
)
})?;
let text = text
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "essence update: missing 'text'"))?;
let outcome = db.essence_update(&ulid, &text, refs).map_err(mnemo_err)?;
db.flush().map_err(mnemo_err)?;
Ok(json!({ "id": id, "outcome": outcome_to_str(outcome) }).to_string())
}
"resolve" => {
let id = id_str
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "essence resolve: missing 'id'"))?;
let ulid = Ulid::from_string(id).map_err(|_| {
RpcError::new(
INVALID_PARAMS,
format!("essence resolve: invalid ULID '{id}'"),
)
})?;
let outcome = db.essence_resolve(&ulid).map_err(mnemo_err)?;
db.flush().map_err(mnemo_err)?;
let s = match outcome {
WriteOutcome::Updated => "resolved",
WriteOutcome::Unchanged => "already-resolved",
_ => "resolved",
};
Ok(json!({ "id": id, "outcome": s }).to_string())
}
"remove" => {
let id = id_str
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "essence remove: missing 'id'"))?;
let ulid = Ulid::from_string(id).map_err(|_| {
RpcError::new(
INVALID_PARAMS,
format!("essence remove: invalid ULID '{id}'"),
)
})?;
db.essence_remove(&ulid).map_err(mnemo_err)?;
db.flush().map_err(mnemo_err)?;
Ok(json!({ "id": id, "outcome": "removed" }).to_string())
}
"render" => {
let budget = args.get("budget").and_then(|v| v.as_u64()).unwrap_or(6144) as usize;
let scope = scope_from(thread, project)?;
let rendered = db.essence(scope, budget).map_err(mnemo_err)?;
Ok(rendered)
}
other => Err(RpcError::new(
INVALID_PARAMS,
format!("essence: unknown op '{other}'"),
)),
}
}
fn tool_thread_ingest(db: &mut Mnemo, args: &Value) -> std::result::Result<String, RpcError> {
let thread = args
.get("thread")
.and_then(|v| v.as_str())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "thread_ingest: missing 'thread'"))?;
let path = args
.get("transcript_path")
.and_then(|v| v.as_str())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "thread_ingest: missing 'transcript_path'"))?;
let format_str = args
.get("format")
.and_then(|v| v.as_str())
.unwrap_or("jsonl");
let format = crate::TranscriptFormat::parse(format_str).ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
format!(
"thread_ingest: unknown format '{format_str}' (want 'jsonl' or 'claude-code-jsonl')"
),
)
})?;
let file = std::fs::File::open(path).map_err(|e| {
RpcError::new(
INVALID_PARAMS,
format!("thread_ingest: cannot open {path}: {e}"),
)
})?;
let turns = crate::read_transcript(file, format).map_err(mnemo_err)?;
let report = db.ingest_thread(thread, &turns).map_err(mnemo_err)?;
db.flush().map_err(mnemo_err)?;
Ok(json!({
"added_records": report.added_records,
"skipped_existing_turns": report.skipped_existing_turns,
"chunked_turns": report.chunked_turns,
"truncated_turns": report.truncated_turns,
})
.to_string())
}
fn tool_history(db: &mut Mnemo, args: &Value) -> std::result::Result<String, RpcError> {
use crate::KeyScope;
let key = args
.get("key")
.and_then(|v| v.as_str())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "history: missing 'key'"))?;
let agent = args.get("agent").and_then(|v| v.as_str());
let shared = args
.get("shared")
.and_then(|v| v.as_bool())
.unwrap_or(false);
if shared && agent.is_some() {
return Err(RpcError::new(
INVALID_PARAMS,
"history: 'agent' and 'shared' are mutually exclusive",
));
}
// v0.8.1 bugfix (lane A): match keyed `remember` slot resolution.
let scope = if shared {
KeyScope::Shared
} else {
match agent {
Some(a) => KeyScope::Private(a.to_string()),
None => KeyScope::private_default(),
}
};
let chain = db.history_in(key, scope).map_err(mnemo_err)?;
let out: Vec<Value> = chain
.iter()
.enumerate()
.map(|(i, m)| {
let mut v = memory_to_json(m);
if let Some(obj) = v.as_object_mut() {
obj.insert(
"state".into(),
Value::String(if i == 0 {
"live".into()
} else {
"superseded".into()
}),
);
}
v
})
.collect();
Ok(serde_json::to_string_pretty(&out).unwrap_or_else(|_| "[]".into()))
}
fn tool_recall(db: &mut Mnemo, args: &Value) -> std::result::Result<String, RpcError> {
// 12.3 step 5: `text` with no embedder on the server is keyword-only.
let mut text_by_keyword = false;
// Accept either `query` (explicit) or `text` (embedded).
let query = match (args.get("query"), args.get("text")) {
(Some(_), Some(_)) => {
return Err(RpcError::new(
INVALID_PARAMS,
"recall: pass EITHER 'query' or 'text', not both",
))
}
(Some(v), None) => v
.as_array()
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "recall: 'query' must be a JSON array"))?
.iter()
.map(|v| v.as_f64().map(|f| f as f32))
.collect::<Option<Vec<f32>>>()
.ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
"recall: 'query' must be an array of numbers",
)
})?,
(None, Some(t)) => {
let text = t
.as_str()
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "recall: 'text' must be a string"))?;
// 12.3 step 5: a server without an embedder (none given, or the
// built-in unavailable) matches the text by keyword only, on v9.
if db.embedder().is_none() && db.stats_summary().format_version >= 9 {
if args.get("keywords").and_then(Value::as_str) == Some("") {
return Err(RpcError::new(
INVALID_PARAMS,
"recall: 'keywords: \"\"' (vector only) needs an embedder on the server",
));
}
text_by_keyword = true;
Vec::new()
} else {
embed_text_via_server(db, "recall", text)?
}
}
// FMT-9d: `keywords` alone is keyword-only recall.
(None, None) if args.get("keywords").is_some() => Vec::new(),
(None, None) => {
return Err(RpcError::new(
INVALID_PARAMS,
"recall: missing 'query', 'text' or 'keywords'",
))
}
};
let top_k = args.get("top_k").and_then(|v| v.as_u64()).unwrap_or(10) as usize;
let metric = match args
.get("metric")
.and_then(|v| v.as_str())
.unwrap_or("cosine")
{
"cosine" => Metric::Cosine,
"l2" => Metric::L2,
"dot" => Metric::Dot,
other => {
return Err(RpcError::new(
INVALID_PARAMS,
format!("recall: unknown metric '{other}'"),
))
}
};
// Scoring v2 (v0.7.0) flipped the default: MCP recalls DO track
// access, so an agent's own retrievals contribute to the usage
// saturation term on later queries. The bump happens in-memory
// (`accessed_at` / `access_count` + `dirty_catalog`), and persists
// through the next flush — recall itself does not fsync, so there
// is no per-tool-call write-amplification cost. Access stats reach
// disk on either (a) the next mutating tool call's exit path (every
// one of `remember` / `forget` / `cache_put_semantic` /
// `cache_get_semantic`-on-miss ends in `db.flush()`), or (b) the
// server's own shutdown flush when stdin closes (see
// `serve_with_streams`), so a read-only session that issued only
// recalls still persists its stats.
let mut req = RecallRequest::new(query)
.top_k(top_k)
.metric(metric)
.track_access(true);
if let Some(k) = args.get("keywords") {
let k = k
.as_str()
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "recall: 'keywords' must be a string"))?;
req = req.keywords(k);
}
// 12.3 step 4: a recall by `text` is hybrid by default; `keywords: ""`
// opts out.
if let Some(t) = args.get("text").and_then(Value::as_str) {
req = req.text(t);
if text_by_keyword && req.keywords.is_none() {
req = req.keywords(t);
}
}
if let Some(types) = args.get("types").and_then(|v| v.as_array()) {
let parsed: Vec<MemoryType> = types
.iter()
.filter_map(|t| t.as_str().and_then(MemoryType::parse))
.collect();
if !parsed.is_empty() {
req = req.types(parsed);
}
}
if let Some(agent) = args.get("agent").and_then(|v| v.as_str()) {
req = req.agent(agent.to_string());
}
// Phase 12.6: filter object. Shape:
// { "session_id": "...",
// "metadata": { "k": v,
// "k2": {"$in": [v1, v2]},
// "k3": {"$exists": true},
// "k4": {"$gte": 5, "$lte": 10} } }
if let Some(filter_obj) = args.get("filter").and_then(|v| v.as_object()) {
req = req.filter(parse_mcp_filter(filter_obj)?);
}
// Phase 12.8: `max_bytes` opts into the budgeted response shape.
let has_max_bytes = args.get("max_bytes").is_some();
if let Some(n) = args.get("max_bytes").and_then(|v| v.as_u64()) {
req = req.max_bytes(n as usize);
}
let resp = db.recall_budgeted(&req).map_err(mnemo_err)?;
let out: Vec<Value> = resp
.hits
.into_iter()
.map(|h| {
let mut obj = memory_to_json(&h.memory);
if let Some(map) = obj.as_object_mut() {
map.insert("score".into(), json!(h.score));
map.insert("similarity".into(), json!(h.similarity));
}
obj
})
.collect();
if has_max_bytes {
// Phase 12.8 wrapped shape so callers can tell whether the
// budget cut anything.
let wrapped = json!({
"hits": out,
"truncated": resp.truncated,
});
Ok(serde_json::to_string_pretty(&wrapped).unwrap_or_else(|_| "{}".into()))
} else {
Ok(serde_json::to_string_pretty(&out).unwrap_or_else(|_| "[]".into()))
}
}
/// Phase 12.6: parse an MCP `filter` object into a [`crate::Filter`].
///
/// Values under `metadata.<key>`:
/// * plain scalar / array / string → [`crate::FilterTerm::Eq`]
/// * `{"$exists": true}` → [`crate::FilterTerm::Exists`]
/// * `{"$in": [...]}` → [`crate::FilterTerm::In`]
/// * `{"$gte": n, "$lte": n}` → [`crate::FilterTerm::Range`] (either bound
/// optional)
/// * `{"$exists": false}` is rejected (use the absence of a term instead)
fn parse_mcp_filter(
obj: &serde_json::Map<String, Value>,
) -> std::result::Result<crate::Filter, RpcError> {
let mut f = crate::Filter::default();
if let Some(sid) = obj.get("session_id").and_then(|v| v.as_str()) {
f = f.with_session(sid.to_string());
}
if let Some(meta) = obj.get("metadata").and_then(|v| v.as_object()) {
for (k, v) in meta {
match v {
// Nested operator object.
Value::Object(ops) => {
for (op_key, op_val) in ops {
match op_key.as_str() {
"$exists" => match op_val.as_bool() {
Some(true) => {
f = f.metadata_exists(k.clone());
}
Some(false) => {
return Err(RpcError::new(
INVALID_PARAMS,
format!(
"filter.metadata.{k}.$exists=false isn't supported; \
drop the filter term instead"
),
));
}
None => {
return Err(RpcError::new(
INVALID_PARAMS,
format!("filter.metadata.{k}.$exists must be a boolean"),
));
}
},
"$in" => {
let arr = op_val.as_array().ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
format!("filter.metadata.{k}.$in must be an array"),
)
})?;
f = f.metadata_in(k.clone(), arr.clone());
}
"$gte" | "$lte" => {
let mut min = None;
let mut max = None;
for (bound, bound_val) in ops {
let n = bound_val.as_f64().ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
format!("filter.metadata.{k}.{bound} must be a number"),
)
})?;
match bound.as_str() {
"$gte" => min = Some(n),
"$lte" => max = Some(n),
other => {
return Err(RpcError::new(
INVALID_PARAMS,
format!(
"filter.metadata.{k}: unsupported range \
operator '{other}' (want $gte, $lte)"
),
));
}
}
}
f = f.metadata_range(k.clone(), min, max);
break; // All operator entries consumed in one pass.
}
other => {
return Err(RpcError::new(
INVALID_PARAMS,
format!(
"filter.metadata.{k}: unknown operator '{other}' \
(want $exists, $in, $gte, $lte)"
),
));
}
}
}
}
// Plain scalar / array / string → equality.
other => {
f = f.metadata_eq(k.clone(), other.clone());
}
}
}
}
Ok(f)
}
fn tool_forget(db: &mut Mnemo, args: &Value) -> std::result::Result<String, RpcError> {
let id_str = args
.get("id")
.and_then(|v| v.as_str())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "forget: missing 'id'"))?;
let ulid = crate::Ulid::from_string(id_str)
.map_err(|_| RpcError::new(INVALID_PARAMS, format!("forget: invalid ULID '{id_str}'")))?;
db.delete(&ulid).map_err(mnemo_err)?;
db.flush().map_err(mnemo_err)?;
Ok(json!({ "deleted": id_str }).to_string())
}
fn tool_list(db: &mut Mnemo, args: &Value) -> std::result::Result<String, RpcError> {
let include_vectors = args
.get("include_vectors")
.and_then(|v| v.as_bool())
.unwrap_or(false);
let mems = db.memories().map_err(mnemo_err)?;
let out: Vec<Value> = mems
.iter()
.map(|m| {
let mut v = memory_to_json(m);
if !include_vectors {
if let Some(o) = v.as_object_mut() {
o.remove("vector");
}
}
v
})
.collect();
Ok(serde_json::to_string_pretty(&out).unwrap_or_else(|_| "[]".into()))
}
fn tool_snapshot_list(db: &mut Mnemo) -> std::result::Result<String, RpcError> {
let snaps = db.snapshots();
let out: Vec<Value> = snaps
.into_iter()
.map(|s| {
json!({
"txn_id": s.txn_id,
"created_at": s.created_at,
"memory_count": s.memory_count,
})
})
.collect();
Ok(serde_json::to_string_pretty(&out).unwrap_or_else(|_| "[]".into()))
}
fn tool_stats(db: &mut Mnemo) -> std::result::Result<String, RpcError> {
let s = db.stats().map_err(mnemo_err)?;
let (cache_pages, cache_capacity) = db.page_cache_stats();
let snapshot_count = db.snapshots().len();
// Field names mirror `Stats` in `store/mod.rs` verbatim so MCP clients
// that reference the Rust doc for the same DB see the same shape.
Ok(json!({
"memories": s.memories,
"deleted": s.deleted,
"dimensions": s.dimensions,
"file_bytes": s.file_bytes,
"agents": s.agents,
"encrypted": s.encrypted,
"created_at": s.created_at,
"wal_pages": s.wal_pages,
"recall_mode": s.recall_mode.as_str(),
"index": s.index,
"snapshot_count": snapshot_count,
"snapshots_retained": s.snapshots_retained,
"oldest_restorable_at": s.oldest_restorable_at,
"snapshot_pinned_bytes": s.snapshot_pinned_bytes,
"cache_pages": cache_pages,
"cache_capacity": cache_capacity,
})
.to_string())
}
// --- Result-cache tool handlers (Phase 10.4) -----------------------------
fn tool_cache_put(db: &mut Mnemo, args: &Value) -> std::result::Result<String, RpcError> {
let ns = args
.get("namespace")
.and_then(|v| v.as_str())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "cache_put: missing 'namespace'"))?;
let key = args
.get("key")
.and_then(|v| v.as_str())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "cache_put: missing 'key'"))?;
let value = args
.get("value")
.and_then(|v| v.as_str())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "cache_put: missing 'value'"))?;
let content_type = args
.get("content_type")
.and_then(|v| v.as_str())
.unwrap_or("text")
.to_string();
let ttl_secs = args.get("ttl_secs").and_then(|v| v.as_u64());
let opts = CachePutOpts {
content_type,
ttl_secs,
cost_hint_ms: None,
};
db.cache_put(ns, key, value.as_bytes(), opts)
.map_err(mnemo_err)?;
db.flush().map_err(mnemo_err)?;
Ok(json!({ "cached": true, "namespace": ns, "key": key, "bytes": value.len() }).to_string())
}
fn tool_cache_get(db: &mut Mnemo, args: &Value) -> std::result::Result<String, RpcError> {
let ns = args
.get("namespace")
.and_then(|v| v.as_str())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "cache_get: missing 'namespace'"))?;
let key = args
.get("key")
.and_then(|v| v.as_str())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "cache_get: missing 'key'"))?;
match db.cache_get(ns, key).map_err(mnemo_err)? {
Some(hit) => Ok(json!({
"hit": true,
"value": String::from_utf8_lossy(&hit.value),
"content_type": hit.content_type,
"created_at": hit.created_at,
"accessed_at": hit.accessed_at,
"access_count": hit.access_count,
})
.to_string()),
None => Ok(json!({ "hit": false }).to_string()),
}
}
fn tool_cache_stats(db: &mut Mnemo, args: &Value) -> std::result::Result<String, RpcError> {
let ns = args.get("namespace").and_then(|v| v.as_str());
let s = db.cache_stats(ns);
Ok(json!({
"namespace": ns,
"entries": s.entries,
"bytes": s.bytes,
"hits": s.hits,
"misses": s.misses,
"hit_rate": s.hit_rate,
"evictions": s.evictions,
})
.to_string())
}
fn tool_cache_put_semantic(db: &mut Mnemo, args: &Value) -> std::result::Result<String, RpcError> {
let ns = args
.get("namespace")
.and_then(|v| v.as_str())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "cache_put_semantic: missing 'namespace'"))?;
let key = args
.get("key")
.and_then(|v| v.as_str())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "cache_put_semantic: missing 'key'"))?;
let value = args
.get("value")
.and_then(|v| v.as_str())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "cache_put_semantic: missing 'value'"))?;
// When `text` is used, derive the model name from the server's
// registered embedder (identity). Explicit `model` wins otherwise.
let (vector, model) = match (args.get("vector"), args.get("text")) {
(Some(_), Some(_)) => {
return Err(RpcError::new(
INVALID_PARAMS,
"cache_put_semantic: pass EITHER 'vector' or 'text', not both",
));
}
(Some(v), None) => {
let vec = v
.as_array()
.ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
"cache_put_semantic: 'vector' must be a JSON array",
)
})?
.iter()
.map(|v| v.as_f64().map(|f| f as f32))
.collect::<Option<Vec<f32>>>()
.ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
"cache_put_semantic: 'vector' must be an array of numbers",
)
})?;
let model = args
.get("model")
.and_then(|v| v.as_str())
.ok_or_else(|| {
RpcError::new(INVALID_PARAMS, "cache_put_semantic: missing 'model'")
})?
.to_string();
(vec, model)
}
(None, Some(t)) => {
let text = t.as_str().ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
"cache_put_semantic: 'text' must be a string",
)
})?;
let vec = embed_text_via_server(db, "cache_put_semantic", text)?;
// Allow explicit model override; else derive from embedder.
let model = match args.get("model").and_then(|v| v.as_str()) {
Some(m) => m.to_string(),
None => {
db.embedder()
.expect("embed_text_via_server would have errored otherwise")
.identity()
.name
}
};
(vec, model)
}
(None, None) => {
return Err(RpcError::new(
INVALID_PARAMS,
"cache_put_semantic: missing 'vector' or 'text'",
))
}
};
let content_type = args
.get("content_type")
.and_then(|v| v.as_str())
.unwrap_or("text")
.to_string();
let ttl_secs = args.get("ttl_secs").and_then(|v| v.as_u64());
let opts = SemanticCachePutOpts {
content_type,
ttl_secs,
cost_hint_ms: None,
model,
};
db.cache_put_semantic(ns, key, vector, value.as_bytes(), opts)
.map_err(mnemo_err)?;
db.flush().map_err(mnemo_err)?;
Ok(json!({ "cached": true, "namespace": ns, "key": key, "bytes": value.len() }).to_string())
}
fn tool_cache_get_semantic(db: &mut Mnemo, args: &Value) -> std::result::Result<String, RpcError> {
let ns = args
.get("namespace")
.and_then(|v| v.as_str())
.ok_or_else(|| RpcError::new(INVALID_PARAMS, "cache_get_semantic: missing 'namespace'"))?;
// When `text` is used, derive the model name from the server's
// registered embedder (identity). Explicit `model` wins otherwise.
let (query, model_owned) = match (args.get("query"), args.get("text")) {
(Some(_), Some(_)) => {
return Err(RpcError::new(
INVALID_PARAMS,
"cache_get_semantic: pass EITHER 'query' or 'text', not both",
));
}
(Some(q), None) => {
let vec = q
.as_array()
.ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
"cache_get_semantic: 'query' must be a JSON array",
)
})?
.iter()
.map(|v| v.as_f64().map(|f| f as f32))
.collect::<Option<Vec<f32>>>()
.ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
"cache_get_semantic: 'query' must be an array of numbers",
)
})?;
let model = args
.get("model")
.and_then(|v| v.as_str())
.ok_or_else(|| {
RpcError::new(INVALID_PARAMS, "cache_get_semantic: missing 'model'")
})?
.to_string();
(vec, model)
}
(None, Some(t)) => {
let text = t.as_str().ok_or_else(|| {
RpcError::new(
INVALID_PARAMS,
"cache_get_semantic: 'text' must be a string",
)
})?;
let vec = embed_text_via_server(db, "cache_get_semantic", text)?;
let model = match args.get("model").and_then(|v| v.as_str()) {
Some(m) => m.to_string(),
None => {
db.embedder()
.expect("embed_text_via_server would have errored otherwise")
.identity()
.name
}
};
(vec, model)
}
(None, None) => {
return Err(RpcError::new(
INVALID_PARAMS,
"cache_get_semantic: missing 'query' or 'text'",
))
}
};
let model = model_owned.as_str();
let threshold = args
.get("threshold")
.and_then(|v| v.as_f64())
.map(|f| f as f32)
.unwrap_or(DEFAULT_SEMANTIC_THRESHOLD);
match db
.cache_get_semantic(ns, &query, threshold, model)
.map_err(mnemo_err)?
{
Some((hit, similarity)) => Ok(json!({
"hit": true,
"similarity": similarity,
"value": String::from_utf8_lossy(&hit.value),
"content_type": hit.content_type,
"created_at": hit.created_at,
"accessed_at": hit.accessed_at,
"access_count": hit.access_count,
})
.to_string()),
None => Ok(json!({ "hit": false }).to_string()),
}
}
/// Serialize a `Memory` into the JSON shape MCP tool responses use.
/// Serde on `Memory` produces the canonical shape; we mirror what the
/// CLI's `memory_to_json` does but without the CLI-only vector-stripping
/// switch (that lives in the individual tools that care).
fn memory_to_json(m: &Memory) -> Value {
serde_json::to_value(m).unwrap_or_else(|_| {
let mut map = Map::new();
map.insert("id".into(), json!(m.id.to_string()));
Value::Object(map)
})
}