ZMem Docs

Use ZMem as governed shared memory for agents collaborating inside a Zerker Gateway Room.

ZMem's Rooms adapter is the tenant-local memory service for Zerker Gateway. It gives each room durable shared memory, keeps member-private memory isolated, and returns an explicit context state instead of treating every successful read as safe to use.

Start The Local Service

Run one tenant-local ZMem process beside Rooms:

export ZMEM_SERVICE_TOKEN="$(openssl rand -hex 32)"

zmem \
  --db .zerker/control.sqlite \
  --policy .zerker/policy.json \
  serve \
  --tenant-id tnt_local \
  --storage-root .zerker/rooms

The default bind is 127.0.0.1:8766. Tenant identity comes from service configuration, not request JSON. Room database paths are derived from opaque tenant-and-room hashes.

The dependency-light default uses FTS. For semantic room goals, install the local dense runtime, explicitly cache the model once, and start Rooms in dense-hybrid mode:

python3 -m pip install 'zerker-memory[dense]'
zmem --db .zerker/control.sqlite embeddings index --download-model --summary-only

zmem \
  --db .zerker/control.sqlite \
  --policy .zerker/policy.json \
  serve \
  --tenant-id tnt_local \
  --storage-root .zerker/rooms \
  --retrieval-mode dense-hybrid

No context request downloads a model. A dense-enabled Rooms service keeps each room's derived index current after writes and catches up missing or stale vectors before reads. The response reports compact retrieval_index readiness without exposing vectors or memory text.

Use liveness and readiness separately:

curl -sS http://127.0.0.1:8766/healthz
curl -sS -i http://127.0.0.1:8766/readyz

/healthz confirms the process is alive. /readyz confirms storage and the configured retrieval mode are usable. FTS is ready immediately. A service configured for dense-hybrid returns HTTP 503 with an exact setup command until FastEmbed is installed and the local model is cached; it returns HTTP 200 once semantic retrieval is ready. This prevents an orchestrator from treating lexical fallback as a healthy semantic deployment.

Verify The Rooms Contract

Run the self-contained local acceptance gate before wiring Gateway:

zmem rooms-acceptance --summary-only

It uses ephemeral SQLite stores and loopback HTTP services, then checks authentication, caller-independent tenant identity, shared and member-private memory, room and tenant isolation, exact context commitments, abstention, idempotent replay, conflict rejection, and concurrent context preparation. It does not write to a deployed tenant.

Latency is reported rather than judged against an invented default SLO. Apply an explicit engineering budget when your deployment has one:

zmem rooms-acceptance --requests 200 --concurrency 8 --max-p95-ms 500 --summary-only

Gateway must still run its own end-to-end test with the production network path, timeout, retry policy, Room sizes, and join behavior.

Prepare Agent Context

curl -fsS http://127.0.0.1:8766/v1/contexts:prepare \
  -H "Authorization: Bearer $ZMEM_SERVICE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "room_id": "rom_alpha",
    "agent_id": "agt_cursor",
    "purpose": "Continue the room release",
    "risk": "medium",
    "context_budget_tokens": 2000
  }'

The response preserves retrieval order and distinguishes:

ready: context is admitted;
partial: admitted context exists, with explicit omissions;
empty: the room has no prior active memory;
blocked: memory existed but policy admitted none;
abstained: evidence conflicted, or an established room produced no confident match;
budget_exhausted: relevant memory did not fit the approved budget.

It also includes selected memory provenance, withheld and budget-dropped counts, packing use, and a digest binding the room, agent, purpose, policy, memory roots, and exact selected IDs.

When an established room has active memory but retrieval finds no relevant candidate, omissions.abstention.reason is no-relevant-memory. That is intentionally distinct from a genuinely new room. Gateway can request review or fall back to separately supplied onboarding documents without pretending the room had no history.

POST /v1/inject is an equivalent compatibility route and accepts task as an alias for purpose.

Write Shared Memory

The trusted Rooms service records accepted state:

curl -fsS http://127.0.0.1:8766/v1/memories:record \
  -H "Authorization: Bearer $ZMEM_SERVICE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "room_id": "rom_alpha",
    "agent_id": "agt_cursor",
    "content": "Release approval is required.",
    "memory_type": "procedural",
    "visibility": "room",
    "source_event_id": "evt_policy_1",
    "idempotency_key": "evt_policy_1:procedure"
  }'

Agent-authored claims use /v1/memories:propose instead. They begin quarantined and cannot shape another agent's context until reviewed. visibility: "member" keeps a memory private to one member inside that room.

Every write is bound to the Rooms source event and is retry-safe. Reusing an idempotency key for different content fails rather than silently changing history.

Integration Boundary

Rooms owns membership, goals, messages, and the event log. ZMem owns memory state, review, retrieval, context packing, and memory receipts. Treeship can attest selected room transitions asynchronously; it is not required for local recall and does not become the primary room store.

The initial adapter is deliberately tenant-local. A hosted shared service requires a separate Gateway authentication, tenant-routing, and isolation review.

Inspect Rooms Locally

Each initialized Room store records a content-free local descriptor containing its configured tenant, opaque Room id, and derived storage id. This makes isolated stores discoverable without exposing memory text or making ZMem authoritative for membership.

zmem \
  --db .zerker/control.sqlite \
  ui \
  --tenant-id tnt_local \
  --rooms-root .zerker/rooms

The console reports room-shared versus member-private counts, review state, observed contributors, latest proof root, and semantic-index coverage. “Observed contributor” means the agent id appears in memory provenance. Gateway membership and authorization remain separate and authoritative.

Zerker Rooms