sessionmem 1.1.2 → 1.3.0

package/dist/cli/commands/ingestHook.js

@@ -0,0 +1,193 @@
+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;
+// Per-field cap applied BEFORE serialization. Truncating the serialized JSON
+// instead would produce a string that is no longer valid JSON, which the
+// `payloadJson` contract rejects (it parses the value) — the event would then be
+// dropped, silently, by the catch-all below. Trim the inputs, not the output.
+const MAX_FIELD_CHARS = 1200;
+// One-line human summary shown in session summaries (summaryShape reads `text`).
+const MAX_TEXT_CHARS = 300;
+/** Emit a hook diagnostic to stderr when SESSIONMEM_DEBUG=1. */
+function debug(message) {
+    if (process.env.SESSIONMEM_DEBUG === "1") {
+        process.stderr.write(`[sessionmem] ingest-hook: ${message}\n`);
+    }
+}
+function truncate(value, max) {
+    return value.length > max ? `${value.slice(0, max)}…` : value;
+}
+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()}`;
+}
+/**
+ * Shorten every string in a tool input to MAX_FIELD_CHARS, recursively. Keeps
+ * the object's shape (so it still serializes to valid JSON) while bounding the
+ * size contributed by large fields such as a Write tool's `content` or an Edit
+ * tool's replacement text.
+ */
+function shrinkValue(value, depth = 0) {
+    if (typeof value === "string")
+        return truncate(value, MAX_FIELD_CHARS);
+    if (depth >= 4)
+        return undefined;
+    if (Array.isArray(value)) {
+        return value.slice(0, 20).map((item) => shrinkValue(item, depth + 1));
+    }
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [key, inner] of Object.entries(value)) {
+            out[key] = shrinkValue(inner, depth + 1);
+        }
+        return out;
+    }
+    // Numbers/booleans/null pass through; functions/undefined/symbols drop out.
+    return value === undefined || typeof value === "function" || typeof value === "symbol"
+        ? undefined
+        : value;
+}
+/**
+ * A short human-readable line describing the tool use. Stored alongside the
+ * structured input as `text`, which the local summarizer prefers over the raw
+ * payload — so session summaries read as prose instead of dumped JSON.
+ */
+function describeToolUse(toolName, input) {
+    const str = (key) => typeof input?.[key] === "string" ? input[key] : "";
+    if (toolName === "Bash") {
+        const command = str("command").replace(/\s+/g, " ").trim();
+        return truncate(command ? `Ran: ${command}` : "Ran a shell command", MAX_TEXT_CHARS);
+    }
+    const filePath = str("file_path") || str("path") || str("notebook_path");
+    const verb = toolName === "Write" ? "Wrote" : "Edited";
+    return truncate(filePath ? `${verb} ${filePath}` : `${verb} a file`, MAX_TEXT_CHARS);
+}
+/**
+ * Serialize the event payload, guaranteeing valid JSON within
+ * MAX_HOOK_PAYLOAD_CHARS. Per-field shrinking handles the common case; if the
+ * result is still over budget (many fields, or one huge key set), drop the
+ * structured input and keep only the human-readable summary rather than
+ * emitting truncated — and therefore unparseable — JSON.
+ */
+function buildPayloadJson(toolName, text, input, cwd) {
+    const full = JSON.stringify({
+        tool: toolName,
+        text,
+        input: shrinkValue(input),
+        cwd,
+    });
+    if (full.length <= MAX_HOOK_PAYLOAD_CHARS)
+        return full;
+    return JSON.stringify({ tool: toolName, text, cwd, truncated: true });
+}
+/**
+ * `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) {
+    let context;
+    try {
+        const payload = await readStdinJson();
+        const toolName = payload.tool_name ?? "";
+        if (!CAPTURED_TOOL_TYPES.has(toolName)) {
+            debug(`skipped: tool "${toolName}" is not captured`);
+            return;
+        }
+        context = ctx ?? createCliContext();
+        const sessionId = resolveSessionId(payload);
+        const projectId = context.projectId;
+        const text = describeToolUse(toolName, payload.tool_input);
+        // eventIndex is intentionally omitted: the service assigns the next free
+        // index per session inside an immediate transaction, so parallel tool calls
+        // cannot collide (see nextSessionEventIndex).
+        const result = await context.service.call("ingestSessionEvents", {
+            projectId,
+            sessionId,
+            events: [{
+                    id: randomUUID(),
+                    eventType: `tool_use:${toolName.toLowerCase()}`,
+                    payloadJson: buildPayloadJson(toolName, text, payload.tool_input, payload.cwd),
+                }],
+        });
+        if (!result.ok) {
+            debug(`ingest failed: ${result.error.message}`);
+        }
+        else {
+            debug(`ingested ${result.ingested} event(s) for session ${sessionId} (project ${projectId})`);
+        }
+        // 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,
+                    });
+                }
+            }
+        }
+    }
+    catch (err) {
+        // Never block tool use — a hook failure must not surface as a tool error.
+        debug(err instanceof Error ? err.message : String(err));
+    }
+    finally {
+        // Close only a context this command opened; an injected ctx belongs to the
+        // caller (tests reuse it across assertions). Previously the close was
+        // inside the try block, so it was skipped on every error path and leaked
+        // the sqlite handle.
+        if (!ctx && context) {
+            try {
+                context.db.close();
+            }
+            catch { /* already closed */ }
+        }
+    }
+}

package/dist/cli/commands/savings.js

@@ -63,7 +63,9 @@ export function savingsCommand(ctx, options) {
         ? [
             "Storage compression:",
             "  No session data ingested yet.",
-            "  Tip: call ingestSessionEvents during sessions to track token usage.",
+            "  Session events are captured automatically by the PostToolUse hook.",
+            "  If this stays empty, run `sessionmem install` to (re)register the hook,",
+            "  then check `sessionmem stats` for the session_events counter.",
         ]
         : [
             "Storage compression:",

package/dist/cli/commands/stats.js

@@ -2,6 +2,7 @@ import { statSync } from "fs";
 import { createCliContext } from "../context.js";
 import { countTokens } from "../../core/injection/tokenBudget.js";
 import { listMemoriesByProject } from "../../core/storage/memoryRepo.js";
+import { countDistinctSessions } from "../../core/storage/tokenSavingsRepo.js";
 import { configFilePath, readPolicyConfig, } from "../../core/config/policyConfig.js";
 export async function statsCommand(ctx, options) {
     const context = ctx ?? createCliContext();
@@ -38,7 +39,13 @@ export async function statsCommand(ctx, options) {
         retentionLine = `Retention: ${retentionDays} days (${eligible} memories eligible for pruning)`;
     }
     const redactionLine = `Redaction: ${redactionEnabled ? "enabled" : "disabled"}`;
+    // Surface the session-event counters. The auto-ingest pipeline is silent by
+    // design (a hook must never fail a tool call), so without these lines a
+    // pipeline that captures nothing looks identical to one that works.
+    const sessions = countDistinctSessions(context.db, context.projectId);
     process.stdout.write(`memories: ${result.totalMemories}\n` +
+        `sessions: ${sessions}\n` +
+        `session_events: ${result.totalSessionEvents}\n` +
         `db_size_bytes: ${sizeBytes}\n` +
         `total_content_tokens: ${totalTokens}\n` +
         `${retentionLine}\n` +

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")
@@ -119,8 +126,6 @@ retention
     .option("--days <n>", "Override the retention window in days")
     .action((options) => retentionPruneCommand(options));
 // config command group — generic get/set over ~/.sessionmem/config.json.
-// config get/set are synchronous and take no CliContext, so the arrow-wrap here
-// only drops commander's trailing Command argument.
 const config = program
     .command("config")
     .description("Read and write sessionmem policy config");
@@ -133,10 +138,6 @@ config
     .description("Persist a config key to ~/.sessionmem/config.json")
     .action((key, value) => configSetCommand(key, value));
 // team command group — turn shared-memory mode on/off and inspect it.
-// enable/status take no CliContext (config-only), so their arrow-wraps just drop
-// commander's trailing Command argument. disable accepts an optional CliContext
-// seam for the --remove-team-memories DB delete; the arrow-wrap forwards only
-// options so production falls through to createCliContext() (NOTE above).
 const team = program
     .command("team")
     .description("Manage shared-path team memory mode");
@@ -154,19 +155,30 @@ team
     .description("Show team mode state and shared-path availability")
     .action(() => teamStatusCommand());
 // re-embed — bulk-update stale embeddings to the current version.
-// reEmbedCommand declares a trailing `ctx?` test seam, so arrow-wrap to drop
-// commander's trailing Command argument (NOTE above).
 program
     .command("re-embed")
     .description("Re-embed all memories with stale embedding versions")
     .action(() => reEmbedCommand());
-// sync — push a local snapshot to the shared path and pull every
-// teammate snapshot back. syncCommand declares a trailing `ctx?` test seam, so
-// arrow-wrap to drop commander's trailing Command argument (NOTE above).
+// sync — push a local snapshot to the shared path and pull every teammate
+// snapshot back.
 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/cli/projectId.js

@@ -1,4 +1,43 @@
 import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+/** Safety bound on the upward walk in {@link findProjectRoot}. */
+const MAX_PARENT_WALK = 64;
+/**
+ * Walk up from `startDir` to the nearest directory containing `.git`, and
+ * return it. Returns null when there is no repository above `startDir`.
+ *
+ * Memory is keyed by project, and a project is the repository — not whichever
+ * directory a command happened to run in. Hashing the raw cwd meant every
+ * subdirectory got its OWN bucket: the Claude Code hooks fire at the repo root
+ * and write there, then `sessionmem stats` run from `src/` reported an empty
+ * store, because it was reading a different project entirely.
+ *
+ * `.git` is matched as a path entry rather than a directory so linked worktrees
+ * and submodules (where `.git` is a FILE pointing at the real gitdir) anchor
+ * correctly too.
+ */
+export function findProjectRoot(startDir) {
+    let current = resolve(startDir);
+    for (let depth = 0; depth < MAX_PARENT_WALK; depth += 1) {
+        try {
+            // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
+            if (existsSync(join(current, ".git"))) {
+                return current;
+            }
+        }
+        catch {
+            // Unreadable directory (permissions, race): stop rather than throw — the
+            // caller falls back to the cwd-derived id.
+            return null;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break; // filesystem root
+        current = parent;
+    }
+    return null;
+}
 /**
  * Sanitize a raw token to the filename-safe character set used across
  * sessionmem (mirrors localUsername). Any character outside [A-Za-z0-9._-]
@@ -45,7 +84,13 @@ export function projectIdFromCwd(cwd) {
 /**
  * Resolve the effective project id: the `SESSIONMEM_PROJECT_ID` env override
  * (operator-controlled test/migration seam; also lets a user pin a legacy
- * basename-only id) wins, otherwise derive from `process.cwd()`.
+ * basename-only id) wins, otherwise derive from the enclosing repository root,
+ * falling back to `process.cwd()` when the cwd is not inside a repository.
+ *
+ * Anchoring to the repository keeps every command — hooks firing at the root,
+ * a `sessionmem stats` typed three directories down — on the same memory
+ * bucket. The id is unchanged for anyone already running at the repo root,
+ * since the root IS the cwd in that case.
  */
 export function deriveProjectId() {
     const envProjectId = process.env.SESSIONMEM_PROJECT_ID;
@@ -65,5 +110,6 @@ export function deriveProjectId() {
             return sanitized;
         }
     }
-    return projectIdFromCwd(process.cwd());
+    const cwd = process.cwd();
+    return projectIdFromCwd(findProjectRoot(cwd) ?? cwd);
 }

package/dist/core/api/contracts.js

@@ -58,12 +58,19 @@ 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),
 });
 export const ingestSessionEventSchema = z.object({
     id: z.string().min(1).max(200),
-    eventIndex: z.number().int().nonnegative(),
+    // Optional: callers that already track an ordering key (batch ingestion of a
+    // transcript) supply it; callers that fire one event at a time from separate
+    // processes (the PostToolUse hook) omit it and the service assigns the next
+    // free index per session. See nextSessionEventIndex for why inventing a
+    // wall-clock index silently loses events.
+    eventIndex: z.number().int().nonnegative().optional(),
     eventType: z.string().min(1).max(100),
     payloadJson: z
         .string()
@@ -144,6 +151,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 +160,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 +390,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

@@ -8,7 +8,7 @@ import { applyRedaction } from "../summarize/redaction.js";
 import { countAllMemoriesByProject, countMemoriesBySession, countMemoriesOlderThan, deleteMemoriesOlderThan, deleteMemoryById, getMemoryOwnerProjectId, getMemoryRecordById, incrementAccessCounts, insertMemory, listMemoriesByProject, resetAccessCounts, updateMemoryContent, upsertImportedMemory, upsertPulledMemory, upsertSessionSummaryMemory, } from "../storage/memoryRepo.js";
 import { SESSION_WRITE_SOFT_LIMIT, configFilePath, DEEP_MODE_RETRIEVAL_CAP, readPolicyConfig, resolvePolicySettings, } from "../config/policyConfig.js";
 import { insertMemoryFeedbackEvent } from "../storage/memoryFeedbackRepo.js";
-import { countAllSessionEvents, insertSessionEvent } from "../storage/sessionEventsRepo.js";
+import { countAllSessionEvents, insertSessionEvent, nextSessionEventIndex, } from "../storage/sessionEventsRepo.js";
 import { batchStoreMemoryItemSchema, batchStoreMemoryRequestSchema, exportMemoriesRequestSchema, forgetMemoryRequestSchema, getMemoryRequestSchema, handleSessionEndRequestSchema, importMemoriesRequestSchema, pullMemoriesRequestSchema, ingestSessionEventsRequestSchema, LIST_MEMORIES_DEFAULT_LIMIT, listMemoriesRequestSchema, pruneMemoriesRequestSchema, redactExistingRequestSchema, resetAccessCountsRequestSchema, retrieveMemoriesRequestSchema, statsRequestSchema, storeMemoryRequestSchema, summarizeSessionToMemoryRequestSchema, } from "./contracts.js";
 import { DomainError, toErrorEnvelope } from "./errors.js";
 import { assertLocalOnlyPolicy, } from "./localOnlyPolicy.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,
@@ -180,15 +186,25 @@ export function createMemoryCoreService(deps) {
             const redactionEnabled = resolveRedactionEnabled(undefined);
             const ingest = db.transaction(() => {
                 let written = 0;
+                // Events that omit eventIndex are appended after the session's current
+                // maximum. Read it once inside the transaction and increment locally so
+                // a multi-event batch stays contiguous.
+                let nextIndex;
                 for (const event of parsed.events) {
                     const redactedPayload = applyRedaction(event.payloadJson, {
                         redactionEnabled,
                     }).text;
+                    let eventIndex = event.eventIndex;
+                    if (eventIndex === undefined) {
+                        nextIndex ??= nextSessionEventIndex(db, parsed.projectId, parsed.sessionId);
+                        eventIndex = nextIndex;
+                        nextIndex += 1;
+                    }
                     written += insertSessionEvent(db, {
                         id: event.id,
                         project_id: parsed.projectId,
                         session_id: parsed.sessionId,
-                        event_index: event.eventIndex,
+                        event_index: eventIndex,
                         event_type: event.eventType,
                         payload_json: redactedPayload,
                         created_at: event.createdAt,
@@ -196,7 +212,11 @@ export function createMemoryCoreService(deps) {
                 }
                 return written;
             });
-            const ingested = ingest();
+            // `immediate` takes the write lock up front so two concurrent hook
+            // processes cannot both read the same next index and have one insert
+            // silently ignored. busy_timeout (db.ts) makes the loser wait rather
+            // than fail.
+            const ingested = ingest.immediate();
             return {
                 ok: true,
                 ingested,
@@ -269,6 +289,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 +311,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 +708,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/retrieve/retrieveMemories.js

@@ -43,7 +43,7 @@ export function retrieveMemories(input) {
     const now = input.now ?? new Date();
     // Use FTS5 pre-filtering to limit cosine similarity computation to ~50 candidates.
     // queryText is guaranteed non-empty by the Zod schema (z.string().min(1)) upstream.
-    const candidates = searchMemoryCandidatesFTS(input.db, input.projectId, queryText);
+    const candidates = searchMemoryCandidatesFTS(input.db, input.projectId, queryText, now);
     const decayedCandidates = decayOldBoosts(candidates, now);
     const dimension = resolveEmbeddingDimension(candidates);
     const queryVector = deterministicEmbed(queryText, dimension).vector;

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;