sessionmem 1.0.0

package/dist/cli/commands/stats.js

@@ -0,0 +1,46 @@
+import { statSync } from "fs";
+import { createCliContext } from "../context.js";
+import { countTokens } from "../../core/injection/tokenBudget.js";
+import { listMemoriesByProject } from "../../core/storage/memoryRepo.js";
+import { configFilePath, readPolicyConfig, } from "../../core/config/policyConfig.js";
+export async function statsCommand(ctx, options) {
+    const context = ctx ?? createCliContext();
+    const result = await context.service.call("stats", {
+        projectId: context.projectId,
+    });
+    if (!result.ok) {
+        console.error(result.error.message);
+        process.exit(1);
+    }
+    let sizeBytes = 0;
+    try {
+        sizeBytes = statSync(context.dbPath).size;
+    }
+    catch {
+        // dbPath may be ":memory:" or the file may have been removed; report 0
+    }
+    const totalTokens = listMemoriesByProject(context.db, context.projectId).reduce((sum, m) => sum + countTokens(m.content), 0);
+    // Effective policy: retention window + redaction state for visibility.
+    const { retentionDays, redactionEnabled } = readPolicyConfig(options?.configPath ?? configFilePath());
+    // retentionDays<=0 disables pruning; report that rather than a
+    // misleading eligible count against a non-positive window.
+    let retentionLine;
+    if (retentionDays <= 0) {
+        retentionLine = "Retention: pruning disabled (retentionDays <= 0)";
+    }
+    else {
+        const prune = await context.service.call("pruneMemories", {
+            projectId: context.projectId,
+            retentionDays,
+            dryRun: true,
+        });
+        const eligible = prune.ok ? prune.eligible : 0;
+        retentionLine = `Retention: ${retentionDays} days (${eligible} memories eligible for pruning)`;
+    }
+    const redactionLine = `Redaction: ${redactionEnabled ? "enabled" : "disabled"}`;
+    process.stdout.write(`memories: ${result.totalMemories}\n` +
+        `db_size_bytes: ${sizeBytes}\n` +
+        `total_content_tokens: ${totalTokens}\n` +
+        `${retentionLine}\n` +
+        `${redactionLine}\n`);
+}

package/dist/cli/commands/sync.js

@@ -0,0 +1,118 @@
+import { join } from "path";
+import { mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from "fs";
+import { configFilePath, readPolicyConfig, } from "../../core/config/policyConfig.js";
+import { importMemoryRecordSchema } from "../../core/api/contracts.js";
+import { createCliContext } from "../context.js";
+/**
+ * `sessionmem sync` — push a full snapshot of local project memories to the
+ * shared path and pull every teammate's snapshot back into the local DB.
+ *
+ * No-ops with a clear message when team mode is disabled. Push writes
+ * `{sharedPath}/{projectId}/{username}.json` atomically (temp-file + rename).
+ * Pull enumerates every other `*.json` in that dir, skip-and-warns
+ * on unreadable/non-array files, validates each record, and merges
+ * via `pullMemories` (MAX-importance LWW + re-redaction + cross-project skip).
+ */
+export async function syncCommand(ctx, options) {
+    const context = ctx ?? createCliContext();
+    const config = readPolicyConfig(options?.configPath ?? configFilePath());
+    const { enabled, sharedPath } = config.team;
+    // Clean no-op (exit 0) when team mode is off or unconfigured.
+    if (!enabled || !sharedPath) {
+        console.log("Team mode is not enabled. Run `sessionmem team enable <path>`.");
+        return;
+    }
+    // ---- PUSH (model export.ts) ----
+    const exportRes = await context.service.call("exportMemories", {
+        projectId: context.projectId,
+    });
+    if (!exportRes.ok) {
+        console.error(exportRes.error.message);
+        process.exit(1);
+        return;
+    }
+    // Build every shared path with path.join ONLY (Windows/UNC safe).
+    // The project dir + filename derive from the LOCAL projectId/username, never
+    // from a string inside a teammate file.
+    // projectId/username are sanitized to [A-Za-z0-9._-] in context.ts
+    // (localUsername/deriveProjectId), so no path traversal here.
+    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
+    const dir = join(sharedPath, context.projectId);
+    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
+    const finalPath = join(dir, `${context.username}.json`);
+    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
+    const tmpPath = join(dir, `${context.username}.json.tmp`);
+    try {
+        mkdirSync(dir, { recursive: true });
+        // Atomic write — temp file in the SAME dir then rename,
+        // so a teammate never reads a half-written snapshot off a network drive.
+        writeFileSync(tmpPath, JSON.stringify(exportRes.memories, null, 2), "utf8");
+        renameSync(tmpPath, finalPath);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // Missing/unwritable shared path -> stderr + non-zero exit.
+        console.error(`Failed to write to shared path: ${message}`);
+        process.exit(1);
+        return;
+    }
+    const pushed = exportRes.memories.length;
+    // ---- PULL (model import.ts) ----
+    let teammateFiles;
+    try {
+        teammateFiles = readdirSync(dir).filter((f) => f.endsWith(".json") && f !== `${context.username}.json`);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`Failed to read shared path: ${message}`);
+        process.exit(1);
+        return;
+    }
+    const memories = [];
+    for (const file of teammateFiles) {
+        let parsed;
+        try {
+            // A truncated/corrupt teammate file is skipped-and-warned, never
+            // aborting the rest of the pull.
+            // file comes from readdirSync(dir) filtered to *.json entries, so it is
+            // a plain filename with no path separators, not user input.
+            // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
+            parsed = JSON.parse(readFileSync(join(dir, file), "utf8"));
+        }
+        catch {
+            console.error(`Skipping unreadable teammate file: ${file}`);
+            continue;
+        }
+        if (!Array.isArray(parsed)) {
+            console.error(`Skipping teammate file (not an array): ${file}`);
+            continue;
+        }
+        for (const raw of parsed) {
+            // Carry author/originProjectId through; per-record skip-and-warn so one
+            // bad record never discards the rest.
+            const check = importMemoryRecordSchema.safeParse(raw);
+            if (!check.success) {
+                console.error(`Skipping invalid record in ${file}: ${check.error.message}`);
+                continue;
+            }
+            memories.push(check.data);
+        }
+    }
+    let pulledNew = 0;
+    let pulledUpdated = 0;
+    if (memories.length > 0) {
+        const pullRes = await context.service.call("pullMemories", {
+            projectId: context.projectId,
+            memories,
+        });
+        if (!pullRes.ok) {
+            console.error(pullRes.error.message);
+            process.exit(1);
+            return;
+        }
+        pulledNew = pullRes.pulledNew;
+        pulledUpdated = pullRes.pulledUpdated;
+    }
+    // The exact summary string.
+    console.log(`Pushed ${pushed} memories, pulled ${pulledNew} new + updated ${pulledUpdated} from teammates.`);
+}

package/dist/cli/commands/team.js

@@ -0,0 +1,96 @@
+import { accessSync, constants, existsSync, unlinkSync, writeFileSync } from "fs";
+import { join } from "path";
+import { randomUUID } from "crypto";
+import { configFilePath, readPolicyConfig, writePolicyConfig, } from "../../core/config/policyConfig.js";
+import { createCliContext } from "../context.js";
+function resolvePath(options) {
+    return options?.configPath ?? configFilePath();
+}
+/**
+ * `sessionmem team enable <path>` — turn on team mode and record the shared path.
+ * Missing/empty path -> error to stderr + exit 1.
+ */
+export function teamEnableCommand(sharedPath, options) {
+    if (!sharedPath || sharedPath.trim() === "") {
+        console.error("team enable requires a shared path argument.");
+        process.exit(1);
+        return;
+    }
+    writePolicyConfig(resolvePath(options), {
+        team: { enabled: true, sharedPath },
+    });
+    console.log(`Team mode enabled. Shared path: ${sharedPath}`);
+}
+/**
+ * `sessionmem team status` — print enabled state + the shared path, and report
+ * whether that path exists and is writable. Reads local fs only.
+ * Does NOT print a last-sync time — there is no synced_at column.
+ */
+export function teamStatusCommand(options) {
+    const config = readPolicyConfig(resolvePath(options));
+    const { enabled, sharedPath } = config.team;
+    console.log(`Team mode: ${enabled ? "enabled" : "disabled"}`);
+    if (!sharedPath) {
+        console.log("Shared path: not set");
+        return;
+    }
+    console.log(`Shared path: ${sharedPath}`);
+    if (!existsSync(sharedPath)) {
+        console.log("Shared path status: does not exist");
+        return;
+    }
+    // accessSync(..., W_OK) is unreliable on Windows for directories
+    // (NTFS ACL semantics differ from POSIX access(), and Node largely ignores
+    // W_OK for directories on Windows). Probe by creating and removing a temp
+    // file, falling back to accessSync only if the probe itself errors
+    // unexpectedly (e.g. sharedPath is not a directory).
+    // Defensive init: guarantees a definite value before the read below even if a
+    // probe branch is later added.
+    // eslint-disable-next-line no-useless-assignment
+    let writable = false;
+    // sharedPath is operator-configured (team enable <path>); the filename
+    // suffix is a randomUUID(), not user input.
+    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
+    const probePath = join(sharedPath, `.sessionmem-write-test-${randomUUID()}`);
+    try {
+        writeFileSync(probePath, "");
+        writable = true;
+        try {
+            unlinkSync(probePath);
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+    }
+    catch {
+        try {
+            accessSync(sharedPath, constants.W_OK);
+            writable = true;
+        }
+        catch {
+            writable = false;
+        }
+    }
+    console.log(`Shared path status: exists, ${writable ? "writable" : "not writable"}`);
+}
+/**
+ * `sessionmem team disable [--remove-team-memories]` — stop team sync.
+ *
+ * By default, flip enabled to false and KEEP already-pulled teammate
+ * rows (no data loss). With `--remove-team-memories`, additionally
+ * delete rows authored by someone other than the local username for the current
+ * project, reverting to a local-only store. The DELETE binds projectId/username
+ * as parameters — never string-concatenated.
+ */
+export function teamDisableCommand(options, ctx) {
+    writePolicyConfig(resolvePath(options), { team: { enabled: false } });
+    if (!options?.removeTeamMemories) {
+        console.log("Team mode disabled. Teammate memories preserved.");
+        return;
+    }
+    const context = ctx ?? createCliContext();
+    const result = context.db
+        .prepare("DELETE FROM memories WHERE project_id = ? AND author != ? AND author != ''")
+        .run(context.projectId, context.username);
+    console.log(`Team mode disabled. Removed ${result.changes} teammate-authored ${result.changes === 1 ? "memory" : "memories"}.`);
+}

package/dist/cli/commands/uninstall.js

@@ -0,0 +1,30 @@
+import { existsSync, rmSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { AdapterFactory } from "../../adapters/factory.js";
+export async function uninstallCommand(options = {}) {
+    const adapter = AdapterFactory.detectAdapter();
+    if (!adapter.uninstall) {
+        console.error(`${adapter.name} does not support automated uninstall. Remove sessionmem from your MCP config manually.`);
+        process.exit(1);
+    }
+    const success = await adapter.uninstall();
+    if (!success) {
+        console.error(`✗ ${adapter.name} config removal failed`);
+        process.exit(1);
+    }
+    console.log(`✓ ${adapter.name} config removed`);
+    // Resolve dbPath: use injected override (for tests) or the default location
+    const dbPath = options.dbPath ?? join(homedir(), ".sessionmem", "memories.db");
+    if (options.purge) {
+        // --purge: delete only memories.db, not logs or the ~/.sessionmem directory
+        if (existsSync(dbPath)) {
+            rmSync(dbPath, { force: true });
+        }
+        console.log("✓ memories.db deleted");
+    }
+    else {
+        // Default: preserve memories.db
+        console.log(`Memory DB preserved at ${dbPath}`);
+    }
+}

package/dist/cli/context.js

@@ -0,0 +1,69 @@
+import { homedir, userInfo } from "os";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { mkdirSync } from "fs";
+import { openDb } from "../core/storage/db.js";
+import { createMemoryCoreService } from "../core/api/memoryCoreService.js";
+/**
+ * Resolve the local OS username once per invocation and sanitize it to a
+ * filename-safe token so it can be embedded in exports/filenames without path
+ * traversal. Any character outside [A-Za-z0-9._-] becomes "_"; an empty result
+ * falls back to "user".
+ */
+export function localUsername() {
+    // Env override is a test-injection seam (mirrors deriveProjectId): the CLI
+    // runs as the invoking user, so SESSIONMEM_USERNAME is operator-controlled at
+    // the same trust level.
+    const envUsername = process.env.SESSIONMEM_USERNAME;
+    const raw = envUsername && envUsername.trim() !== "" ? envUsername : safeUserInfoName();
+    const sanitized = raw.replace(/[^A-Za-z0-9._-]/g, "_");
+    return sanitized === "" ? "user" : sanitized;
+}
+function safeUserInfoName() {
+    try {
+        return userInfo().username ?? "";
+    }
+    catch {
+        // userInfo() can throw on some platforms when there is no /etc/passwd entry.
+        return "";
+    }
+}
+function deriveProjectId() {
+    // Env override is a test-injection seam (mirrors Plan 01's override pattern):
+    // it lets a spawned binary target a deterministic projectId without touching
+    // the real ~/.sessionmem. No privilege boundary is crossed — the CLI runs as
+    // the invoking user and the env var is operator-controlled.
+    const envProjectId = process.env.SESSIONMEM_PROJECT_ID;
+    if (envProjectId && envProjectId.trim() !== "")
+        return envProjectId;
+    const cwd = process.cwd();
+    const parts = cwd.replace(/\\/g, "/").split("/");
+    const raw = parts[parts.length - 1] || "default";
+    // Sanitize to a filename-safe token (mirrors localUsername) so it can be
+    // embedded in shared-path join()s without path traversal.
+    const sanitized = raw.replace(/[^A-Za-z0-9._-]/g, "_");
+    return sanitized === "" || sanitized === "." || sanitized === ".."
+        ? "default"
+        : sanitized;
+}
+function defaultDbPath(dir) {
+    // Env override seam (see deriveProjectId). Defaults to ~/.sessionmem/memories.db.
+    const envDbPath = process.env.SESSIONMEM_DB_PATH;
+    if (envDbPath && envDbPath.trim() !== "")
+        return envDbPath;
+    // `dir` is the fixed ~/.sessionmem dir computed above, not user input.
+    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
+    return join(dir, "memories.db");
+}
+export function createCliContext(overrides = {}) {
+    const dir = join(homedir(), ".sessionmem");
+    mkdirSync(dir, { recursive: true });
+    const dbPath = overrides.dbPath ?? defaultDbPath(dir);
+    const here = dirname(fileURLToPath(import.meta.url));
+    const migrationsDir = overrides.migrationsDir ?? join(here, "..", "core", "schema", "migrations");
+    const username = overrides.username ?? localUsername();
+    const db = overrides.db ?? openDb({ dbPath, migrationsDir });
+    const service = overrides.service ?? createMemoryCoreService({ db, username });
+    const projectId = overrides.projectId ?? deriveProjectId();
+    return { db, service, projectId, username, dbPath };
+}

package/dist/cli/index.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { createRequire } from "node:module";
+import { runMcpServer } from "./commands/run.js";
+import { installCommand } from "./commands/install.js";
+import { uninstallCommand } from "./commands/uninstall.js";
+import { pingCommand } from "./commands/ping.js";
+import { searchCommand } from "./commands/search.js";
+import { listCommand } from "./commands/list.js";
+import { showCommand } from "./commands/show.js";
+import { forgetCommand } from "./commands/forget.js";
+import { exportCommand } from "./commands/export.js";
+import { importCommand } from "./commands/import.js";
+import { statsCommand } from "./commands/stats.js";
+import { redactScanCommand } from "./commands/redactScan.js";
+import { retentionPruneCommand } from "./commands/retention.js";
+import { configGetCommand, configSetCommand } from "./commands/config.js";
+import { teamEnableCommand, teamDisableCommand, teamStatusCommand, } from "./commands/team.js";
+import { syncCommand } from "./commands/sync.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
+// "../../package.json" specifier resolves to the package root.
+const pkg = createRequire(import.meta.url)("../../package.json");
+const program = new Command();
+program.name("sessionmem").version(pkg.version);
+program
+    .command("run")
+    .description("Start the sessionmem MCP server")
+    .action(runMcpServer);
+program
+    .command("install")
+    .description("Install sessionmem into the current MCP host")
+    .action(installCommand);
+program
+    .command("uninstall")
+    .description("Remove sessionmem from the current MCP host")
+    .option("--purge", "Also delete the local memories database")
+    .action(uninstallCommand);
+program
+    .command("ping")
+    .description("Check sessionmem server connectivity")
+    .action(pingCommand);
+// NOTE: commander always appends its own Command instance as the final
+// argument to .action() callbacks. The search/list/show/forget/export/import/
+// stats commands all declare a trailing `ctx?: CliContext` parameter (the
+// test-injection seam). Passing a bare function reference would let commander's
+// Command object land in the ctx slot, so `ctx ?? createCliContext()` resolves
+// to a Command (which has no `.service`) and every command crashes at runtime.
+// Arrow-wrap each handler to forward ONLY the real positional args/options and
+// drop commander's trailing Command argument, leaving ctx undefined in
+// production so each command falls through to createCliContext().
+program
+    .command("search <query>")
+    .description("Search memories by semantic query")
+    .option("--limit <n>", "Maximum number of results", "10")
+    .action((query, options) => searchCommand(query, options));
+program
+    .command("list")
+    .description("List all memories for the current project")
+    .action(() => listCommand());
+program
+    .command("show <id>")
+    .description("Show full details of a memory by ID")
+    .action((id) => showCommand(id));
+program
+    .command("forget <id>")
+    .description("Delete a memory by ID")
+    .option("--force", "Confirm deletion without dry-run prompt")
+    .action((id, options) => forgetCommand(id, options));
+program
+    .command("export [path]")
+    .description("Export memories to a JSON file")
+    .action((path) => exportCommand(path));
+program
+    .command("import <path>")
+    .description("Import memories from a JSON file")
+    .option("--merge", "Overwrite existing memories with imported data")
+    .action((path, options) => importCommand(path, options));
+program
+    .command("stats")
+    .description("Show memory statistics for the current project")
+    .action(() => statsCommand());
+// redact-scan — one-time scrub over existing memories. Scan is the
+// non-destructive default; --apply redacts matching rows in place.
+program
+    .command("redact-scan")
+    .description("Scan existing memories for secrets (dry-run by default)")
+    .option("--apply", "Redact matching memories in place")
+    .action((options) => redactScanCommand(options));
+// retention command group — room for future subcommands. The "prune"
+// subcommand is dry-run by default; --force confirms the hard delete.
+const retention = program
+    .command("retention")
+    .description("Retention policy operations");
+retention
+    .command("prune")
+    .description("Delete memories older than the retention window (dry-run by default)")
+    .option("--force", "Confirm deletion without dry-run")
+    .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");
+config
+    .command("get <key>")
+    .description("Print the effective value of a config key")
+    .action((key) => configGetCommand(key));
+config
+    .command("set <key> <value>")
+    .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");
+team
+    .command("enable <path>")
+    .description("Enable team mode and record the shared memory path")
+    .action((path) => teamEnableCommand(path));
+team
+    .command("disable")
+    .description("Disable team mode (teammate memories preserved by default)")
+    .option("--remove-team-memories", "Also delete teammate-authored memories for this project (local-only revert)")
+    .action((options) => teamDisableCommand(options));
+team
+    .command("status")
+    .description("Show team mode state and shared-path availability")
+    .action(() => teamStatusCommand());
+// 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).
+program
+    .command("sync")
+    .description("Push local memories and pull teammate memories via the shared path")
+    .action(() => syncCommand());
+program.parseAsync(process.argv).catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist/cli/output.js

@@ -0,0 +1,37 @@
+export function formatTable(rows) {
+    const ID_WIDTH = 36;
+    const IMP_WIDTH = 10;
+    const DATE_WIDTH = 10;
+    const PREVIEW_WIDTH = 60;
+    const header = "ID".padEnd(ID_WIDTH) +
+        " | " +
+        "importance".padEnd(IMP_WIDTH) +
+        " | " +
+        "date".padEnd(DATE_WIDTH) +
+        " | " +
+        "preview";
+    const lines = rows.map((row) => {
+        const preview = row.content.replace(/\s+/g, " ").slice(0, PREVIEW_WIDTH);
+        const date = row.createdAt.slice(0, 10);
+        return (row.id.padEnd(ID_WIDTH) +
+            " | " +
+            String(row.importance).padEnd(IMP_WIDTH) +
+            " | " +
+            date.padEnd(DATE_WIDTH) +
+            " | " +
+            preview);
+    });
+    return [header, ...lines].join("\n");
+}
+export function formatKeyValue(memory) {
+    const lines = [
+        `id: ${memory.id}`,
+        `content: ${memory.content}`,
+        `importance: ${memory.importance}`,
+        `created_at: ${memory.createdAt}`,
+        `session_id: ${memory.sessionId}`,
+        `project_id: ${memory.projectId}`,
+        `source_adapter: ${memory.sourceAdapter}`,
+    ];
+    return lines.join("\n");
+}