open-source tools for agentic research

Oh is a local-first ontology kernel, SQLite store, CLI, TypeScript SDK, and Agent Skill for building durable, inspectable research graphs. It stores content-addressed records and an append-only operation log, checks every mutation against an explicit versioned contract, and keeps keyword and semantic indexes derived and replaceable.

Website · Versioned specification · Agent Skill

Why Oh

• Make meaning explicit. Every record declares a kind, stable logical key, ordered dependencies, and canonical JSON content under a versioned ontology and schema contract.
• Keep changes accountable. Content digests, append-only operations, compare-and-swap writes, and replay verification make accepted graph changes inspectable and stale writes visible.
• Keep local state authoritative. Records and operations live in one SQLite file you control. Sync is an explicit transport seam and accepts only fast-forward histories after an exact contract handshake.
• Treat search as a view. FTS5 documents and optional local embeddings are derived from current record digests, so either index can be rebuilt without becoming graph authority.

Install and first run

Bun 1.3.14 or newer is required. Install the current immutable release directly from GitHub:

bun add --global github:hraness/oh#v0.1.1
oh --help

Oh writes to .oh/oh.sqlite and the default space unless you select another path or space. Keep .oh/ out of source control.

oh init
oh put \
  --kind entity \
  --key entity:ada-lovelace \
  --json '{"name":"Ada Lovelace","role":"mathematician"}'
oh get entity:ada-lovelace
oh search "mathematician" --mode keyword
oh verify

This first task creates one entity, reads it back, finds it through the derived keyword index, and verifies the authoritative operation chain. It needs no account, hosted model, remote database, or semantic-search dependency.

What becomes observable

Commands print canonical JSON, except oh version and help. A missing oh get record exits with status 3. Invalid input, an integrity failure, or a concurrent head conflict exits with status 1 and leaves the current log intact.

Run oh contract to inspect the ontology, graph, schema, and SQLite versions compiled into the installed runtime. Opening an Oh database separately checks that its stored contract manifest matches that runtime.

How Oh works

An Oh space has one current graph and one append-only operation chain:

• A record has a stable logical key, one declared kind, ordered dependencies, arbitrary canonical JSON content, and a SHA-256 digest over its envelope.
• A mutation puts or tombstones records in one BEGIN IMMEDIATE transaction. Compare-and-swap checks reject a stale generation before the head moves.
• Every operation binds the parent operation, graph revision, complete record set, contract, actor, timestamp, and sequence to a digest.
• SQLite records and the operation log are authoritative. FTS5 documents and local embedding files can be deleted and rebuilt.
• Sync exchanges bounded operation bundles after an exact contract handshake. Only fast-forward histories settle automatically; divergence fails closed.

The V1 kernel distinguishes seven ideas: entity, statement, assertion, evidence, context, inquiry, and projection. The generic graph envelope also supports schema, vocabulary, review, rights, edition, and activity records. Product-specific meaning belongs in registered codecs and versioned schema records, not in hidden storage conventions.

Use the SDK

For a project dependency, pin the same immutable release in package.json:

{
  "dependencies": {
    "@hraness/oh": "github:hraness/oh#v0.1.1"
  }
}

The base package has no required runtime dependencies. Keyword search, ontology parsing, SQLite storage, replay verification, and sync need no hosted model.

import { Oh } from "@hraness/oh/sdk";

const oh = Oh.open({
  databasePath: ".oh/research.sqlite",
  spaceId: "paper-one",
});

try {
  const head = oh.head();
  oh.put({
    expectedHead: head,
    key: "entity:ada-lovelace",
    kind: "entity",
    value: { name: "Ada Lovelace" },
  });

  const result = await oh.search("Ada", { mode: "keyword" });
  console.log(result.results[0]?.record);
  console.log(oh.verify());
} finally {
  await oh.close();
}

Pass the head you actually reviewed when concurrent writers matter. Do not retry OhConflictError blindly. Read the new head and records, reconcile the intended change, then submit a new operation.

The root entrypoint exports canonical JSON, ontology, schema, graph, operation, and sync contracts. Use @hraness/oh/sqlite for the local store, @hraness/oh/sdk for the Oh facade, @hraness/oh/sync for transport seams, and @hraness/oh/semantic for the optional local embedding backend.

Add local semantic search

Semantic state is a cache. Each QMD result is rejoined to the current SQLite record by exact record digest before Oh returns it.

bun add @tobilu/qmd@2.5.3

import { Oh } from "@hraness/oh/sdk";
import { OhQmdSemanticBackendV1 } from "@hraness/oh/semantic";

const backend = new OhQmdSemanticBackendV1({
  cacheDirectory: ".oh/semantic",
});
const oh = Oh.open({ semanticBackend: backend });

try {
  await oh.indexSemantic();
  const result = await oh.search("early programmable machines", {
    mode: "hybrid",
  });
  console.log(result.results);
} finally {
  await oh.close();
}

The exact V1 profile is documented in the embedding specification. The model download and all inference stay local. Keyword mode remains available when QMD or the model is absent.

Sync through libSQL or Turso

createLibSqlOperationSyncTransportV1 accepts the execute and batch shape implemented by libSQL clients. Oh creates two remote tables for the contract manifest and immutable operation chain. It does not send semantic cache files.

bun add @libsql/client@^0.17.4

import { createClient } from "@libsql/client";
import { Oh } from "@hraness/oh/sdk";
import { createLibSqlOperationSyncTransportV1 } from "@hraness/oh/sync";

const client = createClient({ url: process.env.TURSO_DATABASE_URL! });
const oh = Oh.open();

try {
  const transport = createLibSqlOperationSyncTransportV1(client);
  const result = await oh.sync(transport, { remoteId: "research-cloud" });
  console.log(result);
} finally {
  await oh.close();
  client.close();
}

The consumer owns credentials, client construction, retry policy, and remote availability. The transport handshakes before exchanging data and refuses a different contract or a non-fast-forward history.

For offline transfer, oh sync export writes a bounded bundle to stdout and oh sync import --file <path> verifies and imports it idempotently.

Boundaries and limitations

• Digests detect changed contract, record, operation, and bundle bytes. They do not encrypt data, authenticate an actor, authorize a write, or prove that a research statement is true.
• Oh does not redact record values. Protect the database, filesystem, backups, and any sync destination according to the sensitivity of the research graph.
• The optional QMD cache contains derived record text. Its pinned model and inference stay local, but the cache still needs the same deliberate handling as its source data.
• The libSQL seam validates exact contracts and fast-forward history. The consumer remains responsible for credentials, transport security, access control, tenant isolation, backup, retry, and remote availability.
• Divergent histories do not merge automatically. Oh returns an explicit conflict and leaves reconciliation policy to the consumer.

Read SECURITY.md for the complete public threat model.

Give Oh to a coding agent

The repository includes an installable Agent Skill at skills/oh. Copy or link that directory into the skill location used by your agent runner. The skill teaches an agent to inspect the contract and current head, use generation-checked writes, verify replay, and keep remote sync explicit.

You can also give an agent this prompt:

Install hraness/oh and its Oh Agent Skill from the immutable v0.1.1 tag at
https://github.com/hraness/oh. Verify the CLI with `oh --help` and `oh version`.
Do not create or modify an Oh database until I name its path and ask you to.

Find the right documentation

• Install and prove the local path: follow Install and first run.
• Embed Oh in a tool: use the SDK, then select the narrow package subpath for SQLite, sync, or optional semantics.
• Give Oh to an agent: install the Oh Agent Skill and keep its database, space, sync target, and mutation authority explicit.
• Implement or change a contract: begin with the specification map, then read the applicable V1 narrative and machine-readable schema together.
• Contribute or report a vulnerability: follow CONTRIBUTING.md or the private process in SECURITY.md.

Specification

spec/manifest.json is the machine-readable discovery document. The current contract is V1:

• Canonical JSON and digests
• Ontology
• Schema evolution
• Graph and operations
• SQLite storage
• Sync protocol
• Local embedding profile
• Compatibility and migration

The JSON Schemas describe exchange envelopes. Runtime parsers additionally enforce canonical ordering, byte limits, referential integrity, and digest preimages that JSON Schema cannot express.

Verify a checkout

bun install --frozen-lockfile --ignore-scripts
bun run check

The complete gate type-checks the package, runs the complete test suite, rebuilds the committed dist/ entrypoints, and must leave tracked files unchanged.

Contribute

Read CONTRIBUTING.md before changing a wire contract or migration. Report security issues through the private process in SECURITY.md.

Oh is available under the MIT License.