sessionmem 1.1.2 → 1.3.0

package/README.md

@@ -1,18 +1,41 @@
 # sessionmem
 
-[![npm version](https://img.shields.io/npm/v/sessionmem.svg)](https://www.npmjs.com/package/sessionmem) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/catfish-1234/sessionmem/blob/main/LICENSE)
+<p align="center">
+  <img src=".github/sessionmem-logo.svg" alt="sessionmem" width="480">
+</p>
 
-**Give your AI coding assistant a memory that lasts beyond one conversation — stored entirely on your own computer.**
+<p align="center">
+  <a href="https://www.npmjs.com/package/sessionmem"><img src="https://img.shields.io/npm/v/sessionmem.svg" alt="npm version"></a>
+  <a href="https://github.com/catfish-1234/sessionmem/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+</p>
 
-`sessionmem` is a local-first memory layer for AI coding assistants (Claude Code, Cursor, Codex, Cline, Windsurf, Antigravity, QCoder, and any other tool that speaks [MCP](https://modelcontextprotocol.io)). It watches your coding sessions, writes down the important stuff (decisions, warnings, facts about your project), and quietly reminds the assistant about it the next time you start working — without you having to repeat yourself.
+**85.6% fewer tokens. Every session starts knowing your codebase. Stored entirely on your machine.**
 
-Everything happens on your machine. There is no account to create, no cloud service to trust, and no data that leaves your computer unless you explicitly turn that on.
+```
+New session. Claude starts fresh.
+
+WITHOUT sessionmem:
+  You explain the stack. The JWT bug from last week.
+  The Stripe migration that's halfway done. The billing code to stay away from.
+  Same questions. Different day.
+
+WITH sessionmem:
+  [warning] JWT blacklist must be checked before issuing new tokens. Fixed PR #47.
+  [decision] Stripe migration ~50% done. Do NOT use /lib/billing-v1.
+  [fact] Stack: TypeScript, Next.js, Postgres.
+
+  Claude: "Looks like you're mid-Stripe migration. Where do you want to pick up?"
+```
+
+`sessionmem` is an MCP server that watches your coding sessions and stores what actually mattered -- decisions, warnings, things that would bite you if Claude forgot them. At the start of each new session it injects the relevant bits automatically. Works with Claude Code, Cursor, Cline, Codex, Windsurf, and anything that speaks [MCP](https://modelcontextprotocol.io).
+
+Everything stays on your machine. No account, no cloud, no data leaving your computer unless you explicitly turn that on.
 
 ---
 
 ## Quickstart
 
-No programming experience needed for these steps — just a terminal (Command Prompt, Terminal, or PowerShell) and [Node.js](https://nodejs.org) installed.
+No programming experience needed. You just need a terminal (Command Prompt, Terminal, or PowerShell) and [Node.js](https://nodejs.org) installed.
 
 ### 1. Install sessionmem
 
@@ -30,8 +53,8 @@ sessionmem install
 
 This does three things:
 - Tells your AI tool's MCP host about `sessionmem` so it can be launched automatically.
-- Creates a config file at `~/.sessionmem/config.json` with safe, privacy-respecting defaults — **only if one doesn't already exist.**
-- Injects instructions into `~/.claude/CLAUDE.md` so Claude Code knows about sessionmem's tools and uses them proactively (idempotent — safe to re-run).
+- Creates a config file at `~/.sessionmem/config.json` with safe, privacy-respecting defaults, but only if one doesn't already exist.
+- Injects instructions into `~/.claude/CLAUDE.md` so Claude Code knows about sessionmem's tools and uses them proactively (idempotent, so safe to re-run).
 
 ### 3. Start using your AI tool as normal
 
@@ -39,7 +62,7 @@ This does three things:
 sessionmem run
 ```
 
-(Most of the time you won't run this yourself — your AI tool's host starts it for you automatically once it's registered.)
+(Most of the time you won't run this yourself. Your AI tool's host starts it automatically once it's registered.)
 
 That's it. From here:
 - `sessionmem` watches your sessions in the background.
@@ -85,7 +108,7 @@ This happens because most AI assistants only "know" what's inside the current co
 `sessionmem` fixes this by sitting quietly between your assistant and your project:
 
 1. While you work, it **captures** what happens in the session.
-2. When the session ends, it **summarizes** the important parts — decisions made, warnings, useful facts — into short, durable notes.
+2. When the session ends, it **summarizes** the important parts (decisions made, warnings, useful facts) into short, durable notes.
 3. The next time you start a session, it **reminds** the assistant of the most relevant notes, automatically, in a small amount of text.
 
 You don't run any of these steps yourself. Once installed, it just works in the background.
@@ -99,21 +122,21 @@ There are other "memory for Claude" projects out there (for example, tools like
 | | **sessionmem** | Typical cloud/Claude-only memory tools |
 |---|---|---|
 | **Where is data stored?** | A single SQLite file on your computer (`~/.sessionmem/memories.db`) | Often a hosted service, a cloud vector database, or a separate server process you have to run |
-| **Account / sign-up required?** | No — never | Sometimes |
+| **Account / sign-up required?** | No, never | Sometimes |
 | **Which AI tools does it work with?** | Claude Code, Cursor, Codex, Cline, Windsurf, Antigravity, QCoder, and any other MCP-compatible host | Usually just one specific tool (commonly Claude Code only) |
-| **Secret redaction** | Built in and on by default — API keys, tokens, passwords, private keys, etc. are scrubbed before anything is saved | Often not handled, or left to the user |
+| **Secret redaction** | Built in, on by default. API keys, tokens, passwords, and private keys are scrubbed before anything is saved. | Often not handled, or left to the user |
 | **Token budget control** | Injected memories are trimmed to a small, fixed token budget so they don't bloat every conversation (see benchmarks below) | Varies, often unbounded |
 | **Old/stale memory cleanup** | Built-in retention policy automatically prunes old memories (configurable, on by default) | Often grows forever ("memory rot") |
-| **Team sharing** | Optional, via a shared folder you already control (network drive, synced directory) — no server to host | Usually requires a shared hosted backend |
-| **Offline-capable** | Yes, fully — works with no network connection by default | Usually requires network access to the memory service |
+| **Team sharing** | Optional, via a shared folder you already control (network drive, synced directory). No server needed. | Usually requires a shared hosted backend |
+| **Offline-capable** | Yes, fully. Works with no network connection by default. | Usually requires network access to the memory service |
 
-In short: `sessionmem` aims to be the **boring, local, "just a SQLite file" option** — easy to inspect, easy to back up, easy to delete, and not tied to any one vendor's AI tool.
+In short: `sessionmem` is the **boring, local, "just a SQLite file" option**: easy to inspect, back up, and delete, with no lock-in to any one vendor's AI tool.
 
 ---
 
 ## Benchmark results
 
-These numbers come from `npm run benchmark` (`scripts/benchmark.mjs`), which runs the **real** production retrieval and injection code over a fixed, synthetic set of test data — no network calls, fully reproducible. See [`docs/benchmark.md`](docs/benchmark.md) for the full report and how to regenerate it.
+These numbers come from `npm run benchmark` (`scripts/benchmark.mjs`), which runs the real production retrieval and injection code over a fixed, synthetic set of test data with no network calls. The results are fully reproducible. See [`docs/benchmark.md`](docs/benchmark.md) for the full report and how to regenerate it.
 
 ### Token savings
 
@@ -124,11 +147,11 @@ These numbers come from `npm run benchmark` (`scripts/benchmark.mjs`), which run
 | Full session history (baseline) | 1,587 |
 | What sessionmem injects at the start of your next session | 228 |
 
-In practice: instead of re-reading (or re-explaining) ~1,600 tokens of past context every session, the assistant gets a ~230-token summary of just the things that matter — decisions, warnings, and key facts.
+In practice: instead of re-reading (or re-explaining) about 1,600 tokens of past context every session, the assistant gets a 230-token summary of just the things that matter: decisions, warnings, and key facts.
 
 ### Retrieval accuracy
 
-> **100% hit-rate** — every one of the 10 test queries successfully retrieved the memory it was supposed to.
+> **100% hit-rate**: every one of the 10 test queries successfully retrieved the memory it was supposed to.
 
 | Metric | Result |
 |---|---|
@@ -136,9 +159,9 @@ In practice: instead of re-reading (or re-explaining) ~1,600 tokens of past cont
 | Recall | 100.0% |
 | Precision | 33.3% |
 
-Precision of 33.3% is expected here: each query retrieves the top 3 candidate memories, and only one of those three is the "expected" match for a given test query — the other two are still relevant context for the agent, just not the one being scored. The important number is recall/hit-rate: **the right memory is never missed.**
+Precision of 33.3% is expected here: each query retrieves the top 3 candidate memories, and only one of those three is the "expected" match for a given test query. The other two are still relevant context for the agent, just not the one being scored. The important number is recall/hit-rate: **the right memory is never missed.**
 
-These benchmarks are deterministic and reproducible — run them yourself:
+These benchmarks are deterministic and reproducible. Run them yourself:
 
 ```bash
 npm run build      # benchmark imports the compiled code from dist/
@@ -175,7 +198,7 @@ npm run benchmark  # regenerates docs/benchmark.md
                      └──────────────────────────────────────────────┘
 ```
 
-- **Adapters** are small pieces that know how to talk to each specific AI tool. This is why sessionmem can support many tools — adding a new one doesn't change how memory itself works.
+- **Adapters** are small pieces that know how to talk to each specific AI tool. This is why sessionmem can support many tools: adding a new one doesn't change how memory itself works.
 - **The core engine** is the same no matter which tool you use. It decides what's worth remembering, how relevant it is later, and how much of it fits in a small "reminder" at the start of your next session.
 - **The database** is just a file. You can back it up, move it, inspect it, or delete it like any other file on your computer.
 
@@ -234,24 +257,24 @@ Full details: [`docs/privacy-and-retention.md`](docs/privacy-and-retention.md).
 
 ## Memory rot: keeping memory accurate over time
 
-"Memory rot" is what happens when a memory system keeps accumulating notes forever — eventually it's full of outdated decisions, duplicate facts, and noise, and the assistant starts surfacing **wrong or stale** information instead of helpful information.
+"Memory rot" is what happens when a memory system keeps accumulating notes forever. Eventually it fills up with outdated decisions, duplicate facts, and noise, and the assistant starts surfacing stale information instead of helpful information.
 
 `sessionmem` is designed to avoid this in a few ways:
 
-1. **Retention pruning** — memories older than a configurable window (default **90 days**) are automatically eligible for cleanup. This runs as a light check at the end of every session, and can also be run manually:
+1. **Retention pruning**: memories older than a configurable window (default 90 days) are automatically eligible for cleanup. This runs as a light check at the end of every session, and can also be run manually:
 
    ```bash
-   sessionmem retention prune          # dry run — shows what *would* be deleted
+   sessionmem retention prune          # dry run - shows what *would* be deleted
    sessionmem retention prune --force  # actually deletes
    ```
 
-2. **Importance-weighted ranking** — when memories are retrieved, they're ranked by a blend of *semantic relevance*, *recency*, and *importance*. Old, low-importance notes naturally sink to the bottom and stop being surfaced even before they're pruned.
+2. **Importance-weighted ranking**: when memories are retrieved, they're ranked by a blend of semantic relevance, recency, and importance. Old, low-importance notes naturally sink to the bottom and stop being surfaced even before they're pruned.
 
-3. **Token-budgeted injection** — only the top-ranked, most relevant memories are injected (trimmed to a small token budget, see [benchmarks](#benchmark-results)), so even a large memory store doesn't translate into bloated, noisy context.
+3. **Token-budgeted injection**: only the top-ranked, most relevant memories are injected (trimmed to a small token budget, see [benchmarks](#benchmark-results)), so even a large memory store doesn't produce bloated, noisy context.
 
-4. **Conflict resolution in team mode** — when memories are merged from teammates, the system uses last-write-wins by id (so stale duplicates don't pile up) while preserving the higher importance score (so a critical warning doesn't get silently downgraded).
+4. **Conflict resolution in team mode**: when memories are merged from teammates, the system uses last-write-wins by id (so stale duplicates don't pile up) while preserving the higher importance score (so a critical warning doesn't get silently downgraded).
 
-The retrieval benchmark above (100% hit-rate / 100% recall) demonstrates that even with the ranking and trimming in place, the *right* memory still surfaces — accuracy isn't traded away for compactness.
+The retrieval benchmark above (100% hit-rate / 100% recall) demonstrates that even with the ranking and trimming in place, the right memory still surfaces. Accuracy is not traded away for compactness.
 
 You're always in control: export everything first if you want a permanent record before pruning:
 
@@ -263,15 +286,15 @@ sessionmem export
 
 ## Team mode (optional)
 
-Want your whole team's AI assistants to share decisions and warnings? Point `sessionmem` at a shared folder (a network drive, a synced directory — anything everyone can read and write):
+Want your whole team's AI assistants to share decisions and warnings? Point `sessionmem` at a shared folder (a network drive, a synced directory, or any location everyone can read and write):
 
 ```bash
 sessionmem team enable <shared-path>
 sessionmem sync
 ```
 
-- **Off by default** — nothing is shared until you turn it on.
-- No server to host — it's just files in a folder you already control.
+- **Off by default**: nothing is shared until you turn it on.
+- No server needed. It's just files in a folder you already control.
 - Teammates' memories show up with an `author:` prefix so you know where they came from.
 - Secrets are re-redacted on every pulled memory, so a teammate's snapshot can't reintroduce something your redaction policy would have stripped.
 
@@ -281,9 +304,9 @@ Full details, including the trust model: [`docs/team-mode.md`](docs/team-mode.md
 
 ## Cloud summarization (optional, off by default)
 
-By default, summarization (turning a session into a short memory) happens **entirely locally** — no API calls.
+By default, summarization (turning a session into a short memory) happens entirely locally, with no API calls.
 
-If you explicitly opt in (`allowCloudSummarization=true`) **and** provide an `ANTHROPIC_API_KEY`, summarization can use Claude's API for higher-quality summaries. If that ever fails, it automatically falls back to local summarization — your sessions are never left unsummarized.
+If you explicitly opt in (`allowCloudSummarization=true`) and provide an `ANTHROPIC_API_KEY`, summarization can use Claude's API for higher-quality summaries. If that ever fails, it automatically falls back to local summarization. Your sessions are never left unsummarized.
 
 Details: [`docs/cloud-summarization.md`](docs/cloud-summarization.md).
 
@@ -307,19 +330,28 @@ Details: [`docs/cloud-summarization.md`](docs/cloud-summarization.md).
 
 ## Further documentation
 
-- [Architecture](docs/architecture.md) — how the core engine, adapters, CLI, and SQLite storage fit together.
-- [Benchmark](docs/benchmark.md) — full token-reduction and retrieval-accuracy report, and how to reproduce it.
-- [Privacy and retention](docs/privacy-and-retention.md) — secret redaction, retention pruning, and config.
-- [Team mode](docs/team-mode.md) — shared-path team memory.
-- [Cloud summarization](docs/cloud-summarization.md) — the opt-in cloud summarization path.
-- [Migration](docs/migration.md) — the SQLite migration system and version-upgrade policy.
-- [Troubleshooting](docs/troubleshooting.md) — install failures, adapter issues, and `better-sqlite3` native-build problems.
+- [Architecture](docs/architecture.md): how the core engine, adapters, CLI, and SQLite storage fit together.
+- [Benchmark](docs/benchmark.md): full token-reduction and retrieval-accuracy report, and how to reproduce it.
+- [Privacy and retention](docs/privacy-and-retention.md): secret redaction, retention pruning, and config.
+- [Team mode](docs/team-mode.md): shared-path team memory.
+- [Cloud summarization](docs/cloud-summarization.md): the opt-in cloud summarization path.
+- [Migration](docs/migration.md): the SQLite migration system and version-upgrade policy.
+- [Troubleshooting](docs/troubleshooting.md): install failures, adapter issues, and `better-sqlite3` native-build problems.
 
 ---
 
 ## Troubleshooting
 
-Run into trouble installing or running `sessionmem`? Start with [`docs/troubleshooting.md`](docs/troubleshooting.md) — it covers install failures, adapter-specific issues, and native module (`better-sqlite3`) build problems on different platforms.
+Run into trouble installing or running `sessionmem`? Start with [`docs/troubleshooting.md`](docs/troubleshooting.md). It covers install failures, adapter-specific issues, missing session data, and native module (`better-sqlite3`) build problems on different platforms.
+
+Two quick checks that resolve most reports:
+
+```bash
+sessionmem install   # idempotent — re-registers the MCP server and all three hooks
+sessionmem stats     # memories, sessions, and session_events for the current project
+```
+
+If `stats` shows `sessions: 0` after real work, see [“0 sessions” / no session data recorded](docs/troubleshooting.md#0-sessions--no-session-data-recorded). Memories are keyed to the **repository root**, so every directory inside one repo shares a bucket; outside a repo the working directory itself is the key.
 
 Quick checks:
 
@@ -339,10 +371,10 @@ Install sessionmem (`npm i -g sessionmem`), then run `sessionmem install` in you
 Same install. sessionmem also ships as a Claude Code plugin (the `.claude-plugin` file in the repo), so it works with Claude Code's native plugin system too.
 
 **Is there a local MCP memory server that works offline with no API key?**
-Yes — sessionmem stores everything in a single SQLite file at `~/.sessionmem/memories.db` and works fully offline by default. Nothing leaves your machine unless you explicitly enable the optional cloud summarization path.
+Yes. sessionmem stores everything in a single SQLite file at `~/.sessionmem/memories.db` and works fully offline by default. Nothing leaves your machine unless you explicitly enable the optional cloud summarization path.
 
 **How is sessionmem different from claude-mem?**
-sessionmem is not Claude-only. It works with Cursor, Cline, Codex, Windsurf, Antigravity, QCoder, and any other MCP host — not just Claude Code. It also redacts secrets (API keys, tokens, JWTs) by default, prunes stale memory automatically, and ships reproducible benchmarks you can run yourself.
+sessionmem is not Claude-only. It works with Cursor, Cline, Codex, Windsurf, Antigravity, QCoder, and any other MCP host, not just Claude Code. It also redacts secrets (API keys, tokens, JWTs) by default, prunes stale memory automatically, and ships reproducible benchmarks you can run yourself.
 
 **Does sessionmem send my code to the cloud?**
 No. Nothing leaves your machine by default. The optional cloud summarization path is opt-in and off by default.

package/dist/adapters/claudeMdInjector.js

@@ -19,13 +19,24 @@ hook support), call it once before any task work, or call \`retrieveMemories\`
 with the current task as the query. Never inject twice if context was already
 provided.
 
-### When to store memories (storeMemory)
+### Session event ingestion (auto-ingest path)
+The \`PostToolUse\` hook installed by sessionmem automatically captures Bash, Edit,
+Write, and MultiEdit tool uses as session events. These are summarized by the
+\`SessionEnd\` hook into a durable memory — no manual action required. To ingest
+additional context (e.g. key decisions made mid-session that weren't captured as
+tool use), call \`ingestSessionEvents\` at task boundaries with a description of
+what was accomplished.
+
+### When to store memories explicitly (storeMemory / batchStoreMemory)
 - User makes an architectural or design decision
 - You discover a non-obvious project constraint or convention
 - A debugging session reveals an important root cause
 - User states a preference about how they want things done
 - A warning or pitfall is discovered that future sessions should know about
 
+Use \`tags\` to categorize memories for better retrieval (e.g. \`tags: ["auth", "security"]\`).
+Use \`expiresAt\` for time-limited context (e.g. a temporary workaround).
+
 ### When to retrieve memories mid-session (retrieveMemories)
 - Before making architectural decisions (check if prior decisions exist)
 - When the user references something from a previous session
@@ -37,6 +48,9 @@ informed. Store a concise \`summary\` memory (importance 7) of the key outcomes,
 any new decisions, facts, or warnings. Use \`batchStoreMemory\` to write several at
 once. This is what makes context survive across sessions and saves tokens later.
 
+Note: The SessionEnd hook also auto-summarizes captured session events — you only
+need to call \`batchStoreMemory\` for decisions and facts NOT already captured.
+
 ### Memory kinds
 - \`decision\` — architectural or design choices (importance: 7-9)
 - \`fact\` — project constraints, conventions, patterns (importance: 5-7)
@@ -49,6 +63,7 @@ once. This is what makes context survive across sessions and saves tokens later.
 - \`getMemory\` — fetch a specific memory by ID
 - \`forgetMemory\` — delete an outdated or incorrect memory
 - \`batchStoreMemory\` — store multiple memories in one call (use at session end)
+- \`ingestSessionEvents\` — push raw session events for auto-summarization
 - \`stats\` — check memory count and health
 
 ### Guidelines
@@ -56,6 +71,7 @@ once. This is what makes context survive across sessions and saves tokens later.
 - Don't retrieve memories every single turn — retrieve at task boundaries
 - Keep memory content concise (1-3 sentences) and self-contained
 - Use appropriate importance scores (see kinds above)
+- Use tags to group related memories (\`tags: ["topic"]\`)
 `;
 export function generateClaudeMdBlock() {
     return `${SESSIONMEM_BLOCK_START}\n${BLOCK_CONTENT}\n${SESSIONMEM_BLOCK_END}`;

package/dist/adapters/generic.js

@@ -68,6 +68,7 @@ const TOOL_DEFINITIONS = [
             limit: retrieveMemoriesRequestSchema.shape.limit.describe("Maximum number of memories to return. Integer 1-100, default 20. Increase for broad topic sweeps; keep at default for focused lookups."),
             mode: retrieveMemoriesRequestSchema.shape.mode.describe("'auto' for the standard startup context-load path. 'on-demand' for an explicit mid-session retrieval triggered by a specific task or question."),
             depth: retrieveMemoriesRequestSchema.shape.depth.describe("'default' for standard semantic search. 'deep' for a broader sweep that surfaces less-similar memories — use when the topic is new or unfamiliar."),
+            tags: retrieveMemoriesRequestSchema.shape.tags.describe("Optional tag filter. When provided, only return memories that have ALL listed tags."),
         },
     },
     {
@@ -86,6 +87,8 @@ const TOOL_DEFINITIONS = [
             content: storeMemoryRequestSchema.shape.content.describe("The memory text. Must be self-contained and specific — written so it is useful without surrounding conversation context. Avoid vague phrases like 'the user decided to...'."),
             importance: storeMemoryRequestSchema.shape.importance.describe("Integer 1-10 indicating criticality (10 = most important). Directly affects ranking in future retrieveMemories calls. Use 8-10 for decisions that must not be forgotten; 3-5 for useful but non-critical facts."),
             redactionEnabled: storeMemoryRequestSchema.shape.redactionEnabled.describe("If true, PII is stripped from content before storage. Omit to use the project-level redaction setting from config.json."),
+            tags: storeMemoryRequestSchema.shape.tags.describe("Optional array of tag strings (max 10, each max 50 chars) for categorizing this memory. Example: ['auth', 'db-schema']. Tags are filterable via retrieveMemories."),
+            expiresAt: storeMemoryRequestSchema.shape.expiresAt.describe("Optional UTC ISO timestamp (e.g. '2026-12-31T00:00:00Z') after which this memory is excluded from retrieval. Use for time-limited context like a temporary workaround."),
         },
     },
     {

package/dist/adapters/global/claudeCode.js

@@ -1,7 +1,7 @@
 import { join } from "path";
 import { homedir } from "os";
 import { GenericMCPAdapter } from "../generic.js";
-import { IDEInstaller, SESSIONMEM_HOOK_COMMAND, SESSIONMEM_SESSION_END_HOOK_COMMAND, } from "../ide/installer.js";
+import { IDEInstaller, SESSIONMEM_HOOK_COMMAND, SESSIONMEM_SESSION_END_HOOK_COMMAND, SESSIONMEM_POST_TOOL_HOOK_COMMAND, SESSIONMEM_POST_TOOL_MATCHER, } from "../ide/installer.js";
 export class ClaudeCodeAdapter extends GenericMCPAdapter {
     name = "Claude Code";
     // Capabilities inherited from GenericMCPAdapter (tools only) so the
@@ -44,7 +44,11 @@ export class ClaudeCodeAdapter extends GenericMCPAdapter {
         // session ends — the deterministic write-side counterpart to the
         // SessionStart read-side hook.
         const endHookOk = await IDEInstaller.injectClaudeHook(this.settingsPath(), SESSIONMEM_SESSION_END_HOOK_COMMAND, "SessionEnd");
-        return mcpOk && startHookOk && endHookOk;
+        // Register a PostToolUse hook so high-signal tool uses (Bash/Edit/Write/
+        // MultiEdit) are captured as session events automatically, feeding the
+        // SessionEnd auto-summarizer without the agent calling ingestSessionEvents.
+        const postToolOk = await IDEInstaller.injectClaudeHook(this.settingsPath(), SESSIONMEM_POST_TOOL_HOOK_COMMAND, "PostToolUse", SESSIONMEM_POST_TOOL_MATCHER);
+        return mcpOk && startHookOk && endHookOk && postToolOk;
     }
     async uninstall() {
         const configPath = join(homedir(), ".claude.json");
@@ -53,6 +57,7 @@ export class ClaudeCodeAdapter extends GenericMCPAdapter {
         // reported as an uninstall failure rather than silently ignored.
         const startOk = await IDEInstaller.removeClaudeHook(this.settingsPath(), SESSIONMEM_HOOK_COMMAND);
         const endOk = await IDEInstaller.removeClaudeHook(this.settingsPath(), SESSIONMEM_SESSION_END_HOOK_COMMAND, "SessionEnd");
-        return mcpOk && startOk && endOk;
+        const postToolOk = await IDEInstaller.removeClaudeHook(this.settingsPath(), SESSIONMEM_POST_TOOL_HOOK_COMMAND, "PostToolUse");
+        return mcpOk && startOk && endOk && postToolOk;
     }
 }

package/dist/adapters/ide/installer.js

@@ -1,17 +1,38 @@
+// On Windows, `sessionmem` resolves to a `.cmd` shim which requires cmd.exe to
+// execute. Claude Code spawns hook commands without a shell on Windows, so a
+// bare `sessionmem …` invocation fails silently. Route through `cmd /c` —
+// mirroring the MCP server install fix in claudeCode.ts — so the shim is
+// resolved correctly. On non-Windows platforms the bare command works fine.
+const _isWindows = process.platform === "win32";
 /**
  * The exact command Claude Code runs at session start. Installed as a
  * `SessionStart` hook in ~/.claude/settings.json so prior memories are injected
  * into every session automatically — the deterministic counterpart to the
  * advisory `startup_inject_memories` tool (which the agent must choose to call).
  */
-export const SESSIONMEM_HOOK_COMMAND = "sessionmem session-start";
+export const SESSIONMEM_HOOK_COMMAND = _isWindows
+    ? "cmd /c sessionmem session-start"
+    : "sessionmem session-start";
 /**
  * The command Claude Code runs when a session ends. Installed as a `SessionEnd`
  * hook so the session-end pipeline (light retention prune + auto-summarization
  * of any ingested session events) runs automatically once per session, without
  * relying on the agent choosing to call a tool.
  */
-export const SESSIONMEM_SESSION_END_HOOK_COMMAND = "sessionmem session-end";
+export const SESSIONMEM_SESSION_END_HOOK_COMMAND = _isWindows
+    ? "cmd /c sessionmem session-end"
+    : "sessionmem session-end";
+/**
+ * The command Claude Code runs after each tool use. Installed as a `PostToolUse`
+ * hook so high-signal tool uses (Bash/Edit/Write/MultiEdit) are captured as
+ * session events automatically, giving the SessionEnd auto-summarizer material
+ * to work with without the agent choosing to call ingestSessionEvents.
+ */
+export const SESSIONMEM_POST_TOOL_HOOK_COMMAND = _isWindows
+    ? "cmd /c sessionmem ingest-hook"
+    : "sessionmem ingest-hook";
+/** Tool matcher for the PostToolUse auto-ingest hook. */
+export const SESSIONMEM_POST_TOOL_MATCHER = "Bash|Edit|Write|MultiEdit";
 /** Default Claude Code hook event for the legacy 2-arg hook helpers. */
 const DEFAULT_HOOK_EVENT = "SessionStart";
 export class IDEInstaller {
@@ -166,9 +187,11 @@ export class IDEInstaller {
      * every other key (mcpServers, other hook events, user settings). Defaults to
      * the `SessionStart` event; pass `eventName` for another event (e.g.
      * `SessionEnd`). Idempotent: re-injecting the same command on the same event
-     * never produces a duplicate entry.
+     * never produces a duplicate entry. When `matcher` is provided (e.g. for
+     * `PostToolUse`), the pushed entry carries the matcher so Claude Code scopes
+     * the hook to the matching tools.
      */
-    static injectClaudeHookBlock(content, command, eventName = DEFAULT_HOOK_EVENT) {
+    static injectClaudeHookBlock(content, command, eventName = DEFAULT_HOOK_EVENT, matcher) {
         const config = content.trim()
             ? this.parseJsonc(content)
             : {};
@@ -179,9 +202,13 @@ export class IDEInstaller {
             ? hooks[eventName]
             : [];
         // Drop any pre-existing sessionmem entry so re-install stays idempotent and
-        // a stale command form is replaced rather than duplicated.
+        // a stale command form is replaced rather than duplicated. hookEntryHasCommand
+        // only inspects entry.hooks, so it dedupes correctly whether or not the entry
+        // carries a matcher.
         const filtered = eventEntries.filter((entry) => !this.hookEntryHasCommand(entry, command));
-        filtered.push({ hooks: [{ type: "command", command }] });
+        filtered.push(matcher !== undefined
+            ? { matcher, hooks: [{ type: "command", command }] }
+            : { hooks: [{ type: "command", command }] });
         hooks[eventName] = filtered;
         config.hooks = hooks;
         return JSON.stringify(config, null, 2);
@@ -214,14 +241,14 @@ export class IDEInstaller {
         }
         return JSON.stringify(config, null, 2);
     }
-    static async injectClaudeHook(filePath, command, eventName = DEFAULT_HOOK_EVENT) {
+    static async injectClaudeHook(filePath, command, eventName = DEFAULT_HOOK_EVENT, matcher) {
         try {
             const { readFileSync, writeFileSync, existsSync, mkdirSync } = await import("fs");
             const { dirname } = await import("path");
             const existing = existsSync(filePath)
                 ? readFileSync(filePath, "utf-8")
                 : "{}";
-            const updated = this.injectClaudeHookBlock(existing, command, eventName);
+            const updated = this.injectClaudeHookBlock(existing, command, eventName, matcher);
             const dir = dirname(filePath);
             if (!existsSync(dir)) {
                 mkdirSync(dir, { recursive: true });

package/dist/cli/commands/browse.js

@@ -0,0 +1,33 @@
+import { createCliContext } from "../context.js";
+export async function browseCommand(options = {}, ctx) {
+    const context = ctx ?? createCliContext();
+    const db = context.db;
+    if (options.project) {
+        // Show memories for a specific project
+        const memories = db.prepare("SELECT id, kind, importance, content, created_at FROM memories WHERE project_id = ? ORDER BY updated_at DESC LIMIT 50").all(options.project);
+        if (memories.length === 0) {
+            process.stdout.write(`No memories found for project: ${options.project}\n`);
+            return;
+        }
+        process.stdout.write(`Memories for project: ${options.project} (${memories.length} shown)\n\n`);
+        for (const m of memories) {
+            const preview = m.content.slice(0, 120).replace(/\n/g, " ");
+            process.stdout.write(`[${m.kind}] imp=${m.importance} id=${m.id.slice(0, 8)}…\n  ${preview}${m.content.length > 120 ? "…" : ""}\n\n`);
+        }
+        return;
+    }
+    // List all projects
+    const projects = db.prepare("SELECT project_id, COUNT(*) as memory_count, MAX(updated_at) as newest FROM memories GROUP BY project_id ORDER BY newest DESC").all();
+    if (projects.length === 0) {
+        process.stdout.write("No projects with memories yet.\n");
+        process.stdout.write(`Current project: ${context.projectId}\n`);
+        return;
+    }
+    process.stdout.write(`Projects with memories (${projects.length} total):\n\n`);
+    for (const p of projects) {
+        const marker = p.project_id === context.projectId ? " ← current" : "";
+        process.stdout.write(`${p.project_id}${marker}\n`);
+        process.stdout.write(`  memories: ${p.memory_count}  last_updated: ${p.newest}\n\n`);
+    }
+    process.stdout.write(`Use --project <id> to list memories for a specific project.\n`);
+}

package/dist/cli/commands/dedupe.js

@@ -0,0 +1,139 @@
+import { createCliContext } from "../context.js";
+import { listMemoriesByProject } from "../../core/storage/memoryRepo.js";
+const SIMILARITY_THRESHOLD = 0.85;
+const MAX_PREVIEW_LEN = 200;
+function cosineSimilarity(a, b) {
+    if (a.length !== b.length || a.length === 0)
+        return 0;
+    let dot = 0, normA = 0, normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom === 0 ? 0 : dot / denom;
+}
+/**
+ * Parse and validate the `--threshold` flag. An unparseable or out-of-range
+ * value used to flow through as NaN, and every `sim >= NaN` comparison is
+ * false — so `--threshold banana` reported "no duplicates found" rather than
+ * telling the user their input was rejected.
+ */
+function resolveThreshold(raw) {
+    if (raw === undefined)
+        return SIMILARITY_THRESHOLD;
+    const parsed = Number.parseFloat(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0 || parsed > 1) {
+        console.error(`Invalid --threshold "${raw}": expected a number greater than 0 and at most 1.`);
+        process.exit(1);
+    }
+    return parsed;
+}
+/** Parse a stored embedding, returning null when it is absent or malformed. */
+function parseVector(embedding) {
+    if (!embedding)
+        return null;
+    try {
+        const parsed = JSON.parse(embedding);
+        if (!Array.isArray(parsed) || !parsed.every((n) => Number.isFinite(n))) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export async function dedupeCommand(options = {}, ctx) {
+    const context = ctx ?? createCliContext();
+    const threshold = resolveThreshold(options.threshold);
+    const dryRun = options.dry !== false;
+    // Parse each embedding ONCE. The inner loop used to re-parse the same
+    // candidate's JSON for every outer element — O(n²) JSON.parse calls over a
+    // list that only has n distinct vectors.
+    const candidates = [];
+    for (const memory of listMemoriesByProject(context.db, context.projectId)) {
+        const vector = parseVector(memory.embedding);
+        if (!vector || !memory.embedding_dim)
+            continue;
+        candidates.push({
+            id: memory.id,
+            content: memory.content,
+            importance: memory.importance,
+            vector,
+        });
+    }
+    if (candidates.length < 2) {
+        process.stdout.write("Not enough memories with embeddings to compare.\n");
+        return;
+    }
+    // Highest importance first, id as the tie-break. Pairs are emitted in this
+    // order and the first element of a pair is the one kept, so the survivor of
+    // any duplicate cluster is deterministic.
+    //
+    // Without this the order came from `ORDER BY updated_at DESC`, which is not a
+    // total order — memories written in the same clock tick tie, and the winner
+    // varied by platform. The same three memories could collapse to a different
+    // survivor on Windows than on Linux, and `--apply` is a hard delete.
+    candidates.sort((left, right) => right.importance - left.importance || left.id.localeCompare(right.id));
+    const pairs = [];
+    for (let i = 0; i < candidates.length; i++) {
+        const a = candidates[i];
+        for (let j = i + 1; j < candidates.length; j++) {
+            const b = candidates[j];
+            const sim = cosineSimilarity(a.vector, b.vector);
+            if (sim >= threshold) {
+                pairs.push({
+                    idA: a.id,
+                    idB: b.id,
+                    similarity: sim,
+                    contentA: a.content.slice(0, MAX_PREVIEW_LEN),
+                    contentB: b.content.slice(0, MAX_PREVIEW_LEN),
+                });
+            }
+        }
+    }
+    if (pairs.length === 0) {
+        process.stdout.write(`No near-duplicate memories found (threshold: ${threshold}).\n`);
+        return;
+    }
+    const byId = new Map(candidates.map((c) => [c.id, c]));
+    const deleted = new Set();
+    process.stdout.write(`Found ${pairs.length} near-duplicate pair(s) (threshold: ${threshold}):\n\n`);
+    for (const pair of pairs) {
+        // Skip a pair whose partner is already gone. Similarity is not transitive:
+        // in a chain A~B, B~C with A≁C, deleting B for the (A,B) pair left the
+        // (B,C) pair still to process, and that pass could delete C — a memory
+        // whose only duplicate no longer existed. Nothing kept C from being
+        // dropped on the strength of an already-deleted row.
+        if (deleted.has(pair.idA) || deleted.has(pair.idB))
+            continue;
+        process.stdout.write(`Similarity: ${(pair.similarity * 100).toFixed(1)}%\n`);
+        process.stdout.write(`  A [${pair.idA}]: ${pair.contentA}${pair.contentA.length >= MAX_PREVIEW_LEN ? "…" : ""}\n`);
+        process.stdout.write(`  B [${pair.idB}]: ${pair.contentB}${pair.contentB.length >= MAX_PREVIEW_LEN ? "…" : ""}\n`);
+        if (!dryRun) {
+            const memA = byId.get(pair.idA);
+            const memB = byId.get(pair.idB);
+            if (!memA || !memB)
+                continue;
+            const keepId = memA.importance >= memB.importance ? pair.idA : pair.idB;
+            const dropId = keepId === pair.idA ? pair.idB : pair.idA;
+            const result = await context.service.call("forgetMemory", {
+                projectId: context.projectId,
+                memoryId: dropId,
+            });
+            if (result.ok) {
+                deleted.add(dropId);
+                process.stdout.write(`  → Deleted ${dropId} (kept ${keepId})\n`);
+            }
+            else {
+                process.stdout.write(`  → Failed to delete ${dropId}: ${result.error.message}\n`);
+            }
+        }
+        process.stdout.write("\n");
+    }
+    if (dryRun) {
+        process.stdout.write(`Run with --apply to delete the lower-importance duplicate in each pair.\n`);
+    }
+}