/verify-everos - check a change on a real server

Unit and integration tests run the code with stand-ins; this is how to see the real everos server do it. Grown one task at a time: each task adds the features it actually walked (see the feature map at the end), nothing more.

1. Start your own instance

Never use ~/.everos or a server someone else started. Give every check its own root and port.

ROOT=$(mktemp -d)/root; PORT=18611
lsof -nP -iTCP:$PORT -sTCP:LISTEN          # must print nothing
uv run everos init --root "$ROOT"
EVEROS_LLM__API_KEY=$OPENROUTER_API_KEY \
EVEROS_EMBEDDING__API_KEY=$DEEPINFRA_API_KEY \
EVEROS_RERANK__API_KEY= \
  uv run everos server start --root "$ROOT" --port $PORT > "$ROOT.log" 2>&1 &
echo $! > "$ROOT.pid"

The shipped defaults point the LLM at OpenRouter and the embedding at DeepInfra, so those two keys are all it needs. Reflection is off by default (docs/reflection.md); to turn it on, replace the $ROOT/ome.toml that init scaffolds with [strategies.reflect_episodes]\nenabled = true before starting, as the acceptance tests do.

2. Is it ready?

curl -s http://127.0.0.1:$PORT/health answers 200 within a few seconds. Its cascade.pending is the number of markdown changes not yet in the index. Before reading the index, poll it once a second until it reads 0 on two consecutive samples (docs/api.md, and wait_converged in tests/acceptance/memory_delete/observe.py): a single 0 can come between a markdown write and its projection being queued. A server that exits instead: the last lines of $ROOT.log (usually a missing key).

3. Drive it

• HTTP: POST /api/v2/memory/add, /flush, /delete (user_id / agent_id / session_id), /delete_by_ids ({"memory_type": "episode", "memory_ids": ["<owner>_<entry_id>"]}), /memory/search, /memory/get. Run Reflection now with POST /api/v2/ome/trigger {"name": "reflect_episodes", "force": true}.

• Claude Code, the way users do it: run everos-mcp against your port and start Claude Code with only that server, in a tmux socket of your own (tmux -L <name>), sending keys and reading the pane:

  {"mcpServers": {"everos": {"command": "uv",
    "args": ["run", "--no-project", "--with", "everos-mcp==0.1.1",
             "python", "-m", "everos_mcp.server"],
    "env": {"EVEROS_BASE_URL": "http://127.0.0.1:18611",
            "EVEROS_USER_ID": "me", "EVEROS_SESSION_ID": "walk-1"}}}}

  claude --mcp-config <that file> --strict-mcp-config. A turn is finished when the pane shows its completion line (... for Ns · done), not when some for Ns appears (the thinking line has one too).

• Racing a background task: make acceptance (needs the two keys; the Milvus cases need docker) starts servers behind a local proxy that can hold one model call (tests/acceptance/memory_delete/proxy.py), so a deletion can land while an extraction or a Reflection merge is in flight. Check that the held call is still the only one of its kind when the deletion answers: a model call that times out retries past the hold.

4. Read the outcome where it lives

A search that finds nothing is not proof of a deletion: read the markdown and the index directly.

5. Tear down

Stop the pid you started, after checking it is yours, then wait for the port:

ps -o args= -p $(cat "$ROOT.pid")             # must show `everos server start`
kill $(cat "$ROOT.pid")
for i in $(seq 1 50); do lsof -nP -iTCP:$PORT -sTCP:LISTEN >/dev/null || break; sleep 0.2; done
tmux -L <name> kill-server                     # if you drove Claude Code

Never pkill by pattern: other sessions on the machine run their own servers.

Feature map

One row per feature a task has walked on a real server.