harness-memory

Trigger-aware project memory for Claude Code. harness-memory learns policies and pitfalls from your own sessions — a correction you typed, a command that failed and was then fixed — and surfaces them before the tool runs, at the PreToolUse boundary, instead of dumping a handbook into the system prompt.

It is complementary to claude-mem: claude-mem remembers what happened; harness-memory stops the agent at the moment it is about to repeat a known mistake. No account, no telemetry, no daemon, no LLM call per tool call — the hot path reads one precomputed JSON file.

0.6.0-rc.1 — Claude Code only. Codex hooks arrive in 0.6.1 and OpenCode (V2 plugin) in 0.6.2. v0.5 was an OpenCode plugin; read Upgrading from 0.5 before installing 0.6 over an existing .harness-memory/. Not on npm yet: install the pre-release tarball, see Install.

• How it works in one turn
• Requirements
• Install
• How memory is captured and saved
• The authority model
• What gets injected, when
• Embeddings (optional)
• Configuration
• CLI reference
• Troubleshooting
• Privacy and security
• Upgrading from 0.5
• Roadmap
• Development

How it works in one turn

you:     don't run `npm test` here, run `pnpm test` from packages/api
         └─ UserPromptSubmit hook: correction detected (the previous tool call failed) → ledger line
claude:  (fixes it, runs pnpm test) … Stop
         └─ Stop hook: closes the turn as an episode (evidence weight 2), writes queue/<id>.json,
            spawns the detached worker
worker:  your own `claude -p` (headless, no tools) extracts one fact:
         pitfall · signature bash/cmd "npm test" · scope packages/api → validated →
         active (authority auto, enforcement advise, TTL 30 d) → snapshot rebuilt
next session:
claude:  Bash: npm test
         └─ PreToolUse hook (≈ 50 ms, no SQLite): signature matches — `npm test`, `npm run test` and
            `& npm.cmd test` canonicalize the same way; `pnpm test` never matches it → additionalContext:
            "[harness-memory] PITFALL (auto, provisional): Run pnpm test from packages/api …"
            An auto rule is born at advise. When a second session confirms the correction it climbs to
            soft_deny, and the same call is denied: "… If this does not apply, call the tool again to proceed."
claude:  Bash: pnpm test

Three ideas carry the design:

1. Timing. Knowledge has four lifecycle triggers — session_start, before_model, before_tool, after_tool — and the one that matters most is before_tool: Claude Code's only pre-execution channel is permissionDecision: ask | deny, so every memory carries an enforcement level (advise, confirm, soft_deny, deny) that maps onto it.
2. Evidence is not memory. Hooks only append raw events to a per-session ledger. Memories are structured facts (type, scope glob, trigger signature, triggers, confidence, provenance) produced by one write path: episode → extraction → validation → deterministic reconcile.
3. Governed autonomy. The LLM extracts; authority stays explicit. A pitfall learned from one correction activates on its own (authority = auto, with a TTL and a lower trust multiplier). Human memories can never be demoted, superseded or rejected by the automatic path — it may only propose, and you decide in hm review.

Requirements

• Node.js ≥ 20 (developed on 24). Hooks are plain node processes; the worker runs SQLite through sql.js (WASM) — no native dependencies.
• Claude Code ≥ 2.1.139 for exec-form hooks ({"command": "<node>", "args": [...]}). Older versions get shell-form hooks automatically when claude --version can be detected; with no claude binary found the version is unknown and exec form is assumed — if Claude Code then reports a hook error on every call, re-run hm install --host claude --hook-form shell.
• An extraction CLI, logged in from a terminal, for learning: claude (preferred) or codex. Extraction runs through your own headless CLI and subscription — no API key. The login is optional for enforcement: the hooks fire every rule already in the snapshot (hm memory:add, imported rows) without it; turning new hm import bullets into typed rows and learning from your sessions — including what you ask it to remember — start after claude auth login (older CLIs: claude, then /login; the desktop app's login does not apply to claude -p). Until then bullets and episodes wait in the queue and nothing is lost.
• Windows, macOS, Linux. On Windows, Git Bash is optional (see below).

Install

Install the release candidate

0.6.0-rc.1 is not on npm yet: npm install -g harness-memory still installs 0.5.1, the OpenCode plugin, which has no hm binary. Install the tarball attached to the GitHub pre-release instead:

node --version                      # ≥ 20; with nvm, the version you will keep (nvm alias default <v>)
npm uninstall -g harness-memory     # removes a leftover 0.5.1; harmless when nothing is installed
npm install -g https://github.com/smc2315/harness-memory/releases/download/v0.6.0-rc.1/harness-memory-0.6.0-rc.1.tgz
hm --version                        # 0.6.0-rc.1
cd <your project>
hm install --host claude            # from a plain terminal, not from a shell inside a Claude Code session
hm status

• hm not found. The npm global prefix (npm prefix -g; Windows default %APPDATA%\npm) is not on PATH, or the terminal predates the Node install — open a new one. Meanwhile node "$(npm root -g)/harness-memory/dist/bin/harness-memory.js" --version works. harness-memory --version printing 0.5.1 means another Node's global directory wins: npm ls -g harness-memory under each Node.
• Windows PowerShell: hm.ps1 cannot be loaded because running scripts is disabled is npm's PowerShell shim under the default execution policy (npm's own npm.ps1 fails the same way). Once: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned, or run hm.cmd / use Git Bash. The hooks never use the shim: they run node.exe directly.
• Per project instead of global: npm install -D <same URL>, then npx hm install --host claude; the hooks then point at node_modules/harness-memory/dist/hook.js. Not npx harness-memory … while npm's latest is 0.5.1 (that runs the old plugin's install), and not from git (github:smc2315/harness-memory#redesign/v0.6 has no dist/; the build runs only in prepack).
• Later: npm install -g harness-memory@next once the rc is published under the next tag, plain harness-memory once 0.6.0 is latest. After any update run hm install --host claude again in each project: it migrates the database (backup first), replaces the hook entries, re-probes and re-runs the self-test. A global install keeps its hook path, so nothing breaks in between.
• Learning needs the claude CLI logged in from a terminal: claude auth login (older CLIs: claude, then /login). The desktop app's login does not count, and the desktop app alone puts no claude on your PATH — install the CLI; without it hm install reports provider none found and still succeeds. Enforcement of imported and hand-added rules works without the login; probe not_logged_in / queue N (waiting: not_logged_in) are expected until then, and hm install --host claude re-probes at once afterwards.
• Moving to another machine: nothing to copy. .harness-memory/ is per project and git-ignored, so a fresh clone starts empty; to carry memories, copy that project's memory.sqlite (and config.json) with Claude Code closed and run hm install --host claude there. Never copy .claude/settings.local.json or install-manifest.json: they hold the other machine's node and hook paths. Korean step-by-step checklist: docs/setup-new-machine.ko.md.

Abridged output of hm install --host claude on a new project:

harness-memory 0.6.0-rc.1 installed for Claude Code
  project     C:\src\my-app
  hooks       9 events → C:\src\my-app\.claude\settings.local.json (exec form)
  node        C:\Program Files\nodejs\node.exe  (claude 2.1.172)
  hook script C:\Users\me\AppData\Roaming\npm\node_modules\harness-memory\dist\hook.js
  database    C:\src\my-app\.harness-memory\memory.sqlite v22 (created)
  snapshot    built (active 0, candidates 0)
  config      C:\src\my-app\.harness-memory\config.json (created); embeddings off
  git         .claude/settings.local.json added to C:\src\my-app\.git\info\exclude
  git         C:\src\my-app\.harness-memory\.gitignore written (nothing under .harness-memory/ is ever committed)
  provider    claude — probe not_logged_in (Not logged in · Please run /login); the hooks enforce rules without the login — …; learning from sessions … starts after `claude auth login` …
  self-test   session-start ok (105ms, hook status ok)
  manifest    C:\src\my-app\.harness-memory\install-manifest.json
Open Claude Code in this project; `hm status` shows what the hooks learn.

A project that already has a v0.5 database shows v22 (migrated from v9, backup …\memory.sqlite.bak-v9) instead; read Upgrading from 0.5 first.

No restart is needed: Claude Code's file watcher picks up the new hook entries (if hm doctor → hooks.calls still says never after your first prompt, start a new session). Open the project in Claude Code, work normally, and watch hm status. If the project has a CLAUDE.md or AGENTS.md, the install output also suggests hm import --from CLAUDE.md, which turns its bullets into human memories after a confirmation table.

Claude Code's own auto memory (~/.claude/projects/<slug>/memory/, notes with type: feedback) is a second import source: hm import --from auto-memory turns those notes into human rules through the same confirmation table, so a correction Claude already wrote down starts being enforced at the tool boundary. The install output mentions it when such notes exist.

What hm install writes

Each registered hook is an exec-form command — the absolute Node binary that ran hm install plus the absolute dist/hook.js and the event name:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|PowerShell|Edit|MultiEdit|Write|NotebookEdit|WebFetch|mcp__.*",
        "hooks": [
          {
            "type": "command",
            "command": "C:\\Program Files\\nodejs\\node.exe",
            "args": ["C:\\...\\harness-memory\\dist\\hook.js", "pre-tool"],
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Read, Grep, Glob and Task are deliberately not registered on PreToolUse (no 50 ms process on the most frequent tools); a memory whose signature names one of them is re-labelled to before_model by the validator.

Node path, npx, and Windows shells

• Node path. Hooks record the exact node binary that ran hm install (process.execPath, resolved through symlinks and Windows junctions, so fnm, nvm-windows and Scoop links pin the real version) and the exact dist/hook.js of that package. That makes them immune to PATH, nvm and volta switches — but if that Node version goes away or the package moves, the hooks stop silently: brew upgrade node removes the old Cellar/node/<version> (install warns), nvm uninstall does the same, and a reinstall under pnpm / yarn / npx changes the path. hm doctor reports it (install.node, install.hook_script) and hm doctor --fix rewrites the entries to the current binary and script; with nvm, nvm alias default <v> before hm install keeps the pinned version around. The CLI itself needs node on PATH (hm is a #!/usr/bin/env node script); the hooks do not.
• npx, pnpm, yarn. Do not run npx harness-memory … while npm's latest is 0.5.1: it fetches the old OpenCode plugin and runs its install. pnpm and npx (and yarn when the package lands under .yarn/) keep one directory per version, so the registered dist/hook.js dies with the next upgrade (install warns; run hm install --host claude again afterwards). npm installs — global or project devDependency — keep the same path across upgrades.
• Git Bash / PowerShell (Windows). Claude Code runs Bash through Git Bash and exposes a PowerShell tool when Git Bash is absent. harness-memory maps both to the canonical tool bash and records the dialect, so a pitfall learned under one shell fires under the other (pnpm test; git status and & npm test canonicalize the same way). Exec-form hooks involve no shell at all. If shell form is needed (old Claude Code), install picks "shell": "bash" when Git Bash is found (CLAUDE_CODE_GIT_BASH_PATH, Program Files\Git, %LOCALAPPDATA%\Programs\Git, PATH) and "powershell" otherwise. The detached worker runs with windowsHide, so no console window flashes. Shell-form entries for PowerShell carry the call operator (& "<node>" "<hook.js>" <event>); without it PowerShell prints the quoted command instead of running it.
• WSL. Install the package and run hm install inside the environment that runs Claude Code: a WSL session needs the Linux node and a Linux dist/hook.js path in .claude/settings.local.json, and a checkout under /mnt/c holds one settings file, so pick one side. With a user-space Node (nvm, a tarball under $HOME) source its environment in the shell that runs hm, and keep the prefix out of /tmp, which systemd clears at every WSL boot.

Verify and remove

hm status              # one line: active N (auto M) | candidates | proposals | queue | last extraction | probe | snapshot | p95
hm doctor              # every check with OK / WARN / FAIL; --self-test runs the session-start hook once
hm uninstall           # removes the hook entries, the git exclude line and the manifest; keeps .harness-memory/
hm uninstall --purge   # also deletes .harness-memory/ except memory.sqlite.bak-v<N> backups

How memory is captured and saved

hooks (no DB)          ledger/*.jsonl ──► queue/<episode>.json ──► worker extract ──► memory.sqlite ──► snapshot/*.v1.*
                       state/*.json        (turn segment)           claude -p +         (one lock,        read by every hook
                                                                    V1–V12 + reconcile   write_ops)

1. Ledger — what the hooks write

Every hook appends one JSON line (≤ 32 KB, a single appendFileSync, credentials redacted first) to .harness-memory/ledger/claude-code-<session_key>.jsonl, where session_key = sha1("claude-code:" + session_id).slice(0, 16). Hooks never open SQLite; the only other hook-written files are state/claude-code-<session_key>.json (open turn: turn_key, turn_start_offset, segment, correction_for) and queue/*.json.

Regexes are used only to set flags — they never produce memory text (the v0.5 "template candidate" defect). Signals:

• correction — the previous turn's last tool call failed, or the prompt matches correction vocabulary (don't, instead, wrong, revert, 아니, 하지 마, 말고, 대신, 틀렸, …).
• remember — remember, from now on, 기억, 앞으로, 절대; always / 항상 only at a sentence start or together with another cue. The flag weights the episode (3). The human path of §7.3 additionally needs an explicit request in the prompt itself (remember this, 기억해, from now on followed by a rule); I don't remember whether … never counts.
• failure → resolution — a tool_ok for the same tool and the same path (or the same canonical program token, e.g. pm test) as an earlier unresolved tool_fail. A failing npm test followed by a successful ls is not a resolution; a successful pnpm test is.
• decision marker — decided, we'll use, switch to, 결정, 이제부터, 전환, … in the last assistant message.

2. Episode — the turn segment is the queue

Stop, PreCompact and SessionEnd close the open segment ([turn_start_offset, EOF), ≤ 4 MB) into queue/<episode_id>.json: scope refs, tools used, failure signatures with their resolutions, flags, which memories fired and whether the agent overrode or heeded a soft_deny, and

evidence_weight = correction 2 + remember 3 + (resolution 2 | unresolved failure 1 per failure)   (cap 10)

Only episodes with evidence_weight ≥ 1 or a decision marker go to the LLM; read-only turns are skipped as no_signal. The next UserPromptSubmit closes a turn the host never finished (interrupted); the SessionStart hook and hm dream sweep turns idle for more than an hour (idle). Episode ids are deterministic (host:session:turn_key:segment), so re-closing the same segment is a no-op and a turn compacted mid-way yields two episodes.

3. Extraction — a detached worker and your own CLI

The hook spawns node dist/worker.js <root> extract detached (stdio: ignore, windowsHide), so the hook returns in milliseconds. The worker, under locks/worker.lock:

1. inserts the queued episodes (INSERT OR IGNORE), rolls fire_count / override_count up from the fired lists, leases ≤ 3 episodes — corrections first — and applies the daily cap (extraction.max_runs_per_day, default 40; correction episodes are exempt);

2. renders the prompt: episode header, the previous turn's last ≤ 12 tool lines as non-citable context when this is a correction, every ledger line numbered e<seq> (failures and resolutions in full, the rest summarized), the last assistant message, up to 40 existing memories whose scope intersects, the canonical tool vocabulary and the type boundary rules — capped at 24,000 chars;

3. calls the provider (extraction.provider: auto → claude if found, else codex):

   claude -p --output-format json --json-schema <schema> --tools "" --disallowedTools "mcp__*" \
     --strict-mcp-config --no-session-persistence \
     --settings '{"disableAllHooks":true,"autoMemoryEnabled":false}' --model <extraction.model, default sonnet>
   

   with the prompt on stdin, cwd ~/.harness-memory/worker/<repo_hash>/ (outside every repository, so no CLAUDE.md, project hooks or auto-memory load), an allowlisted environment (no CLAUDECODE, CLAUDE_CODE_*; HARNESS_MEMORY_DISABLE=1 so hooks inside the child exit immediately), a 120 s wall clock and the raw answer cached 24 h in raw/<run_id>.json. The binary is resolved from HARNESS_MEMORY_CLAUDE_BIN, then CLAUDE_CODE_EXECPATH, then PATH, then the winget package directory. A probe (a one-field schema call) classifies the provider as ok, not_logged_in, missing, nested_refusal, probe_timeout or invalid_output; an ok is trusted for a day, a failure is retried after ten minutes, and unavailable providers leave episodes queued without burning an attempt.

The extractor answers a fixed JSON schema: episode_summary, nothing_to_learn and ≤ 8 facts, each with action (create | reinforce | propose_supersede | propose_stale), type, summary (12–160 chars), details, scope_glob, relevant_tools, trigger_signature ({tool, target, pattern_kind, pattern}), lifecycle_triggers, confidence, evidence_refs (e<seq> citations), knowledge_kind, rationale and aliases (≤ 8 synonyms, including the user's language). There is no delete and no edit: the LLM can only create, reinforce or propose.

4. Validation — V1 to V12

Each fact passes a deterministic validator before it touches the database: schema shape (V1); every evidence_refs entry resolves to a line of this episode (V2); the scope is a repository-relative glob that intersects the episode's files unless a signature carries the precision (V3); the signature's tool was actually used in the episode (V4); regexes compile, have no nested quantifiers and sweep 4 KB samples within the budget — 2 ms, or 2.5× a reference pattern of the same shape measured alongside on a slower machine (V5); the security scanner passes and the text does not talk about harness-memory itself (V6); reinforce / propose_* targets exist (V7); the fact is not a restatement of the prompt (V8); no duplicate semantic_key within the batch (V9); signatures are specific — cmd ≥ 2 tokens, substring ≥ 8 chars, globs with a path fragment (V10); before_tool is kept only where a hook can deliver it (V11); and a signature is rejected when it also matches the command that resolved the cited failure while that command differs from the failing one — pm test would fire on the pnpm test that fixed npm test (V12). A run that is not JSON, has more than 8 facts or more than 50 % hallucinated citations is marked suspect and skipped whole; otherwise rejected facts are counted and the rest are applied.

5. Reconcile — one transaction, then the snapshot

Under locks/db.lock (held for seconds, never around the LLM call) the worker applies the facts fact-by-fact (SAVEPOINT each): create becomes a new row with authority = 'auto', status = 'candidate', source_ref = 'episode:<id>'; an identical or near-identical live row (semantic_key, or Jaccard ≥ 0.6 on the normalized summary) is reinforced instead; propose_* opens or supports a proposal. Every fact records memory_provenance (episode, cited line, confidence); derived counters (evidence_count, evidence_score = Σ episode weights, distinct_session_count, auto confidence) are recomputed immediately, then decideTier decides active or candidate (see auto tier). The run id is written to write_ops, so replaying the same run is a no-op; policy_rules are re-derived from active policy memories; db_generation increments; the database is saved atomically (.tmp-<pid> → fsync → .prev → rename) and snapshot/*.v1.* is rebuilt. A corrupted main file is recovered from .prev.

Consolidation (worker dream; spawned at SessionEnd when the last run is older than dream.interval_hours = 6, or hm dream) never invents memories: TTL expiry (correction/failure-derived rows get a revalidate proposal first), auto candidates older than 45 d → rejected, proposals past 30 d → expired, TTL extension for rows that fired recently, override downgrade (an auto row overridden ≥ 3 times with evidence_score < 3 drops to advise), merge proposals for auto near-duplicates, embedding backfill, the idle-turn sweep and garbage collection (ledger segments 14 d, raw/ 24 h, tmp files 10 min, audit log 30 d).

.harness-memory/ layout — what to back up

hm install writes .harness-memory/.gitignore (*), so nothing in the directory reaches git; hm doctor warns if files there were committed earlier. hm memory:export writes a deterministic SQL dump for backups that should live in version control.

The authority model

Two axes on every memory

• authority ∈ {human, auto} — who may change its status. human rows come from hm memory:add, hm import (a file you wrote), hm memory:promote, accepted activate_* proposals, replacement rows you accept, and any human edit (memory:enforce, scope changes). They have no TTL, a trust multiplier of 1.0, and the automatic path can never demote, supersede, stale or reject them — transitionMemory throws AuthorityViolationError and writes nothing. auto rows are born from extraction; they carry a TTL, a trust multiplier of 0.65 → 0.8 → 0.95 as validations accumulate, and they can be demoted by 2-session contradicting evidence or by repeated overrides.
• enforcement ∈ {advise, confirm, soft_deny, deny} — how a before_tool hit is delivered. deny can only be set by a human; the LLM never raises enforcement.

The delivery ladder (Claude Code)

confirm, soft_deny and deny also emit one systemMessage line for you (harness-memory: pitfall 3f9a… fired (soft_deny)); advise is silent. The injected text looks like [harness-memory] PITFALL (auto, provisional): <summary> — <details>; labels are human, human, unconfirmed import or auto, provisional, plus , contested on a human advise row that two sessions have argued against. Reasons are ≤ 600 chars; the hook never emits allow.

Default enforcement (enforcementDefault, always overridable with hm memory:enforce)

Auto tier — when a memory activates on its own

decideTier runs for every created or reinforced auto candidate, right after its counters are recomputed:

• active when all hold: type ∈ {pitfall, workflow}, a valid repository-relative scope, a trigger signature or relevant_tools, a trigger a hook can reach, confidence ≥ 0.7, evidence_score ≥ 2, the scanner is clean, the row is not a replacement row of an open proposal, the caps are not hit (extraction.max_auto_activations_per_episode = 3, max_auto_activations_per_day = 10) and autonomy_level = standard. The row gets ttl_expires_at = now + 30 d for correction / failure-resolution knowledge (7 d for conventions), revalidate_after at half that, validation_count = evidence_count − 1.
• candidate otherwise — with a reason (evidence, cap, confidence, type, replacement, autonomy, …) and, for policy, an activate_policy proposal; for a signature-less global row, an activate_global proposal. decision and architecture_constraint always wait for you.

"Enough evidence" is a weight sum, not an episode count: one correction (2) or one failure → resolution pair (2) activates immediately. The cost side is the TTL, the 0.65 trust multiplier at first activation, the 2-session rule for demotion, V10 specificity, the override downgrade and the daily cap. Reinforcement never shrinks a TTL (ttl = max(existing, now + max(7·2^validations, base)), capped at 90 d); a fired memory is extended by 14 d.

Proposals and review

Eight proposal kinds: supersede, stale, activate_policy, activate_global, fix_scope (from the v0.5 migration), fix_signature, revalidate, merge. One open proposal per (kind, target, candidate); repeated claims only raise support_count / support_sessions. The extractor's propose_stale / propose_supersede against a human row only opens a proposal and marks the row contested; against an auto active row it is applied automatically only with support from ≥ 2 sessions, at least one of which carries a human signal (a correction or remember) or a deterministic observation — an agent cannot erase your correction in two of its own turns. Rejecting a proposal suppresses the same claim for 30 days; proposals expire after 30 days (fix_scope: 90).

Review is exception handling, with a budget (≤ 3 items per active day is the dogfood gate): hm review walks proposals on human memories → revalidate → policy candidates → global candidates → fix_scope / fix_signature → merge → unconfirmed imports → human candidates, with keys accept, reject, skip, trace, promote. Accepting a supersede makes the replacement row human; accepting activate_* promotes the row as hm memory:promote would. The SessionStart hook shows a one-line systemMessage digest once a day (harness-memory: N proposal(s) open, M expiring within 7 days — run hm review). No review text ever reaches the model's context.

autonomy_level

standard (default) — the table above. shadow — decisions are only logged to audit_log (auto_activation_shadow); nothing activates. off — decideTier never activates anything.

What gets injected, when

before_tool in detail: the hook canonicalizes the tool (Bash / PowerShell → bash, Edit / MultiEdit / NotebookEdit → edit, WebFetch → fetch, mcp__server__tool → mcp:server/tool), picks the target (command, file_path, url or the MCP input JSON) and the path-like tokens in it, reads the ledger tail to learn what already fired this turn, then filters the snapshot: status and TTL → trigger → relevant_tools → signature match (cmd patterns match on the canonical command form: npm test ≡ npm run test ≡ & npm.cmd test, while the family forms pm test / bin vitest cover every package manager / runner; glob / regex / substring on the target) or, for signature-less policy / pitfall rows, scope regex × path tokens → derived policy rules → ranking by enforcement, signature match, human first, score → quotas (policy 2, pitfall 2, workflow 1) → budget. Rows imported from a file the host already loads (CLAUDE.md, CLAUDE.local.md) are skipped at session_start / before_model so nothing is said twice. hm memory:why --tool bash --target "npm test" runs exactly this function and prints every activation and suppression reason.

Embeddings (optional)

Dense retrieval is off by default and never on the PreToolUse path. When you want it for before_model:

hm install --host claude --with-embeddings   # npm install @xenova/transformers in the package root, embeddings.enabled = true

--with-embeddings runs npm install @xenova/transformers inside the installed package directory (for a global install $(npm root -g)/harness-memory), which also pulls that manifest's devDependencies: about 350 MB and 17 s on a fast machine, measured on the rc tarball. It needs write access there — a sudo-installed prefix refuses (installed with problems; the hooks are registered all the same); then install the dependency next to the package instead, npm install -g @xenova/transformers (with sudo if that prefix needs it; Node resolves it from the parent node_modules), and set embeddings.enabled: true in config.json. Never run hm install itself with sudo: it would leave root-owned files in the project. The next package upgrade drops the in-package copy, so run hm install --host claude --with-embeddings again afterwards. A leaner, upgrade-proof location under ~/.harness-memory/ is planned for 0.6.1.

• A small helper process (dist/embed-helper.js <root>) serves top-k queries over a Windows named pipe (\\.\pipe\harness-memory-embed-<repo_hash>) or a Unix socket harness-memory-embed-<repo_hash>.sock in $XDG_RUNTIME_DIR (else the temp directory) — never under the repository, so a deep checkout stays below the Unix socket path limit; hm doctor prints the path. The prompt hook asks it with a before_model.dense_timeout_ms (80 ms) budget and falls back to lexical-only when it does not answer; the first miss spawns the helper detached (throttled to once per 60 s). It loads snapshot/dense.v1.bin, reloads when that file changes, and exits by itself after embeddings.idle_exit_minutes (15) of inactivity or on SIGTERM. There is no installed service and no fixed port.
• Model: Xenova/multilingual-e5-small (quantized), cached under ~/.harness-memory/models (embeddings.cache_dir). The download happens once, only when embeddings are enabled and the model is absent; it is the only network access besides your own extraction CLI.
• The worker embeds new rows right after extraction (passage: prefix) and hm dream backfills the rest; dense.v1.bin is only written when at least one row has an embedding.
• Korean and other aliases need no embeddings: the extractor emits up to eight aliases per fact (in the user's language when the prompt was not English), and the lexical snapshot indexes them with a code-aware, Hangul-particle-stripping tokenizer, so a Korean prompt reaches an English memory through BM25.

Configuration

.harness-memory/config.json (schema config.v1). Unknown keys are ignored and invalid values fall back to the defaults, so a bad config never breaks a hook.

Environment variables: HARNESS_MEMORY_DISABLE=1 makes every hook exit before reading anything; HARNESS_MEMORY_DEBUG=1 adds a full JSON detail line per hook call to logs/hooks.log; HARNESS_MEMORY_HOME relocates ~/.harness-memory; HARNESS_MEMORY_CLAUDE_BIN / HARNESS_MEMORY_CODEX_BIN pin the extraction binaries; HARNESS_MEMORY_PROVIDER forces a provider.

CLI reference

Binary harness-memory, alias hm. Every command accepts --json (machine-readable output), --db <path> (database file; <x>/.harness-memory/memory.sqlite also selects project <x>) and --root <dir> (project root; default: the nearest ancestor holding .harness-memory/, else .git/, else the cwd). hm <command> --help lists a command's options; hm --version prints the version.

Exit codes: 0 ok · 1 error · 2 usage error, unknown command, or a command not in this build · 75 the database lock is busy (another writer holds locks/db.lock; retry).

hm eval:live (the live three-arm evaluation) is the only command hm --help still marks (not in this build); it prints a one-line explanation and exits 2.

Names and flags are taken from the dispatcher (src/cli/registry.ts and the command modules under src/cli/commands/); test/docs-cli-reference.test.ts fails when this table and the dispatcher disagree.

Troubleshooting

Read hm status first. active 12 (auto 4) | candidates 3 | proposals 1 | queue 2 (waiting: not_logged_in) | last extraction 3h ago ok | probe not_logged_in | snapshot fresh | p95 61ms tells you how many rows can fire, what is waiting for review, whether episodes are stuck and why, whether the provider works, whether the hooks read a current snapshot, and how slow PreToolUse is. Then hm doctor.

logs/hooks.log has one line per hook call:

2026-11-08T12:00:01.234Z pre-tool tool=bash gen=42 activated=1 suppressed=17 decision=deny delivery=before enforcement=soft_deny dur=48ms ok

status is ok, bad_stdin, snapshot_missing, disabled, not_installed, skipped:<reason> or error:<code>; gen is the snapshot's db_generation. HARNESS_MEMORY_DEBUG=1 (or log.debug: true) adds a JSON line with the full detail (activated ids, suppression kinds, rule hits). Hooks never fail the host: any exception becomes one log line, {} on stdout and exit 0. logs/worker.log has the worker's lease / extraction / end lines (lease … waiting=<reason> names what blocks the queue). HARNESS_MEMORY_DISABLE=1 in Claude Code's environment turns every hook into an immediate exit when you need to rule harness-memory out.

Privacy and security

• No account, no telemetry, no server. Everything lives in <project>/.harness-memory/ and ~/.harness-memory/. The only processes that talk to a network are (1) the extraction CLI you already use — claude -p or codex exec under your own login, called by the detached worker — and (2) the optional, one-time embedding model download when you enable --with-embeddings.
• What the extractor sees. For an eligible episode: your prompt text (≤ 4,000 chars), the tool calls of the turn as digests (command text or repository-relative path, ≤ 500 chars), tool output head/tail (2,000 / 1,000 chars) and error text (1,500) for failing and resolving calls, the last assistant message (≤ 2,000), the previous turn's ≤ 12 tool lines when the turn is a correction, and up to 40 existing memories (id, type, status, authority, scope, signature, summary). Never the transcript file, never your file contents beyond what tool output already showed. The call runs with --tools "", all hooks and auto-memory disabled, no session persistence, an allowlisted environment and a cwd outside every repository.
• Redaction before anything is written. Ledger lines pass redactCredentials first: private key blocks, sk-ant-…, sk-…, GitHub ghp_… / github_pat_…, GitLab glpat-…, npm npm_…, Stripe sk_live_… / sk_test_…, AWS AKIA…, Slack xox… / xapp-…, Google AIza…, JWTs, Bearer … and Basic … headers, credentials in a URL of any scheme (postgres://user:pass@), curl -u user:pass, --password …, mysql -p…, and KEY=value / "key": "value" / key: value assignments whose key names a password, secret, token or API key (DB_PASSWORD=, AWS_SECRET_ACCESS_KEY=, accessToken:) become <redacted>; $VAR references are kept. The same redaction runs over scope_refs, failure_sig and program_token (capped at 256 chars per token, 4,000 in total) and over the text of imported bullets.
• Extracted text is scanned (invisible Unicode and control characters, prompt-injection phrases in English and Korean such as "ignore previous instructions" / "이전 지시를 무시", credential assignments, instructions to conceal or to disobey the user) and facts that mention harness-memory, its commands or memory ids are rejected (V6), so the model cannot write itself a rule through a tool output. The extraction prompt wraps recorded events, the previous turn, the last assistant message and the existing-memory list in data fences and states that fenced content is data, never an instruction; a legacy candidate whose stored text fails the scan can be reinforced but never auto-activates.
• Hooks are read-only. They open no database, hold no lock and return exit 0 on every path; their only writes are the ledger, the session state and queue files. PreToolUse never emits allow, so it can never widen your own permission prompts.
• Retention. Ledger segments 14 d, raw provider output 24 h, audit log 30 d, hooks.log 5 MB × 3 — configurable under retention / log. hm uninstall --purge removes it all except the memory.sqlite.bak-v<N> backups.

Upgrading from 0.5

v0.5 was an OpenCode plugin with a different write path (conversation buffer → evidence rows → dream consolidation → human-reviewed promotion). v0.6 keeps your memory.sqlite and the five types / four triggers, and rebuilds everything around it:

• hm install --host claude migrates user_version 9 / 10 / 16 → 22 (migrations 017–022), after copying the file to memory.sqlite.bak-v<N>. No memory row is deleted. Every row gets an authority: candidate rows and auto-promoted rows become auto, every other row human; v0.5 LLM rows with scope **/* and only before_model get needs_scope = 1 and a fix_scope proposal (90 d) in hm review; the v0.5 dream tables are renamed legacy_* (read by hm memory:history for one release), template candidates are rejected, duplicate live rows get merge proposals.
• OpenCode is not supported by 0.6.0 (V2 plugin in 0.6.2; Codex hooks in 0.6.1). Remove the v0.5 plugin entry from opencode.json (and .opencode/package.json, .opencode/commands/harness-memory-*.md) yourself; hm uninstall --purge removes the legacy .conversation-buffer.json / .dream-extract-state.json files.
• hm db:rollback restores the pre-migration backup; the next writer migrates forward again, so hm uninstall first when you mean to go back to 0.5.

Details, the migration table and the old → new command map are in docs/redesign/upgrade-from-0.5.md.

Roadmap

• 0.6.0 — Claude Code (this release). Gates: eval:replay green, eval:latency p95 ≤ 90 ms, two weeks of dogfood with ≤ 3 review items per active day and an autonomy regret (rejected auto activations) ≤ 10 %.
• 0.6.1 — Codex host (.codex/hooks.json, apply_patch, turn_id, the codex exec provider).
• 0.6.2 — OpenCode V2 plugin (Plugin.define, permission.assert, context hook).
• 0.7 — global memory sync, auto↔auto merge, heeded-fire inference, snapshot buckets, dropping the legacy_* tables.

Development

npm install
npm run build            # tsup → dist/hook.js, hook-bundle.js, worker.js, embed-helper.js, bin/harness-memory.js (+ migrations)
npm test                 # vitest
npm run typecheck        # tsc --noEmit
npm run package:verify   # pack, install the tarball into a temp project, run hm install / status / doctor

Design documents: docs/redesign/spec-v0.6.md (Korean, the authoritative design), docs/redesign/implementation-plan.md, docs/redesign/m0-facts.md (facts measured on a real machine), docs/redesign/phase-a-notes.md and docs/redesign/phase-b-notes.md (module APIs). Pages under docs/product/ and docs/spec/ describe v0.5 and carry a banner saying so.

Korean README: README.ko.md. Changes: CHANGELOG.md.

License

MIT