DX on-ramp: memctl data-plane + docker-compose + examples (#38) - #56
Merged
Conversation
…#38) memctl was control-plane only (token issue / gen-keypair / version), so the quickstart needed hand-built grpcurl JSON+base64 for every data op. Add verbs that talk to a running server using the token memctl already issues, reusing the in-tree Go stubs — no grpcurl. - kv put/get, semantic search, episodic tail (live stream), graph neighbors, ns ls (Admin.ListNamespaces). - Shared --addr ($MEMSIDECAR_ADDR or 127.0.0.1:7777), --token ($MEMSIDECAR_TOKEN), --tls flags; the capability token rides an outgoing metadata interceptor (x-memsidecar-capability: Bearer …) on unary + stream. - Flags may appear before or after the positionals (the stdlib flag package otherwise stops at the first positional). Verified end-to-end against a live server: kv round-trip, ns ls counts reflect writes, semantic/graph/episodic calls authenticate and stream, and a bad token is rejected with Unauthenticated. go vet + golangci-lint clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
`docker compose up --build` brings up memsidecar backed by Postgres (pgvector, so the semantic block works) and MinIO (S3 artifacts), with helper services to mint a token and run memctl verbs — no local Go/buf toolchain needed. - docker-compose.yml: postgres (pgvector/pgvector:pg16, healthchecked), minio + a one-shot minio-setup that creates the bucket, memsidecar (built from the Dockerfile, waits for both healthy), and `token` / `memctl` helper services under the `tools` profile. - configs/compose.yaml: binds 0.0.0.0, backs every durable block with Postgres and artifacts with MinIO via env-injected DSN + S3 creds. - .dockerignore: exclude node_modules / website / ts dist from the build context (the image only builds the Go server + memctl). Verified: `docker compose up --build` boots the server on Postgres+MinIO; `docker compose run --rm -T token` mints a token; `memctl kv put/get` round-trips through Postgres and `memctl ns ls` shows the postgres + s3 backends. DEV credentials only (the PASETO keypair is public in-repo). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- examples/agent_tour.py: a runnable tour of all six blocks framed as one agent turn (episodic log, kv cache, semantic recall, artifact store, graph link, lease), plus examples/README.md. Verified end-to-end against a live server. - quickstart.md: lead with `docker compose up` (no toolchain) and drive the data plane with `memctl` verbs instead of hand-built grpcurl JSON+base64; point at the example tour. Docusaurus build clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This was referenced Aug 1, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes the remaining #38 bullets. Time-to-first-value went from "install buf + grpcurl, hand-build JSON+base64 for every op" to
docker compose up+memctl.1.
memctldata-plane verbsmemctl was control-plane only; now it talks to a running server with the token it already issues (no grpcurl):
kv put/get,semantic search,episodic tail(live stream),graph neighbors,ns ls(Admin.ListNamespaces).--addr/--token/--tls; capability rides an outgoing metadata interceptor on unary + stream. Flags work before or after positionals.2.
docker-compose.ymldocker compose up --build→ memsidecar + Postgres (pgvector) + MinIO (S3), with a one-shot bucket setup andtoken/memctlhelper services (toolsprofile).configs/compose.yamlbinds 0.0.0.0 and backs every durable block with Postgres + artifacts with MinIO..dockerignoretightened (no node_modules/website in the build context).3.
examples/agent_tour.py+ quickstartA runnable tour of all six blocks as one agent turn (episodic → kv → semantic → artifact → graph → lease). The quickstart now leads with Compose and drives everything through
memctlinstead of grpcurl.Verification (all real, not just compiles)
kv put/getround-trips,ns lscounts reflect writes, semantic/graph/episodic authenticate + stream, a bad token is rejectedUnauthenticated.docker compose up --buildboots on Postgres+MinIO;kv put/getround-trips through Postgres andns lsshows the postgres + s3 backends.buf lint,go vet,go test -race ./...,golangci-lint(0 issues), Docusaurus build all clean.With this, #38 is fully closed (the PyPI-publish bullet shipped in #55). DEV credentials only — the compose PASETO keypair is public in-repo.