# iHow Memory

> iHow Memory is an open-source, local-first memory layer for AI coding agents. Switch the AI, the session, or the person taking over and keep going — with verify-first handoff: a fresh agent re-checks git/file anchors before trusting the previous session's notes. Published on npm (`ihow-memory`, public alpha).

Website: https://ihowmemory.com/
Product (GitHub): https://github.com/iHow1/ihow-memory-core
npm: https://www.npmjs.com/package/ihow-memory
Open standard (GitHub): https://github.com/iHow1/ihow-memory-standard

## What it is

iHow Memory keeps a project's memory — decisions, constraints, preferences, handoff logs — as local, readable, editable Markdown, shared across AI coding agents. Its core difference from generic "AI that remembers facts": verify-first. After you switch tools, sessions, or people, a fresh agent re-checks whether the work actually changed (git/file fingerprint anchors) before trusting the prior notes — so it never confidently continues from stale or altered state.

It is a neutral, local layer between the big vendors' memory silos: one memory that Claude Code, Codex, Cursor, OpenCode, Hermes, OpenClaw and Tencent WorkBuddy can share. For teams and companies it doubles as a project knowledge base and the information hub / relay layer between people and AI.

## Key facts

- Open-source (Apache-2.0), published on npm as `ihow-memory` (public alpha).
- Local-first: data never leaves your machine; no cloud required; zero dependencies. Needs Node ≥ 22.12; macOS / Linux are validated daily, Windows via WSL (native Windows is experimental, covered by a windows-latest CI smoke).
- One-command connect for supported runtimes: Claude Code, Codex, Cursor, Claude Desktop, VS Code, Gemini CLI, OpenCode, Hermes, OpenClaw, and Tencent WorkBuddy. Fresh installs use `npx ihow-memory setup`; existing installations update with `npx ihow-memory upgrade`, and a damaged frozen updater can recover with `npx ihow-memory rescue`. npm `latest` points to `0.1.1`; npm `next` points to `0.1.1`. Stable installs use the unqualified package; `next` may diverge again for future prereleases. Publication does not replace an already-running frozen runtime.
- Memory is git-diffable, auditable Markdown; auto-captured entries can be rolled back via the CLI.
- Recall is on by default and safety-gated. Alpha.26 applies one bounded, relevance-gated, fail-closed selector across supported Claude hooks, Codex/no-hook context probes, and local recall preview/explanation. Deleted, unreadable, malformed, stale-rewritten, and symlink-replaced sources are excluded before injection; excluded/private content is represented by counts and reasons rather than leaked snippets.
- Alpha.27 adds bounded checkpoint drafts and immutable artifacts, native Claude Code/Codex PreCompact finalization, checkpoint-first continue, and crash-floor recovery. Checkpoint claims remain UNVERIFIED until live git/file anchors are recomputed.
- The alpha.27 npm surface includes the Hermes Plugin plus `ihow-memory-hermes-bridge`; merged evidence is described only as HOST VERIFIED/READY, not independently certified ACTIVE.
- Alpha.27.1 fixes explicit workspace-root precedence over ambient memory-root variables, makes the test runner remove ambient memory/Hermes/Codex routing roots from child processes with subprocess proof, and separates parent harness timing from the production PreCompact watchdog; it does not rewrite existing memory roots.
- One-gesture correction: `ihow-memory forget <what you said>` tombstones a memory so it stops surfacing in search AND recall everywhere — reversible with `ihow-memory remember`, fully audited, the file itself is never deleted.
- Optional semantic search lane (`enable-semantic`): additive paraphrase retrieval through a user-provided local Ollama embedding sidecar; the default install stays zero-dependency lexical FTS5. A working embedding probe proves readiness, not quality. Real-model observations are explicitly model/fixture/version/path-specific, lexical fallback is visible, and controlled synonym-oracle gains are labeled architecture proof rather than learned-model evidence.
- Backed by an open standard (`ihow-memory-standard`) for memory-handoff conformance: 5 reliability scenarios and 4 interface semantics (events · context · writeback · audit).

## Differentiator

Not "another memory store." The point is verified continuity — re-check the work after a handoff, then decide whether to trust it.

## Links

- Connect guide: https://ihowmemory.com/connect-guide.html
- Release history: https://ihowmemory.com/changelog.html
- Product repo: https://github.com/iHow1/ihow-memory-core
- npm package: https://www.npmjs.com/package/ihow-memory
- Open standard: https://github.com/iHow1/ihow-memory-standard

## Preferred description

iHow Memory is an open-source, local-first, verify-first memory layer for AI coding agents (npm: `ihow-memory`, public alpha) — switch AI / sessions / people without losing the thread; it re-checks the work before trusting prior memory.

## 2026-09 Core 0.1.1 (current stable release)

- Lexical retrieval excludes recognized Core-generated operational metadata while preserving original Markdown, business dates, and governance eligibility. Legacy indexes migrate transactionally; tied ranks have stable path ordering.
- Workspace and activation-ledger locks recover aged empty or malformed records. Owner records are initialized before atomic publication; live owners remain protected. Same-directory hard links are required; interrupted recovery guards require operator recovery after owner verification.
- Upgrade frozen installations with `npx ihow-memory upgrade`, then restart their hosts. Separately pinned adapters need their own dependency upgrade and verification; publication alone does not establish loaded runtime state.
- Release: https://github.com/iHow1/ihow-memory-core/releases/tag/v0.1.1

## 2026-09 Core 0.1.0 (first stable release)

- First stable Core release, published 2026-09-05. The source CHANGELOG date is 2026-09-01. Release: https://github.com/iHow1/ihow-memory-core/releases/tag/v0.1.0
- Includes managed OMP lifecycle, bounded memory reads, the separately consumed DSH host contract, and project-scoped automatic startup handoffs. Explicit memory.continue retains cross-project discovery.
- Stable setup: `npx ihow-memory setup`; update: `npx ihow-memory upgrade`; damaged updater: `npx ihow-memory rescue`. Restart and verify the affected host after updating.
- Core publication does not install or activate the independently versioned dsh-ihow-memory adapter. That adapter needs its own pinned dependency, upgrade and host verification.
- Evidence remains limited to documented single-machine smoke and dogfood. Replayable local lifecycle completion remains ACTIVATION_COMPLETION_UNATTESTED; stable release identity does not claim production certification or complete enterprise multi-tenant administration.
- Full item-by-item Chinese and English release notes, including alpha.32–34: https://ihowmemory.com/changelog.html

## 2026-08 alpha.31.4 (historical release)
- Privacy by explicit consent: optional anonymous metrics remain off by default, noninteractive and JSON execution never prompts, there is no built-in upload endpoint, and transport requires both an explicit credential-free endpoint and a manual `telemetry flush`.
- Hermes installation closure: setup/connect installs both packaged adapters, enables the lifecycle plugin, selects the explicit compaction `MemoryProvider`, and rolls back the transaction on adapter/config/MCP failure.
- Host-truth hardening: replayable managed-hook completion remains `READY — WAITING FOR FIRST ACTIVITY` with `ACTIVATION_COMPLETION_UNATTESTED`; it does not become `ACTIVE` without a non-replayable host provenance boundary.
- Queue and opt-out hardening: consent, queue, record, flush, and off transitions are serialized across local processes; `telemetry off` removes the queue, installation ID, and bounded atomic-write crash remnants.
- Historical channel state at the 2026-08-18 release: `next` was `0.1.0-alpha.31.4` and `latest` was `0.1.0-alpha.31.2`. These are not the current channel pointers; reproduce historical versions only with an exact version pin.

## 2026-07 alpha.31.2
- Stable Hook bootstrap: Claude Code/Codex keep a byte-stable `.runtime/cli.js`, while release implementation bytes live in `.runtime/cli-runtime.js`; legacy activation evidence migrates once without rewriting correct Hook files.
- Two-generation runtime activation: a new generation is staged and integrity-checked before the atomic swap, then MCP is probed; probe failure restores the exact previous self-verifying generation.
- Recovery paths: existing installations use `upgrade`; `rescue` works through a freshly downloaded package when the frozen updater is damaged; `--runtime <name>` backs up and repairs only one stale host registration.
- Agent-facing update guidance is deterministic: explicit update/repair requests use `upgrade`, `rescue`, and `doctor` instead of manual Hook/MCP edits. Publication alone does not switch an already-running frozen runtime; restart the affected host after a successful update.
- Published on npm under `next` as `0.1.0-alpha.31.2` with registry signature and SLSA provenance. These are tested update/recovery contracts, not proof that complete lifecycle automation is ACTIVE in every host.

## 2026-07 alpha.31.1
- Runtime-adapter safety hotfix: WorkBuddy user-scope setup now writes `~/.workbuddy/.mcp.json`, preserving existing servers with backup, atomic replacement, dry-run, and malformed-JSON fail-closed behavior.
- Codex least privilege and rollback: setup adds only missing approvals for read-only handoff tools, preserves existing stricter policy, and restores the prior registration plus exact TOML bytes if approval editing fails.
- Frozen-runtime integrity: the vendored BSD-3-Clause TOML parser keeps the npm package self-contained with zero external runtime dependencies.
- Published on npm under `next` as `0.1.0-alpha.31.1` with registry signature and SLSA provenance. These are tested setup contracts, not proof that complete lifecycle automation is ACTIVE in every host; existing live runtimes must still be verified separately.

## 2026-07 alpha.31
- Deterministic continuity: content-bound turn receipts, ordinary-language governed capture, checkpoint evidence prerequisites, and deeper Hermes lifecycle integration.
- Measured semantic activation: real `bge-m3` / 1024-dimension local Metal evidence covers English/Chinese paraphrase recall, no-answer, freshness/privacy, restart identity, and latency boundaries; this is fixture/model/path-specific evidence, not a universal quality claim.
- Review-first maintenance: the recurring organize tick is idempotent, receipt/TTL/lock-bound, and report-only; proposal states stop at APPROVED/REJECTED/EXPIRED with no APPLIED or authoritative-write path.
- Privacy-bounded evidence: Grounded Media stores metadata only and reports `EQUAL_UNTRUSTED`; the bounded Activity Ledger records observer state, and `COMMITTED` does not mean task success.
- Published on npm under `next` as `0.1.0-alpha.31` with provenance. Publication does not imply runtime activation or production certification; the separately installed Hermes/live runtime must be verified independently.

## 2026-07 alpha.27
- Checkpoint Core: bounded mutable drafts finalize into immutable hash-addressed artifacts with atomic publication, audit evidence, dedup/supersedes, and fail-closed validation.
- Native PreCompact: Claude Code and Codex finalize transcript-free checkpoints under an 8-second internal fail-open watchdog and 10-second host hook timeout.
- Checkpoint-first continue and crash floor: resume prefers complete then partial/shadow checkpoints before transcript/floor candidates; stale valid drafts can be recovered as bounded partial checkpoints.
- Verify-first hardening: same-HEAD statusHash drift is RED, missing statusHash fails closed, and git anchor collection disables repository-controlled textconv/fsmonitor execution.
- Hermes package surface: plugin descriptor, Python plugin, and bounded Node bridge are included in the 64-file npm package; lifecycle wording remains HOST VERIFIED/READY.
- Scope boundary: alpha.27 remains an alpha release. Checkpoint narratives are unverified until live anchors are checked; no production certification or independently authenticated Hermes ACTIVE claim is made.

## 2026-07 alpha.27.1
- Workspace isolation: explicit managed `root` wins over ambient `MEMORY_ROOT` / `IHOW_MEMORY_ROOT`; explicit `memoryRoot` remains authoritative.
- Hermetic tests: child test processes receive a sanitized environment, verified by a real subprocess integration test.
- PreCompact harness: success-path parent timeout is above the 8-second internal watchdog and 10-second host envelope; the strict fail-open production contracts are unchanged.
- Published on npm under `next` as `0.1.0-alpha.27.1` with SLSA provenance; this remains an alpha release, not production certification.

## 2026-07 alpha.26
- Recall Quality Gates v1: shared bounded relevance selection and fail-closed source validation across supported runtime recall paths.
- Prompt-injection boundary hardening: deleted, unreadable, malformed, stale-rewritten, and symlink-replaced memory sources are excluded before prompt injection.
- Private recall diagnostics: `ihow-memory recall-preview <prompt>` explains why candidates would be included or excluded without printing excluded/private memory content.
- Cross-runtime parity: Claude hooks, Codex/no-hook `context_probe`, and recall preview/explanation use the same core selection semantics rather than drifting independently.
- Semantic readiness and claim honesty: real-model quality lift, neutral measured paraphrase lift, and controlled architecture proof are separate machine/reporting fields; zero/negative/fallback runs cannot claim a gain.
- Official CLI setup hardening: stricter whole-result parsing, fail-closed uncertain-state handling, and idempotency coverage for Claude setup paths.
- Scope boundary: alpha.26 did not claim universal semantic quality, production certification, proactive context-load monitoring/checkpointing, or complete status/behavior classifier coverage; alpha.27 supersedes the checkpointing limitation.
- Previous alpha.25 enterprise governance gates, alpha.24 Safe Memory Gardener, and alpha.22 Automation Reliability Pass remain included.

## 2026-07 alpha.25
- Enterprise Gate Matrix v0 for Safe Memory Gardener: deterministic local gates for project/public/private/source/audit boundaries.
- Audit completeness baseline v0 for candidate write, promote, journal rollback, organize, and export.
- Source Adapter Contract v0: fixture/markdown-only contract layer for validating source-lane imports without connecting real external systems or reading credentials.
- Blocked export fail-closed policy v0: drafts with blocked items refuse Markdown export and audit the refusal.
- Durable write dedupe/stale/supersede baseline v0: review-first metadata only; no silent overwrite, delete, archive, or curated-memory rewrite.
- Scope boundary: alpha.25 is still alpha governance infrastructure, not full enterprise RBAC/ABAC and not a real Feishu/Obsidian/ima adapter release.
- Previous alpha.24 Safe Memory Gardener organize/export MVP and alpha.22 Automation Reliability Pass remain included.