Runbook: Memory Service

Status: prototype

Use this after explicitly enabling dubnium.memory.enable = true for the workstation host. The memory service is intentionally opt-in during Phase 1 so first bring-up does not automatically start additional persistent services.

The memory service is the local persistent context substrate for Dubnium. It does not govern agent behavior by itself. Anthesis or another orchestrator should authorize retrieval, inspect provenance, and decide whether retrieved memory may be injected into an agent prompt.

Service Boundary

Anthesis / orchestrator
  -> Dubnium memory API
  -> Postgres + pgvector
  -> Redis working context / queue substrate
  -> vLLM prompt assembly outside the memory service

The API must remain bound to 127.0.0.1 for the Phase 1 prototype.

Service Impact

Enabling dubnium.memory starts additional local services:

postgresql.service
redis-dubnium-memory.service
dubnium-memory-api.service

It also runs packaged memory-service migrations before the API starts. Validate the package and module evaluation before enabling this on the bare-metal workstation target.

Enable Locally

The default workstation target keeps the memory service disabled. Enable it through a host-local override such as hosts/workstation/user.nix:

{
  dubnium.memory = {
    enable = true;
    api.host = "127.0.0.1";
    api.port = 8090;
    retention.defaultTtlDays = null;
  };
}

Then build before switching:

nix --extra-experimental-features "nix-command flakes" build .#memory-service
sudo nixos-rebuild build --flake .#workstation

Verify Disabled Default

Without a host-local override, the workstation target should keep the prototype disabled:

nix --extra-experimental-features "nix-command flakes" eval .#nixosConfigurations.workstation.config.dubnium.memory.enable

Expected:

false

Verify Enabled Configuration

After enabling through hosts/workstation/user.nix, verify:

nix --extra-experimental-features "nix-command flakes" eval .#nixosConfigurations.workstation.config.dubnium.memory.enable
nix --extra-experimental-features "nix-command flakes" eval .#nixosConfigurations.workstation.config.dubnium.memory.api.host
nix --extra-experimental-features "nix-command flakes" eval .#nixosConfigurations.workstation.config.services.postgresql.enable
nix --extra-experimental-features "nix-command flakes" eval .#nixosConfigurations.workstation.config.services.redis.servers.dubnium-memory.enable

Expected:

true
"127.0.0.1"
true
true

Verify Services

After switching an enabled configuration:

systemctl status postgresql
systemctl status redis-dubnium-memory
systemctl status dubnium-memory-api
ai-memory health

Expected health response:

{
  "status": "ok"
}

Raw HTTP is also available for debugging:

curl http://127.0.0.1:8090/healthz

Scope Convention

Use explicit scope prefixes for new memory rows:

personal:
project:
session:
agent:
workflow:

Examples:

project:dubnium
session:11111111-1111-4111-8111-111111111111
agent:anthesis-reviewer
workflow:memory-phase-2

The current implementation provides advisory scope helpers. Full runtime enforcement is intentionally deferred until existing callers and examples are migrated.

CLI Smoke Test

Store one memory:

ai-memory store --file docs/examples/memory-store-request.json

Retrieve scoped memory:

ai-memory retrieve \
  --query "What is Dubnium memory for?" \
  --scope project:dubnium \
  --require-verified \
  --purpose review \
  --actor-type agent \
  --actor-id anthesis-reviewer \
  --envelope-id env-manual-smoke-test

Inspect retrieval events:

ai-memory events

Expire old memories:

ai-memory expire --now 2026-05-28T00:00:00Z

Use a non-default API URL when needed:

ai-memory --url http://127.0.0.1:8090 health

API Smoke Test

The CLI is preferred for operator use. Raw HTTP examples are kept for debugging and automation parity.

Store one memory:

curl -sS http://127.0.0.1:8090/memory/store \
  -H 'Content-Type: application/json' \
  -d @docs/examples/memory-store-request.json

Retrieve scoped memory:

curl -sS http://127.0.0.1:8090/memory/retrieve \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "What is Dubnium memory for?",
    "scope": "project:dubnium",
    "allowed_sensitivity": ["internal"],
    "require_verified": true,
    "limit": 8
  }'

Inspect retrieval events:

curl -sS http://127.0.0.1:8090/memory/retrieval-events

Retrieval Behavior

Normal retrieval excludes memory when:

scope does not match the request
sensitivity is not explicitly allowed
require_verified is true and memory is not verified
memory is expired by TTL
memory has validation_status = rejected

Rejected memory is excluded even when require_verified = false. Audit retrieval of rejected memory is future work and should use a separate endpoint or explicit audit mode.

Security Checks

API binds to 127.0.0.1
raw vLLM remains separate from durable memory
memory rows include scope, sensitivity, validation status, source, and provenance
expired memories are excluded from retrieval
rejected memories are excluded from normal retrieval
sensitive memories are excluded unless explicitly allowed
retrieval events record returned memory ids and artifact ids
logs must not contain raw token-like values
prompt assembly must happen outside the memory service

Anthesis Governance Hook

Phase 1 does not implement Anthesis directly. The intended integration contract is:

Anthesis classifies the task and authorizes retrieval scope
Anthesis calls /memory/retrieve with explicit scope, allowed_sensitivity, and require_verified
The memory service returns memories plus a retrieval event id
Anthesis records the retrieval event, memory ids, provider decision, and prompt assembly in an execution envelope
Anthesis decides whether retrieved memory may enter the model context

Memory may inform an agent, but governance decides whether it is allowed to do so.

Troubleshooting

journalctl -u dubnium-memory-api -b
journalctl -u postgresql -b
journalctl -u redis-dubnium-memory -b

Common failure buckets:

database role or socket mismatch
pgvector extension unavailable for the selected Postgres package
migration failure
API accidentally bound to a non-local address
malformed JSON payload
scope mismatch during retrieval

Validation Before Merge

git diff --check
nix --extra-experimental-features "nix-command flakes" build .#memory-service
nix --extra-experimental-features "nix-command flakes" eval .#nixosConfigurations.workstation.config.dubnium.memory.enable
pytest pkgs/memory-service/tests

Default workstation expectation before opt-in:

false

If the full workstation build fails on host-specific hardware configuration, report that separately from the memory service package/module validation.

Keyboard shortcuts

Dubnium