dreambaku

DreamBaku — baku CLI

DreamBaku is an offline-first developer memory system. It stores durable facts as canonical Markdown and builds a replaceable local PGlite index for hybrid recall: vector, tsvector, NFC literal, and exact slug/alias channels fused with RRF.

• Current architecture
• Testing architecture
• Deferred work
• Detailed init flow

Availability

DreamBaku 0.0.2 publication uses a human-authorized workflow. Verify live registry availability before any registry install:

npm view dreambaku@0.0.2 version --registry=https://registry.npmjs.org/

The command must return exactly 0.0.2; the public npm registry is the availability authority. The 0.0.0-reserved version is only a name reservation, not this CLI. The package name is dreambaku, and its installed executable is baku; npx dreambaku is not the supported release contract.

Release readiness is candidate-specific: a clean HEAD, tarball SRI, and all seven evidence lanes must agree in a fresh aggregate READY verdict. READY does not authorize publication. Registry installs must follow the versioned external-consumer policy below; a plain unqualified global install is not the release contract. Before registry availability is confirmed, install only from a reviewed checkout or an exact reviewed local tarball.

npx baku resolves an unrelated third-party package. It is never a DreamBaku invocation.

Declared release envelope

Runtime / platform	Current truth
Node.js 22 and 24	Accepted by package.json; Story 9.2's exact-candidate Linux x86_64 glibc jobs were green on both versions. Every later candidate must repeat the matrix.
Linux x86_64, glibc, ext-family local filesystem	Story 9.2's exact-candidate packed install, runtime, real-capability, performance, and uninstall evidence was READY. Evidence does not transfer to a later HEAD or tarball SRI.
musl/Alpine, ARM64, macOS, Windows	Unsupported until platform-specific evidence exists.
Remote, virtual, volatile, or unknown filesystems	No durability-positive claim; private-root and DB mutation paths refuse unsupported storage.
Standalone executable	Not shipped. The only release target is the npm package running on Node.js.

Install from a reviewed checkout

Checkout package.json pins onnxruntime-node@1.27.0, global-agent@4.1.3, and adm-zip@0.6.0 via overrides (applied by npm ci). Prefer linking the built CLI from that tree rather than a bare global install of . (which is not the consumer release contract and may re-resolve older transitive pins):

git clone https://github.com/FuzzyKala/dreambaku.git
cd dreambaku
npm ci
npm run build
npm link
baku --version
baku --help

On npm 10.0.0 through 11.15.x, npm ci / npm link still work; the strict consumer allowScripts flags apply only to the external-consumer policy below. npm below 10 is unsupported.

npm link and a checkout install are for local development only — they are not release evidence.

To test an exact local artifact instead, build and pack first, review the reported filename/integrity, then install that exact .tgz path into an isolated prefix. The repository-owned npm run test:release:npm lane automates this process without publishing.

External consumer install-script policy

Install policy belongs to the consumer root; a dependency's allowScripts and overrides do not transfer downstream. With npm 11.16.0 or newer, an external prefix consumer must use this exact root policy:

{
  "name": "dreambaku-consumer",
  "private": true,
  "overrides": {
    "onnxruntime-node": "1.27.0",
    "global-agent": "4.1.3",
    "adm-zip": "0.6.0"
  },
  "allowScripts": {
    "onnxruntime-node@1.27.0": true,
    "protobufjs@7.6.5": true,
    "sharp@0.34.5": true
  }
}

The overrides force onnxruntime-node@1.27.0 and global-agent@4.1.3 so the deprecated transitive boolean@3.2.0 path from the older onnxruntime-node@1.24.3 pin inside @huggingface/transformers@4.2.0 is not installed, and force adm-zip@0.6.0 so GHSA-xcpc-8h2w-3j85 (high) is not left on the onnxruntime-node ^0.5.16 range. That prefix install also uses --strict-allow-scripts and --dangerously-allow-all-scripts=false. A future global install of an exact reviewed tarball must apply the same install-root package.json overrides (and, on npm 11.16.0+, the same allowScripts plus --strict-allow-scripts / --dangerously-allow-all-scripts=false). npm only honors overrides on the install root — a bare npm install -g without a policy root still resolves the older onnxruntime-node@1.24.3 pin and is not the release contract. The release smoke materializes the documented $prefix/lib/node_modules + $prefix/bin layout from that policy root.

npm 10.0.0 through 11.15.x cannot enforce the allowScripts half of this policy and is an explicit unenforced compatibility fallback: do not pass those unsupported policy flags, and record that enforcement was unavailable. npm below 10 is unsupported and must be refused before installation. With the reviewed overrides applied, packed install evidence requires warningClean: true and zero boolean@* package identities; any remaining deprecation fails closed.

First Run

Interactive init offers exactly two recall choices:

1. semantic — recommended pinned local semantic recall; model acquisition requires review and exact consent;
2. keyword-only — immediate, healthy, zero-download recall.

baku init
baku health

For automation, create an effect-free plan, review its ID/digest, then apply that exact plan. Bare non-TTY init refuses instead of prompting.

baku init --plan --recall keyword-only --json
PLAN_ID='<plan-id from the reviewed JSON>'
PLAN_DIGEST='<sha256 digest from the reviewed JSON>'
baku init --apply --recall keyword-only --plan-id "$PLAN_ID" --approve "$PLAN_DIGEST" --json

Resolve, Plan, and Review do not write, download, spawn, or call a provider. Apply performs only the approved recoverable effects; Verify observes the result rather than hiding repair work. See the detailed init flow.

Command Catalog

README is the user-facing command-catalog SSOT. The table records the exact arguments and generated option tokens; constraints and defaults follow the token that owns them.

Command	Arguments	Options and defaults	Implemented behavior
baku	none	-V, --version -h, --help	Show the installed version or root help.
baku search	<query...>	-t, --top <n> (range 1-50; default: 5) --json -h, --help	Search active-project plus global memory.
baku index	none	--force-prune --approve <manifest-digest> --rebuild -h, --help	Bootstrap/reconcile derived state; rebuild stages a replacement, while large prune requires exact force-prune approval.
baku promote	<slug>	--apply --json -h, --help	Dry-run project-to-global promotion; --apply performs the reviewed copy.
baku consolidate	none	--run-id <id> --approve <digest> --save --review <proposal-id> --page <n> (default: 1) --revoke <digest> --json -h, --help	Preview, save, review, or revoke one complete active-project proposal.
baku consolidate apply	<proposal-id>	--approve <proposal-digest> (exactly once) --json -h, --help	Apply exact saved consolidation Markdown with durable crash recovery.
baku consolidate undo	<operation-id>	--approve <undo-approval-digest> (exactly once) --json -h, --help	Restore exact consolidation artifacts with durable crash recovery.
baku health	none	--json -h, --help	Inspect identity, config, corpus, DB, recall, operations, and optional consolidation readiness without mutation or download.
baku show	<slug-or-alias>	--json -h, --help	Return one full canonical memory by exact slug or lookup-only alias.
baku add	<name>	--description <text> (required) --type <type> (required: feedback, reference, project, or user) --body <text> or bounded stdin --scope <scope> (only project-only) --egress <policy> (only deny) --json -h, --help	Create one validated canonical memory in the active project tier.
baku init	none	--plan --apply --recall <mode> (semantic or keyword-only) --plan-id <id> --approve <digest> --json -h, --help	Resolve, plan, review, apply, and verify owner-local initialization.

There is no public compatibility alias for removed commands or options.

Output, Prompt, and Exit Contract

Contract	Exact public value
JSON base fields	schemaVersion: 1, ok, code, and present data
Optional JSON fields	status, warnings, recovery, operationId, proposalId only when meaningful
Streams	one newline-terminated JSON object on stdout; bounded progress/diagnostics on stderr; no JSONL stream
Prompting	human-capable TTY only; non-TTY, --json, or TERM=dumb never prompts
Exit classes	0, 1, 2, 3, 4, 5, 130, 143

ok is true if and only if the command exits 0. Exit 1 means a truthful not-initialized or degraded state; 2 means usage, configuration, or trust refusal; 3 means an unavailable external dependency/provider; 4 means an effect-free stale/CAS refusal; 5 means recovery, partial completion, or index-pending. SIGINT and SIGTERM map to 130 and 143. Human results use stdout. Animated progress requires a capable stderr TTY; nonempty NO_COLOR disables color and TERM=dumb disables rich/animated behavior.

Values such as verify-pinned-model-manifest inside a reviewed init plan are bounded plan-step identifiers, not CLI commands. Runnable recovery fields begin with baku and use only the command catalog above; state values such as retry or none are not shell commands.

Canonical Memory

The complete public corpus is:

memory/global/*.md
memory/projects/<project-id>/*.md

Canonical identity is (scope_id, slug). The active project and global tier may share a slug; active-project lookup wins. MEMORY.md and INDEX.md are pointer files, not corpus entries. Repository documents, arbitrary directories, agent-native folders, symlinks, and DB-only rows cannot become memory sources.

Each canonical file contains one fact, exact YAML frontmatter, and a nonempty body. The filename stem and name are the same 1–80-character lowercase ASCII kebab slug. Files are limited to 8,000 UTF-8 bytes. Direct invalid edits remain on disk but are excluded from indexing, consolidation, and egress.

Add, search, show, and promote

baku add stable-identifiers --type reference --description "Project identifier rule" --body "Use one stable identifier."
printf '%s\n' "One durable fact." | baku add team-note --type project --description "Team note"
baku search "stable identifier" --top 10
baku search "命名規範" --json
baku show stable-identifiers
baku promote stable-identifiers
baku promote stable-identifiers --apply

baku add writes only to the bound active project. Markdown commits before best-effort indexing; an indexing failure preserves the file and returns index-pending/exit 5 with baku index as recovery. baku show is DB-independent and returns full validated Markdown. Promotion copies bytes to global only after policy, secret/PII, containment, and canonical/alias collision checks; the project file remains.

Recall Modes

Keyword-only

Keyword-only is a healthy zero-download mode, not a degraded fake-vector mode. It combines:

• scoped PostgreSQL tsvector ranking over complete validated text;
• bounded NFC literal substring matching over the same text;
• exact canonical slug and lookup-only alias matching.

The literal channel preserves useful Traditional Chinese/CJK recall even when tokenization produces no hit. DreamBaku does not claim unsupported CJK tokenizer quality or performance beyond the measured current release profile.

Semantic

The one semantic identity is fixed:

runtime: @huggingface/transformers@4.2.0
model: Xenova/bge-m3
revision: b4489ca8cdd6791828a50de78a5089f8ccc6bf1b
dtype/dimensions/pooling/normalization: q8 / 1024 / CLS / L2
adapter contract: bge-m3-cls-l2-v1

A semantic init plan shows exact artifact paths, byte sizes, SHA-256 digests, approved hosts (huggingface.co, us.aws.cdn.hf.co, cas-bridge.xethub.hf.co), redirect/transport rules, and the storage floor. Acquisition begins only after digest-bound approval of that reviewed plan. Model downloads send no memory, query, or project identity.

Semantic recall becomes active only when the current model loads, the immutable identity and scope manifests match, and every eligible row is covered. Desired mode, cached files, a fingerprint, or 0/0 coverage alone never activates the vector channel. If selected semantic capability becomes unavailable, search keeps lexical/exact recall and reports the degraded semantic state honestly.

Effective Configuration and Owner Binding

Exactly one config source wins, without merging:

1. validated BAKU_CONFIG_JSON as a complete ephemeral replacement;
2. owner-private XDG config.toml;
3. strict defaults.

Repository config/dotenv and ambient provider variables do not activate behavior. Only owner-local PGlite and the pinned local embedding identity exist. Workspace path, marker, project ID, and git remote nominate a scope; the owner-private projects.json binding alone authorizes access. BAKU_ROOT selects workspace context and never relocates owner state.

Exact Accepted Configuration Shape

The provider blocks are strict local defaults. The recall and remoteConsolidation blocks are independently optional; when present, their keys and values are exactly the following:

[providers.db]
type = "pglite"

[providers.embed]
type = "local"

[recall]
desiredMode = "keyword-only"

[remoteConsolidation]
type = "openai-compatible"
baseURL = "https://example.invalid/v1/"
model = "model-name"
purpose = "remote-consolidation"

recall.desiredMode accepts exactly "semantic" or "keyword-only"; the example selects the zero-download mode.

Unknown keys and inline credentials are rejected. BAKU_LLM_API_KEY is the sole runtime credential source for optional remote consolidation; it is never a config field.

Linux defaults are:

~/.local/share/baku/  memory/, db/, operations/, projects.json
~/.config/baku/       config.toml
~/.cache/baku/        models/
~/.local/state/baku/  consent.json

Optional Remote Consolidation

Remote consolidation is the only memory-egress feature. It is optional: missing remote consolidation configuration does not degrade local recall. Running baku consolidate without it returns effect-free first-use guidance.

Add only non-secret intent to the owner XDG config:

[remoteConsolidation]
type = "openai-compatible"
baseURL = "https://<api-root>/v1"
model = "<model>"
purpose = "remote-consolidation"

Supply the credential only to the invocation environment as BAKU_LLM_API_KEY; never persist it in TOML or BAKU_CONFIG_JSON.

For the current 0.0.2 release-candidate evidence, the maintained reference lane uses the OpenAI-compatible Cerebras endpoint https://api.cerebras.ai/v1/ with gemma-4-31b. This is the recommended starting point for reproducing the release lane, not a bundled default, automatic fallback, or promise that every account tier will retain the same model, limits, price, or data policy. Review the provider's current terms and limits, keep the key runtime-only, and require DreamBaku's synthetic qualification to pass before any real memory is sent. Other OpenAI-compatible providers remain owner-selected and must pass the same qualification contract.

For candidate clusters, choose preview or saved-proposal mode before creating the plan. The first unapproved run remains effect-free and returns an exact egress plan, run ID, digest, disclosure, budget, and matching rerun command. The approved rerun records and spends exact consent once, qualifies the endpoint/model, then attempts only the authorized classification requests. Reusing the run ID/digest is refused as consent-grant-spent. Every transmission revalidates destination, scanner policy, current consent, payload, and budget immediately before the first network byte. Egress approval does not authorize Markdown mutation.

# For a read-only preview, omit --save from both commands instead.
baku consolidate --save
RUN_ID='<run-id from the egress plan>'
EGRESS_DIGEST='<egress-plan digest>'
baku consolidate --run-id "$RUN_ID" --approve "$EGRESS_DIGEST" --save
PROPOSAL_ID='<saved proposal id>'
PROPOSAL_DIGEST='<reviewed proposal digest>'
baku consolidate --review "$PROPOSAL_ID" --page 1
baku consolidate apply "$PROPOSAL_ID" --approve "$PROPOSAL_DIGEST"
OPERATION_ID='<completed operation id>'
UNDO_DIGEST='<reviewed undo-approval digest>'
baku consolidate undo "$OPERATION_ID" --approve "$UNDO_DIGEST"

The proposal accounts for every canonical active-project memory exactly once. It preserves unique, conflicting, distinct-context, invalid, and policy-excluded facts instead of forcing a target file count. Preview writes no state; --save creates one immutable owner-private proposal; review is bounded and read-only. Apply writes only the exact approved Markdown bytes and never reruns the remote model. Undo is operation-specific and refuses later-edit conflicts.

If Markdown apply/undo succeeds but derived reconciliation fails, the canonical change remains authoritative and the command returns index-pending/exit 5. Run the exact reported baku index recovery; never delete operation evidence or rewrite Markdown to satisfy the DB.

Data Preservation and Transfer

Authoritative/non-rebuildable Baku-owned state:

• canonical Markdown under memory/;
• owner project bindings in projects.json;
• saved proposals, journals, preimages, and archives under operations/.

Replaceable derived state

• PGlite under db/;
• verified model artifacts under models/;
• generated vectors, excerpts, and coverage metadata.

Operation bundles have no automatic expiry in 0.0.2. Preserve the authoritative state before moving machines. Transfer it using an owner-chosen secure method, then review/recreate the local config and consent you actually intend to keep, run baku index or the explicit reviewed baku index --rebuild, and inspect baku health. There is no generic backup, restore, migration, or cleanup command.

The current package has no uninstall cleanup hook and DreamBaku has no data deletion command. The exact-candidate uninstall lane has proved package removal, byte-identical preservation of all seven owner roots, reinstall, and rediscovery; the evidence must be rebound after any later tracked candidate/HEAD change.

Agent Use

DreamBaku is CLI-only and baku init does not edit agent settings, repository guidance, or native memory folders. Humans and agents may manually invoke the same authorized baku add, baku search, and baku show commands. There is no runtime agent detection, redirect, settings mutation, or managed agent integration in 0.0.2.

Maintainer Verification

Source-only benchmark and release harnesses are maintainer tools, not installed CLI commands. Their exact execution contract lives in TESTING.md. Ordinary tests are hermetic and do not download the real model or call a remote provider. Publication and release readiness remain separate explicit decisions.

License and Contributing

DreamBaku is Apache-2.0 licensed. See LICENSE and NOTICE. Contributions use DCO sign-off; see the repository contribution guide.