Teach Claude a rule today.
Watch a session next week apply it — and show you the message it came from.

1. step 01 Get a model API key and put it in .env

   The shipped design calls OpenAI: a chat model for the memory passes and text-embedding-3-small for every stored record. Create a key at platform.openai.com/api-keys. Add it as OPENAI_API_KEY to .env in the repository root. Compose reads that file automatically, and Git ignores it.

   your terminalcopy

   $ git clone https://github.com/memseekai/memseek && cd memseek

   Another provider? Point examples/agent_memory_catalog/conf/models.yaml at any OpenAI-compatible endpoint that also offers embeddings, name its key variable in api_key_env, and put that variable in .env.

2. step 02 Start the stack with one command

   --wait returns only once the API is healthy and the one-shot steps have exited 0. First build: a few minutes. After that: seconds.

   your terminalcopy

   $ docker compose up -d --build --wait
   $ docker compose logs setup --no-log-prefix
   
   workspace 'local' created; key written to /state/api_key
   published agent_memory@0.3.0 (20 files) from examples/agent_memory_catalog
   MCP interface ready — 7 tools: context, recall, standing_rules,
     replay_session, remember, record, answer

   migrate and setup are supposed to show as exited in docker compose ps -a: they apply the schema and publish the memory design, then have nothing left to do. If setup still shows as running, it is mid-publish — give it a few seconds.

3. step 03 Read the workspace key

   The setup step writes it to a bind-mounted file instead of printing it into interleaved logs. This is the key the plugin will ask for.

   your terminalcopy

   $ cat .memseek/api_key

4. step 04 Check the service answers

   Liveness including the database, then the exact tool contract the plugin's MCP connection depends on — checked from inside the container, so Docker stays the only requirement.

   your terminalcopy

   $ curl -s http://127.0.0.1:8000/health
   {"ok":true,"db":true}
   
   $ docker compose exec \
       -e MEMSEEK_URL=http://127.0.0.1:8000 \
       -e MEMSEEK_API_KEY="$(cat .memseek/api_key)" \
       api memseek mcp --check
   
   # expect: package agent_memory 0.3.0, seven tools, and
   #   "streamable_http": "http://127.0.0.1:8000/mcp"

5. step 05 Prove your model credentials work — before Claude is involved

   This is the check that separates “my API key is wrong” from “the plugin is broken”, and it takes 30 seconds. Write one message over HTTP, then watch the worker do the real model work.

   your terminalcopy

   $ curl -sS -X POST http://127.0.0.1:8000/records \
       -H "Authorization: Bearer $(cat .memseek/api_key)" \
       -H 'Content-Type: application/json' \
       -d '{"records":[{"collection":"messages","type":"message",
            "entity":"project:preflight",
            "text":"Every distributed-cache key must start with orbit:.",
            "content":{"text":"Every distributed-cache key must start with orbit:.",
                        "role":"user","session_id":"preflight","ordinal":0},
            "dedupe_key":"preflight:0"}]}'
   
   {"inserted":[{"index":0,"id":"4882d928-…","ready":false}],"duplicates":[]}
   
   $ docker compose logs -f worker
   
   # within ~30s, one line per stage:
   "processor":"embedding_v1","provider":"openai","status":"ok"
   "derivation":"l1_extract","status":"ok","output_count":1
   "derivation":"scene_synthesis","status":"ok","output_count":1

   That is the ladder forming from a single message: evidence embedded, a reusable memory extracted, a topic summary written. ready:false in the first response is expected — the record is stored, its embedding is pending. A "status":"error" line naming authentication or a model is your key or your model name, and it is much cheaper to see it here.

   your terminalcopy

   # is the derived memory retrievable?
   $ curl -sS -X POST http://127.0.0.1:8000/views/memory_recall/query \
       -H "Authorization: Bearer $(cat .memseek/api_key)" \
       -H 'Content-Type: application/json' \
       -d '{"entity":"project:preflight","task":"distributed cache key prefix"}'
   
   # then delete the throwaway entity so it cannot pollute the real test
   $ curl -sS -X POST http://127.0.0.1:8000/erase \
       -H "Authorization: Bearer $(cat .memseek/api_key)" \
       -H 'Content-Type: application/json' \
       -d '{"entity":"project:preflight"}'

# stop, keep the memory and the key
$ docker compose down

# delete everything this test created
$ docker compose down -v && rm -rf .memseek

# and the plugin itself
$ claude plugin uninstall memseek-memory@memseek --scope local
$ claude plugin marketplace remove memseek

The repo carries the same procedure with every expected output in full, plus the capture-mode matrix and the complete troubleshooting table: docs/claude-code-plugin.md.