sessionmem 1.1.1 → 1.2.0

package/README.md

@@ -2,9 +2,9 @@
 
 [![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)
 
-**Give your AI coding assistant a memory that lasts beyond one conversation — stored entirely on your own computer.**
+**Give your AI coding assistant a memory that lasts beyond one conversation, stored entirely on your own computer.**
 
-`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.
+`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, so you never have to repeat yourself.
 
 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.
 
@@ -12,7 +12,7 @@ Everything happens on your machine. There is no account to create, no cloud serv
 
 ## 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 +30,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 +39,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 +85,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 +99,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 +124,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 +136,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 +175,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 +234,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 +263,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 +281,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 +307,19 @@ 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, and native module (`better-sqlite3`) build problems on different platforms.
 
 Quick checks:
 
@@ -339,10 +339,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/cline.js

@@ -50,8 +50,6 @@ export class ClineAdapter extends GenericMCPAdapter {
         // "Code" is VS Code stable, but Cline also installs into Insiders, VSCodium,
         // and Cursor. Pick the first variant whose globalStorage dir already exists;
         // fall back to stable "Code" when none is found (fresh install).
-        // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
-        // `name` is from the hardcoded VSCODE_EDITOR_VARIANTS constant above — not user input.
         const editorName = VSCODE_EDITOR_VARIANTS.find((name) => existsSync(join(base, name, "User", "globalStorage"))) ?? "Code";
         return join(base, editorName, ...rest);
     }

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,72 @@
+import { createCliContext } from "../context.js";
+import { listMemoriesByProject } from "../../core/storage/memoryRepo.js";
+const SIMILARITY_THRESHOLD = 0.85;
+const MAX_TAG_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;
+}
+export async function dedupeCommand(options = {}, ctx) {
+    const context = ctx ?? createCliContext();
+    const threshold = options.threshold ? parseFloat(options.threshold) : SIMILARITY_THRESHOLD;
+    const dryRun = options.dry !== false;
+    const memories = listMemoriesByProject(context.db, context.projectId);
+    const withEmbeddings = memories.filter((m) => m.embedding && m.embedding_dim);
+    if (withEmbeddings.length < 2) {
+        process.stdout.write("Not enough memories with embeddings to compare.\n");
+        return;
+    }
+    const pairs = [];
+    for (let i = 0; i < withEmbeddings.length; i++) {
+        const a = withEmbeddings[i];
+        const vecA = JSON.parse(a.embedding);
+        for (let j = i + 1; j < withEmbeddings.length; j++) {
+            const b = withEmbeddings[j];
+            const vecB = JSON.parse(b.embedding);
+            const sim = cosineSimilarity(vecA, vecB);
+            if (sim >= threshold) {
+                pairs.push({
+                    idA: a.id,
+                    idB: b.id,
+                    similarity: sim,
+                    contentA: a.content.slice(0, MAX_TAG_LEN),
+                    contentB: b.content.slice(0, MAX_TAG_LEN),
+                });
+            }
+        }
+    }
+    if (pairs.length === 0) {
+        process.stdout.write(`No near-duplicate memories found (threshold: ${threshold}).\n`);
+        return;
+    }
+    process.stdout.write(`Found ${pairs.length} near-duplicate pair(s) (threshold: ${threshold}):\n\n`);
+    for (const pair of pairs) {
+        process.stdout.write(`Similarity: ${(pair.similarity * 100).toFixed(1)}%\n`);
+        process.stdout.write(`  A [${pair.idA}]: ${pair.contentA}${pair.contentA.length >= MAX_TAG_LEN ? "…" : ""}\n`);
+        process.stdout.write(`  B [${pair.idB}]: ${pair.contentB}${pair.contentB.length >= MAX_TAG_LEN ? "…" : ""}\n`);
+        if (!dryRun) {
+            // Keep A (higher importance or first by date), delete B.
+            const memA = withEmbeddings.find((m) => m.id === pair.idA);
+            const memB = withEmbeddings.find((m) => m.id === pair.idB);
+            const keepId = memA.importance >= memB.importance ? pair.idA : pair.idB;
+            const dropId = keepId === pair.idA ? pair.idB : pair.idA;
+            await context.service.call("forgetMemory", {
+                projectId: context.projectId,
+                memoryId: dropId,
+            });
+            process.stdout.write(`  → Deleted ${dropId} (kept ${keepId})\n`);
+        }
+        process.stdout.write("\n");
+    }
+    if (dryRun && pairs.length > 0) {
+        process.stdout.write(`Run with --apply to delete the lower-importance duplicate in each pair.\n`);
+    }
+}

package/dist/cli/commands/ingestHook.js

@@ -0,0 +1,104 @@
+import { createCliContext } from "../context.js";
+import { randomUUID } from "node:crypto";
+// High-signal tool types that we capture as session events.
+const CAPTURED_TOOL_TYPES = new Set(["Bash", "Edit", "Write", "MultiEdit"]);
+// Max payload size stored per hook event (chars). The full hook payload can be
+// large (file diffs); cap it so a single tool use can't bloat session_events.
+const MAX_HOOK_PAYLOAD_CHARS = 4000;
+async function readStdinJson() {
+    if (process.stdin.isTTY)
+        return {};
+    return new Promise((resolve) => {
+        let data = "";
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                resolve(JSON.parse(data));
+            }
+            catch {
+                resolve({});
+            }
+        };
+        const timer = setTimeout(() => {
+            process.stdin.removeAllListeners();
+            process.stdin.pause();
+            finish();
+        }, 500);
+        timer.unref?.();
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (c) => { data += c; });
+        process.stdin.on("end", () => { clearTimeout(timer); finish(); });
+        process.stdin.on("error", () => { clearTimeout(timer); finish(); });
+    });
+}
+function resolveSessionId(payload) {
+    if (typeof payload.session_id === "string" && payload.session_id.trim()) {
+        return payload.session_id.trim();
+    }
+    return process.env.CLAUDE_CODE_SESSION_ID ?? process.env.SESSION_ID ?? `session-${Date.now()}`;
+}
+/**
+ * `sessionmem ingest-hook` — PostToolUse hook handler.
+ * Reads Claude Code's PostToolUse JSON payload from stdin and stores it as a
+ * session event so the SessionEnd auto-summarizer has material to work with.
+ * Also auto-stores git commits as decision memories (git commit detection).
+ */
+export async function ingestHookCommand(ctx) {
+    try {
+        const payload = await readStdinJson();
+        const toolName = payload.tool_name ?? "";
+        if (!CAPTURED_TOOL_TYPES.has(toolName))
+            return;
+        const context = ctx ?? createCliContext();
+        const sessionId = resolveSessionId(payload);
+        const projectId = context.projectId;
+        // Trim payload to cap storage per event.
+        const fullPayload = JSON.stringify({
+            tool: toolName,
+            input: payload.tool_input,
+            cwd: payload.cwd,
+        });
+        const trimmedPayload = fullPayload.length > MAX_HOOK_PAYLOAD_CHARS
+            ? fullPayload.slice(0, MAX_HOOK_PAYLOAD_CHARS) + "…"
+            : fullPayload;
+        // Store as a session event (for SessionEnd auto-summarize).
+        await context.service.call("ingestSessionEvents", {
+            projectId,
+            sessionId,
+            events: [{
+                    id: randomUUID(),
+                    eventIndex: Date.now(), // monotonic within the session
+                    eventType: `tool_use:${toolName.toLowerCase()}`,
+                    payloadJson: trimmedPayload,
+                }],
+        });
+        // Git commit detection: auto-store as a decision memory.
+        if (toolName === "Bash") {
+            const cmd = typeof payload.tool_input?.command === "string"
+                ? payload.tool_input.command
+                : "";
+            const commitMatch = cmd.match(/git\s+commit[^|&;]*(?:-m\s+['"]([^'"]+)['"]|--message=?['"]([^'"]+)['"])/);
+            if (commitMatch) {
+                const message = (commitMatch[1] ?? commitMatch[2] ?? "").trim();
+                if (message) {
+                    await context.service.call("storeMemory", {
+                        projectId,
+                        sessionId,
+                        memoryId: `gitcommit-${Date.now()}`,
+                        sourceAdapter: "sessionmem-hook",
+                        kind: "decision",
+                        content: `Git commit: ${message}`,
+                        importance: 5,
+                    });
+                }
+            }
+        }
+        context.db.close();
+    }
+    catch {
+        // Never block tool use — swallow all errors silently.
+    }
+}

package/dist/cli/context.js

@@ -38,10 +38,7 @@ export function expandTilde(p) {
     if (p === "~")
         return homedir();
     if (p.startsWith("~/") || p.startsWith("~\\")) {
-        // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
-        // `homedir()` is the fixed base; `p` is SESSIONMEM_DB_PATH, a local CLI
-        // config the operator sets for their own filesystem — not external user input.
-        return join(homedir(), p.slice(2));
+        return join(homedir(), p.slice(2)); // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
     }
     return p;
 }

package/dist/cli/index.js

@@ -21,6 +21,9 @@ import { configGetCommand, configSetCommand } from "./commands/config.js";
 import { teamEnableCommand, teamDisableCommand, teamStatusCommand, } from "./commands/team.js";
 import { syncCommand } from "./commands/sync.js";
 import { reEmbedCommand } from "./commands/reEmbed.js";
+import { ingestHookCommand } from "./commands/ingestHook.js";
+import { dedupeCommand } from "./commands/dedupe.js";
+import { browseCommand } from "./commands/browse.js";
 // Source the version from package.json (single source of truth) so `--version`
 // never drifts from the published manifest. createRequire + resolveJsonModule
 // reads the manifest relative to this module; from dist/cli/index.js the
@@ -40,6 +43,10 @@ program
     .command("session-end")
     .description("Run the session-end pipeline (auto-summarize ingested session events + light retention prune) for the current project (invoked automatically by the SessionEnd hook installed during `sessionmem install`)")
     .action(() => sessionEndCommand());
+program
+    .command("ingest-hook")
+    .description("Process a Claude Code PostToolUse hook payload from stdin and store it as a session event (invoked automatically by the hook installed during `sessionmem install`)")
+    .action(() => ingestHookCommand());
 program
     .command("install")
     .description("Install sessionmem into the current MCP host")
@@ -167,6 +174,20 @@ program
     .command("sync")
     .description("Push local memories and pull teammate memories via the shared path")
     .action(() => syncCommand());
+// dedupe — find near-duplicate memories by embedding cosine similarity.
+// Dry-run by default; --apply deletes the lower-importance duplicate per pair.
+program
+    .command("dedupe")
+    .description("Find and optionally remove near-duplicate memories")
+    .option("--apply", "Delete the lower-importance duplicate in each pair (default: dry-run)")
+    .option("--threshold <n>", "Cosine similarity threshold 0-1 (default: 0.85)")
+    .action((options) => dedupeCommand({ dry: !options.apply, threshold: options.threshold }));
+// browse — cross-project memory viewer.
+program
+    .command("browse")
+    .description("List all projects with memories, or browse a specific project")
+    .option("--project <id>", "Show memories for a specific project ID")
+    .action((options) => browseCommand({ project: options.project }));
 program.parseAsync(process.argv).catch((err) => {
     console.error(err instanceof Error ? err.message : String(err));
     process.exit(1);

package/dist/core/api/contracts.js

@@ -58,6 +58,8 @@ export const memorySchema = z.object({
     accessCount: z.number().int().nonnegative(),
     lastAccessed: z.string().nullable(),
     effectiveImportance: z.number().int().min(1).max(10),
+    tags: z.array(z.string()).nullable().optional(),
+    expiresAt: z.string().nullable().optional(),
     createdAt: z.string().min(1),
     updatedAt: z.string().min(1),
 });
@@ -144,6 +146,8 @@ export const storeMemoryRequestSchema = z.object({
     // the service layer can fall back to the policy-config redactionEnabled
     // setting (override > config.json > default precedence).
     redactionEnabled: z.boolean().optional(),
+    tags: z.array(z.string().min(1).max(50)).max(10).optional(),
+    expiresAt: z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/, "must be UTC ISO timestamp").optional(),
 });
 export const retrieveMemoriesRequestSchema = z.object({
     projectId: z.string().min(1),
@@ -151,6 +155,7 @@ export const retrieveMemoriesRequestSchema = z.object({
     limit: z.number().int().min(1).max(100).default(20),
     mode: z.enum(["auto", "on-demand"]).default("auto"),
     depth: z.enum(["default", "deep"]).default("default"),
+    tags: z.array(z.string().min(1).max(50)).max(10).optional(),
 });
 export const listMemoriesRequestSchema = z.object({
     projectId: z.string().min(1),
@@ -380,6 +385,8 @@ export const batchStoreMemoryItemSchema = z.object({
     content: z.string().min(1).max(MAX_CONTENT_LENGTH),
     importance: z.number().int().min(1).max(10),
     redactionEnabled: z.boolean().optional(),
+    tags: z.array(z.string().min(1).max(50)).max(10).optional(),
+    expiresAt: z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/, "must be UTC ISO timestamp").optional(),
 });
 export const batchStoreMemoryRequestSchema = z.object({
     projectId: z.string().min(1),

package/dist/core/api/memoryCoreService.js

@@ -75,6 +75,8 @@ function toMemoryDto(record) {
         accessCount: record.access_count,
         lastAccessed: record.last_accessed,
         effectiveImportance: computeEffectiveImportance(record.importance, record.access_count),
+        tags: record.tags ? JSON.parse(record.tags) : null,
+        expiresAt: record.expires_at ?? null,
         createdAt: record.created_at,
         updatedAt: record.updated_at,
     };
@@ -114,6 +116,10 @@ function toRetrievedMemoryDto(record) {
         accessCount: record.access_count,
         lastAccessed: null,
         effectiveImportance: computeEffectiveImportance(record.importance, record.access_count),
+        // The semantic-search candidate projection does not carry tags/expires_at;
+        // expired rows are already filtered out by the retrieval SQL.
+        tags: null,
+        expiresAt: null,
         createdAt: record.created_at,
         updatedAt: record.updated_at,
         semantic: record.semantic,
@@ -269,6 +275,8 @@ export function createMemoryCoreService(deps) {
                 // because this row did not come from another project's store.
                 author: localAuthor,
                 origin_project_id: null,
+                tags: JSON.stringify(parsed.tags ?? null),
+                expires_at: parsed.expiresAt ?? null,
             });
             const inserted = getMemoryRecordById(db, parsed.projectId, parsed.memoryId);
             if (!inserted) {
@@ -289,12 +297,24 @@ export function createMemoryCoreService(deps) {
         async retrieveMemories(request) {
             const parsed = parseRequest(retrieveMemoriesRequestSchema, request);
             const limit = parsed.depth === "deep" ? Math.min(parsed.limit * 2, DEEP_MODE_RETRIEVAL_CAP) : parsed.limit;
-            const ranked = retrieveMemories({
+            const rankedAll = retrieveMemories({
                 db,
                 projectId: parsed.projectId,
                 queryText: parsed.query,
                 limit,
             });
+            // Optional tag filter: keep a memory only when its stored tags contain ALL
+            // requested tags. The semantic candidate projection omits tags, so re-read
+            // each row's tags by id (this is an explicit, infrequent filter path).
+            const ranked = parsed.tags && parsed.tags.length > 0
+                ? rankedAll.filter((m) => {
+                    const rec = getMemoryRecordById(db, parsed.projectId, m.id);
+                    const recTags = rec?.tags
+                        ? JSON.parse(rec.tags)
+                        : [];
+                    return parsed.tags.every((t) => recTags.includes(t));
+                })
+                : rankedAll;
             if (ranked.length > 0 && parsed.mode !== "on-demand") {
                 // Only boost access counts for startup injection (mode='auto'), not for
                 // explicit on-demand retrieval, so a mid-session lookup does not inflate
@@ -674,6 +694,8 @@ export function createMemoryCoreService(deps) {
                                 embedding_version: embedding.embeddingVersion,
                                 author: localAuthor,
                                 origin_project_id: null,
+                                tags: JSON.stringify(item.tags ?? null),
+                                expires_at: item.expiresAt ?? null,
                             });
                             const inserted = getMemoryRecordById(db, parsed.projectId, item.memoryId);
                             if (!inserted) {

package/dist/core/retrieve/decay.js

@@ -1,15 +1,22 @@
 const DEFAULT_DECAY_THRESHOLD_DAYS = 7;
 const DAY_IN_MS = 24 * 60 * 60 * 1000;
+/**
+ * Apply time-based importance decay. Memories decay by 1 point per week
+ * after the first week of inactivity, capping decay at -3 so even old
+ * memories remain discoverable (minimum effective importance = stored - 3).
+ * This produces a smoother ranking fade-out vs. the previous single -1 step.
+ */
 export function decayOldBoosts(memories, now = new Date(), thresholdDays = DEFAULT_DECAY_THRESHOLD_DAYS) {
     return memories.map((memory) => {
         const updatedAt = new Date(memory.updated_at);
         const ageDays = Math.max(0, (now.getTime() - updatedAt.getTime()) / DAY_IN_MS);
-        const shouldDecay = Number.isFinite(ageDays) && ageDays > thresholdDays;
+        const weeksOverThreshold = Number.isFinite(ageDays) && ageDays > thresholdDays
+            ? Math.floor((ageDays - thresholdDays) / 7)
+            : 0;
+        const decayAmount = Math.min(weeksOverThreshold, 3);
         return {
             ...memory,
-            decayedImportance: shouldDecay
-                ? Math.max(1, memory.importance - 1)
-                : memory.importance,
+            decayedImportance: Math.max(1, memory.importance - decayAmount),
         };
     });
 }

package/dist/core/schema/migrations/010_memory_tags.sql

@@ -0,0 +1,9 @@
+-- Memory tags: optional JSON-encoded string array for categorizing memories so
+-- they can be filtered at retrieval time. Added to the existing `memories` table
+-- without rewriting it so pre-existing rows survive (they get NULL tags).
+--
+-- Idempotency: SQLite has no `ADD COLUMN IF NOT EXISTS`. Re-running this
+-- migration (only possible if the _migrations record was lost) throws
+-- "duplicate column name", which runMigrations catches and treats as
+-- already-applied. See src/core/schema/runMigrations.ts.
+ALTER TABLE memories ADD COLUMN tags TEXT;

package/dist/core/schema/migrations/011_memory_expiry.sql

@@ -0,0 +1,9 @@
+-- Memory expiry: optional UTC ISO timestamp after which a memory is considered
+-- expired and excluded from retrieval/listing. Added to the existing `memories`
+-- table without rewriting it so pre-existing rows survive (NULL = never expires).
+--
+-- Idempotency: SQLite has no `ADD COLUMN IF NOT EXISTS`. Re-running this
+-- migration (only possible if the _migrations record was lost) throws
+-- "duplicate column name", which runMigrations catches and treats as
+-- already-applied. See src/core/schema/runMigrations.ts.
+ALTER TABLE memories ADD COLUMN expires_at TEXT;

package/dist/core/storage/memoryRepo.js

@@ -6,10 +6,12 @@ const UPSERT_INSERT_HEAD = `
   INSERT INTO memories (
     id, project_id, session_id, source_adapter, kind, content, normalized_content,
     importance, embedding, embedding_dim, embedding_version, author, origin_project_id,
+    tags, expires_at,
     created_at, updated_at
   ) VALUES (
     @id, @project_id, @session_id, @source_adapter, @kind, @content, @normalized_content,
     @importance, @embedding, @embedding_dim, @embedding_version, @author, @origin_project_id,
+    @tags, @expires_at,
     COALESCE(@created_at, strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
     COALESCE(@updated_at, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
   )
@@ -26,6 +28,8 @@ const UPSERT_INSERT_TAIL = `
     embedding_version = excluded.embedding_version,
     author = excluded.author,
     origin_project_id = excluded.origin_project_id,
+    tags = excluded.tags,
+    expires_at = excluded.expires_at,
     created_at = excluded.created_at,
     updated_at = excluded.updated_at
 `;
@@ -39,10 +43,12 @@ function getStatements(db) {
     INSERT INTO memories (
       id, project_id, session_id, source_adapter, kind, content, normalized_content,
       importance, embedding, embedding_dim, embedding_version, author, origin_project_id,
+      tags, expires_at,
       created_at, updated_at
     ) VALUES (
       @id, @project_id, @session_id, @source_adapter, @kind, @content, @normalized_content,
       @importance, @embedding, @embedding_dim, @embedding_version, @author, @origin_project_id,
+      @tags, @expires_at,
       COALESCE(@created_at, strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
       COALESCE(@updated_at, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
     )
@@ -51,10 +57,12 @@ function getStatements(db) {
     INSERT INTO memories (
       id, project_id, session_id, source_adapter, kind, content, normalized_content,
       importance, embedding, embedding_dim, embedding_version, author, origin_project_id,
+      tags, expires_at,
       created_at, updated_at
     ) VALUES (
       @id, @project_id, @session_id, @source_adapter, 'summary', @content, @normalized_content,
       @importance, @embedding, @embedding_dim, @embedding_version, @author, @origin_project_id,
+      @tags, @expires_at,
       COALESCE(@created_at, strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
       COALESCE(@updated_at, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
     )
@@ -70,6 +78,8 @@ function getStatements(db) {
       embedding_version = excluded.embedding_version,
       author = excluded.author,
       origin_project_id = excluded.origin_project_id,
+      tags = excluded.tags,
+      expires_at = excluded.expires_at,
       updated_at = COALESCE(excluded.updated_at, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
     ON CONFLICT(id)
     DO UPDATE SET
@@ -84,15 +94,19 @@ function getStatements(db) {
       embedding_version = excluded.embedding_version,
       author = excluded.author,
       origin_project_id = excluded.origin_project_id,
+      tags = excluded.tags,
+      expires_at = excluded.expires_at,
       updated_at = COALESCE(excluded.updated_at, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
   `),
         listByProject: db.prepare(`
     SELECT
       id, project_id, session_id, source_adapter, kind, content, normalized_content,
       importance, embedding, embedding_dim, embedding_version, author, origin_project_id,
+      tags, expires_at,
       access_count, last_accessed, created_at, updated_at
     FROM memories
     WHERE project_id = ?
+      AND (expires_at IS NULL OR expires_at > strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
     ORDER BY updated_at DESC
   `),
         // Lightweight projection for token-savings accounting: only `content` is
@@ -110,6 +124,7 @@ function getStatements(db) {
       SELECT
         id, project_id, session_id, source_adapter, kind, content, normalized_content,
         importance, embedding, embedding_dim, embedding_version, author, origin_project_id,
+        tags, expires_at,
         access_count, last_accessed, created_at, updated_at
       FROM memories
       WHERE project_id = ? AND id = ?
@@ -194,6 +209,8 @@ function toParams(input) {
         embedding_version: input.embedding_version ?? null,
         author: input.author ?? "",
         origin_project_id: input.origin_project_id ?? null,
+        tags: input.tags ?? null,
+        expires_at: input.expires_at ?? null,
         created_at: input.created_at ?? null,
         updated_at: input.updated_at ?? null,
     };

package/dist/core/storage/memorySearchRepo.js

@@ -14,6 +14,7 @@ function getSearchStatements(db) {
       embedding, embedding_dim, embedding_version
     FROM memories
     WHERE project_id = ?
+      AND (expires_at IS NULL OR expires_at > strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
       AND (
         importance >= 8
         OR updated_at > strftime('%Y-%m-%dT%H:%M:%fZ', 'now', '-90 days')
@@ -29,6 +30,7 @@ function getSearchStatements(db) {
     JOIN memories m ON m.rowid = memories_fts.rowid
     WHERE memories_fts MATCH ?
       AND m.project_id = ?
+      AND (m.expires_at IS NULL OR m.expires_at > strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
     ORDER BY rank
     LIMIT ?
   `),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sessionmem",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "private": false,
   "type": "module",
   "description": "Local-first MCP memory layer for coding agents across Claude Code, Codex, Cursor, Cline, Windsurf, and other MCP-compatible hosts.",