Native Knowledge owner

Start with AKF, evidence and determinism for the knowledge lifecycle, portability evidence and workflow explanation.

mnemos knowledge reads signed AKF v2 snapshots without opening a Context database or starting the assistant loop. PRISM's prism-mem knowledge facade forwards the same protocol. The owner is a filesystem service inside the existing executable; it does not require a daemon, scheduler, model, or SQLite database. The executable also contains other features that use SQLite.

For a smaller owner-only executable, first use an unstable source checkout containing the linked build target below; main does not contain that target. From that checkout's kernel/, run ./scripts/zb knowledge-only -Doptimize=ReleaseSafe. This opt-in step installs zig-out/bin/mnemos-knowledge without changing the normal full build. Invoke it with the same argument shape, for example mnemos-knowledge knowledge status --json --config /absolute/brains.kdl. It delegates to the same knowledge CLI and rejects other top-level surfaces. The knowledge-only build target is defined in that source revision.

mnemos knowledge status --json --config /absolute/brains.kdl
mnemos knowledge get --json --config /absolute/brains.kdl

Send one v1 JSON request on stdin. Configuration is selected only through the CLI:

{"schema_version":1,"operation":"get","request_id":"lookup-1","scope":{"realm_id":"local","namespace":"project","project_id":"demo","context_scopes":[],"join_id":null,"disclosure":"private"},"input":{"brain":"main","path":"knowledge/answer.md","max_bytes":8192}}

Success returns {schema_version,request_id,ok,data,error}. Every knowledge result includes domain:"knowledge", operation, brain, the requested authorized scope, bundle ID/revision, exact blake3: manifest digest, and authentication:"verified". Pages carry full bodies, effective disclosure scope, page ID/revision and exact bundle/page/path/digest citations. Status reports the registered snapshot's page count. A signed snapshot is not evidence that it is the latest published head.

Only project scope is supported. Context joins and nonempty context scopes are rejected. A non-null session restriction is rejected because curated knowledge has no operational session provenance. There is no fallback to another brain, project, revision, database, or broader disclosure.

Availability

This reference describes the implemented Knowledge owner on JARVIS unstable. Website publication does not promote that runtime to main. Check the installed binary's knowledge help; an older download may not expose this interface.

Register an immutable signed snapshot

The operator places an AKF snapshot at /srv/brains/demo/revisions/r1 and supplies an independently trusted public key and digest in a separate KDL file. The snapshot must have valid manifest membership, exact page and metadata bytes, sources/history closure, and at least one trusted Ed25519 manifest signature. Unsigned, unknown, expired, or revoked signing keys fail authentication. Integrity checks alone never authenticate a snapshot.

principal "operator"
brain {
  alias "main"
  store_root "/srv/brains"
  bundle_id "demo"
  revision "r1"
  manifest_digest "blake3:REPLACE_WITH_64_LOWERCASE_HEX_DIGITS"
  realm "local"
  project "demo"
  disclosure "private"
  namespace "knowledge"
  authority "sovereign"
  operation "revise"
  ranking "lexical"
  max_context_bytes "8192"
  startup_reserved_bytes "2048"
  transfer_root "/srv/transfers"
  audience "recipient"
  may_export "true"
}
signer {
  key_id "ownerkey"
  principal_id "operator"
  public_key_hex "REPLACE_WITH_64_LOWERCASE_HEX_DIGITS"
  may_approve "true"
  expires_at "2000000000"
}

The placeholders are deliberately invalid: substitute independently verified actual values. manifest_digest hashes the exact canonical _integrity/manifest.json bytes. Never copy trust policy or approvals out of untrusted bundle text. Signatures attest manifest bytes using the existing AKF-SIGNED-MANIFEST-V2\n domain. The historical signer field may_approve defaults to false and must be explicitly set to "true" to permit manifest-signature verification or use that key to verify an operation-bound approval. This key-verification permission alone does not grant publication authority: the separate operation grants and signed approval intent still apply.

KDL uses the same bounded restricted parser as Context policy: quoted leaf values, child blocks, comments and semicolons/newlines, maximum 64 KiB. Unknown fields, duplicate fields/brain aliases/signing key IDs, malformed enums/integers/booleans/hex and noncanonical absolute paths are rejected. Root paths and their components must not be symlinks. Grants and principals remain local operator authority.

Retrieval and transfer

Operation	Input in addition to brain
status	none
get	path, optional max_bytes (default 65536)
search	query, optional max_bytes/max_items (16384/20)
pack	objective, optional max_bytes/max_items (16384/20)
export, import	destination
propose, publish	revision, base_revision

The operator selects ranking "legacy" or ranking "lexical" per brain in KDL. An omitted field defaults to legacy for existing configurations. Unknown ranking values, including model or menu names, fail policy parsing; requests cannot choose a mode. The example above enables lexical ranking explicitly. max_context_bytes defaults to 65536 and must be 1–65536. startup_reserved_bytes defaults to 0 and must be less than max_context_bytes; both are operator-only settings. The effective retrieval wire limit for one get, search, or pack packet is the smaller of the request's max_bytes and max_context_bytes - startup_reserved_bytes. For example, 8192 total with 2048 reserved permits at most 6144 retrieved response bytes. The caller cannot enlarge that limit. These settings budget startup plus one retrieved packet per assembly; they do not cap an entire multi-turn chat or measure the startup hook themselves.

Legacy search and pack retain deterministic substring matching over page bodies and paths: queries are split on ASCII space/tab/CR/LF and the punctuation .,:;!?()[]{}", and any nonempty query token may match anywhere in the candidate text. Comparison folds ASCII case only; non-ASCII UTF-8 bytes are compared exactly. Results use OR semantics and preserve canonical manifest order. For example, legacy cat matches concatenate.

Lexical search and pack use whole query tokens against whole tokens in page bodies, paths and a title derived from the first matching ATX-style line in the authenticated page body. The bounded line heuristic scans at most the first 4 KiB and accepts one to six # markers after at most three leading spaces. If the complete trimmed heading exceeds 256 UTF-8 bytes, its title is empty; it is never truncated into a partial lexical token. It is not a full Markdown parser: a matching # line inside a fenced code block may count as a title. A page without a matching line has an empty title. The title only affects ranking; the page body, citation, and metadata stay unchanged. ASCII letters are case folded; non-ASCII UTF-8 letters compare exactly, without Unicode normalization. The tokenizer recognizes an explicit bounded set of Unicode punctuation and spaces as word separators, including smart quotes, em dashes, ideographic commas and nonbreaking spaces; Japanese iteration marks, numerals and combining marks remain token content. It does not implement every Unicode category. C#, .NET and internal hyphens remain part of a token, so C does not match C#, NET does not match .NET, and cat does not match concatenate. A bounded set of up to 64 distinct query tokens is scored. Common question words have low weight; when a query has a substantive term, a page must match at least one such term. Terms found in fewer eligible pages weigh more, while title, path and adjacent substantive query terms receive deterministic boosts. Equal scores keep manifest order. This is a local lexical rule, with no embeddings, models, external calls or learned index.

Both modes exclude navigation, source and history documents from page results. Each page is checked against the authenticated manifest and projected through its disclosure and provenance rules before lexical scoring; denied pages never enter the ranker. Ranking precedes max_items and max_bytes, but does not change manifest serialization. Exact get uses its requested pinned path and bypasses ranking. Page text remains data and cannot direct execution.

Requests and responses are limited to 1 MiB. Retrieval max_bytes and the operator limit bound the entire serialized response including its newline, not just page text; maximum 65536. max_items is 1–100. Pages are returned whole. Pack/search disclose omitted candidates through omissions.items and reason:"budget_or_scope"; get returns a budget error when its whole page cannot fit. A page that does not match is not counted as a budget omission. Source/history omissions in transfer are reported separately.

Transfer always copies the pinned registered revision into a fresh directory under transfer_root; destination is a simple identifier, not a path. Both export and import use the same signed quarantine verification and no-replace rename. may_export, recipient audience and disclosure policy must be configured. The externally pinned digest is checked before any destination publication. Existing destinations are never overlaid. Operational Context and caches are not portable knowledge.

To use a transferred directory in a fresh environment, arrange the destination as that environment's <store_root>/<bundle_id>/revisions/<revision> slot, then register it in recipient-owned KDL with the same ID, revision, digest and independently trusted signer. Importing content creates no publication or execution grants. No source Context database is needed.

Proposal and ASM publication

A candidate is a complete rendered, signed AKF snapshot already staged at <store_root>/<bundle_id>/staging/<revision>. A JSON request selects only its revision and expected base. It cannot provide root paths, keys, principal, authority, grants or approvals. base_revision:"" bootstraps an empty store. The registered read revision need not exist during bootstrap publication.

A proposal validates and authenticates the candidate and checks the local proposal grant against the current authenticated head and candidate parent. Its response contains candidate_revision, base_revision, candidate_digest, and outcome:"proposed". This is a candidate receipt; it does not change the head or publish anything.

Publication uses the existing durable ASM store commit, with its exclusive bundle lock, immutable revision, receipt, and atomic head update. It reloads the named KDL file and real current time under the lock, rechecks routing, actor, grants, revocations, and operation-bound approvals. Exact replays can return already_committed; changed policy can deny even a replay. Stale parents and approvals fail closed. No request field can bypass ASM.

Example actor and independent human approval grants:

grant {
  principal_id "operator"
  namespace "knowledge"
  scope "private"
  operation "revise"
  authority "sovereign"
  may_propose "true"
  may_publish "true"
}
signer {
  key_id "reviewerkey"
  principal_id "reviewer"
  public_key_hex "REPLACE_WITH_64_LOWERCASE_HEX_DIGITS"
  may_approve "true"
  expires_at "2000000000"
}
grant {
  principal_id "reviewer"
  key_id "reviewerkey"
  namespace "knowledge"
  scope "private"
  operation "revise"
  authority "sovereign"
  human "true"
  may_approve "true"
}
approval {
  principal_id "reviewer"
  key_id "reviewerkey"
  manifest_digest "blake3:REPLACE_WITH_EXACT_CANDIDATE_DIGEST"
  namespace "knowledge"
  scope "private"
  operation "revise"
  base_revision "r1"
  authority "sovereign"
  expires_at "2000000000"
  signature_hex "REPLACE_WITH_128_LOWERCASE_HEX_DIGITS"
}

Approval signatures are Ed25519 over AKF-OWNER-APPROVAL-V1\n followed by compact JSON, in this exact field order:

{"principal_id":"reviewer","key_id":"reviewerkey","manifest_digest":"blake3:...","namespace":"knowledge","scope":"private","operation":"revise","base_revision":"r1","authority":"sovereign","expires_at":2000000000}

expires_at is a JSON integer; other values are strings. knowledge/config.zig:approvalMessage is the canonical encoder at the cited source revision. The approval authenticates the key/principal binding, exact digest, namespace, scope, operation, base and authority. Optional revoked_at is an external local policy cutoff. Snapshot signatures are never converted into approvals. Sovereign authority requires a distinct human approver. Consensus uses distinct principals and the top-level consensus_threshold (default 2, minimum 2). Self approval is disabled. Existing stronger page/history authority cannot be reduced by a weaker requested target.

An active approval with an unknown key, an untrusted key/principal binding, or an invalid signature invalidates the publication policy for the entire KDL file: all propose/publish operations using that file fail closed until the operator corrects or removes the bad approval. Such entries are not silently skipped. Expired or revoked approvals contribute no authority; malformed KDL or approval encodings reject the configuration itself.

All signer/grant/approval expiry and revocation comparisons use current Unix seconds, including the locked reload. KDL contains public keys and signatures only; signing private keys do not belong in JSON requests or bundles.

Exit codes are 0 success, 2 invalid/unsupported/budget, 3 denied/approval required, and 4 unavailable/authentication/integrity/conflict. Error details are fixed diagnostics and never include bundle contents or local root paths. Scheduling, retention, live model activation and installed client integration are outside this owner surface.