@iamem/amem 0.1.0

package/dist/freshness.js

@@ -0,0 +1,93 @@
+import { existsSync, statSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+export function parseAnchors(codeAnchorsJson) {
+    try {
+        const parsed = JSON.parse(codeAnchorsJson);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((a) => typeof a === "string" && Boolean(a.trim()));
+    }
+    catch {
+        return [];
+    }
+}
+function resolveAnchorPath(rootPath, anchor) {
+    if (isAbsolute(anchor))
+        return anchor;
+    return join(rootPath, anchor);
+}
+/**
+ * Compare claim.updated_at to filesystem mtimes of code_anchors.
+ * Missing paths → missing_anchor; any newer file → stale.
+ */
+export function assessClaimFreshness(rootPath, claim) {
+    const anchors = parseAnchors(claim.code_anchors);
+    if (anchors.length === 0) {
+        return { status: "unanchored", staleAnchors: [], missingAnchors: [] };
+    }
+    if (!rootPath) {
+        return { status: "unknown", staleAnchors: [], missingAnchors: [] };
+    }
+    const claimUpdatedMs = Date.parse(claim.updated_at);
+    if (Number.isNaN(claimUpdatedMs)) {
+        return { status: "unknown", staleAnchors: [], missingAnchors: [] };
+    }
+    const staleAnchors = [];
+    const missingAnchors = [];
+    let sawFile = false;
+    for (const anchor of anchors) {
+        const full = resolveAnchorPath(rootPath, anchor);
+        if (!existsSync(full)) {
+            // Workspace-style anchors (slug names) are not real paths — ignore those.
+            if (!anchor.includes("/") && !anchor.includes("\\") && !anchor.includes(".")) {
+                continue;
+            }
+            missingAnchors.push(anchor);
+            continue;
+        }
+        try {
+            const st = statSync(full);
+            if (!st.isFile() && !st.isDirectory())
+                continue;
+            sawFile = true;
+            // 2s skew: avoid false stale right after apply on slow FS
+            if (st.mtimeMs > claimUpdatedMs + 2000) {
+                staleAnchors.push(anchor);
+            }
+        }
+        catch {
+            missingAnchors.push(anchor);
+        }
+    }
+    if (staleAnchors.length > 0) {
+        return { status: "stale", staleAnchors, missingAnchors };
+    }
+    if (missingAnchors.length > 0 && !sawFile) {
+        return { status: "missing_anchor", staleAnchors, missingAnchors };
+    }
+    if (missingAnchors.length > 0 && sawFile) {
+        // Some anchors ok, some missing — treat as soft missing, still usable
+        return { status: "fresh", staleAnchors, missingAnchors };
+    }
+    if (!sawFile && missingAnchors.length === 0) {
+        // Only non-path anchors (workspace labels)
+        return { status: "unanchored", staleAnchors: [], missingAnchors: [] };
+    }
+    return { status: "fresh", staleAnchors: [], missingAnchors: [] };
+}
+/** Multiplier applied to retrieval score (1 = full trust). */
+export function freshnessScoreMultiplier(status) {
+    switch (status) {
+        case "stale":
+            return 0.35;
+        case "missing_anchor":
+            return 0.5;
+        case "unknown":
+            return 0.85;
+        case "unanchored":
+            return 0.9;
+        case "fresh":
+        default:
+            return 1;
+    }
+}

package/dist/hook.d.ts

@@ -0,0 +1,16 @@
+export type HookPayload = {
+    hook_event_name?: string;
+    /** Claude Code uses `hook_event_name` or top-level event aliases */
+    event?: string;
+    prompt?: string;
+    text?: string;
+    conversation_id?: string;
+    session_id?: string;
+    workspace_roots?: string[];
+    cwd?: string;
+    transcript_path?: string | null;
+};
+export type HookResponse = Record<string, unknown>;
+/** Normalize Cursor + Claude Code event names into the Cursor-style set. */
+export declare function normalizeHookEvent(raw: string): string;
+export declare function handleHookPayload(raw: string): HookResponse;

package/dist/hook.js

@@ -0,0 +1,177 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { logContextUsage } from "./api/routes.js";
+import { captureMissLearnDraft, captureSessionDraft, findRecentContextMisses, isUsefulCaptureText, } from "./capture.js";
+import { getRepoByCwd, insertConversationNote, listConversationNotes, upsertRepo, } from "./db.js";
+import { detectRepoIdentity } from "./repo-identity.js";
+const SECRET = /password|api[_-]?key|secret|token\s*[:=]|begin (rsa |openssh )?private/i;
+function workspaceRoot(payload) {
+    const roots = payload.workspace_roots;
+    if (Array.isArray(roots) && typeof roots[0] === "string" && roots[0]) {
+        return resolve(roots[0]);
+    }
+    if (typeof payload.cwd === "string" && payload.cwd.trim()) {
+        return resolve(payload.cwd);
+    }
+    const envRoot = process.env.CURSOR_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR;
+    if (envRoot)
+        return resolve(envRoot);
+    return process.cwd();
+}
+function sessionId(payload) {
+    return payload.conversation_id || payload.session_id || process.env.CURSOR_SESSION_ID || "unknown";
+}
+function bindRepo(cwd) {
+    if (!existsSync(cwd))
+        return null;
+    const existing = getRepoByCwd(cwd);
+    if (existing)
+        return existing;
+    const identity = detectRepoIdentity(cwd);
+    return upsertRepo(identity, hookPlatform());
+}
+function cap(text, max = 2400) {
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, max)}\n\n_[amem truncated]_`;
+}
+function hookPlatform() {
+    if (process.env.CLAUDE_PROJECT_DIR && !process.env.CURSOR_PROJECT_DIR)
+        return "claude";
+    return "cursor";
+}
+/** Normalize Cursor + Claude Code event names into the Cursor-style set. */
+export function normalizeHookEvent(raw) {
+    const e = (raw || "").trim();
+    if (!e)
+        return "";
+    const lower = e.toLowerCase();
+    if (lower === "userpromptsubmit" || e === "UserPromptSubmit")
+        return "beforeSubmitPrompt";
+    if (lower === "stop" || e === "Stop")
+        return "stop";
+    if (lower === "sessionstart" || e === "SessionStart")
+        return "sessionStart";
+    if (lower === "sessionend" || e === "SessionEnd")
+        return "sessionEnd";
+    return e;
+}
+function injectPacket(repo, query, session, platform) {
+    const { markdown, packet } = logContextUsage({
+        repoId: repo.id,
+        platform,
+        sessionId: session,
+        query: query || "(session start)",
+    });
+    if (packet.claims.length === 0 && packet.notes.length === 0)
+        return null;
+    return cap(markdown);
+}
+export function handleHookPayload(raw) {
+    try {
+        return handleHookPayloadInner(raw);
+    }
+    catch {
+        return { continue: true };
+    }
+}
+function handleHookPayloadInner(raw) {
+    let payload = {};
+    const trimmed = raw.trim();
+    if (trimmed) {
+        try {
+            payload = JSON.parse(trimmed);
+        }
+        catch {
+            return { continue: true };
+        }
+    }
+    const event = normalizeHookEvent(payload.hook_event_name || payload.event || "");
+    const cwd = workspaceRoot(payload);
+    const repo = bindRepo(cwd);
+    if (!repo)
+        return { continue: true };
+    const sid = sessionId(payload);
+    const platform = hookPlatform();
+    if (event === "sessionStart") {
+        const context = injectPacket(repo, "", sid, platform);
+        return context
+            ? {
+                continue: true,
+                additional_context: `amem local memory for ${repo.repo_name}. Prefer these file anchors over broad exploration.\n\n${context}`,
+            }
+            : { continue: true };
+    }
+    if (event === "beforeSubmitPrompt") {
+        const prompt = typeof payload.prompt === "string" ? payload.prompt : "";
+        if (isUsefulCaptureText(prompt)) {
+            insertConversationNote({
+                repoId: repo.id,
+                platform,
+                sessionId: sid,
+                role: "user",
+                text: prompt,
+            });
+        }
+        const context = isUsefulCaptureText(prompt) ? injectPacket(repo, prompt, sid, platform) : null;
+        return context
+            ? {
+                continue: true,
+                additional_context: `amem already knows this about ${repo.repo_name}. Use it before grepping broadly.\n\n${context}`,
+            }
+            : { continue: true };
+    }
+    if (event === "afterAgentResponse") {
+        const text = typeof payload.text === "string" ? payload.text : "";
+        if (text.trim().length > 40 && !SECRET.test(text)) {
+            insertConversationNote({
+                repoId: repo.id,
+                platform,
+                sessionId: sid,
+                role: "assistant",
+                text,
+            });
+            // Miss → learn: if a recent context lookup returned nothing, draft from this answer.
+            const misses = findRecentContextMisses(repo.id, { sessionId: sid, limit: 3 });
+            for (const miss of misses) {
+                captureMissLearnDraft({
+                    repo,
+                    platform,
+                    sessionId: sid,
+                    miss,
+                    answer: text,
+                });
+            }
+        }
+        return {};
+    }
+    if (event === "stop" || event === "sessionEnd") {
+        const recent = listConversationNotes(repo.id, 12);
+        const lastUser = recent.find((n) => n.role === "user");
+        const lastAssistant = recent.find((n) => n.role === "assistant");
+        if (lastAssistant?.text) {
+            const misses = findRecentContextMisses(repo.id, { sessionId: sid, limit: 3 });
+            for (const miss of misses) {
+                captureMissLearnDraft({
+                    repo,
+                    platform,
+                    sessionId: sid,
+                    miss,
+                    answer: lastAssistant.text,
+                });
+            }
+        }
+        if (lastUser) {
+            captureSessionDraft({
+                repo,
+                platform,
+                sessionId: sid,
+                prompt: lastUser.text,
+                answer: lastAssistant?.text,
+                notes: recent.slice(0, 8).map((n) => ({ role: n.role, text: n.text })),
+            });
+        }
+        return {};
+    }
+    return { continue: true };
+}

package/dist/hygiene-schedule.d.ts

@@ -0,0 +1,28 @@
+export declare const HYGIENE_LABEL = "co.amem.hygiene";
+export declare const HYGIENE_SYSTEMD_SERVICE = "amem-hygiene.service";
+export declare const HYGIENE_SYSTEMD_TIMER = "amem-hygiene.timer";
+export type HygieneScheduleOpts = {
+    /** Hour of day local time 0–23 (default 4). */
+    hour?: number;
+};
+export declare function hygieneLaunchAgentPath(): string;
+export declare function hygieneSystemdServicePath(): string;
+export declare function hygieneSystemdTimerPath(): string;
+export declare function hygieneWindowsStartupPath(): string;
+export declare function isHygieneScheduleInstalled(): boolean;
+export declare function hygieneSchedulePath(): string;
+export declare function installHygieneSchedule(opts?: HygieneScheduleOpts): {
+    path: string;
+    platform: string;
+    hour: number;
+};
+export declare function uninstallHygieneSchedule(): {
+    path: string;
+    platform: string;
+};
+export declare function writeHygieneHelperScript(): string;
+export declare function hygieneScheduleStatus(): {
+    installed: boolean;
+    path: string;
+    platform: string;
+};

package/dist/hygiene-schedule.js

@@ -0,0 +1,221 @@
+/**
+ * Schedule weekly local hygiene (decay + merge). Pro/IT at run time.
+ * Uses LaunchAgent (macOS), systemd user timer (Linux), or Startup cmd (Windows).
+ */
+import { existsSync, mkdirSync, unlinkSync, writeFileSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { amemHome } from "./paths.js";
+import { resolveAmemProgramArgs } from "./install/skills.js";
+export const HYGIENE_LABEL = "co.amem.hygiene";
+export const HYGIENE_SYSTEMD_SERVICE = "amem-hygiene.service";
+export const HYGIENE_SYSTEMD_TIMER = "amem-hygiene.timer";
+function escapeXml(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+function hygieneArgs() {
+    return resolveAmemProgramArgs("hygiene", "--scheduled");
+}
+function shellQuote(args) {
+    return args.map((a) => (/\s/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a)).join(" ");
+}
+export function hygieneLaunchAgentPath() {
+    return join(homedir(), "Library", "LaunchAgents", `${HYGIENE_LABEL}.plist`);
+}
+export function hygieneSystemdServicePath() {
+    return join(homedir(), ".config", "systemd", "user", HYGIENE_SYSTEMD_SERVICE);
+}
+export function hygieneSystemdTimerPath() {
+    return join(homedir(), ".config", "systemd", "user", HYGIENE_SYSTEMD_TIMER);
+}
+export function hygieneWindowsStartupPath() {
+    const appData = process.env.APPDATA || join(homedir(), "AppData", "Roaming");
+    return join(appData, "Microsoft", "Windows", "Start Menu", "Programs", "Startup", "amem-hygiene.cmd");
+}
+export function isHygieneScheduleInstalled() {
+    if (process.platform === "darwin")
+        return existsSync(hygieneLaunchAgentPath());
+    if (process.platform === "linux")
+        return existsSync(hygieneSystemdTimerPath());
+    if (process.platform === "win32")
+        return existsSync(hygieneWindowsStartupPath());
+    return false;
+}
+export function hygieneSchedulePath() {
+    if (process.platform === "darwin")
+        return hygieneLaunchAgentPath();
+    if (process.platform === "linux")
+        return hygieneSystemdTimerPath();
+    if (process.platform === "win32")
+        return hygieneWindowsStartupPath();
+    return "";
+}
+function uid() {
+    return String(process.getuid?.() ?? "");
+}
+export function installHygieneSchedule(opts = {}) {
+    const hour = Math.min(23, Math.max(0, opts.hour ?? 4));
+    const args = hygieneArgs();
+    if (process.platform === "darwin") {
+        const path = hygieneLaunchAgentPath();
+        mkdirSync(join(homedir(), "Library", "LaunchAgents"), { recursive: true });
+        const argXml = args.map((a) => `    <string>${escapeXml(a)}</string>`).join("\n");
+        // Weekly: Sunday at hour:20
+        const body = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${HYGIENE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${argXml}
+  </array>
+  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Weekday</key>
+    <integer>0</integer>
+    <key>Hour</key>
+    <integer>${hour}</integer>
+    <key>Minute</key>
+    <integer>20</integer>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(join(amemHome(), "hygiene.log"))}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(join(amemHome(), "hygiene.err.log"))}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+  </dict>
+</dict>
+</plist>
+`;
+        writeFileSync(path, body, "utf8");
+        try {
+            execFileSync("launchctl", ["bootout", `gui/${uid()}`, path], {
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+        }
+        catch {
+            // not loaded
+        }
+        try {
+            execFileSync("launchctl", ["bootstrap", `gui/${uid()}`, path], {
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+        }
+        catch {
+            // next login picks it up
+        }
+        return { path, platform: "darwin", hour };
+    }
+    if (process.platform === "linux") {
+        const unitDir = join(homedir(), ".config", "systemd", "user");
+        mkdirSync(unitDir, { recursive: true });
+        const svc = hygieneSystemdServicePath();
+        const timer = hygieneSystemdTimerPath();
+        writeFileSync(svc, `[Unit]
+Description=amem local memory hygiene
+[Service]
+Type=oneshot
+ExecStart=${shellQuote(args)}
+Environment=PATH=/usr/local/bin:/usr/bin:/bin:${homedir()}/.local/bin
+`, "utf8");
+        writeFileSync(timer, `[Unit]
+Description=Weekly amem memory hygiene
+[Timer]
+OnCalendar=Sun *-*-* ${String(hour).padStart(2, "0")}:20:00
+Persistent=true
+[Install]
+WantedBy=timers.target
+`, "utf8");
+        try {
+            execFileSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" });
+            execFileSync("systemctl", ["--user", "enable", "--now", HYGIENE_SYSTEMD_TIMER], {
+                stdio: "ignore",
+            });
+        }
+        catch {
+            // unit files are on disk
+        }
+        return { path: timer, platform: "linux", hour };
+    }
+    if (process.platform === "win32") {
+        const path = hygieneWindowsStartupPath();
+        mkdirSync(join(path, ".."), { recursive: true });
+        writeFileSync(path, `@echo off\r\nrem amem weekly hygiene (runs at login; Pro/IT required)\r\n${shellQuote(args)}\r\n`, "utf8");
+        return { path, platform: "win32", hour };
+    }
+    throw new Error(`Hygiene scheduling not supported on ${process.platform}`);
+}
+export function uninstallHygieneSchedule() {
+    if (process.platform === "darwin") {
+        const path = hygieneLaunchAgentPath();
+        if (existsSync(path)) {
+            try {
+                execFileSync("launchctl", ["bootout", `gui/${uid()}`, path], {
+                    stdio: ["ignore", "pipe", "pipe"],
+                });
+            }
+            catch {
+                // ignore
+            }
+            unlinkSync(path);
+        }
+        return { path, platform: "darwin" };
+    }
+    if (process.platform === "linux") {
+        const timer = hygieneSystemdTimerPath();
+        const svc = hygieneSystemdServicePath();
+        try {
+            execFileSync("systemctl", ["--user", "disable", "--now", HYGIENE_SYSTEMD_TIMER], {
+                stdio: "ignore",
+            });
+        }
+        catch {
+            // ignore
+        }
+        if (existsSync(timer))
+            unlinkSync(timer);
+        if (existsSync(svc))
+            unlinkSync(svc);
+        return { path: timer, platform: "linux" };
+    }
+    if (process.platform === "win32") {
+        const path = hygieneWindowsStartupPath();
+        if (existsSync(path))
+            unlinkSync(path);
+        return { path, platform: "win32" };
+    }
+    throw new Error(`Hygiene scheduling not supported on ${process.platform}`);
+}
+export function writeHygieneHelperScript() {
+    const script = join(amemHome(), "bin", "amem-hygiene.sh");
+    mkdirSync(join(amemHome(), "bin"), { recursive: true, mode: 0o700 });
+    const body = `#!/usr/bin/env bash
+set -euo pipefail
+exec ${shellQuote(hygieneArgs())}
+`;
+    writeFileSync(script, body, { mode: 0o700 });
+    try {
+        chmodSync(script, 0o700);
+    }
+    catch {
+        // ignore
+    }
+    return script;
+}
+export function hygieneScheduleStatus() {
+    return {
+        installed: isHygieneScheduleInstalled(),
+        path: hygieneSchedulePath(),
+        platform: process.platform,
+    };
+}

package/dist/hygiene.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Local memory hygiene: decay unused facts, find near-duplicates, review inbox.
+ * Apply/schedule is Pro/IT only. Preview counts are free (soft paywall).
+ * Nothing is uploaded.
+ */
+import { type ClaimRow } from "./db.js";
+export type HygieneDuplicate = {
+    keepId: string;
+    dropId: string;
+    similarity: number;
+};
+export type HygieneReport = {
+    stale: ClaimRow[];
+    duplicates: HygieneDuplicate[];
+    pendingDrafts: number;
+    active: number;
+};
+export type HygienePreview = {
+    active: number;
+    staleCount: number;
+    duplicateCount: number;
+    pendingDrafts: number;
+    /** Estimated active count after decay + merge */
+    afterCleanup: number;
+    softPaywall: boolean;
+};
+export declare const SOFT_PAYWALL_FACTS = 200;
+export declare const SOFT_PAYWALL_NOISE = 15;
+/** Free: counts only for soft paywall / banners. Never applies changes. */
+export declare function hygienePreview(repoId: string, unusedDays?: number): HygienePreview;
+/** Aggregate preview across all tracked repos (for All memory scope). */
+export declare function hygienePreviewAll(unusedDays?: number): HygienePreview;
+export declare function hygieneReport(repoId: string, unusedDays?: number): HygieneReport;
+export declare function decayStaleClaims(repoId: string, unusedDays?: number): {
+    decayed: string[];
+};
+export declare function mergeDuplicate(repoId: string, keepId: string, dropId: string): {
+    keepId: string;
+    dropId: string;
+};
+/** Decay unused + merge near-duplicates in one step (Pro/IT). */
+export declare function acceptSafeCleanups(repoId: string, unusedDays?: number): {
+    decayed: string[];
+    merged: Array<{
+        keepId: string;
+        dropId: string;
+        similarity: number;
+    }>;
+};
+/** Scheduled job: clean every tracked repo when licensed. */
+export declare function runScheduledHygiene(unusedDays?: number): {
+    skipped?: boolean;
+    reason?: string;
+    repos: Array<{
+        repoId: string;
+        name: string;
+        decayed: number;
+        merged: number;
+        error?: string;
+    }>;
+};