harness-mem Managed Companion Contract

Claude-harness treats harness-mem as a managed companion, not as embedded code.

This contract keeps the boundary simple:

• Claude-harness owns orchestration: setup entrypoints, status display, hook wiring, compatibility checks, and safe user commands.
• harness-mem owns the runtime: daemon, local database, migrations, doctor logic, update logic, and deletion semantics.

Standard Paths

Claude-harness assumes the harness-mem defaults below, but must not inspect the SQLite schema.

Resource	Standard path
Runtime checkout	~/.harness-mem/runtime/harness-mem
Database	~/.harness-mem/harness-mem.db
Config	~/.harness-mem/config.json
Doctor artifact	~/.harness-mem/runtime/doctor-last.json

Claude-harness may check whether these paths exist to decide whether harness-mem looks installed. It must not query, migrate, rewrite, or infer behavior from the database tables.

Claude-harness CLI Surface

harness mem exposes the user-facing companion controls:

Command	Behavior
harness mem status [--json]	Reads harness-mem doctor --json --platform codex,claude --skip-version-check when an installed CLI is available. Missing harness-mem is reported as not_configured, not as a broken Harness install.
harness mem setup	If doctor is not all-green or harness-mem is missing, runs non-interactive setup for codex,claude with auto-update enabled.
harness mem update	Delegates to harness-mem update.
harness mem doctor	Delegates to harness-mem doctor --platform codex,claude unless the caller passes a platform.
harness mem off	Delegates to harness-mem recall off. This disables contextual recall injection, not the database.
harness mem purge --confirm-purge	Delegates to harness-mem uninstall --platform codex,claude --purge-db. Without explicit confirmation it refuses to run.
harness mem health	Backward-compatible daemon health check for Session Monitor.

purge is intentionally noisy and manual. Auto setup must never delete the database.

Auto Setup

Plugin Setup:init may attempt companion setup once.

Default behavior:

npx -y --package @chachamaru127/harness-mem harness-mem setup \
  --platform codex,claude \
  --skip-quality \
  --auto-update enable

Rules:

• Default is on.
• Disable with CLAUDE_CODE_HARNESS_MEM_AUTO_SETUP=0.
• The attempt is marked in .claude/state/harness-mem-companion-setup.json.
• A failure must not fail Claude-harness setup.
• SessionStart must not run setup.
• Auto setup never runs uninstall, purge, or any database deletion command.

harness-mem Doctor JSON

Claude-harness expects harness-mem doctor --json to return one JSON object with at least:

{
  "status": "healthy",
  "all_green": true,
  "failed_count": 0,
  "checks": [],
  "fix_command": "harness-mem doctor --fix",
  "backend_mode": "local",
  "contract_version": "claude-harness-companion.v1",
  "harness_mem_version": "0.17.0"
}

Additional fields are allowed. Claude-harness treats malformed JSON as an unknown companion state and asks the user to run harness mem doctor.

Compatibility Rules

• Claude-harness may call setup, doctor, update, recall off, and uninstall --purge-db.
• Claude-harness may forward elicitation-event.v1 observations through /v1/events/record with event_type: "elicitation_event" when harness-mem is healthy.
• Claude-harness must not import harness-mem source files as libraries.
• Claude-harness must not directly read or mutate ~/.harness-mem/harness-mem.db.
• Claude-harness must silently fall back to its local ledger when elicitation forwarding fails.
• harness-mem may change internal tables when it preserves this CLI and JSON contract.
• The contract version changes only when Claude-harness must alter behavior.