iHow Memory

Your AI can change. Your work should not reset.

iHow Memory gives coding agents one local, human-readable memory they can hand off across sessions and tools. On supported capture paths, when context is compressed, a runtime crashes, or you move from Claude Code to Codex, the next agent receives the prior state, evidence, blockers, and next step.

It does not trust that narrative on sight. The receiving agent re-checks live git anchors first; a matching repo can earn GREEN, while drift forces RED. Memory stays Markdown on your machine, with citations and an audit trail.

简体中文

See it in 3 minutes

Requires Node.js >= 22.12 on macOS or Linux. WSL is supported; native Windows is experimental. No account or API key is required.

Set up

npx ihow-memory setup

setup detects supported runtimes, backs up configuration before editing it, connects the local MCP server, and reports what is verified, pending, or needs a restart.

Run the proof

npx ihow-memory proof

The proof uses only synthetic data in a throwaway git repo and temporary memory workspace. It demonstrates an UNVERIFIED prior-agent narrative, matching live anchors earning GREEN, later repo drift forcing RED, and agent A's governed memory reaching agent B with a citation and audit event. It does not edit your project or runtime configuration.

Want to inspect before running? Read the 30–45 second evidence storyboard or run the repo-local synthetic demo.

What survives the interruption

Git repos provide the strongest branch / HEAD / dirty anchors. Non-git workspaces still get file-fingerprint drift checks, but not commit-level GREEN/RED.

Evidence boundary: Claude Code is the daily-dogfooded path. Other listed runtimes have narrower single-machine smoke coverage, and some are receive-only. Default retrieval is lexical FTS5, not semantic recall. Experimental surfaces may change; check Runtime support and Limitations before production use.

If agent resets have cost you real work, star iHow Memory so other developers can find the project—and tell us which handoff you need next.

Continue real work

After /clear, a new session, or a switch to another supported runtime:

npx ihow-memory continue            # optional repo keyword: continue <name>

continue carries the previous narrative as UNVERIFIED and gives the receiver machine anchors to re-check before acting. GREEN is deliberately narrow; drift or conflict forces RED. If this is your first run and there is no captured session yet, the CLI says that plainly and points back to proof instead of printing an empty handoff envelope. In Claude Code you can simply say “continue” / “继续”.

Correct a wrong memory

npx ihow-memory forget "text or memory/path.md"
# reversible:
npx ihow-memory remember "text or memory/path.md"

forget tombstones one unambiguous match so it stops surfacing in search and recall; the file is untouched and the action is reversible and audited.

Why the handoff is different

1. Verify before continuing. The previous agent's status is narrative, not authority. Live git or file anchors decide whether the receiver sees GREEN or RED.
2. Cross-agent by design. Claude Code, Codex, Cursor, WorkBuddy, Claude Desktop, OpenCode, Hermes, OpenClaw, VS Code, Gemini CLI, and Cline can participate according to the support table below.
3. Governed, inspectable writes. Candidates can be reviewed and promoted; secret-like content is rejected; promoted memory has citations and audit events.
4. Local and human-readable. The default core uses Markdown plus SQLite FTS5, with no account, required cloud, or telemetry by default.

What setup connects

Claude Code is the daily-dogfooded path. Codex, OMP, OpenClaw, Hermes, OpenCode and WorkBuddy have single-machine real-app smoke. Cursor, Claude Desktop and VS Code are receiver-only because they do not expose a resumable local session store. See Runtime support before making production assumptions.

To connect only one runtime, or to inspect the exact config instead of applying it:

npx ihow-memory connect --runtime claude-code --dry-run
npx ihow-memory connect --runtime claude-code
npx ihow-memory init --runtime claude-code       # print the MCP snippet only
npx ihow-memory doctor --runtime claude-code

Activation is evidence-based, not inferred from installation text. The workspace-frozen CLI and exact managed Claude/Codex hook or OMP extension wiring can produce bounded local completion evidence, but the same OS user can replay that command, so it does not authenticate the host: doctor keeps these runtimes at READY — WAITING FOR FIRST ACTIVITY with reason code ACTIVATION_COMPLETION_UNATTESTED. TOOLS ONLY means cooperative MCP tools are available without a verified lifecycle hook; NEEDS REPAIR means managed wiring is broken or stale. Synthetic probes and started-only events never become ACTIVE. The ledger stores hashed bindings and bounded metadata, never prompts, transcripts, environment values, or error text.

The governed loop, explicitly

Agents use the same path over MCP. This shell version makes the review gate visible:

npx ihow-memory init --space demo
CAND=$(npx ihow-memory write-candidate "Decision: ship weekly release notes." --no-auto-promote --space demo | sed -n 's/.*"path": "\([^"]*\)".*/\1/p')
PROMOTED=$(npx ihow-memory promote "$CAND" --scope team --title "Release notes cadence" --space demo | sed -n 's/.*"path": "\([^"]*\)".*/\1/p')
npx ihow-memory search "release notes" --space demo
npx ihow-memory read "$PROMOTED" --space demo
npx ihow-memory reset --space demo

Without --no-auto-promote, a clean write can auto-promote into a durable yellow tier; secrets and falsified anchors are still blocked. Search/read results cite the exact Markdown source, and promote creates an audit event.

Updating and recovery

connect freezes a runtime copy into the workspace. Runtime registrations keep using the stable .runtime/mcp/server.js path, while Claude Code and Codex hooks use a byte-stable .runtime/cli.js bootstrap; release CLI implementation bytes live in .runtime/cli-runtime.js. Because npm update does not refresh this frozen runtime by itself, run npx ihow-memory upgrade and then restart the runtime. The new generation is staged and integrity-checked before the atomic .runtime / .runtime.previous swap, then the MCP server is probed; probe failure restores the exact prior generation. Existing legacy installations refresh their activation evidence once when they first move to the stable bootstrap—without rewriting correct hook files—while later implementation-only upgrades leave both hook config and generation unchanged. If one runtime registration points at a deleted/moved workspace, pass it explicitly—for example npx ihow-memory upgrade --runtime opencode—to back up and repair only that registration. If the installed/frozen runtime is damaged, use the independent package entry npx ihow-memory rescue (optionally with --runtime <name>). doctor fails instead of silently accepting version skew or broken activation wiring.

Runtime support

connect registers the MCP server for eleven runtimes; setup wires every detected one in a single command and, where the runtime has an instructions file, injects a "call memory.continue on resume" nudge. Two sides matter: connect (the runtime can call the memory tools) and a resume reader (that runtime's own past sessions can be picked up by memory.continue). Verification below is single-machine real-app smoke unless noted; this is the documented evidence boundary.

The MCP tools and governed loop are runtime-agnostic. Claude Code uses a skill plus Stop / SessionStart / PreCompact / UserPromptSubmit hooks. Codex uses native SessionStart / PreCompact / UserPromptSubmit hooks plus an auto-injected ~/.codex/AGENTS.md proactive memory loop (continue/search/read/write/forget discipline); the Codex SessionStart hook also triggers the existing capture-floor sweep at thread boundaries, with the normal idle gate still protecting active sessions. OMP uses a managed extension for session_start, before_agent_start, native PreCompact, and session switch/shutdown capture; its readable JSONL transcript also feeds memory.continue and the crash-floor sweep. For Hermes, connect / setup installs both packaged adapters under $HERMES_HOME/plugins, enables ihow-memory, selects memory.provider=ihow-memory-compaction, and binds both to the workspace's integrity-checked frozen bridge. It refuses to replace another configured external memory provider and rolls back partial adapter/config/MCP writes on failure. The pre-compress handoff is bounded and transcript-free, but stays explicitly UNVERIFIED until live anchors are checked; this is not an ACTIVE or host-authentication claim. Resume guidance is also auto-injected for WorkBuddy, OpenClaw, Hermes and OpenCode.

DeepSeek Harness support intentionally stays outside connect and setup: the separately published dsh-ihow-memory bundle owns DSH Profile installation, MCP mounting, and native Host event listeners, while Core 0.1.0 exposes only the bounded Core contract and capability evidence. Publishing Core does not install or activate the adapter; install it separately and restart the target DSH Profile. DSH startup reuses the verify-first checkpoint/MCP handoff path; Core does not parse DSH persistence as a native transcript source.

Runtimes wired without an auto-injected resume nudge (Cursor · Claude Desktop · VS Code Copilot · Gemini CLI)

For these, connect wires the shared MCP server but iHow does not auto-write a global rules file (their instruction surface is app- or project-managed), so add the resume nudge yourself once. Cursor, Claude Desktop and VS Code Copilot are also receiver-only — no readable local session store, so iHow cannot resume their past sessions; they instead pull a verify-first handoff packet (query + GREEN/YELLOW/RED verdict + verbatim-unverified narrative) recorded by any capture runtime (Claude Code, Codex, …), e.g. pick up in VS Code work that Claude Code left off. Gemini CLI is now a passive reader (its on-disk user-prompt log — see the table above) but still needs the manual GEMINI.md nudge:

• Cursor — npx ihow-memory connect --runtime cursor (merges ~/.cursor/mcp.json, backed up; never clobbers an unparseable file). Add a User Rule like: "On resume / when I say 继续, call the memory.continue MCP tool first; treat its narrative as UNVERIFIED and run its git preflight before acting."
• Claude Desktop — npx ihow-memory connect --runtime claude-desktop (writes claude_desktop_config.json; macOS ~/Library/Application Support/Claude/, Linux ~/.config/Claude/, Windows %APPDATA%\Claude). Restart the app to load the tools.
• VS Code (Copilot) — npx ihow-memory connect --runtime vscode writes the user mcp.json (macOS ~/Library/Application Support/Code/User/mcp.json, Linux ~/.config/Code/User/mcp.json, Windows %APPDATA%\Code\User\mcp.json) under the servers key with a type: "stdio" entry, backed up; an unparseable file is never overwritten. Reload the window, then enable the server in Copilot agent mode. Add a line to .github/copilot-instructions.md: "On resume, call the memory.continue MCP tool first and verify its anchors before acting."
• Gemini CLI — npx ihow-memory connect --runtime gemini adds an mcpServers entry to ~/.gemini/settings.json (backed up; unparseable file left untouched). Restart gemini, confirm with /mcp list. Add the same nudge to your GEMINI.md.

For any of these, npx ihow-memory init --runtime <name> prints the exact snippet to paste by hand instead of writing it, and npx ihow-memory doctor --runtime <name> round-trips the configured server to confirm it is reachable.

Retrieval engine

The default retrieval engine is zero-dependency local full-text search — Node built-ins plus node:sqlite FTS5 only: no third-party runtime deps, no embedding downloads, no model or API key, with citation-bearing results. An optional local vector provider (separate process) adds semantic retrieval; if unconfigured or unhealthy, retrieval falls back visibly to FTS. Governance, write guards and audit behavior never change with the retrieval backend. The memory itself stays human-readable, editable, rollback-able Markdown.

Retrieval-quality evidence

Retrieval recall is not iHow's differentiator — verify-first governance is. We publish the honest shipped numbers anyway, because "claimed vs observed" must never diverge for a tool whose whole pitch is don't trust green.

The headline numbers are the ones you actually get out of the box — the default zero-dependency FTS5 lexical engine (BM25). On the in-repo reproducible fixture (node scripts/retrieval-bench.mjs):

This is a deterministic, stranger-reproducible harness: node scripts/retrieval-bench.mjs seeds a labeled fixture through the same write → promote → search path the product uses and scores R@5/R@10/MRR + tokens-per-query, with no cloud, no LLM and no third-party deps.

The honest floor: paraphrase recall is the weak spot. Keyword and partial-keyword queries recall well (15/15 in the fixture), but paraphrase / synonym queries that share no surface tokens score 2/5 = 0.40 — a reworded query exposes a lexical engine's lack of semantics. An optional semantic provider is intended to address that gap, but its quality must be measured rather than inferred from provider readiness or model identity.

The fixture above is a self-authored 20-doc / 20-query set. So that the numbers don't rest on our own data, there is also a stranger-reproducible run on a public, MIT-licensed standard dataset — LongMemEval (oracle variant, arXiv:2410.10813) — on the same default FTS5 binary:

node scripts/standard-bench.mjs --download fetches + sha256-verifies the dataset and runs all 419 usable instances (831 session-docs) on the default engine; the vendored N=8 slice runs offline (node scripts/standard-bench.mjs). This is global-corpus retrieval — find the gold evidence session among every instance's sessions, which is harder than the paper's per-instance oracle setup. Recall@k is recall_any@k (the official reading); MRR is our own metric (LongMemEval reports NDCG), so it is not directly comparable to the paper's tables. The weak spots stay visible: assistant-answer and preference questions — where the evidence lives in the assistant's turn or is implicit, so the indexed user turns share little surface with the query — recall worst, the same lexical gap an optional semantic provider is intended to address and may lift only when a measured run shows a positive delta.

Optional semantic sidecar (not the default binary)

Higher recall figures exist, but they come from a different lane and must not be read as the shipped default:

Not directly comparable to vendor end-to-end LLM-judged figures.

Semantic recall requires a user-provided embedding sidecar (e.g. Ollama nomic-embed-text) running as a separate local process. The default install is lexical-only and zero-dependency by design — that is a deliberate technical choice, not an omission. If the sidecar is unconfigured or unhealthy, retrieval falls back visibly to FTS.

Turn it on per space with one command — it probes your local Ollama and only enables if the model is actually pulled, then persists the opt-in so connect/setup launch the server with the (bundled) sidecar:

ollama pull nomic-embed-text            # once
npx ihow-memory enable-semantic    # probes Ollama; writes <space>/.runtime/semantic.json
# re-run `setup`/`connect` + restart your runtime to apply · reverse anytime: disable-semantic

enable-semantic refuses (non-zero, with guidance) if Ollama is unreachable or the model isn't pulled — it never enables a lane that would only fall back. doctor then reports semantic health as a warning, never a failure (the lane is additive). A successful nomic-embed-text probe means the ranking sidecar can run; it does not establish a quality lift. Real-model snapshots on the 20-doc / 20-query fixture currently conflict: an earlier direct-sidecar harness observed paraphrase recall 2/5 → 2/5 (Δ0), while a fresh run through the product's normal rebuild() path observed 2/5 → 5/5 (Δ+3). The fresh product-path snapshot is positive, but these results are fixture/model/version/path-sensitive and do not establish a stable, generalizable real-model floor; treat the output of your own rerun as authoritative. Prompt-bypass eligibility remains fail-closed absent a separately calibrated model floor. The independently labeled deterministic synonym-oracle also reaches 2/5 → 5/5, but only as a controlled architecture proof of RRF wiring, never learned-model quality evidence. The default binary stays lexical-only with capabilities.semantic=false until you opt in.

Evidence manifest: LongMemEval_S retrieval-stage run, 2026-05-11.

MCP tools

The stdio MCP server (registered by connect, or manually via the init snippet) exposes these tools:

CLI reference

ihow-memory setup            zero-config: detect runtimes -> wire MCP + skill + auto-capture/recall hooks -> verify (recommended; idempotent, local-only) [--dry-run] [--json]
ihow-memory init             create a managed workspace, print the MCP config snippet
ihow-memory connect          auto-configure a runtime (claude-code | codex | cursor | workbuddy | claude-desktop | opencode | hermes | openclaw | vscode | gemini) [--easy] [--dry-run] [--json]
ihow-memory continue         resume after a context boundary — verify-first handoff with live git anchors (GREEN/YELLOW/RED) [project-keyword] [--list] [--json]
ihow-memory install-skill    copy the Claude Code proactive-memory skill into ~/.claude/skills/
ihow-memory install-hook     add runtime hooks — Claude Code: Stop + SessionStart + UserPromptSubmit (project-local by default; --global-hook for user-wide). Codex: SessionStart + UserPromptSubmit in ~/.codex/hooks.json. Recall is on by default; --no-recall skips it.
ihow-memory doctor           environment + setup checks [--share-diagnostics for a redacted report]
ihow-memory verify           reproducible self-proof receipt: local store + each runtime's reachability + this checkout's resume verdict, every line re-runnable [--runtime name] [--json]
ihow-memory status           workspace, engine, index and sync state [--json]
ihow-memory search <query>   citation-bearing local search [--limit n]
ihow-memory read <path>      bounded 8,000-character preview by default [--max-chars n] [--full; ignores max-chars]
ihow-memory write-candidate  propose a memory candidate (sandbox inbox)
ihow-memory promote          promote a candidate (explicit, audited)
ihow-memory durable-promote  durable write — requires --dry-run or --real-write
ihow-memory journal <text>   append a low-weight auto-capture entry (searchable, ranked below curated)
ihow-memory organize         Safe Memory Gardener: create a review-first JSON draft with source evidence, safety status, duplicate/stale review flags, and an organize audit event [--scope project] [--since 7d] [--draft] [--json]
ihow-memory export-vault     export a gardener draft to an Obsidian-compatible Markdown view artifact with evidence links and an export audit event; the export is not source of truth [--from-draft <draft_id>] [--format markdown]
ihow-memory import           import existing memory you wrote elsewhere (Claude Code MEMORY.md, ai-memory markdown, any .md folder) into the searchable journal lane [--from path] [--apply] [--update]
ihow-memory audit            list the append-only event log [--since YYYY-MM-DD]
ihow-memory rollback         undo one auto-captured journal entry (--event <id>)
ihow-memory forget <text|path>  one-gesture correction: stop a memory surfacing in search AND recall everywhere (reversible tombstone; file untouched; reviewed entries need --yes; --list shows what's forgotten)
ihow-memory remember <text|path>  reverse a forget — the entry surfaces again
ihow-memory reindex          rebuild the SQLite index from Markdown
ihow-memory migrate-local-day  one-time: re-bucket UTC-named journal/event files to local-day (dry-run unless --apply)
ihow-memory upgrade          refresh the workspace's frozen server copy after updating the package (then restart the runtime)
ihow-memory rescue           reinstall + probe the workspace runtime through a freshly downloaded package; optionally repair one runtime registration
ihow-memory proof            one-command governed-loop proof in a throwaway space
ihow-memory benchmark        deterministic local proof of the verify-first guarantees (the three-color verdict discriminates; the floor blocks junk) — re-run for the same result
ihow-memory feedback         print a prefilled GitHub issue + redacted diagnostics
ihow-memory reset            remove a managed demo space (requires --space)
ihow-memory console          read-only local web UI [--port 8788]
ihow-memory telemetry        on | off | status — anonymous counters, OFF by default

Defaults: root ~/.ihow-memory; space derived from the current directory unless --space is given. Run npx ihow-memory --help for full flags.

The console is read-only, loopback-only, and single-user / trusted-machine by design — there is no auth token yet, so do not run it on a shared or multi-user host.

Safe Memory Gardener (alpha.24)

Safe Memory Gardener adds a review-first organize/export path for local workspaces:

npx ihow-memory organize --scope project --draft --json
npx ihow-memory export-vault --from-draft <draft_id> --format markdown

organize scans in-scope Markdown memory, writes a deterministic JSON draft under gardener/drafts/, links every evidence-backed item to source files and line numbers, flags duplicate/stale-looking claims for manual review, records a memory.organized audit event, and never rewrites curated memory. export-vault renders that draft as an Obsidian-compatible Markdown digest under gardener/exports/, runs the redaction/secret detector on the rendered Markdown, preserves evidence links, and records a memory.exported audit event.

The exported Markdown is a view/editor artifact only: it is not the source of truth, and editing it does not update governed memory. The source of truth remains the governed Markdown memory store plus the append-only audit trail. This alpha.24 feature is deliberately narrow; it does not claim full enterprise memory policy automation (no RBAC/ABAC, namespace leak matrix, adapter framework, admin UI, or durable retention automation).

See docs/safe-memory-gardener.md for the command contract and the sanitized enterprise-style fixture.

Memory layout and write boundaries

A managed space is plain files:

~/.ihow-memory/<space>/
  memory/
    candidate/inbox/     # agent proposals land here, never durable by themselves
    scopes/<scope>/      # promoted, durable Markdown
    _events/             # append-only audit log (ndjson)
  history/               # archived candidates after durable promote
  index.sqlite           # FTS index (rebuildable via reindex)
  index-manifest.json

You can also point iHow Memory at an existing Markdown directory without moving it:

npx ihow-memory doctor --memory-root <memory-root> --state-root <state-root>

In that mode the write boundary is strict: existing durable Markdown is read-only by default; candidates go under memory/_mcp/candidates/, staged promotes under memory/_mcp/promoted/, audit events under memory/_mcp/_events/; SQLite state stays under <state-root>, outside the memory root. Durable writes into the existing tree happen only through durable-promote, which refuses to run without an explicit --dry-run (prints the full plan) or --real-write.

Diagnostics, feedback, reset, uninstall

Doctor report you can share. npx ihow-memory doctor --runtime <runtime> --share-diagnostics prints a redacted report: local paths replaced with placeholders, secret-like values removed, memory content omitted. It is printed locally and never uploaded.

Feedback. npx ihow-memory feedback --runtime <runtime> prints a prefilled GitHub issue URL, a Markdown template and a redacted doctor summary. Nothing is submitted automatically.

Reset. npx ihow-memory reset --space <name> removes a managed space. It requires an explicit --space, only removes managed spaces, and refuses --memory-root — it cannot delete an existing shared memory root.

Uninstall.

1. Remove the ihow-memory entry from the runtime: claude mcp remove ihow-memory --scope user, codex mcp remove ihow-memory, or edit ~/.cursor/mcp.json (a *.ihow-bak-* backup sits next to it if connect wrote it).
2. Delete demo spaces with npx ihow-memory reset --space <name>.
3. If installed globally: npm uninstall -g ihow-memory.
4. Delete any custom state root only after reviewing its contents.

Troubleshooting

• A write was rejected as secret-like but isn't. The pre-write check is deliberately conservative (it pattern-matches tokens/keys/credentials). Rephrase to drop the secret-shaped substring, or keep the value out of memory entirely. Auto-capture redacts rather than rejects, so this affects manual write-candidate / promote.
• search finds nothing you just wrote. The FTS index rebuilds on write, but if it looks stale run npx ihow-memory reindex to rebuild from Markdown. Confirm the index status with npx ihow-memory status.
• doctor flags node:sqlite. You need Node.js ≥ 22.12 (the version that ships node:sqlite). Check with node -v.
• Hook installed but nothing captured (Claude Code). Restart Claude Code after install-hook so it loads the settings. The cooperative Stop hook depends on the agent honoring the prompt; the deterministic SessionStart floor only fires for a previous session that ended without a cooperative journal (so a session that already journaled is correctly skipped). Inspect outcomes with npx ihow-memory audit.
• Codex hooks installed but not firing. Restart Codex after connect --runtime codex --easy / install-hook --runtime codex. If Codex asks you to review hooks, open /hooks and trust the iHow Memory command hooks; writing hooks.json is the installation step, while Codex still owns the trust gate.
• connect --auto across projects only backs up one. Floor capture is single-cwd (see Limitations).
• Old hook points into a cleared npx cache. Re-run npx ihow-memory setup (or install-hook for that workspace). It moves only strictly identified iHow entries into canonical hook groups, removes duplicate iHow entries, and points them at the workspace-frozen .runtime/cli.js without replacing third-party hooks. Hook argv are shell-escaped, including workspaces whose paths contain spaces, quotes, $, or backticks.
• Turn prompt recall back off after it was installed. Re-run install-hook --no-recall (or setup --no-recall). It removes only iHow's managed UserPromptSubmit recall entry and preserves third-party prompt hooks.
• Setup refreshed the frozen runtime bundle. The bundle is integrity-stamped, staged, and validated before an atomic .runtime / .runtime.previous generation swap; the stable .runtime/cli.js bootstrap and per-space semantic.json opt-in are preserved. Setup reports the affected registered runtime as requiring reload/restart instead of claiming no changes. If an official Claude/Codex CLI replacement add fails, setup restores the exact previous registration when possible and reports any failed rollback as a real mutation.
• The local frozen runtime is damaged or its updater cannot start. Run npx ihow-memory rescue from the target workspace. Add --runtime opencode (or another supported runtime) only when that host's saved registration also needs repair. Rescue keeps the last self-verifying generation active when the new server probe fails.
• Windows. Use WSL; native Windows is experimental. Native installs fail closed on unsafe shell metacharacters rather than emitting an injectable hook command.

Proactive memory

The MCP tools are available to any client, but agents use memory only if they decide to. iHow Memory
adds runtime-specific layers where the host exposes stable hooks or instruction files:

• Skill — recall + record discipline. ihow-memory install-skill (or connect --runtime claude-code --install-skill) installs a thin policy layer (skills/ihow-memory/SKILL.md)
  that nudges Claude Code to search at the start of a task and record a candidate after a decision or
  handoff. It changes when memory is used, not the mechanism. Other runtimes get the same nudge from
  the MCP tool descriptions.
• Claude Code session-end auto-capture (cooperative) — experimental. connect --runtime claude-code --install-hook adds a
  Stop hook that, at session end, asks the in-session agent to record a handoff into the low-weight
  journal lane via memory.journal. It is best-effort (re-prompts as the session grows, stops once
  an entry is recorded), project-scoped by default (--global-hook for user-wide), and reversible
  (ihow-memory audit / rollback).
• Next-session floor (deterministic) — experimental. The same Claude Code install-hook also wires a
  SessionStart hook: when a new session starts, it floors the previous session deterministically iff
  that session ended without a cooperative journal. It parses the prior transcript, composes a
  last-substantive-segment summary within a locked scope (assistant text + file paths + command binary
  names + first prompt — never tool output, never raw shell), redacts it, and writes a low-weight,
  auditable, rollback-able journal entry. It is the safety net under the cooperative nudge: single-cwd,
  silent (it only captures — the floor itself injects nothing), and never throws. Offline evaluation on 22 real
  historical transcripts passed the backstop quality gate; live natural floor hits remain under dogfood
  because cooperative capture currently covers all observed sessions.
• Codex native hooks — experimental. connect --runtime codex --easy (or install-hook --runtime codex)
  writes ~/.codex/hooks.json with SessionStart + UserPromptSubmit hooks. SessionStart adds the same
  resumable-session pointer and triggers the Codex capture-floor sweep at thread boundaries while keeping
  the normal idle gate; UserPromptSubmit runs the same bounded, relevance-gated recall path. Codex Stop is
  not installed by default yet because Codex documents Stop as turn-scoped, so treating it as "session end"
  would be too noisy. After install, restart Codex and use /hooks to review/trust the command hooks if
  Codex prompts for approval.

iHow Memory — continuity protocol (alpha.22)

1. Thread start: call memory.context_probe({eventHint:'session_start', cwd, runtime:'workbuddy'}). Read returned packet. Treat narrative as UNVERIFIED — verify anchors before acting.
2. User says 继续/进度/上次/接手/之前/Codex/Claude/OpenClaw: call memory.context_probe({eventHint:'prompt', cwd, promptDigest:'<summary>'}) before answering.
3. Task done: call memory.context_probe({eventHint:'session_end', cwd}). If action='journal', call memory.journal with a brief entry.
4. If you forgot steps 1-3, no data loss — next session_start will detect stale marker and catch up.
5. context_probe does NOT auto-write for no-hook runtimes. You must call memory.journal yourself when action='journal'.

For no-hook runtimes, session_end means task completion or delivery, not process close. For multi-agent work, use the Harness Contract: OpenClaw/human as Planner, Codex-style runtimes as Generators, Hermes-style reviewers as Evaluators, and WorkBuddy-style no-hook runtimes as cooperative reviewers that return structured review packets instead of being assumed callable.

Experimental & Claude Code-first. Auto-capture is two layers: a cooperative Stop-hook nudge (whether
an entry is written depends on the agent following the prompt) and a deterministic SessionStart floor
backstop that captures the prior session when the nudge was not honored. Both write
low-weight, unreviewed notes — use promote / durable-promote for trusted long-term memory. The
floor is offline-validated as a backstop; it is not yet promoted to a primary/default-weight path, and
recall (reading memory back into a new session) is on by default and relevance-gated (off-topic prompts get nothing). Since alpha.19 it surfaces reviewed decisions and auto-captured soft facts (preferences, configs) seamlessly, while unverified status claims ("all green") and risky behavior-priors ("skip approval") are excluded from the ambient default surface — ask about status explicitly and the unverified note is shown. Output is one seamless bounded <recalled-memory> reference fence, not per-item trust tags. Remembered something wrong? ihow-memory forget <what you'd say> stops it surfacing everywhere, reversibly (remember undoes it). Skip hook installation with --no-recall, disable runtime injection with IHOW_RECALL_OFF=1, or restore reviewed-only with IHOW_RECALL_AUTO_DEFAULT=0. IHOW_RECALL_INCLUDE_AUTO=1 additionally admits engine-anchored auto facts, but never bypasses behavior safety or status-intent gates.

Examples

Runnable, self-contained walkthroughs live in examples/, including the short verify-first handoff demo. All examples use synthetic data only.

Privacy

• The open-source core runs locally: no account, no required network calls, cloud and sync are disabled and report as such in status and doctor.
• Metrics are off by default and require an explicit three-way consent choice or ihow-memory telemetry on. Noninteractive and --json setup never prompt or save a consent decision. When enabled, only versioned allowlisted event names, a random installation ID, timestamps, and allowlisted categorical runtime/error values can enter the bounded local queue; memory, prompts, queries, paths, git data, user/host names, and hardware identifiers cannot. No upload endpoint is built in. A network request requires both an explicitly configured credential-free HTTP(S) endpoint and the user's manual ihow-memory telemetry flush; telemetry off removes the queue and installation ID. See the metrics and privacy contract.
• Diagnostics are redacted by design; memory content is never included. feedback only prints a template — you decide whether to open the issue.

Hosted runtime

A hosted runtime is not included in this npm package or this repository.

Status

Stable release candidate 0.1.0 (local release-ready only — the npm badge above shows the latest published version; see CHANGELOG.md). Package identity is stable, while runtime evidence remains deliberately bounded: Claude Code is dogfooded daily and has the richest native-hook path; Codex has native SessionStart / PreCompact / UserPromptSubmit hooks plus a proactive AGENTS memory loop; OMP has a managed lifecycle extension and readable local transcripts; Hermes has packaged lifecycle and compaction adapters; the separately published DSH adapter has one-machine Host smoke against official 0.1.1-rc.2; the other runtimes have the narrower evidence recorded in Runtime support. Node >= 22.12 is a hard requirement (node:sqlite). Validated on macOS and Linux; native Windows is experimental (supported path: WSL). The npm package contains the compiled CLI, stdio MCP server, read-only local console, OMP lifecycle extension, packaged Hermes adapters, DSH Core contract, privacy contract, and evidence-first release assets. Experimental surfaces may still change.

Stable 0.1.0 engineering detail: promotes the verified Alpha.34 surface, including project-scoped automatic DSH session-start and no-hook startup handoff injection. Explicit memory.continue still supports cross-project discovery. The bounded DSH Host adapter API, hashed activation evidence, and ACTIVATION_COMPLETION_UNATTESTED boundary remain unchanged; Core publication alone does not install, update, or activate dsh-ihow-memory. npm latest is the source of truth for stable package availability; next is reserved for future prereleases.

Alpha.31.2 engineering detail: makes package updates recoverable without turning user configuration into release state. Claude Code/Codex hooks keep a byte-stable .runtime/cli.js bootstrap while implementation bytes move to cli-runtime.js; a verified upgrade refreshes legacy activation evidence once without rewriting correct Hook files, then later implementation-only upgrades leave Hook config and activation generation unchanged. Runtime replacement uses two self-verifying generations and restores the exact previous generation if the new MCP server fails its probe. upgrade --runtime <name> provides bounded repair for a stale host registration, and the fresh-package rescue entry can recover a damaged frozen updater. Alpha.31.1's WorkBuddy effective-path, Codex least-privilege/transactional rollback, and zero-runtime-dependency fixes remain included. This proves the documented update and recovery contracts—it does not claim every host lifecycle is ACTIVE; doctor may still report TOOLS ONLY, READY — WAITING FOR FIRST ACTIVITY, or NEEDS REPAIR where lifecycle evidence is absent. npm latest is the source of truth for stable package availability; publication does not itself update a frozen runtime or imply production certification. The Alpha.31 review-first boundaries remain unchanged: continuous consolidation is report-only and never automatically rewrites authoritative memory; Grounded Media reports only EQUAL_UNTRUSTED; Activity Ledger COMMITTED does not imply task success.

Install and update. Fresh installs use npx ihow-memory setup. A connected workspace keeps a frozen runtime bundle, so existing installations use npx ihow-memory upgrade and then restart the affected runtime; use npx ihow-memory rescue when the frozen updater is damaged. Publication alone does not replace an already-running frozen runtime.

Limitations

• Floor capture is single-cwd. The SessionStart floor backs up only its designated workspace/cwd. If you connect --auto across multiple projects sharing one workspace, the floor covers one cwd; broad multi-cwd rollout is pending further dogfood.
• Default retrieval is lexical, not semantic. The shipped default is zero-dependency FTS5 lexical search. The vector + lexical hybrid (behind the published recall figures) is an optional local provider, not in the out-of-the-box binary.
• Auto-tier memory is machine-judged, not human-reviewed. Since alpha.19 relevant auto-captured SOFT facts do surface by default — but behind measured guardrails: status/completion claims and actionability-bypass priors are excluded from the ambient surface (red-team gated), the journal/floor lanes are still never auto-injected, and IHOW_RECALL_AUTO_DEFAULT=0 restores reviewed-only. The keyword guardrails are deliberately broad, not a perfect classifier — a wrongly held-back soft fact just doesn't surface, and ihow-memory forget reversibly silences anything that surfaced wrongly. Use promote / durable-promote for trusted long-term memory.
• Storage grows without bound (no rotation/compaction/GC yet). Journals, the audit ndjson log and *.ihow-bak-* backups currently accumulate, and every write rebuilds the full FTS index — rotation/compaction/GC is planned but not shipped. Fine for normal use; heavy long-running use will pile up. Manual mitigation: occasional ihow-memory reindex and pruning of old backups by hand.
• Windows native is experimental (use WSL); only macOS and Linux are validated lanes.

Links

• Website: ihowmemory.com
• Format & conformance (mechanism): iHow1/ihow-memory-standard
• Benchmark evidence manifest: conformance/evidence/longmemeval-s-2026-05-11.md
• npm package: npmjs.com/package/ihow-memory

Contributing

See CONTRIBUTING.md (DCO sign-off required — DCO.md). Security reports: SECURITY.md — please do not open public issues for vulnerabilities.

License

Apache License 2.0 — see LICENSE and NOTICE. You may use, modify, fork, and distribute the Core commercially under that license, provided you comply with its conditions, including retaining applicable license, copyright, and attribution notices and prominently marking modified files. The Apache license does not grant rights to the iHow / iHow Memory names or logos; see TRADEMARK.md.

The separately distributed iHow Memory desktop application and related commercial services are proprietary products owned by iHow. They are not licensed under the Core's Apache-2.0 license; bundled open-source components retain their own licenses.