memfork 0.3.0

Git for agent memory, shared by every AI tool on your machine: fork, merge, rewind and hand off work between agents over MCP.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
//! `memfork mcp` — the MCP server over stdio (DESIGN §6).
//!
//! The tool surface comes from [`crate::tools`], so the MCP server, the vendor
//! function-calling formats and `memfork call` are three views of one registry.
//! Schemas are served exactly as written there, in the conservative subset of
//! DESIGN §6.1, rather than being derived from Rust types — a derive would emit
//! `$schema`, `format` and `anyOf`, which some clients sanitise and some
//! reject.
//!
//! **State is durable by default** (DESIGN §4.5). The binary persists unless
//! `--ephemeral` says otherwise, which is the opposite of the library default:
//! a library should not write to someone's disk unasked, and an agent memory
//! that empties on restart is not memory. This server is the one the daemon
//! runs, and the one an `--ephemeral` session runs directly; every other
//! client reaches it through [`crate::proxy`].

use std::sync::Arc;

use rmcp::model::{
    CallToolRequestParams, CallToolResponse, CallToolResult, GetPromptRequestParams,
    GetPromptResponse, Implementation, InitializeRequestParams, InitializeResult,
    ListPromptsResult, ListToolsResult, PaginatedRequestParams, ServerCapabilities, ServerConfig,
    Tool,
};
use rmcp::service::RequestContext;
use rmcp::transport::IntoTransport;
use rmcp::{ErrorData, RoleServer, ServerHandler, ServiceExt};
use serde_json::json;

use crate::namespace;
use crate::tools::{self, dispatch::Session, dispatch::ToolError};

/// What the client is told about this server when it connects.
///
/// Shared with the proxy, so a client sees the same thing whether it reached
/// a direct server or one forwarding to the daemon.
pub const INSTRUCTIONS: &str = "\
MemFork gives you branchable memory: store and recall things, and — the part \
that matters — fork the whole of memory before a risky step, then merge it if \
the attempt worked or discard it if it did not. Forking costs the same whatever \
memory holds, so fork freely: it is cheaper than being careful. Writes on a \
fork are invisible to the branch you came from until you merge, and discarding \
leaves that branch exactly as it was. You can also read memory as it was at any \
earlier point.

What you store is kept on disk and is still there next time, so memory you \
write in one session is memory you can recall in the next. Other clients can \
be using the same memory at the same time, and will see what you write; each \
of you keeps your own current branch, so switching branches never moves \
anybody else.";

/// The experimental capability a proxy uses to tell the daemon who it is
/// speaking for: `{"namespace": …, "client": …}`.
///
/// A proxy is the daemon's client, so the daemon's own `clientInfo` would only
/// ever say "memfork-proxy". The proxy knows the real client's name, from that
/// client's `initialize`, and the project, from its working directory, and
/// passes both on here — an ordinary MCP capability field, so any other
/// client simply does not send it.
pub const SESSION_CAPABILITY: &str = "memfork/session";

/// What the client is told when it connects: [`INSTRUCTIONS`], then which
/// project this session is in and the conventions that go with it.
///
/// Built per session, because the namespace is per session. This is how every
/// agent learns its project's name and the handoff routine without anyone
/// editing a file.
pub fn instructions(ns: &str) -> String {
    let decision = namespace::prefix(ns, "decision");
    let task = namespace::prefix(ns, "task");
    format!(
        "{INSTRUCTIONS}

This session's project namespace is `{ns}`. Keep what you record about this \
project under it, with colons between the parts: each decision and its reason \
under `{decision}<topic>`, open tasks under `{task}<id>`. Call memfork_resume \
when you start, to pick up what earlier agents decided and did, and \
memfork_handoff before you stop, so the next one can continue from you. Fork \
before anything risky, merge if it worked, discard if it did not. Other \
projects share this store under their own names, and keys without a project \
in front are still there for the tools that take a key."
    )
}

/// Take what a client said in `initialize` into its session: who it is, for
/// attribution, and — from a proxy — which project it is working in.
pub fn adopt(session: &Session, request: &InitializeRequestParams) {
    let hello = request
        .capabilities
        .experimental
        .as_ref()
        .and_then(|e| e.get(SESSION_CAPABILITY));
    let named = hello
        .and_then(|h| h.get("client"))
        .and_then(|c| c.as_str())
        .filter(|c| !c.trim().is_empty());
    session.set_writer(named.unwrap_or(&request.client_info.name));
    // A namespace that is not valid is ignored rather than refused: the
    // session keeps the one it had, and the handshake still succeeds.
    if let Some(ns) = hello
        .and_then(|h| h.get("namespace"))
        .and_then(|n| n.as_str())
        .filter(|n| namespace::validate(n).is_ok())
    {
        session.set_namespace(ns.to_owned());
    }
    // A proxy's own session id, so its claims survive its reconnects.
    if let Some(id) = hello
        .and_then(|h| h.get("session"))
        .and_then(|s| s.as_str())
    {
        session.set_session_id(id);
    }
    session.announce();
}

/// The tool list, built from the registry.
///
/// Shared with the proxy, which answers `tools/list` from here rather than
/// asking the daemon: the surface is static, so going upstream for it would
/// mean starting a daemon to answer a question about MemFork itself.
pub fn tool_list() -> Vec<Tool> {
    tools::all()
        .into_iter()
        .map(|t| Tool::new(t.name, t.description, Arc::new(t.schema)).with_title(t.title))
        .collect()
}

/// The MCP server: one session over one in-memory database.
#[derive(Debug, Clone)]
pub struct MemforkServer {
    session: Arc<Session>,
}

impl MemforkServer {
    /// A server over the given session.
    pub fn new(session: Arc<Session>) -> Self {
        MemforkServer { session }
    }
}

impl ServerHandler for MemforkServer {
    async fn list_prompts(
        &self,
        _request: Option<PaginatedRequestParams>,
        _context: RequestContext<RoleServer>,
    ) -> Result<ListPromptsResult, ErrorData> {
        Ok(ListPromptsResult::with_all_items(crate::prompts::list()))
    }

    async fn get_prompt(
        &self,
        request: GetPromptRequestParams,
        _context: RequestContext<RoleServer>,
    ) -> Result<GetPromptResponse, ErrorData> {
        crate::prompts::get(
            &request.name,
            request.arguments.as_ref(),
            &self.session.namespace(),
        )
        .map(Into::into)
        .map_err(|why| ErrorData::invalid_params(why, None))
    }

    fn get_info(&self) -> ServerConfig {
        ServerConfig::new(
            ServerCapabilities::builder()
                .enable_tools()
                .enable_prompts()
                .build(),
        )
        .with_server_info(
            Implementation::new("memfork", env!("CARGO_PKG_VERSION"))
                .with_title("MemFork — branchable agent memory"),
        )
        .with_instructions(instructions(&self.session.namespace()))
    }

    async fn initialize(
        &self,
        request: InitializeRequestParams,
        context: RequestContext<RoleServer>,
    ) -> Result<InitializeResult, ErrorData> {
        adopt(&self.session, &request);
        context.peer.set_peer_info(request.clone());
        self.negotiate_initialize(&request)
    }

    async fn list_tools(
        &self,
        _request: Option<PaginatedRequestParams>,
        _context: RequestContext<RoleServer>,
    ) -> Result<ListToolsResult, ErrorData> {
        // Sixteen tools fit in one page comfortably, and DESIGN §6.1 caps the
        // count at sixteen, so there is nothing to paginate.
        Ok(ListToolsResult::with_all_items(tool_list()))
    }

    async fn call_tool(
        &self,
        request: CallToolRequestParams,
        _context: RequestContext<RoleServer>,
    ) -> Result<CallToolResponse, ErrorData> {
        let args = request.arguments.unwrap_or_default();
        match self.session.call(&request.name, &args) {
            Ok(value) => Ok(CallToolResult::structured(value).into()),

            // The caller's request could not be routed or understood. MCP
            // renders these as protocol errors, which is right: the fault is in
            // the request, not in what the tool found.
            Err(e @ (ToolError::UnknownTool(_) | ToolError::BadArguments(_))) => {
                Err(ErrorData::invalid_params(e.to_string(), None))
            }

            // The tool ran and the engine said no — an unknown branch, a bad
            // sequence number. The model should see this and correct itself, so
            // it comes back as a tool-level error with the reason in it.
            Err(e @ ToolError::Engine(_)) => Ok(CallToolResult::structured_error(json!({
                "error": e.to_string(),
                "tool": request.name,
            }))
            .into()),

            // A write that looked like it held a credential. The agent should
            // see why, fix it and try again, so this is a tool-level error too;
            // it names the rule and the place, never the text.
            Err(ToolError::Secret(refused)) => {
                let mut body = json!({
                    "error": refused.to_string(),
                    "tool": request.name,
                });
                if let crate::secrets::Refused::Secret(found) = &refused {
                    body["secret"] = found.to_json();
                }
                Ok(CallToolResult::structured_error(body).into())
            }
        }
    }
}

/// Serve MCP over stdio until the client disconnects.
///
/// Anything written to stdout would corrupt the protocol stream, so every
/// diagnostic in this path goes to stderr.
pub async fn serve_stdio(session: Arc<Session>) -> Result<(), String> {
    let server = MemforkServer::new(session);
    let transport = Discoverable::new(rmcp::transport::stdio().into_transport(), server.get_info());
    let service = server
        .serve(transport)
        .await
        .map_err(|e| format!("cannot start the MCP server: {e}"))?;
    service
        .waiting()
        .await
        .map_err(|e| format!("the MCP server stopped with an error: {e}"))?;
    Ok(())
}

/// A transport that answers `server/discover` itself, before the SDK sees it.
///
/// One client probes a server with `server/discover` (a 2026-07-28 request)
/// on the same connection and then shakes hands the older way, with
/// `initialize`, and goes on with plain requests. The SDK treats a discover
/// as the opening of an inline session and from then on refuses any request
/// without per-request metadata — including the plain `tools/list` that
/// client sends next — so the client can connect and never use a tool. Here
/// the probe is answered with the same discovery result the SDK would give,
/// and the SDK sees a connection that starts with `initialize`, which is the
/// session the client is actually in.
pub struct Discoverable<T> {
    inner: T,
    info: ServerConfig,
}

impl<T: std::fmt::Debug> std::fmt::Debug for Discoverable<T> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Discoverable")
            .field("inner", &self.inner)
            .finish_non_exhaustive()
    }
}

impl<T> Discoverable<T> {
    /// Wrap a transport, answering probes with `info`.
    pub fn new(inner: T, info: ServerConfig) -> Self {
        Discoverable { inner, info }
    }
}

impl<T> rmcp::transport::Transport<RoleServer> for Discoverable<T>
where
    T: rmcp::transport::Transport<RoleServer> + Send,
{
    type Error = T::Error;

    fn send(
        &mut self,
        item: rmcp::model::ServerJsonRpcMessage,
    ) -> impl std::future::Future<Output = Result<(), Self::Error>> + Send + 'static {
        self.inner.send(item)
    }

    async fn receive(&mut self) -> Option<rmcp::model::ClientJsonRpcMessage> {
        loop {
            let message = self.inner.receive().await?;
            let probe = match &message {
                rmcp::model::JsonRpcMessage::Request(request)
                    if matches!(
                        request.request,
                        rmcp::model::ClientRequest::DiscoverRequest(_)
                    ) =>
                {
                    Some(request.id.clone())
                }
                _ => None,
            };
            let Some(id) = probe else {
                return Some(message);
            };
            let result = rmcp::model::DiscoverResult::from_server_info(
                rmcp::model::ProtocolVersion::KNOWN_VERSIONS.to_vec(),
                self.info.clone(),
            );
            let answer = rmcp::model::ServerJsonRpcMessage::response(
                rmcp::model::ServerResult::DiscoverResult(result),
                id,
            );
            if self.inner.send(answer).await.is_err() {
                return None;
            }
        }
    }

    fn close(&mut self) -> impl std::future::Future<Output = Result<(), Self::Error>> + Send {
        self.inner.close()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn every_registry_tool_is_offered_with_its_schema() {
        let listed = tool_list();
        let registry = tools::all();
        assert_eq!(listed.len(), registry.len());
        for (tool, def) in listed.iter().zip(&registry) {
            assert_eq!(tool.name, def.name);
            assert_eq!(tool.description.as_deref(), Some(def.description.as_str()));
            assert_eq!(
                tool.input_schema.as_ref(),
                &def.schema,
                "the server altered the schema of {}",
                def.name
            );
        }
    }

    #[test]
    fn the_instructions_describe_what_this_build_actually_does() {
        // These have been wrong twice, both times because a phase changed the
        // behaviour and left the words behind. So each claim that has been
        // wrong before gets an assertion.
        let lower = INSTRUCTIONS.to_ascii_lowercase();
        assert!(lower.contains("kept on disk"), "{INSTRUCTIONS}");
        assert!(lower.contains("still there next time"), "{INSTRUCTIONS}");
        assert!(
            !lower.contains("nothing is written to disk"),
            "the instructions still claim nothing is persisted"
        );
        assert!(
            lower.contains("other clients can be using the same memory"),
            "the instructions do not mention sharing: {INSTRUCTIONS}"
        );
        assert!(
            !lower.contains("start a second copy") && !lower.contains("one process owns"),
            "the instructions still describe the single-process behaviour that \
             the daemon replaced"
        );
    }

    #[test]
    fn each_session_is_told_its_project_and_the_routine() {
        let text = instructions("shop-front");
        assert!(text.starts_with(INSTRUCTIONS));
        assert!(text.contains("project namespace is `shop-front`"), "{text}");
        assert!(text.contains("`shop-front:decision:<topic>`"), "{text}");
        assert!(text.contains("`shop-front:task:<id>`"), "{text}");
        for step in [
            "memfork_resume",
            "memfork_handoff",
            "fork",
            "merge",
            "discard",
        ] {
            assert!(text.contains(step), "no `{step}` in: {text}");
        }
    }

    fn hello(client: &str, experimental: Option<serde_json::Value>) -> InitializeRequestParams {
        let mut caps = rmcp::model::ClientCapabilities::default();
        if let Some(serde_json::Value::Object(obj)) = experimental {
            let mut map = std::collections::BTreeMap::new();
            map.insert(SESSION_CAPABILITY.to_owned(), obj);
            caps.experimental = Some(map);
        }
        InitializeRequestParams::new(caps, Implementation::new(client, "1.0"))
    }

    #[test]
    fn a_direct_client_is_recorded_by_the_name_it_gives() {
        let session = Session::in_namespace(memfork_core::Db::new(), "here");
        adopt(&session, &hello("some-client", None));
        assert_eq!(session.writer().as_deref(), Some("some-client"));
        assert_eq!(session.namespace(), "here");
    }

    #[test]
    fn a_proxy_speaks_for_its_client_and_project() {
        let session = Session::new(memfork_core::Db::new());
        adopt(
            &session,
            &hello(
                "memfork-proxy",
                Some(json!({"client": "real-client", "namespace": "shop"})),
            ),
        );
        assert_eq!(session.writer().as_deref(), Some("real-client"));
        assert_eq!(session.namespace(), "shop");
        assert!(instructions(&session.namespace()).contains("`shop`"));
    }

    #[test]
    fn an_unusable_namespace_in_a_hello_is_ignored() {
        let session = Session::in_namespace(memfork_core::Db::new(), "kept");
        adopt(
            &session,
            &hello("memfork-proxy", Some(json!({"namespace": "Not Valid:"}))),
        );
        assert_eq!(session.namespace(), "kept");
        assert_eq!(session.writer().as_deref(), Some("memfork-proxy"));
    }

    #[test]
    fn the_instructions_name_no_vendor() {
        const VENDORS: &[&str] = &[
            "claude",
            "anthropic",
            "openai",
            "gpt",
            "gemini",
            "grok",
            "cursor",
            "codex",
        ];
        let lower = instructions("project").to_ascii_lowercase();
        for v in VENDORS {
            assert!(!lower.contains(v), "instructions mention `{v}`");
        }
    }
}