Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/ihow1/ihow-memory-core

Local-first shared memory for AI agents — zero-dependency, governed writes, citations, MCP. Source behind the ihow-memory npm package.
https://github.com/ihow1/ihow-memory-core

agent-memory ai-agents claude-code codex local-first mcp memory-handoff nodejs sqlite

Last synced: about 2 hours ago
JSON representation

Local-first shared memory for AI agents — zero-dependency, governed writes, citations, MCP. Source behind the ihow-memory npm package.

Awesome Lists containing this project

README 

          
# iHow Memory



> Local shared-memory runtime for heterogeneous coding agents — one git-auditable Markdown memory they share and hand off through.



[![npm version](https://img.shields.io/npm/v/ihow-memory.svg)](https://www.npmjs.com/package/ihow-memory)

[![CI](https://github.com/iHow1/ihow-memory-core/actions/workflows/ci.yml/badge.svg)](https://github.com/iHow1/ihow-memory-core/actions/workflows/ci.yml)

[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](./LICENSE)



[简体中文](./README.zh-CN.md)



**Requires Node.js >= 22.12 · macOS / Linux (alpha; Windows via WSL, native Windows experimental).** No account, no API key, no third-party runtime dependencies. (Node >= 22.12 is a hard requirement — the engine uses `node:sqlite`.)



**Who this is for:** best for git-using coding workflows, where the verify-first handoff gets the strongest anchors; usable beyond git too, with file-fingerprint anchors instead (see below).



iHow Memory is a local, shared-memory runtime for heterogeneous coding agents — one human-readable, git-auditable memory that Claude Code, Codex, Cursor and other MCP clients share and hand off through. Memory is plain Markdown on disk that you read, diff and roll back with git. A pre-write check rejects candidates that look like they contain secrets, every promote is an audited event, and agents leave a handoff candidate — current state, evidence, blockers, next step — that the next agent reads. Agents talk to it over a stdio MCP server; you use the same flow from the CLI.



## Why it is different



1. **Verify-first handoff — resume without re-briefing.** After `/clear`, or when a *different* tool picks up the work, run `memory.continue` (or `ihow-memory continue`). You get the prior session's handoff together with **live git anchors the receiver re-checks (GREEN / RED) before trusting the narrative** — so a fresh agent continues where you left off without you re-explaining, and without acting on a stale "done / shipped" claim. Other memory tools retrieve *facts*; this is a cross-tool resume with a built-in trust check. This is the point of iHow Memory. In a git repo you get the strongest verify-first anchors (branch / HEAD / dirty). In a non-git project, the handoff still works — you get the prior session's narrative plus file-fingerprint anchors (the receiver re-hashes the touched files to detect drift) — just without git's commit-level GREEN/RED.

2. **Cross-vendor by design.** One memory that Claude Code, Codex, Cursor, Tencent WorkBuddy, Claude Desktop, OpenCode, Hermes and OpenClaw can share — across vendors, on your machine, one command each. The big platforms have every reason to keep memory inside their own ecosystem; iHow is the neutral local layer between them. In this alpha only Claude Code is dogfooded daily; the others are single-machine real-app smoke, and Cursor and Claude Desktop are receive-only (they call the tools but cannot resume) — see [Runtime support](#runtime-support).

3. **Safe writes + governance.** Multiple agents share one memory, with writes serialized by a workspace lock so they never clobber each other. A pre-write check rejects candidates that look like they hold secrets (tokens, keys, credentials), and every promote is an audited event.

4. **Human-readable and yours.** Memory is plain Markdown you read, diff and roll back with git — no vendor lock-in, no black-box vector store, no account, no telemetry by default. Governance (candidate → review → promote) is available when your team needs it, not a forced step.



## Quickstart



### Fastest start — one command



```bash

npx ihow-memory@next setup

```



`setup` detects your installed agents, registers the `ihow-memory` MCP server with each, installs the Claude Code skill + auto-capture hook, injects a "call `memory.continue` on resume" instruction for the agents whose config supports it (WorkBuddy, OpenClaw, Hermes, OpenCode), and verifies with `doctor`. It is idempotent (safe to re-run), reversible (every edited config is backed up), and local-only. Prefer step-by-step? Use `connect` below.



### 1. Connect a single runtime



```bash

npx ihow-memory@next connect --runtime claude-code   # or: codex | cursor | workbuddy | claude-desktop | opencode | hermes | openclaw | vscode | gemini

```



`connect` provisions a managed workspace under `~/.ihow-memory` (space name derived from the current directory unless you pass `--space`) and registers the `ihow-memory` MCP server with the selected runtime:



- Claude Code and Codex are configured through their official CLIs (`claude mcp add-json`, `codex mcp add`).

- Cursor is configured by merging `~/.cursor/mcp.json`, with a timestamped backup of the existing file first; an unparseable config is never overwritten.

- To preview without changing anything, append `--dry-run`:



```bash

npx ihow-memory@next connect --runtime claude-code --dry-run

```



If you prefer to edit runtime config by hand, `npx ihow-memory@next init --runtime ` prints the exact MCP snippet instead of applying it.



### 2. Verify



```bash

npx ihow-memory@next doctor --runtime claude-code

```



`doctor` checks the Node version, `node:sqlite` availability, memory-root writability, runtime setup, retrieval-engine readiness and the index manifest, and confirms cloud/sync are disabled.



### 3. The governed loop in 60 seconds



This is the same flow agents use over MCP, run from your shell. The block is copy-pasteable as a whole:



```bash

npx ihow-memory@next init --space demo

CAND=$(npx ihow-memory@next write-candidate "Decision: ship weekly release notes." --no-auto-promote --space demo | sed -n 's/.*"path": "\([^"]*\)".*/\1/p')

PROMOTED=$(npx ihow-memory@next promote "$CAND" --scope team --title "Release notes cadence" --space demo | sed -n 's/.*"path": "\([^"]*\)".*/\1/p')

npx ihow-memory@next search "release notes" --space demo

npx ihow-memory@next read "$PROMOTED" --space demo

```



What you should see:



- `write-candidate` returns a candidate path under `memory/candidate/inbox/` — proposed, not yet durable. The `--no-auto-promote` flag makes the **two-step gate explicit** so you can see it; **without it, clean writes auto-promote in one step** (the engine floor picks the yellow sub-tier), and `write-candidate` then returns the already-durable path directly;

- `promote` returns the promoted path under `memory/scopes/team/` plus an `eventId` — the audit event;

- `search` and `read` return JSON whose `citation` field points at the exact Markdown file behind the answer.



Clean up the demo space when done:



```bash

npx ihow-memory@next reset --space demo

```



One-command version of the same proof, in a throwaway space:



```bash

npx ihow-memory@next proof

```



### 4. Resume without re-briefing — the payoff



After a `/clear`, or in a brand-new session, pick up the previous session's work instead of re-explaining it:



```bash

npx ihow-memory@next continue            # or pass a repo keyword: continue 

```



`continue` finds the project you were in (from the files you edited last session) and prints a handoff: the project's **live git anchors** — branch / HEAD / dirty, the only facts — plus the previous session's own summary, quoted and marked **UNVERIFIED**. The receiver re-checks those anchors against the live repo before trusting anything: **GREEN** (they match) → continue smoothly with a small step; **RED** (they conflict, or the narrative asks for a risky/irreversible action) → stop and diagnose. In Claude Code you can simply say "继续" — a fresh session even reminds you it can resume.



### Updating



`connect` freezes a runtime copy of the server into the workspace, so `npm update` does **not** refresh the running MCP server by itself. After updating the package, run `npx ihow-memory@next upgrade` (then restart the runtime) to refresh the connected server. `doctor` warns when the connected server is older than the installed package (a "runtime-bundle" check).



## Runtime support



`connect` registers the MCP server for ten 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 alpha.



| Runtime | connect | resume reader | Notes |

| --- | --- | --- | --- |

| Claude Code | ✓ (`claude mcp add-json`) | ✓ | real-app + ongoing dogfood; skill + auto-capture hooks |

| Codex | ✓ (`codex mcp add`) | ✓ | single-machine real-app smoke |

| OpenClaw | ✓ (`~/.openclaw/openclaw.json`) | ✓ | single-machine real-app smoke (memory.continue + git preflight) |

| Hermes | ✓ (`hermes mcp add`) | ✓ (JSON + `state.db`) | single-machine real-app smoke |

| OpenCode | ✓ (`~/.config/opencode`) | ✓ (`opencode.db`) | single-machine real-app smoke |

| WorkBuddy | ✓ (`~/.workbuddy/mcp.json`) | ✓ | single-machine real-app smoke |

| Cursor | ✓ (merges `~/.cursor/mcp.json`) | ✗ | receiver-only — Cursor keeps chats in a binary IndexedDB, not readable for resume |

| Claude Desktop | ✓ | ✗ | receiver-only (chat app; no resumable local sessions) |

| VS Code (Copilot) | ✓ (user `mcp.json`, `servers` key) | ✗ | receiver-only — reaches `memory.search`/`read`/`continue`; no readable local session store to resume from |

| Gemini CLI | ✓ (`~/.gemini/settings.json`) | ✓ (`~/.gemini/tmp/*/logs.json`) | passive reader of Gemini's on-disk **user-prompt log** (Gemini records no assistant turns) → session topic + git anchors; manual `GEMINI.md` nudge. Verified against real local data |

| Cline (VS Code) | — (add via Cline's own MCP settings) | ✓ (`globalStorage` / `~/.cline/data`) | passive reader of `tasks//api_conversation_history.json`; cwd from `environment_details`. Fixture-tested, not yet real-app smoke |



The MCP tools and governed loop are runtime-agnostic. The proactive skill + auto-capture hooks are Claude Code-specific; the resume nudge is auto-injected for the runtimes whose config exposes an instructions file (Claude Code, WorkBuddy, OpenClaw, Hermes, OpenCode).



### 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](./docs/handoff-schema.md) (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@next 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@next 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@next 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@next 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@next init --runtime ` prints the exact snippet to paste by hand instead of writing it, and `npx ihow-memory@next doctor --runtime ` 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`):



| Metric | Default FTS5 (shipped, zero-dependency) |

| --- | --- |

| R@5 | **0.85** |

| R@10 | **0.85** |

| MRR | **0.85** |

| tokens/query | **~5.7** |



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. That gap is exactly what an optional semantic provider is meant to lift.



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](https://arxiv.org/abs/2410.10813)) — on the **same default FTS5 binary**:



| Metric (default FTS5 · global-corpus · recall_any@k) | LongMemEval-oracle |

| --- | --- |

| Recall@5 | **0.788** |

| Recall@10 | **0.857** |

| MRR | **0.651** |



`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 lifts.



#### 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:



| Figure | Provenance |

| --- | --- |

| recall_all@10 = 1.0, ndcg_any@10 ≈ 0.946 | **OPT-IN semantic sidecar** (not the default binary), **EXPERIMENTAL hybrid lane**, from an **EXTERNAL evidence manifest** (repo `iHow1/ihow-memory-standard`, dated 2026-05-11), **RETRIEVAL-STAGE recall only** (NOT end-to-end LLM-judged). |



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 the moat, 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:



```bash

ollama pull nomic-embed-text            # once

npx ihow-memory@next enable-semantic    # probes Ollama; writes /.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). On the in-repo fixture this lifts paraphrase recall from **2/5 → 5/5** (fused R@5 0.85 → 1.0); the default binary stays lexical-only with `capabilities.semantic=false` until you opt in.



Evidence manifest: [LongMemEval_S retrieval-stage run, 2026-05-11](https://github.com/iHow1/ihow-memory-standard/blob/main/conformance/evidence/longmemeval-s-2026-05-11.md).



## MCP tools



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



| Tool | What it does |

| --- | --- |

| `memory.search` | Search local memory with FTS. Returns citation path and snippet. |

| `memory.read` | Read a memory Markdown file by path. Returns exact content plus citation. |

| `memory.write_candidate` | Record a memory. Clean content auto-promotes into durable yellow tiers: verified, unverified, or flagged. Secrets and falsified anchors are rejected. |

| `memory.promote` | Explicit manual promote of a candidate into governed staging, with an audit event. |

| `memory.durable_promote` | Governed durable promote. Requires explicit `dryRun: true` or `realWrite: true`. |

| `memory.journal` | Append a low-weight, append-only journal entry (auto-capture lane). Searchable but ranked below curated memory. |

| `memory.forget` | One-gesture correction: tombstone the matching memory so it stops surfacing in search and recall everywhere. Reversible, audited, file untouched; human-reviewed entries need explicit confirmation. |

| `memory.remember` | Reverse a `memory.forget` — the entry surfaces again. |

| `memory.status` | Report workspace, retrieval provider, index and sync status. |



## CLI reference



```text

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) [--dry-run]

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 the hooks — Stop (cooperative nudge) + SessionStart (deterministic floor) + UserPromptSubmit recall (🟢 reviewed, on by default; --no-recall to skip) (Claude Code; --global-hook for user-wide)

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    citation-bearing local search [--limit n]

ihow-memory read       read one memory file with citation

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    append a low-weight auto-capture entry (searchable, ranked below curated)

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 )

ihow-memory forget   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   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 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@next --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.



## Memory layout and write boundaries



A managed space is plain files:



```text

~/.ihow-memory//

  memory/

    candidate/inbox/     # agent proposals land here, never durable by themselves

    scopes//      # 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:



```bash

npx ihow-memory@next doctor --memory-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 ``, 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@next doctor --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@next feedback --runtime ` prints a prefilled GitHub issue URL, a Markdown template and a redacted doctor summary. Nothing is submitted automatically.



**Reset.** `npx ihow-memory@next reset --space ` 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@next reset --space `.

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@next reindex` to rebuild from Markdown. Confirm the index status with `npx ihow-memory@next 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@next audit`.

- **`connect --auto` across projects only backs up one.** Floor capture is single-cwd (see Limitations).

- **npx cache cleared / hook command broke.** Installing from an `npx` cache path can be wiped; for a durable hook install globally (`npm i -g ihow-memory`) then re-run `install-hook`.

- **Windows.** Use WSL; native Windows is experimental.



## Proactive memory (Claude Code)



The MCP tools are available to any client, but agents use memory only if they decide to. iHow Memory

adds two layers to raise that on Claude Code:



- **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`](./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.

- **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, `next` only.** The same `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.



> **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 (`next` only) 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, fenced as reference. Remembered something wrong? `ihow-memory forget ` stops it surfacing everywhere, reversibly (`remember` undoes it). Disable recall with `--no-recall` or `IHOW_RECALL_OFF=1`; restore reviewed-only with `IHOW_RECALL_AUTO_DEFAULT=0`.



## Examples



Runnable, self-contained walkthroughs live in [`examples/`](./examples/) (numbered 01–03). 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`.

- Telemetry is **off by default** and opt-in (`ihow-memory telemetry on`). When enabled it records only a fixed allow-list — event name, runtime, package version, error type, timestamp — never memory content, file names, queries, paths or prompts. In the current alpha, events are appended to a local file (`~/.ihow-memory/telemetry-events.jsonl`) and are not uploaded anywhere.

- 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



Alpha prerelease (`0.1.0-alpha` line — the npm badge above shows the latest published version; see [CHANGELOG.md](./CHANGELOG.md)). Maturity is **alpha + single-machine real-app smoke**: only Claude Code is dogfooded daily; the other runtimes are single-machine real-app smoke, and Cursor and Claude Desktop are receive-only (they can call the tools but cannot resume). Node >= 22.12 is a hard requirement (`node:sqlite`). Validated daily on macOS and Linux; native Windows is **experimental** — the `packageDir` path bug is fixed and a `windows-latest` CI lane covers build + a connect/doctor reachability smoke + the full test suite, with WSL as the supported path. The npm tarball ships the compiled CLI, the stdio MCP server and the read-only local console; the TypeScript sources live in this repository. Expect breaking changes between alpha releases.



**Which version has what (dist-tags).** Prereleases publish under the `next` dist-tag; `npm install ihow-memory` resolves `latest`.



| dist-tag | auto-capture |

| --- | --- |

| `latest` | cooperative Stop-hook nudge only (depends on the agent honoring it) |

| `next` | adds the **deterministic SessionStart floor** backstop (single-cwd, low-weight, offline-validated), turns **recall on** (reviewed + guard-railed auto soft facts since alpha.19; status/bypass claims held back), and ships **one-gesture `forget`/`remember`** |



To try the floor backstop: `npm install ihow-memory@next`. A plain `npm install ihow-memory` stays on the conservative `latest`.



## 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](https://ihowmemory.com)

- Format & conformance (mechanism): [iHow1/ihow-memory-standard](https://github.com/iHow1/ihow-memory-standard)

- Benchmark evidence manifest: [conformance/evidence/longmemeval-s-2026-05-11.md](https://github.com/iHow1/ihow-memory-standard/blob/main/conformance/evidence/longmemeval-s-2026-05-11.md)

- npm package: [npmjs.com/package/ihow-memory](https://www.npmjs.com/package/ihow-memory)



## Contributing



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



## License



Apache License 2.0 — see [LICENSE](./LICENSE) and [NOTICE](./NOTICE). The iHow / iHow Memory names and logos are trademarks; see [TRADEMARK.md](./TRADEMARK.md).