memfork 0.2.1

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
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
//! `memfork serve` — the local daemon (DESIGN §5).
//!
//! One process owns the data directory and the write-ahead log; every
//! `memfork mcp` is a proxy to it. That is what lets two clients share one
//! memory, which is the normal case rather than the exotic one.
//!
//! Loopback only, always. The daemon binds `127.0.0.1` and nothing else, and
//! every request must carry the bearer token from the endpoint file, so a
//! process that cannot read that file cannot reach the memory. rmcp's own
//! `Host` validation stays on as a second line against DNS rebinding.
//!
//! The daemon exits on its own after an idle period. Nobody wants a background
//! process they did not start living forever, and an autostarted daemon that
//! never stops is exactly that.

use std::future::Future;
use std::net::{Ipv4Addr, SocketAddr};
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::Arc;
use std::time::{Duration, Instant};

use http_body_util::{BodyExt, Full};
use hyper::body::{Bytes, Incoming};
use hyper::{Request, Response, StatusCode};
use rmcp::transport::streamable_http_server::session::local::LocalSessionManager;
use rmcp::transport::StreamableHttpService;
use tokio_util::sync::CancellationToken;

use crate::cli::Command;
use crate::events::{Event, Events};
use crate::mcp::MemforkServer;
use crate::persist::{Endpoint, Store};
use crate::tools::dispatch::Session;

/// The path the MCP endpoint is served at.
pub const MCP_PATH: &str = "/mcp";

/// The path `memfork stop` posts to.
pub const SHUTDOWN_PATH: &str = "/shutdown";

/// The path `memfork watch` reads the activity stream from.
pub const EVENTS_PATH: &str = "/events";

/// The path the command line posts its operations to.
pub const CLI_PATH: &str = "/cli";

/// The name the command line's writes are recorded under.
pub const CLI_WRITER: &str = "memfork-cli";

/// How long a client session may go without a request before the daemon
/// forgets it. A proxy ends its session when its client goes away, so this
/// only matters for one that was killed; and a proxy whose session was
/// forgotten simply starts another.
pub const DEFAULT_SESSION_SECONDS: u64 = 1800;

/// How long the daemon waits with nothing to do before exiting.
pub const DEFAULT_IDLE_SECONDS: u64 = 600;

/// How to run the daemon.
#[derive(Debug, Clone)]
pub struct ServeOptions {
    /// Port to bind on loopback. Zero asks the operating system to pick.
    pub port: u16,
    /// Exit after this long with no requests. Zero means never.
    pub idle_seconds: u64,
    /// Forget a client session after this long with no requests from it.
    pub session_seconds: u64,
}

/// Why the daemon stopped.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Stopped {
    /// Nothing asked anything of it for the idle period.
    Idle,
    /// `memfork stop`, or something else that posted to the shutdown path.
    Asked,
    /// The listener failed.
    Failed,
}

/// Shared between the request handler and the idle watcher.
#[derive(Debug)]
struct Clock {
    /// Milliseconds since the daemon started, at the last request.
    last_seen: AtomicU64,
    started: Instant,
}

impl Clock {
    fn new() -> Self {
        Clock {
            last_seen: AtomicU64::new(0),
            started: Instant::now(),
        }
    }

    fn touch(&self) {
        let elapsed = self.started.elapsed().as_millis() as u64;
        self.last_seen.store(elapsed, Ordering::Relaxed);
    }

    fn idle_for(&self) -> Duration {
        let now = self.started.elapsed().as_millis() as u64;
        Duration::from_millis(now.saturating_sub(self.last_seen.load(Ordering::Relaxed)))
    }
}

/// Run the daemon until it is asked to stop or goes idle.
///
/// `store` is the open data directory: holding it is what makes this process
/// the single writer, and dropping it releases the lock and removes the
/// endpoint file.
pub async fn run(
    db: memfork_core::Db,
    store: Arc<Store>,
    options: ServeOptions,
) -> Result<Stopped, String> {
    let token = crate::persist::lock::new_token().map_err(|e| e.to_string())?;

    let listener =
        tokio::net::TcpListener::bind(SocketAddr::from((Ipv4Addr::LOCALHOST, options.port)))
            .await
            .map_err(|e| format!("cannot listen on 127.0.0.1:{}: {e}", options.port))?;
    let port = listener
        .local_addr()
        .map_err(|e| format!("cannot read the port that was bound: {e}"))?
        .port();

    // Publish only once the socket is listening, so anything that reads the
    // endpoint file can connect immediately rather than racing the bind.
    let mut endpoint = Endpoint::for_this_process();
    endpoint.port = Some(port);
    endpoint.token = Some(token.clone());
    store.publish(&endpoint).map_err(|e| e.to_string())?;

    let shutdown = CancellationToken::new();
    let clock = Arc::new(Clock::new());
    clock.touch();

    // Every HTTP session gets its own MCP session over the one database, so
    // two clients share the data and keep their own current branch.
    let events = Arc::new(Events::default());
    let shared = db.clone();
    let hub = Arc::clone(&events);
    let mut sessions = LocalSessionManager::default();
    sessions.session_config.keep_alive = Some(Duration::from_secs(options.session_seconds.max(1)));
    let service = StreamableHttpService::new(
        // Each session starts in the fallback namespace with no writer; its
        // `initialize` says which project and client it is (see
        // `crate::mcp::adopt`), and from then on it reports what it does.
        move || {
            Ok(MemforkServer::new(Arc::new(
                Session::new(shared.clone()).reporting_to(Arc::clone(&hub)),
            )))
        },
        Arc::new(sessions),
        // Our tools are request-and-response, so the server can answer in
        // plain JSON and the proxy needs no event-stream parsing. The default
        // allowed-hosts list is loopback only, which is left alone: it is a
        // second line against DNS rebinding on top of binding 127.0.0.1.
        rmcp::transport::streamable_http_server::StreamableHttpServerConfig::default()
            .with_json_response(true)
            .with_legacy_session_mode(true),
    );

    let idle = {
        let clock = Arc::clone(&clock);
        let shutdown = shutdown.clone();
        let limit = options.idle_seconds;
        tokio::spawn(async move {
            if limit == 0 {
                return false;
            }
            let limit = Duration::from_secs(limit);
            loop {
                tokio::select! {
                    _ = shutdown.cancelled() => return false,
                    _ = tokio::time::sleep(Duration::from_millis(250)) => {
                        if clock.idle_for() >= limit {
                            shutdown.cancel();
                            return true;
                        }
                    }
                }
            }
        })
    };

    let accept = {
        let shutdown = shutdown.clone();
        let clock = Arc::clone(&clock);
        let token = token.clone();
        async move {
            loop {
                let stream = tokio::select! {
                    _ = shutdown.cancelled() => break,
                    accepted = listener.accept() => match accepted {
                        Ok((stream, _)) => stream,
                        // One bad connection is not a reason to stop serving
                        // the others.
                        Err(_) => continue,
                    },
                };
                let service = service.clone();
                let shutdown = shutdown.clone();
                let clock = Arc::clone(&clock);
                let token = token.clone();
                let events = Arc::clone(&events);
                let db = db.clone();
                tokio::spawn(async move {
                    let guard = Guard {
                        inner: service,
                        token,
                        clock,
                        shutdown,
                        events,
                        db,
                        port,
                    };
                    let io = hyper_util::rt::TokioIo::new(stream);
                    let _ = hyper::server::conn::http1::Builder::new()
                        .serve_connection(io, hyper_util::service::TowerToHyperService::new(guard))
                        .await;
                });
            }
        }
    };

    accept.await;
    let stopped = if idle.await.unwrap_or(false) {
        Stopped::Idle
    } else {
        Stopped::Asked
    };

    // Flush before the lock goes, so a looser fsync policy does not lose the
    // last commits to a shutdown the daemon chose itself.
    store.flush().map_err(|e| e.to_string())?;
    Ok(stopped)
}

/// Checks the token, notices activity, and answers the shutdown path itself.
#[derive(Clone)]
struct Guard {
    inner: StreamableHttpService<MemforkServer, LocalSessionManager>,
    token: String,
    clock: Arc<Clock>,
    shutdown: CancellationToken,
    events: Arc<Events>,
    db: memfork_core::Db,
    port: u16,
}

type BoxBody = http_body_util::combinators::BoxBody<Bytes, std::io::Error>;

fn text(status: StatusCode, message: &str) -> Response<BoxBody> {
    let body = Full::new(Bytes::from(message.to_owned()))
        .map_err(|never| match never {})
        .boxed();
    Response::builder()
        .status(status)
        .header("content-type", "text/plain; charset=utf-8")
        .body(body)
        .unwrap_or_else(|_| Response::new(BoxBody::default()))
}

impl tower_service::Service<Request<Incoming>> for Guard {
    type Response = Response<BoxBody>;
    type Error = std::convert::Infallible;
    type Future = std::pin::Pin<
        Box<dyn Future<Output = Result<Self::Response, Self::Error>> + Send + 'static>,
    >;

    fn poll_ready(
        &mut self,
        _cx: &mut std::task::Context<'_>,
    ) -> std::task::Poll<Result<(), Self::Error>> {
        std::task::Poll::Ready(Ok(()))
    }

    fn call(&mut self, request: Request<Incoming>) -> Self::Future {
        // Watching is not using: a `memfork watch` left open must not keep
        // an otherwise idle daemon alive.
        if request.uri().path() != EVENTS_PATH {
            self.clock.touch();
        }

        let presented = request
            .headers()
            .get(hyper::header::AUTHORIZATION)
            .and_then(|v| v.to_str().ok())
            .and_then(|v| v.strip_prefix("Bearer "))
            .unwrap_or_default()
            .to_owned();
        // Compared in full rather than short-circuiting on the first differing
        // byte. The daemon is loopback-only and the token is 32 random bytes,
        // so this is belt and braces, but it costs nothing.
        let authorized = presented.len() == self.token.len()
            && presented
                .bytes()
                .zip(self.token.bytes())
                .fold(0u8, |acc, (a, b)| acc | (a ^ b))
                == 0;

        if !authorized {
            return Box::pin(async {
                Ok(text(
                    StatusCode::UNAUTHORIZED,
                    "this MemFork daemon needs the token from its endpoint file\n",
                ))
            });
        }

        if request.uri().path() == SHUTDOWN_PATH {
            self.shutdown.cancel();
            return Box::pin(async { Ok(text(StatusCode::OK, "stopping\n")) });
        }

        if request.uri().path() == EVENTS_PATH {
            return Box::pin(std::future::ready(Ok(event_stream(
                &self.events,
                self.port,
                self.shutdown.clone(),
            ))));
        }

        if request.uri().path() == CLI_PATH {
            let db = self.db.clone();
            let events = Arc::clone(&self.events);
            return Box::pin(async move { Ok(run_cli(request, db, events).await) });
        }

        let mut inner = self.inner.clone();
        Box::pin(async move {
            match tower_service::Service::call(&mut inner, request).await {
                Ok(response) => Ok(response.map(|b| b.map_err(std::io::Error::other).boxed())),
                Err(never) => match never {},
            }
        })
    }
}

fn json_response(status: StatusCode, value: &serde_json::Value) -> Response<BoxBody> {
    let body = Full::new(Bytes::from(value.to_string()))
        .map_err(|never| match never {})
        .boxed();
    Response::builder()
        .status(status)
        .header("content-type", "application/json")
        .body(body)
        .unwrap_or_else(|_| Response::new(BoxBody::default()))
}

/// The activity stream: one JSON object per line, starting with who is
/// connected, ending when the daemon stops.
fn event_stream(events: &Events, port: u16, shutdown: CancellationToken) -> Response<BoxBody> {
    let hello = crate::events::Hello {
        kind: "hello".to_owned(),
        version: crate::VERSION.to_owned(),
        port,
        clients: events.connected(),
    };
    let first = serde_json::to_string(&hello).unwrap_or_default();
    let receiver = events.subscribe();
    let stream = futures::stream::unfold(
        (Some(first), receiver, shutdown),
        |(first, mut receiver, shutdown)| async move {
            if let Some(line) = first {
                return Some((line, (None, receiver, shutdown)));
            }
            loop {
                tokio::select! {
                    _ = shutdown.cancelled() => return None,
                    got = receiver.recv() => match got {
                        Ok(event) => {
                            let line = serde_json::to_string(&event).unwrap_or_default();
                            return Some((line, (None, receiver, shutdown)));
                        }
                        // A watcher that fell behind misses what it missed,
                        // and carries on.
                        Err(tokio::sync::broadcast::error::RecvError::Lagged(_)) => continue,
                        Err(tokio::sync::broadcast::error::RecvError::Closed) => return None,
                    },
                }
            }
        },
    );
    let frames = futures::StreamExt::map(stream, |line| {
        Ok::<_, std::io::Error>(hyper::body::Frame::data(Bytes::from(line + "\n")))
    });
    let body = BodyExt::boxed(http_body_util::StreamBody::new(frames));
    Response::builder()
        .status(StatusCode::OK)
        .header("content-type", "application/x-ndjson")
        .header("cache-control", "no-store")
        .body(body)
        .unwrap_or_else(|_| Response::new(BoxBody::default()))
}

/// One command-line operation, carried out on the shared store exactly as
/// `--ephemeral` would carry it out in memory, and reported to watchers.
async fn run_cli(
    request: Request<Incoming>,
    db: memfork_core::Db,
    events: Arc<Events>,
) -> Response<BoxBody> {
    let bad = |why: String| {
        json_response(
            StatusCode::BAD_REQUEST,
            &serde_json::json!({ "error": why }),
        )
    };
    let bytes = match request.into_body().collect().await {
        Ok(collected) => collected.to_bytes(),
        Err(e) => return bad(format!("the request could not be read: {e}")),
    };
    #[derive(serde::Deserialize)]
    struct Call {
        branch: String,
        command: Command,
        namespace: Option<String>,
    }
    let call: Call = match serde_json::from_slice(&bytes) {
        Ok(call) => call,
        Err(e) => return bad(format!("the request did not parse: {e}")),
    };
    if !call.command.allowed_in_script() {
        return bad(format!(
            "`memfork {}` is not an operation on the store",
            call.command.name()
        ));
    }
    let Call {
        branch,
        command,
        namespace,
    } = call;
    let (key, target) = crate::exec::target(&command, &branch);
    let name = command.name();
    let outcome = tokio::task::spawn_blocking(move || {
        crate::exec::execute_as(&db, &branch, &command, Some(CLI_WRITER))
    })
    .await;
    let outcome = match outcome {
        Ok(outcome) => outcome,
        Err(e) => Err(crate::exec::ExecError::Usage(format!(
            "the operation did not finish: {e}"
        ))),
    };
    events.publish(Event {
        operation: Some(name.to_owned()),
        key,
        branch: target,
        ok: outcome.is_ok(),
        error: outcome.as_ref().err().map(ToString::to_string),
        ..Event::about(CLI_WRITER, namespace.as_deref())
    });
    match outcome {
        Ok(outcome) => json_response(
            StatusCode::OK,
            &serde_json::json!({ "text": outcome.text, "json": outcome.json }),
        ),
        Err(e) => json_response(
            StatusCode::UNPROCESSABLE_ENTITY,
            &serde_json::json!({ "error": e.to_string() }),
        ),
    }
}

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

    #[test]
    fn the_idle_clock_measures_from_the_last_request() {
        let clock = Clock::new();
        clock.touch();
        assert!(clock.idle_for() < Duration::from_millis(100));
    }

    /// Short enough that a forgotten daemon goes away, long enough that a
    /// client which pauses to think does not lose its server. Checked at
    /// compile time, since both sides are constants.
    const _: () = {
        assert!(DEFAULT_IDLE_SECONDS >= 300);
        assert!(DEFAULT_IDLE_SECONDS <= 3600);
    };
}