Skip to content

Guides

Memory and continuity

Pass context with provenance and retrieve details when needed.

Declare the measurement source

The token gate distinguishes reported, estimated, supplied and unavailable usage. Missing measurement is not zero. Query the gate before the next block; never decide rotation using an invented number.

ork gate next <thread> --proximo GO

Three levels of context

Critical content goes directly into the handoff. Important content becomes a pointer with a retrieval condition. Summarizable content gets a summary with provenance. Each item retains its source, location and hash; source changes must be noticed before trusting old context.

ork handoff export <thread> --proxima-fase GO
ork recall <thread> --fase CHECK

Unavailable memory

OrkMind is a memory integration, not gate authority. When unavailable, the effective mode and degradation must be explicit. Check ork memory status before claiming context was stored or retrieved.

ork memory status shows the regime requested in the manifest and the effective one, the tenant, the database variable, whether the DSN is in the environment (never printing its value) and the OrkMind CLI. In the files regime, degradation appears as modo.files, with the fix to turn on semantic memory: memory.mode: orkmind and the DSN source in the manifest, either memory.database_url_env or memory.database_url_file. The cycle does not stop because of it: the handoff stays triaged in three levels, and ork recall keeps resolving pointers.

ork memory status

The DSN outside the agents' environment

With memory.database_url_env, the DSN lives in the process environment and reaches the environment of every agent session that inherits it. The second source takes the DSN out of there: memory.database_url_file points to a file in ork's secrets folder, read at the moment of use.

The two sources are exclusive: declaring both database_url_file and database_url_env fails the manifest, and ork never falls back from one to the other. The accepted path is ~/.orkastery/segredos/<name>, with no subfolder; the file is a regular file owned by the user running ork, with mode 0600 or 0400, up to 4 KiB and a single line with the DSN. No folder in the path may be a symbolic link, and every use reads the file again.

A missing, unsafe or invalid file moves the regime to files, with dsn.arquivo-ausente, dsn.arquivo-inseguro or dsn.arquivo-invalido and the fix. A child process response that repeats the DSN or its password is refused entirely, with memory.transport.secret. ork memory status shows the source without the value, and ork doctor warns about the DSN source and about a DSN still exported in a dispatched session's environment.

memory:
  mode: orkmind
  tenant: orkastery
  database_url_file: "~/.orkastery/segredos/orkastery.dsn"

ork memory status

Search by meaning

Tag search remains the deterministic path: it builds the prompt, recall and handoff. Search by meaning is a separate surface that finds paraphrases that tags and exact words miss. Every result is marked deterministico: false, and nothing semantic enters the prompt on its own.

It stays off until the manifest declares the memory.embedding block, with provider, model, dimension and the name of the key variable, never its value. The vector index is local, derived from the tenant and kept out of git; reindexing unchanged content embeds nothing. Indexed text and every query go to the configured provider: use a dedicated key with a credit limit. The token and cost estimate is not an invoice. Without embeddings, the reason is embeddings.*, and the orkmind regime and tag recall stay the same.

The index, the vectors, FTS and ork memory status use the same search universe: the tenant’s active entries in the collections of ork, minus those the library flags with injection_risk. An entry from another tenant or collection is a typed failure (memory.query.scope-violation), never a silent drop, and is not embedded. When the read window fills up, the answer is memory.query.window-saturated instead of truncating, and ork memory index exits 1 without embedding anything.

status and index show the universe per collection and count, as numbers only, what stays out of search: entries flagged injection_risk, expired ones and those in other collections, such as session and semantic_log. Coverage compares the vectors with that universe; the reindex warning appears only when reindexing helps, and entries left out of the index by design are counted separately.

ork memory status --sondar
ork memory index --dry-run --json
ork memory index
ork memory search --texto "trocar de conta quando acaba a cota" --json