Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

7.2 KB
Raw Blame

Memory providers

QM keeps its built-in notebook memory unless MEMORY_PROVIDER_CONFIG defines a scope-aware provider router. Routes independently select where each scope recalls from, accepts explicit writes, and receives automatic post-turn capture.

Prompt memory

Each turn carries at most 6,000 characters of memory, selected across every notebook the conversation may read, one heading per notebook. With PostgreSQL and an embedding model, facts are ranked by exact cosine similarity to the current message and recent dialogue; otherwise the newest facts come first. Later turns add only newly selected facts.

Choose the model with the org setting memory-embedding-model ({ "modelId": "gateway/<model>" }, or null to turn ranking off). Gateway models with mode=embedding are listed automatically; a direct OpenAI-compatible model is registered in the model registry with "kind": "embedding". The provider receives fact text during background indexing and the query during recall. PostgreSQL stores typed vectors in memory_fact_vectors; recall ranks live, disclosed facts once per scope in SQL and returns compact ranked matches. No approximate vector index is used.

Semantic recall requires the PostgreSQL vector extension. Its migration is registered only after a configured embedding model resolves, not during an unconfigured startup. If the application database role cannot install extensions, an administrator must install vector first. File-backed installations use newest-first recall, even with a model selected.

A single background indexer embeds at most 64 missing facts and removes stale vectors in bounded batches every 30 seconds. It also sends a short dimension probe every ten minutes so a provider's vector-width change is detected even when its model identifier stays the same.

New or edited facts may wait for a background tick before becoming semantic matches. Unindexed facts participate at the recency fallback score alongside indexed semantic matches. If the provider/database fails, recall falls back to newest-first. Text search (memory search, POST /v1/memory/search) remains immediate and does not use embeddings.

External routing

{
  "providers": [
    {
      "id": "org-knowledge",
      "type": "mcp",
      "url": "http://memory-provider.internal:8080",
      "timeoutMs": 3000,
      "read": {
        "tool": "search_knowledge",
        "clientIdEnv": "KNOWLEDGE_RO_CLIENT_ID",
        "clientSecretEnv": "KNOWLEDGE_RO_CLIENT_SECRET"
      },
      "write": {
        "tool": "write_knowledge",
        "clientIdEnv": "KNOWLEDGE_RW_CLIENT_ID",
        "clientSecretEnv": "KNOWLEDGE_RW_CLIENT_SECRET"
      }
    }
  ],
  "routes": [
    {
      "provider": "default",
      "scopes": ["personal", "channel", "group", "team"],
      "capture": "automatic"
    },
    {
      "provider": "org-knowledge",
      "scopes": ["org"],
      "capture": "explicit",
      "manage": false,
      "label": "Organizational knowledge"
    }
  ]
}

Set the compact JSON document as MEMORY_PROVIDER_CONFIG. default names QM's local/Postgres notebook. A scope selector may be a kind (org) or an exact scope ID (org:acme). Earlier matching routes can compose multiple recall providers; the first route with manage enabled supplies notebook editing and revision history.

Capture policies are:

  • off: recall only;
  • explicit: writes only through deliberate memory actions;
  • automatic: explicit writes plus post-turn capture.

MCP reads receive query and acting_user by default. Writes receive content and acting_user. Operation entries can map optional fields with queryArg, contentArg, actorArg, scopeArg, maxCharsArg, inputArg, replyArg, capturedAtArg, sourceArg, and idempotencyArg. Only configured optional fields are sent, so providers can match strict MCP schemas.

Read and write operations use separate OAuth client-credential pairs. Omit write and set route capture to off for a read-only provider. External routes fail open by default so an outage does not block recall; set failOpen: false on a route to make it strict. Provider calls time out after timeoutMs (3 seconds by default). Explicit writes always fail visibly. QM continues to decide readable/writable scopes and passes the acting user to the provider.

Migrating from the retired BRAIN_* variables

Earlier releases wired an external knowledge server through BRAIN=mcp, BRAIN_MCP_URL, BRAIN_QUERY_TOOL, and the BRAIN_RO_*/BRAIN_RW_* OAuth client pairs, exposing read_brain and write_brain tools. Those variables are ignored now; startup logs a [config] warning while any of them is still set. Express the same server as an mcp provider above: url takes the old BRAIN_MCP_URL, read.tool the old BRAIN_QUERY_TOOL, and read/write name the env variables holding each OAuth client pair. Static bearer tokens (BRAIN_AUTH=bearer) have no equivalent; the provider framework authenticates with client credentials only.

Procedural memory (Memorable)

A provider with type: "memorable" records procedures rather than facts: when a turn's automatic capture fires, QM derives a deterministic tool-call trace from the session (which files changed, which commands verified the work), redacts any secret values, and hands it to the Memorable CLI with memorable record. Recall runs memorable inject with the turn's task and appends the returned pointer to the prompt. No model is involved in either direction.

{
  "providers": [{ "id": "procedures", "type": "memorable" }],
  "routes": [
    { "provider": "default", "scopes": ["personal", "channel", "group", "team", "org"], "capture": "automatic" },
    { "provider": "procedures", "scopes": ["personal"], "capture": "automatic", "manage": false, "label": "Procedures" }
  ]
}

Options: bin (default memorable; a string or an argv array such as ["node", "/opt/memorable/cli.js"]), passEnv (extra environment variable names to hand the CLI, e.g. ["MEMORABLE_STORE_KEY"]), injectTimeoutMs (default 15000) and recordTimeoutMs (default 120000). The CLI is not bundled: install it with npm i -g memorable-cli@latest — the qm backend needs 0.5.9 or newer, and an npm min-release-age setting can silently pick an older release, so check memorable --version (its qm backend also needs the pg package resolvable from QM's working directory). Recording calls the Memorable extraction service, so set both MEMORABLE_API_URL and MEMORABLE_API_KEY; recall is local. Consent is the CLI's own act, per scope: nothing is recorded for a scope until memorable enable --scope <scope-id> has been run with the same MEMORABLE_BACKEND=qm and MEMORABLE_DB_URL. It sees only an allow-listed environment — MEMORABLE_*, PATH, HOME, proxy and TLS variables — with MEMORABLE_BACKEND defaulting to qm and the database reachable solely as MEMORABLE_DB_URL. Routes to this provider accept capture: "automatic" or "off"; explicit remember writes are facts, not procedures, and are left to the notebook. A consent refusal from the CLI is reported as a capture error; like any external route it fails open by default, so the notebook write still lands and the refusal is logged. The provider never exposes a notebook, so keep manage: false and let default handle editing.