Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs(config): document bind and server_url together

yubr-zzhb5369b65b4c1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0a8c0725..5137e0a3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,22 @@ version in [`docs/changelog/`](docs/changelog/):
## [Unreleased]
### Fixed
+- Fixed the thin-client commands ignoring a custom `bind`, which could write
+ into the wrong store. `server_url` defaulted to `http://127.0.0.1:49374`
+ and was never derived from `bind`, so `ai-memory --data-dir X status` (and
+ `write-page`, `search`, `purge-project`, ...) called the default port
+ whatever `bind` said. With nothing listening there the command failed; with
+ another server listening there it operated on that server's data, and one
+ reporter wrote test pages into their real store this way. When neither
+ `config.toml` nor `AI_MEMORY_SERVER_URL` sets `server_url`, it is now
+ derived from `bind`: an unspecified address maps to loopback (`0.0.0.0` to
+ `127.0.0.1`, `[::]` to `[::1]`) and any other host is used as given,
+ hostname included. An explicit value in the file or the environment still
+ wins, a `bind` that is not a `host:port` leaves the default URL alone, and
+ the default `bind` resolves to the same URL as before, so an install that
+ never changed either key is unaffected. A derived URL is not reported as an
+ operator-configured one, so `install-hooks` and `install-mcp` behave as
+ they always have for someone who only edited `bind`. (#1269)
- Fixed Windows capture dropping the body of file and shell tool events
the client had kept. With `[capture] ignore_paths` active, server
re-inspection compiled a POSIX never-match sentinel and treated the
diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rs
index 549aa00c..7008259e 100644
--- a/crates/ai-memory-cli/src/config.rs
+++ b/crates/ai-memory-cli/src/config.rs
@@ -3619,6 +3619,28 @@ mod tests {
}
}
+ /// The shipped `config.default.toml` must actually load.
+ ///
+ /// It is `include_str!`-ed by `init` and written as-is, so a template
+ /// that does not parse would only surface when someone ran `init` and
+ /// started the server. Comments added by #1269 are the kind of edit that
+ /// can break it silently (a stray quote, a line that stops being a
+ /// comment), and nothing tested the file itself.
+ #[test]
+ fn the_shipped_default_config_parses() {
+ const TEMPLATE: &str = include_str!("../templates/config.default.toml");
+ let cfg = load_with_toml(TEMPLATE).expect("config.default.toml must load");
+ assert_eq!(cfg.bind, DEFAULT_BIND);
+ assert_eq!(
+ cfg.server_url, DEFAULT_SERVER_URL,
+ "the template leaves server_url unset, so the default bind derives the default URL"
+ );
+ assert!(
+ !cfg.server_url_derived_from_bind,
+ "the default bind short-circuits the derivation, so nothing is marked derived"
+ );
+ }
+
/// #1269: a thin client must reach the server the SAME config starts.
///
/// `server_url` defaulted to a constant and was never derived from `bind`,
diff --git a/crates/ai-memory-cli/templates/config.default.toml b/crates/ai-memory-cli/templates/config.default.toml
index 43b627cf..091695dd 100644
--- a/crates/ai-memory-cli/templates/config.default.toml
+++ b/crates/ai-memory-cli/templates/config.default.toml
@@ -9,6 +9,19 @@
# HTTP bind address used by `ai-memory serve`.
bind = "127.0.0.1:49374"
+# Base URL the thin-client commands (`status`, `write-page`, `search`,
+# `purge-project`, ...) use to reach the server. Left unset, it is derived
+# from `bind` above, so a client run against this data dir reaches the server
+# this same file starts. Set it only when the server is reached at a different
+# address than it binds -- behind a reverse proxy, a tunnel, or from another
+# host:
+#
+# server_url = "https://memory.example"
+#
+# AI_MEMORY_SERVER_URL overrides this. Changing `bind` alone is enough for a
+# local install; the two do not have to be kept in sync by hand.
+# server_url = "http://127.0.0.1:49374"
+
# Host-header allowlist for the HTTP server (DNS-rebinding defence).
# Keep loopback defaults for local-only use. When binding to a LAN
# address, include the host/IP clients will use, e.g.
diff --git a/docs/install.md b/docs/install.md
index b7ff9d97..28b46e4d 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -658,6 +658,18 @@ bind = "0.0.0.0:49374"
allowed_hosts = ["homelab", "192.168.0.90", "localhost", "127.0.0.1"]
```
+`server_url` does not need to be set here. When neither `config.toml` nor
+`AI_MEMORY_SERVER_URL` names one, the thin-client commands derive it from
+`bind`, so a local `ai-memory status` reaches this server rather than the
+default port. An unspecified bind is mapped to loopback (`0.0.0.0` becomes
+`127.0.0.1`, `[::]` becomes `[::1]`). Set `server_url` only when clients
+reach the server at an address it does not bind, such as behind a reverse
+proxy or a tunnel:
+
+```toml
+server_url = "https://memory.example"
+```
+
```bash
# optional: replace the token init wrote
TOKEN=$(ai-memory generate-auth-token)