Skip to content

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

Rust

M2.5-A: Dockerfile, docker-compose, README quick-start

AkitaOnRails1b7a0858f77f
diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 00000000..2f2eefc7
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,20 @@
+# Build artefacts.
+target/
+**/target/
+
+# Local state.
+.local-data/
+*.log
+flamegraph.svg
+perf.data*
+
+# VCS internals — Docker build doesn't need them.
+.git/
+
+# Editor / OS.
+.idea/
+.vscode/
+.DS_Store
+
+# Sandbox marker.
+.ai-jail
diff --git a/README.md b/README.md
index 5f30d975..a830a084 100644
--- a/README.md
+++ b/README.md
@@ -64,37 +64,59 @@ page-level FTS5, then optional graph-walk expansion.
Storage moves between machines via `git push` of the wiki dir +
`sqlite3 .backup` of the DB, or just `rsync` of the data dir.
-## Quick start (M0)
+## Quick start
-Requires Rust 1.95+. Currently exercises only `init` / `status` — the
-MCP server lands in M2.
+Requires Rust 1.95+. Three ways to run it, in increasing order of
+"homelab-ready":
+
+### Local: cargo build
```bash
-# Build.
-cargo build --workspace
+# Build, init, and run the MCP server over stdio (attach with claude mcp).
+cargo build --release --workspace
+./target/release/ai-memory init
+claude mcp add ai-memory -- ./target/release/ai-memory serve --transport stdio
+```
-# Create the data directory layout.
-./target/debug/ai-memory init
+Or with HTTP transport for `mcp-inspector` / curl / a remote Claude Code:
-# Or override the location.
-AI_MEMORY_DATA_DIR=/srv/ai-memory ./target/debug/ai-memory init
+```bash
+./target/release/ai-memory serve --transport http --bind 127.0.0.1:7777
+```
-# Inspect.
-./target/debug/ai-memory status --json
+### Local: Docker Compose
+
+```bash
+docker compose -f docker/docker-compose.yml up -d --build
+# State lives in the `ai-memory-data` named volume.
+# Attach Claude Code at http://localhost:7777/mcp
```
-After M2, the MCP server will be attachable via:
+### Other CLI commands
```bash
-claude mcp add ai-memory -- ai-memory serve --transport stdio
+./target/release/ai-memory --help # full subcommand list
+./target/release/ai-memory init # create the data dir layout
+./target/release/ai-memory write-page \
+ --path notes/foo.md --title Foo --body "..." # exercise the wiki write
+./target/release/ai-memory search "karpathy" # FTS5 query
+./target/release/ai-memory recent # (M2-B) most-recent pages
+./target/release/ai-memory status --json # counts + paths
+./target/release/ai-memory watch # standalone filesystem watcher
+./target/release/ai-memory serve # MCP server (stdio default)
+./target/release/ai-memory reset --confirm # wipe data (refuses if siblings alive)
```
-After M2.5, the Docker quick-start will be:
+### Override the data dir
```bash
-docker run -v ai-memory:/data -p 7777:7777 ghcr.io/akitaonrails/ai-memory:latest
+AI_MEMORY_DATA_DIR=/srv/ai-memory ./target/release/ai-memory init
```
+Default location is `dirs::data_local_dir().join("ai-memory")` —
+`~/.local/share/ai-memory` on Linux, `~/Library/Application Support/ai-memory`
+on macOS.
+
## Docs
Long-form research and design lives under [`docs/`](docs/):
diff --git a/docker/Dockerfile b/docker/Dockerfile
new file mode 100644
index 00000000..5f4e33c2
--- /dev/null
+++ b/docker/Dockerfile
@@ -0,0 +1,38 @@
+# syntax=docker/dockerfile:1.7
+#
+# Multi-stage build for the ai-memory MCP server.
+# Builder: rust:1.95-slim with the release binary cached against
+# BuildKit's cargo registry + target caches.
+# Runtime: debian:bookworm-slim with a non-root `ai-memory` user that
+# owns /data. CA certificates included for outgoing HTTPS (LLM
+# providers in M6+).
+
+FROM rust:1.95-slim AS builder
+WORKDIR /work
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends pkg-config build-essential \
+ && rm -rf /var/lib/apt/lists/*
+COPY Cargo.toml Cargo.lock rust-toolchain.toml deny.toml ./
+COPY crates ./crates
+RUN --mount=type=cache,target=/usr/local/cargo/registry \
+ --mount=type=cache,target=/work/target \
+ cargo build --release -p ai-memory-cli \
+ && cp target/release/ai-memory /usr/local/bin/ai-memory
+
+FROM debian:bookworm-slim
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends ca-certificates \
+ && rm -rf /var/lib/apt/lists/* \
+ && useradd --system --uid 1000 --user-group --home-dir /data \
+ --shell /usr/sbin/nologin ai-memory \
+ && mkdir -p /data \
+ && chown -R ai-memory:ai-memory /data
+COPY --from=builder /usr/local/bin/ai-memory /usr/local/bin/ai-memory
+USER ai-memory
+ENV AI_MEMORY_DATA_DIR=/data
+WORKDIR /data
+EXPOSE 7777
+HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
+ CMD ["/usr/local/bin/ai-memory", "status"]
+ENTRYPOINT ["/usr/local/bin/ai-memory"]
+CMD ["serve", "--transport", "http", "--bind", "0.0.0.0:7777"]
diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml
new file mode 100644
index 00000000..1b45c4cf
--- /dev/null
+++ b/docker/docker-compose.yml
@@ -0,0 +1,37 @@
+# docker-compose.yml for ai-memory.
+#
+# Run from this directory:
+# docker compose up -d
+# Attach Claude Code (or any MCP HTTP client) at
+# http://localhost:7777/mcp
+# State persists in the `ai-memory-data` volume; move it between hosts
+# by stopping the container, `docker volume export` (or rsync the
+# mountpoint), and importing on the target.
+
+services:
+ ai-memory:
+ image: ai-memory:local
+ build:
+ context: ..
+ dockerfile: docker/Dockerfile
+ container_name: ai-memory
+ restart: unless-stopped
+ user: "1000:1000"
+ volumes:
+ - ai-memory-data:/data
+ ports:
+ # Bind to loopback by default; flip to 0.0.0.0:7777 when serving
+ # the homelab LAN. Keep behind a reverse proxy if you do.
+ - "127.0.0.1:7777:7777"
+ environment:
+ - RUST_LOG=ai_memory=info,ai_memory_store=info,ai_memory_wiki=info,ai_memory_mcp=info,tracing_appender=warn
+ healthcheck:
+ test: ["CMD", "/usr/local/bin/ai-memory", "status"]
+ interval: 30s
+ timeout: 5s
+ retries: 3
+ start_period: 5s
+
+volumes:
+ ai-memory-data:
+ name: ai-memory-data