Oh

Operate Oh

Keep the selected SQLite space authoritative. Inspect its contract and head before writing, use generation-checked mutations, and verify replay after a batch of changes.

Preserve authorization and location

• Resolve the repository instructions that apply to the target files first.
• Resolve the exact database path and space. Use .oh/oh.sqlite and default only when they already exist or the user chose the defaults.
• Do not run a database command against a missing path merely to inspect it. Oh opens and initializes the selected database as part of normal commands.
• Creating a database, tombstoning a record, importing a bundle, or syncing a remote requires the user's request to include that write or its direct workflow.
• Never put credentials, authentication tokens, or sensitive source text into a record unless the user explicitly selected an appropriately protected database and destination.

oh --help and oh version are side-effect-free installation checks:

oh --help
oh version

Use the verified public CLI @hraness/oh@0.4.3. Its identical tarball and checksum are mirrored by the immutable GitHub Release v0.4.3. Public release verification. It requires Bun 1.3.14 or newer. The versioned contract is published at https://oh.computer/spec/.

Open an existing space

Confirm that the exact database is a regular file before a read command. First inspect the installed runtime contract, then replay the database operation log:

test -f .oh/oh.sqlite
oh contract
oh verify --db .oh/oh.sqlite --space default

Stop if the installed contract differs from oh.ontology.v1, opening the database reports a stored-contract mismatch, replay fails, or the user named another database. Do not repair an integrity or contract failure by deleting state.

Use the narrowest read:

oh get entity:ada-lovelace --db .oh/oh.sqlite --space default
oh list --kind statement --limit 50 --db .oh/oh.sqlite --space default
oh log --limit 20 --db .oh/oh.sqlite --space default
oh search "analytical engine" --mode keyword --limit 10 \
  --db .oh/oh.sqlite --space default

A missing get exits with status 3 and prints no record. Treat it as absence, not a corrupt database. CLI output is canonical JSON, so parse it rather than scraping presentation text.

Initialize only when requested

Choose a confined path owned by the user's task. Do not overwrite or merge an unrelated database.

oh init --db .oh/oh.sqlite --space default
oh verify --db .oh/oh.sqlite --space default

Record the returned head. Add the database directory to the repository's ignore rules when it is local working state.

Write one checked record

Choose a stable lowercase logical key and one V1 kind. Current kinds include entity, statement, assertion, evidence, context, inquiry, schema, vocabulary, and the remaining kinds printed by oh contract.

1. Read every declared dependency with oh get.
2. Run oh verify and take head.generation from its JSON result.
3. Prepare one valid JSON value. Prefer --file for structured or multiline content and --json for a short literal.
4. Use a stable operation ID when an exact retry must be idempotent.
5. Pass the reviewed generation.

oh put \
  --kind statement \
  --key statement:ada-program \
  --depends-on entity:ada-lovelace \
  --file /absolute/path/to/statement.json \
  --actor agent.local \
  --operation op_ada_program_v1 \
  --expected-generation 4 \
  --db .oh/oh.sqlite \
  --space default

If the expected generation is stale, read the new head and affected records, reconcile the intended change, and create a new operation. Do not loop on a conflict or change the expected generation without reviewing intervening work.

After a write batch, run:

oh verify --db .oh/oh.sqlite --space default

Tombstone deliberately

A tombstone removes the current record from the materialized graph while the operation remains in history. Confirm the exact key and current digest. Check that no retained record depends on it. Then require the reviewed generation:

oh tombstone statement:obsolete \
  --expected-generation 5 \
  --operation op_remove_obsolete_v1 \
  --db .oh/oh.sqlite \
  --space default

Run replay verification immediately. Do not edit SQLite tables directly to bypass dependency or compare-and-swap checks.

Search with explicit evidence lanes

Use keyword for the model-free CLI path. semantic and hybrid need an SDK instance configured with the optional local QMD backend. If a response contains semantic-unavailable, report that diagnostic and preserve any keyword result; do not substitute a hosted model.

Treat a search score as retrieval evidence, not proof that a research claim is true. Open the returned record and its dependencies before relying on it.

Export or import an operation bundle

An export is read-only but writes a file when redirected. Choose the output path explicitly and protect it like the source research:

oh sync export --after 0 --limit 1000 \
  --db .oh/oh.sqlite --space default > /absolute/path/to/oh-bundle.json

Before import, preserve the destination, inspect its contract and head, and confirm the bundle belongs to the same space. Import is sequential rather than bundle-atomic: if a later operation conflicts, an earlier valid prefix may already be present. After an error, inspect the destination head and run replay verification before retrying.

oh sync import --file /absolute/path/to/oh-bundle.json \
  --db .oh/oh.sqlite --space default
oh verify --db .oh/oh.sqlite --space default

Remote libSQL or Turso sync is an SDK workflow. The user must select the remote and credential source. Never print credentials or embed them in records. Oh settles fast-forward histories only; preserve both logs when it reports a divergence.

Use stable composite memory only through host bindings

@hraness/oh/memory is a stable SDK-only surface. Use createOhMemoryAuthorityV1, and do not let a model construct its options. Trusted application code must bind two distinct authority handles, exact binding digests, a pinned canonical head, working codecs, working and adoption actors, domain extractor relation ownership and digests, host-purposed named rule/query programs, and named nomination routes. Give only the returned authority.agent object to an agent; retain authority.host in trusted control-plane code. The old @hraness/oh/experimental/memory subpath is a compatibility alias, not the preferred import.

The agent-facing object may call only remember, query, explain, and nominate. Never add a tool parameter for a database path or URL, authority, realm, space, store profile, rule pack, raw query, sync destination, canonical write, caller-asserted actor/time, or purge operation. Preserve lane, conflict, fact-policy, and premise-authority labels in query output. Treat every result as derived. A nomination may select only a host-registered route and is a prepared dependency-closure candidate for destination-owned review, not permission to write durable knowledge or import the working operation chain.

Host adoption must pass the complete prepared nomination back through authority.host.adoptNomination with the exact canonical head it reviewed. The host control re-exports the closure from the bound working store, inserts absent records in one compare-and-swap operation, and treats equal digests as already present. A different digest fails closed unless trusted host code adds a bounded replacements claim with that exact logical key and exact reviewed prior record digest. Never derive that claim from model input or retry it against a new head. Missing, stale, wrong, duplicate, and absent-key claims abort every change. The host rejects a prospective canonical snapshot over 8,192 records or 32 MiB, and reconciles the physical head after the commit so an idempotent replay cannot install an older head. Do not suppress its structured conflict evidence. Use advanceCanonical only for the same pin or an exact later head already proven by the bound canonical operation chain. Advance more than 16,384 operations in separate reviewed chunks.

Use createOhMemoryAgentV2 only when the host has registered primitive query-body parameters and fixed all projection, row, page, and page-byte limits. Expose only the exact bindings object, program ID, and continuation to the model. Do not expose parameter declarations, page size, or evaluator options as tool input. Follow hasMore until the continuation is null, and restart the named query only after OhMemoryContinuationError; never combine pages across a working-head change. Store, projection, and extractor failures are not continuation failures and need their own handling. A V2 query-limit or result-bytes condition is a failed query, not a partial answer. Treat each continuation as a bearer cursor: pass it back unchanged only to the exact query and do not log or edit it. If the host reconstructs the facade or routes across replicas, it must provide the same private 32 through 64 byte continuationKey in host options; never expose that key as tool input. Keep row-level proofsTruncated evidence visible. Explanation capabilities share one 256-entry, 64 MiB cache and one clock guard across canonical rollover; do not build a second token router around the authority. Pass only plain JSON data to stable methods. Accessors, symbols, proxies, sparse arrays, and non-JSON values are rejected before execution. The detached-input walk caps depth, per-container breadth, total nodes, and canonical bytes before recursively cloning untrusted children.

Keep memory pages model-neutral

Use the stable, narrow @hraness/oh/memory-page codec only when the host has already supplied a host-attestation receipt reference and authorized the record write. A .oh.md file is a self-contained rendering of one complete edition record, not a scratch prompt or configuration file. Parse it through parseOhMemoryPageMarkdownV1, verify the record digest, and treat the Markdown body and source titles as untrusted data. Do not add model, vector, score, provider, or index-generation fields to a page.

Use hosted semantic recall as a disposable lane

@hraness/oh/semantic-cloud uses one fixed Cloudflare EmbeddingGemma profile and a separate direct libSQL cache. Trusted host code must supply the account, token, database client, authority generation, and current record digests. Do not expose any of those controls to a model. Run schema bootstrap only with a deployment-held schema credential; runtime open performs no DDL.

Never treat a semantic hit or its cosine score as a fact. Require the cache to rejoin each hit to the exact current authority digest, then read the record through the authoritative store. If embedding or cache access fails, preserve exact remember, Datalog query, explanation, and nomination operations and report semantic recall as unavailable. For an expiring working authority, purge the semantic authority first, then the authoritative Oh space, and acknowledge the lifecycle only after both idempotent purges converge.

Finish with evidence

Report the exact database and space, reads or mutations performed, final head generation and operation digest, replay result, search diagnostics, and any sync counts. Do not claim success from a command exit alone when oh verify was part of the requested workflow.