@iamem/amem 0.1.3 → 0.2.0

package/dist/api/routes.js

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
 import { resolve, join } from "node:path";
 import { createHash } from "node:crypto";
-import { estimateUsdSaved, metricsFromPacket, USD_PER_MILLION_INPUT_TOKENS } from "../estimate.js";
+import { estimateUsdSaved, metricsFromPacket, savingsBasis, USD_PER_MILLION_INPUT_TOKENS, } from "../estimate.js";
 import { buildActivityGraph, speedForEvent } from "../activity.js";
 import { getRepoByCwd, getRepoById, getRepoByName, renameWorkspace, getSetupState, insertUsageEvent, listClaims, listClaimsAll, listComponents, listComponentsAll, listEdges, listEdgesAll, listFlows, listFlowsAll, listRepos, listSessions, listSessionsAll, listUsageEvents, listProposalDrafts, listProposalDraftsAll, countProposalDrafts, countProposalDraftsAll, getProposalDraft, setProposalDraftStatus, listTasks, listTasksAll, getSkillDraft, insertSkillDraft, listSkillDrafts, recordSkillUse, setSkillDraftStatus, setSkillRepo, findTaskAnyRepo, getTask, insertTask, updateTask, completeTask, deleteTask, countTasks, countTasksAll, normalizeTaskStatus, updateClaim, setClaimPinned, deleteClaim, setReportedOnLatest, setReportedTokensSaved, upsertRepo, upsertSetupState, wipeRepo, openDb, closeDb, } from "../db.js";
 import { deleteSkill, findSkillOnDisk, isValidSkillName, listIndexedSkills, listSkillAssets, rankSkills, readSkillAsset, readSkillBody, renderSkillMarkdown, scanSkillContent, skillsDir, slugifySkillName, syncSkillIndex, writeSkill, } from "../skills.js";
@@ -358,10 +358,14 @@ function aggregateUsage(events, windowDays = 30) {
     }
     const queries = events.length;
     const estimatedTokensSaved = events.reduce((s, e) => s + e.estimated_tokens_saved, 0);
+    const reportedTokensSaved = events.reduce((s, e) => s + (e.reported_tokens_saved ?? 0), 0);
     return {
         pricing: {
             usdPerMillionInputTokens: USD_PER_MILLION_INPUT_TOKENS,
             basis: "input",
+            // How much to trust the numbers below. Until reported savings exist,
+            // every "saved" figure is a model, and callers must say so.
+            ...savingsBasis(reportedTokensSaved),
         },
         byPlatform: Object.values(byPlatform).map((p) => ({
             ...p,
@@ -378,7 +382,7 @@ function aggregateUsage(events, windowDays = 30) {
             queries,
             estimatedTokensSaved,
             estimatedUsdSaved: estimateUsdSaved(estimatedTokensSaved),
-            reportedTokensSaved: events.reduce((s, e) => s + (e.reported_tokens_saved ?? 0), 0),
+            reportedTokensSaved,
             estimatedMsSaved,
             localHits,
             serverTrips,

package/dist/capture.js

@@ -1,8 +1,9 @@
 import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
+import { PLACEHOLDER_ANCHOR } from "./freshness.js";
 import { insertProposalDraft, listProposalDrafts, listProposalDraftsAll, listUsageEvents, setProposalDraftStatus, } from "./db.js";
-import { compactClaimText, compactFromNotes, inferClaimKind, isDurableCapture } from "./kinds.js";
+import { compactClaimText, compactFromNotes, inferClaimKind, isDurableCapture, isFactLike, } from "./kinds.js";
 import { loadPolicy } from "./policy.js";
 import { applyProposal } from "./proposal.js";
 import { scoreProposal } from "./draft-quality.js";
@@ -49,12 +50,20 @@ function buildClaimDraft(input) {
     }
     const anchors = extractCaptureAnchors(`${input.prompt}\n${input.answer ?? ""}`, input.repoRoot);
     const kind = input.forceKind ?? inferClaimKind(input.prompt, input.answer ?? "");
-    const usableAnchors = anchors.length > 0 ? anchors : kind === "constraint" || kind === "gotcha" ? ["README.md"] : [];
+    const usableAnchors = anchors.length > 0
+        ? anchors
+        : kind === "constraint" || kind === "gotcha"
+            ? [PLACEHOLDER_ANCHOR]
+            : [];
     if (!isDurableCapture(input.prompt, input.answer, usableAnchors.length)) {
         if (usableAnchors.length === 0)
             return null;
     }
     const text = compactClaimText(input.prompt, input.answer);
+    // Single choke point for every capture path. Conversational residue never
+    // becomes a durable claim, however many file paths it happens to mention.
+    if (!isFactLike(text))
+        return null;
     const id = `${input.idPrefix}_${createHash("sha256").update(text).digest("hex").slice(0, 12)}`;
     return {
         id,
@@ -85,7 +94,7 @@ export function shouldAutoApplyProposal(proposal) {
         return false;
     if (!DURABLE_AUTO_KINDS.has((claim.kind || "").toLowerCase()))
         return false;
-    const anchors = (claim.code_anchors ?? []).filter((a) => a && a !== "README.md");
+    const anchors = (claim.code_anchors ?? []).filter((a) => a && a !== PLACEHOLDER_ANCHOR);
     return anchors.length > 0;
 }
 function maybeAutoApplyDraft(repoId, draft, proposal) {
@@ -195,7 +204,7 @@ function extraSessionFacts(input, skipId) {
     const sentences = answer
         .split(/(?<=[.!?])\s+/)
         .map((s) => s.replace(/\s+/g, " ").trim())
-        .filter((s) => s.length >= 48 && [...s.matchAll(PATH_RE)].length > 0);
+        .filter((s) => s.length >= 48 && [...s.matchAll(PATH_RE)].length > 0 && isFactLike(s));
     const out = [];
     for (const sentence of sentences.slice(0, 3)) {
         const built = buildClaimDraft({
@@ -251,7 +260,7 @@ export function captureMissLearnDraft(input) {
     });
     if (!built)
         return null;
-    const realAnchors = built.anchors.filter((a) => a !== "README.md");
+    const realAnchors = built.anchors.filter((a) => a !== PLACEHOLDER_ANCHOR);
     if (realAnchors.length === 0)
         return null;
     built.proposal.claims[0].code_anchors = realAnchors;

package/dist/cli.js

@@ -11,7 +11,7 @@ import { installHost } from "./install/hosts.js";
 import { amemHome, dbPath, tryEnsureDir } from "./paths.js";
 import { assertExportAllowed, assertPlatformAllowed, assertRemoteAllowed, assertUiAllowed, loadPolicy, } from "./policy.js";
 import { applyProposal, diffProposal, exportRepoMemory, formatProposalDiff, loadProposalFile, validateProposal, } from "./proposal.js";
-import { detectRepoIdentity, parseWorkspaceSlug, workspaceIdentity } from "./repo-identity.js";
+import { detectRepoIdentity, parseWorkspaceSlug, unbindableRootReason, workspaceIdentity, } from "./repo-identity.js";
 import { runDesktopApp } from "./app-shell.js";
 import { startUiServer, buildUiLandingUrl, openUiInBrowser, isAddrInUse, probeUiHealth, } from "./ui/server.js";
 import { installLoginService, isServiceInstalled, isServiceSupported, uninstallLoginService } from "./service.js";
@@ -25,7 +25,7 @@ import { rememberContract } from "./remember-contract.js";
 import { vaultStatus } from "./vault.js";
 import { applyLicenseFile, clearLicense, generateLicenseKeys, licenseStatus, signLicense, } from "./license.js";
 import { embedIndexIssues, embedStatus, reindexAllEmbeds, setEmbedBackend, } from "./embed.js";
-import { acceptSafeCleanups, decayStaleClaims, hygieneReport, mergeDuplicate, runScheduledHygiene } from "./hygiene.js";
+import { acceptSafeCleanups, decayStaleClaims, hygieneReport, mergeDuplicate, purgeNonFactClaims, runScheduledHygiene, } from "./hygiene.js";
 import { hygieneSchedulePath, installHygieneSchedule, isHygieneScheduleInstalled, uninstallHygieneSchedule, writeHygieneHelperScript, } from "./hygiene-schedule.js";
 import { syncPinnedRules } from "./rules-sync.js";
 import { listSkillDrafts } from "./db.js";
@@ -36,7 +36,7 @@ function usage() {
 
 Usage:
   amem setup [--personal] [--platform <host>]
-  amem init --platform cursor|claude|windsurf|continue|aider|zed
+  amem init --platform cursor|claude|claude-desktop|windsurf|continue|aider|zed
   amem init --workspace <name> [--path <dir>] [--platform …]
   amem init --personal
   amem rename "<display name>" --workspace <slug>
@@ -63,6 +63,7 @@ Usage:
   amem backup unschedule
   amem restore --file <backup.db|backup.db.enc> [--passphrase <secret>]
   amem hygiene [--days 90] [--decay] [--accept-safe] [--merge <keepId> <dropId>]
+  amem hygiene --purge-nonfacts [--all] [--apply]   # default is a dry run
   amem hygiene --scheduled
   amem hygiene schedule [--hour <0-23>]
   amem hygiene unschedule
@@ -230,11 +231,29 @@ async function main() {
                 }
                 const platform = flagString(flags, "platform");
                 if (!platform) {
-                    throw new Error("amem init requires --platform cursor|claude|windsurf|continue|aider|zed, --workspace <name>, or --personal");
+                    throw new Error("amem init requires --platform cursor|claude|claude-desktop|windsurf|continue|aider|zed, --workspace <name>, or --personal");
                 }
                 const policy = loadPolicy().policy;
                 assertPlatformAllowed(platform, policy);
+                // Claude Desktop, Windsurf, Continue and Zed read a single machine-wide
+                // MCP config. There is nothing repo-specific to bind, and binding the
+                // cwd here is exactly how running this from a home directory
+                // registered the whole home as a repo.
+                if (HOST_INSTALL_IDS.has(platform) && platform !== "aider") {
+                    const hostInfo = installHost(platform, { workspace: PERSONAL_SLUG });
+                    console.log(`Configured ${hostInfo.host} (machine-wide, no repo binding)`);
+                    for (const cfgPath of hostInfo.paths)
+                        console.log(`Config: ${cfgPath}`);
+                    for (const note of hostInfo.notes)
+                        console.log(`Note: ${note}`);
+                    break;
+                }
                 const identity = detectRepoIdentity();
+                const unbindable = unbindableRootReason(identity.rootPath);
+                if (unbindable) {
+                    throw new Error(`Refusing to bind ${unbindable} (${identity.rootPath}) as a repo. ` +
+                        "cd into a project first, or use: amem init --workspace <name>");
+                }
                 assertRemoteAllowed(identity.remoteUrl, policy);
                 const repo = upsertRepo(identity, platform);
                 let installInfo = { skills: [] };
@@ -655,6 +674,33 @@ async function main() {
                     }
                     break;
                 }
+                if (flags.get("purge-nonfacts")) {
+                    const all = Boolean(flags.get("all"));
+                    const scope = all ? {} : { repoId: resolveBinding(flags).id };
+                    // Dry run unless --apply is passed: deletion is not reversible.
+                    const preview = purgeNonFactClaims({ ...scope, dryRun: true });
+                    const byReason = new Map();
+                    for (const row of preview.matched) {
+                        byReason.set(row.reason, (byReason.get(row.reason) ?? 0) + 1);
+                    }
+                    console.log(`Scanned ${preview.scanned} claim(s)${all ? " across every repo" : ""}; ${preview.matched.length} look like clear junk.`);
+                    for (const [reason, n] of [...byReason].sort((a, b) => b[1] - a[1])) {
+                        console.log(`  ${reason}: ${n}`);
+                    }
+                    for (const row of preview.matched.slice(0, 8)) {
+                        console.log(`  - [${row.repoName}] ${row.reason}: ${row.preview}`);
+                    }
+                    if (preview.matched.length > 8) {
+                        console.log(`  … and ${preview.matched.length - 8} more`);
+                    }
+                    if (!flags.get("apply")) {
+                        console.log("Dry run. Re-run with --apply to delete. Back up first: amem backup");
+                        break;
+                    }
+                    const result = purgeNonFactClaims({ ...scope, dryRun: false });
+                    console.log(`Deleted ${result.deleted} claim(s).`);
+                    break;
+                }
                 const repo = resolveBinding(flags);
                 const days = Number(flagString(flags, "days") ?? "90");
                 const keep = flagString(flags, "merge");

package/dist/estimate.d.ts

@@ -2,14 +2,38 @@ import type { ContextPacket } from "./context.js";
 /** Rough chars→tokens. */
 export declare function estimateTokensFromText(text: string): number;
 /**
- * Proxy for exploration avoided:
+ * Assumed cost of one file the agent did not have to open. This is a MODELLED
+ * constant, not a measurement: it credits a saving whether or not the agent
+ * would actually have read that file. It dominates the headline number, so
+ * treat any total built from it as an upper bound until calibrated against
+ * real reported savings (`amem usage report --saved <n>`).
+ */
+export declare const ASSUMED_TOKENS_PER_FILE = 4000;
+export declare const ASSUMED_TOKENS_PER_CLAIM = 200;
+/**
+ * Proxy for exploration avoided, net of what the packet itself cost:
  * anchors_returned * 4000 + claims_returned * 200 - packet_tokens
+ *
+ * Deliberately NOT clamped at zero. A packet that returns little and still
+ * costs input tokens is a net loss, and the metric has to be able to say so —
+ * clamping made the dashboard structurally incapable of reporting that amem
+ * ever cost anything, which is not a property you want in your own numbers.
  */
 export declare function estimateTokensSaved(input: {
     anchorsCount: number;
     claimsCount: number;
     packetTokens: number;
 }): number;
+/**
+ * How a savings figure should be presented. "measured" only once real reported
+ * savings exist; until then the number is a model and must be labelled as one.
+ */
+export declare function savingsBasis(reportedTokensSaved: number): {
+    savingsBasis: "measured" | "modelled";
+    calibrated: boolean;
+    assumedTokensPerFile: number;
+    assumedTokensPerClaim: number;
+};
 /** Typical Cursor/Claude tool round-trip to read a file (~1.2s) plus a little per claim. */
 export declare const MS_PER_FILE_ROUNDTRIP = 1200;
 export declare const MS_PER_CLAIM = 80;

package/dist/estimate.js

@@ -3,11 +3,42 @@ export function estimateTokensFromText(text) {
     return Math.max(1, Math.ceil(text.length / 4));
 }
 /**
- * Proxy for exploration avoided:
+ * Assumed cost of one file the agent did not have to open. This is a MODELLED
+ * constant, not a measurement: it credits a saving whether or not the agent
+ * would actually have read that file. It dominates the headline number, so
+ * treat any total built from it as an upper bound until calibrated against
+ * real reported savings (`amem usage report --saved <n>`).
+ */
+export const ASSUMED_TOKENS_PER_FILE = 4000;
+export const ASSUMED_TOKENS_PER_CLAIM = 200;
+/**
+ * Proxy for exploration avoided, net of what the packet itself cost:
  * anchors_returned * 4000 + claims_returned * 200 - packet_tokens
+ *
+ * Deliberately NOT clamped at zero. A packet that returns little and still
+ * costs input tokens is a net loss, and the metric has to be able to say so —
+ * clamping made the dashboard structurally incapable of reporting that amem
+ * ever cost anything, which is not a property you want in your own numbers.
  */
 export function estimateTokensSaved(input) {
-    return Math.max(0, input.anchorsCount * 4000 + input.claimsCount * 200 - input.packetTokens);
+    return (input.anchorsCount * ASSUMED_TOKENS_PER_FILE +
+        input.claimsCount * ASSUMED_TOKENS_PER_CLAIM -
+        input.packetTokens);
+}
+/**
+ * How a savings figure should be presented. "measured" only once real reported
+ * savings exist; until then the number is a model and must be labelled as one.
+ */
+export function savingsBasis(reportedTokensSaved) {
+    const calibrated = Number(reportedTokensSaved) > 0;
+    return {
+        // Distinct from pricing.basis ("input"), which is about which side of the
+        // token bill is being priced, not about how trustworthy the figure is.
+        savingsBasis: calibrated ? "measured" : "modelled",
+        calibrated,
+        assumedTokensPerFile: ASSUMED_TOKENS_PER_FILE,
+        assumedTokensPerClaim: ASSUMED_TOKENS_PER_CLAIM,
+    };
 }
 /** Typical Cursor/Claude tool round-trip to read a file (~1.2s) plus a little per claim. */
 export const MS_PER_FILE_ROUNDTRIP = 1200;
@@ -18,7 +49,9 @@ export function estimateMsSaved(input) {
 /** Mid-range frontier *input* $/1M tokens (Sonnet-class). Avoided exploration is input-side. Not a bill. */
 export const USD_PER_MILLION_INPUT_TOKENS = 3;
 export function estimateUsdSaved(tokens, usdPerMillion = USD_PER_MILLION_INPUT_TOKENS) {
-    return Math.max(0, (Number(tokens) / 1_000_000) * usdPerMillion);
+    // Unclamped for the same reason as estimateTokensSaved: a negative here is
+    // real information, not an error to be hidden.
+    return (Number(tokens) / 1_000_000) * usdPerMillion;
 }
 export function eventKind(claimsCount, notesCount = 0) {
     return claimsCount > 0 || notesCount > 0 ? "local_hit" : "server_trip";

package/dist/freshness.d.ts

@@ -5,6 +5,13 @@ export type ClaimFreshness = {
     staleAnchors: string[];
     missingAnchors: string[];
 };
+/**
+ * capture.ts falls back to this when it cannot extract a real file anchor.
+ * README churns constantly, so honouring it as a real anchor marks those claims
+ * stale forever and drowns the genuine staleness signal. Treat it as no anchor.
+ * (capture.ts already filters it out of "does this claim have real anchors".)
+ */
+export declare const PLACEHOLDER_ANCHOR = "README.md";
 export declare function parseAnchors(codeAnchorsJson: string): string[];
 /**
  * Compare claim.updated_at to filesystem mtimes of code_anchors.

package/dist/freshness.js

@@ -1,5 +1,12 @@
 import { existsSync, statSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
+/**
+ * capture.ts falls back to this when it cannot extract a real file anchor.
+ * README churns constantly, so honouring it as a real anchor marks those claims
+ * stale forever and drowns the genuine staleness signal. Treat it as no anchor.
+ * (capture.ts already filters it out of "does this claim have real anchors".)
+ */
+export const PLACEHOLDER_ANCHOR = "README.md";
 export function parseAnchors(codeAnchorsJson) {
     try {
         const parsed = JSON.parse(codeAnchorsJson);
@@ -21,7 +28,7 @@ function resolveAnchorPath(rootPath, anchor) {
  * Missing paths → missing_anchor; any newer file → stale.
  */
 export function assessClaimFreshness(rootPath, claim) {
-    const anchors = parseAnchors(claim.code_anchors);
+    const anchors = parseAnchors(claim.code_anchors).filter((a) => a !== PLACEHOLDER_ANCHOR);
     if (anchors.length === 0) {
         return { status: "unanchored", staleAnchors: [], missingAnchors: [] };
     }

package/dist/hygiene.d.ts

@@ -67,3 +67,28 @@ export declare function runScheduledHygiene(unusedDays?: number): {
         error?: string;
     }>;
 };
+export type NonFactClaim = {
+    repoId: string;
+    repoName: string;
+    id: string;
+    kind: string;
+    reason: string;
+    preview: string;
+};
+/** Stored claims that are clear junk. Pinned claims are never included. */
+export declare function findNonFactClaims(opts?: {
+    repoId?: string;
+}): NonFactClaim[];
+/**
+ * Delete clear-junk claims. Always run with dryRun first — deletion is not
+ * reversible from inside amem, only from a backup.
+ */
+export declare function purgeNonFactClaims(opts?: {
+    repoId?: string;
+    dryRun?: boolean;
+}): {
+    scanned: number;
+    matched: NonFactClaim[];
+    deleted: number;
+    dryRun: boolean;
+};

package/dist/hygiene.js

@@ -2,11 +2,12 @@
  * Local memory hygiene: decay unused facts, find near-duplicates, review inbox.
  * Completely free and open — runs on-device, nothing uploaded.
  */
-import { getClaim, listClaims, listProposalDrafts, listRepos, listUsageEvents, setClaimStatus, } from "./db.js";
+import { deleteClaim, getClaim, listClaims, listClaimsAll, listProposalDrafts, listRepos, listUsageEvents, setClaimStatus, } from "./db.js";
 import { FEATURE_HYGIENE, hasFeature, requireFeature } from "./license.js";
 import { applyProposal, applySupersedes } from "./proposal.js";
 import { tokenJaccard } from "./search.js";
 import { parseAnchors } from "./freshness.js";
+import { nonFactReason } from "./kinds.js";
 export const SOFT_PAYWALL_FACTS = 200;
 export const SOFT_PAYWALL_NOISE = 15;
 /** Soft-paywall when session chat takeaways dominate the graph. */
@@ -251,3 +252,42 @@ export function runScheduledHygiene(unusedDays = 90) {
     }
     return { repos };
 }
+/** Stored claims that are clear junk. Pinned claims are never included. */
+export function findNonFactClaims(opts = {}) {
+    const names = new Map(listRepos().map((r) => [r.id, r.repo_name]));
+    const claims = opts.repoId ? listClaims(opts.repoId) : listClaimsAll();
+    const out = [];
+    for (const claim of claims) {
+        if (claim.pinned)
+            continue;
+        const reason = nonFactReason(claim.text);
+        if (!reason)
+            continue;
+        out.push({
+            repoId: claim.repo_id,
+            repoName: names.get(claim.repo_id) ?? claim.repo_id,
+            id: claim.id,
+            kind: claim.kind,
+            reason,
+            preview: claim.text.replace(/\s+/g, " ").slice(0, 120),
+        });
+    }
+    return out;
+}
+/**
+ * Delete clear-junk claims. Always run with dryRun first — deletion is not
+ * reversible from inside amem, only from a backup.
+ */
+export function purgeNonFactClaims(opts = {}) {
+    const dryRun = opts.dryRun !== false;
+    const scanned = (opts.repoId ? listClaims(opts.repoId) : listClaimsAll()).length;
+    const matched = findNonFactClaims({ repoId: opts.repoId });
+    let deleted = 0;
+    if (!dryRun) {
+        for (const row of matched) {
+            if (deleteClaim(row.repoId, row.id))
+                deleted += 1;
+        }
+    }
+    return { scanned, matched, deleted, dryRun };
+}

package/dist/install/hosts.d.ts

@@ -11,6 +11,21 @@ export declare function installContinue(workspace?: string): HostInstallResult;
 export declare function installAider(repoRoot: string): HostInstallResult;
 /** Zed: settings.json context_servers / mcp style. */
 export declare function installZed(workspace?: string): HostInstallResult;
+/** Absolute path to the POSIX launcher shipped with the package. */
+export declare function mcpLauncherPath(): string;
+/** Claude Desktop stores MCP config here (also read by Cowork). */
+export declare function claudeDesktopConfigPath(): string;
+/**
+ * Claude Desktop / Cowork: stdio MCP entry in claude_desktop_config.json.
+ *
+ * GUI apps are not launched from a login shell, so they inherit a minimal PATH
+ * with no Homebrew and no nvm. A bare `amem` — or even `node` — registers as a
+ * connector but never completes tool discovery, and the host reports no reason.
+ * Point at the launcher, which re-resolves node at spawn time; fall back to an
+ * absolute node + cli.js pair where a shell script cannot run (Windows).
+ */
+export declare function installClaudeDesktop(workspace?: string): HostInstallResult;
+export declare function claudeDesktopInstallHealth(): string[];
 export declare function continueInstallHealth(): string[];
 export declare function zedInstallHealth(): string[];
 export declare function windsurfInstallHealth(): string[];

package/dist/install/hosts.js

@@ -1,8 +1,8 @@
-import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
-import { mcpClientConfig } from "../mcp.js";
-import { resolveAmemBin, writeJson, readJsonObject } from "./skills.js";
+import { dirname, join } from "node:path";
+import { mcpClientConfig, stdioMcpLaunch } from "../mcp.js";
+import { getPackageRoot, resolveAmemBin, writeJson, readJsonObject } from "./skills.js";
 function ensureDir(path) {
     mkdirSync(path, { recursive: true });
 }
@@ -130,6 +130,72 @@ export function installZed(workspace = "personal") {
         ],
     };
 }
+/** Absolute path to the POSIX launcher shipped with the package. */
+export function mcpLauncherPath() {
+    return join(getPackageRoot(), "scripts", "mcp-launch.sh");
+}
+/** Claude Desktop stores MCP config here (also read by Cowork). */
+export function claudeDesktopConfigPath() {
+    if (process.platform === "darwin") {
+        return join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    }
+    if (process.platform === "win32") {
+        const appData = process.env.APPDATA || join(homedir(), "AppData", "Roaming");
+        return join(appData, "Claude", "claude_desktop_config.json");
+    }
+    return join(homedir(), ".config", "Claude", "claude_desktop_config.json");
+}
+/**
+ * Claude Desktop / Cowork: stdio MCP entry in claude_desktop_config.json.
+ *
+ * GUI apps are not launched from a login shell, so they inherit a minimal PATH
+ * with no Homebrew and no nvm. A bare `amem` — or even `node` — registers as a
+ * connector but never completes tool discovery, and the host reports no reason.
+ * Point at the launcher, which re-resolves node at spawn time; fall back to an
+ * absolute node + cli.js pair where a shell script cannot run (Windows).
+ */
+export function installClaudeDesktop(workspace = "personal") {
+    const path = claudeDesktopConfigPath();
+    ensureDir(dirname(path));
+    const existing = readJsonObject(path);
+    const servers = existing.mcpServers ?? {};
+    const launcher = mcpLauncherPath();
+    const usable = process.platform !== "win32" && existsSync(launcher);
+    if (usable) {
+        try {
+            chmodSync(launcher, 0o755);
+        }
+        catch {
+            // npm preserves the exec bit; a read-only install is not fatal here
+        }
+    }
+    const stdio = stdioMcpLaunch(workspace);
+    servers.amem = usable
+        ? { command: launcher, args: [], env: { AMEM_WORKSPACE: workspace } }
+        : {
+            command: stdio.command,
+            args: stdio.args,
+            env: { ...stdio.env, AMEM_WORKSPACE: workspace },
+        };
+    writeJson(path, { ...existing, mcpServers: servers });
+    const shown = usable ? launcher : `${stdio.command} ${stdio.args.join(" ")}`;
+    return {
+        host: "claude-desktop",
+        paths: [path],
+        notes: [
+            `Claude Desktop MCP amem \u2192 ${shown} (workspace ${workspace}).`,
+            "Quit Claude Desktop fully (Cmd+Q) and relaunch \u2014 config is read at startup, closing the window is not enough.",
+            "stdio needs no daemon: amem ui does not have to be running.",
+        ],
+    };
+}
+export function claudeDesktopInstallHealth() {
+    const path = claudeDesktopConfigPath();
+    if (!fileMentionsAmem(path)) {
+        return ["Claude Desktop has no amem MCP entry \u2014 run amem init --platform claude-desktop"];
+    }
+    return [];
+}
 function fileMentionsAmem(path) {
     if (!existsSync(path))
         return false;
@@ -167,6 +233,8 @@ export function windsurfInstallHealth() {
 }
 export function hostInstallHealth(host) {
     switch (host) {
+        case "claude-desktop":
+            return claudeDesktopInstallHealth();
         case "continue":
             return continueInstallHealth();
         case "zed":
@@ -180,6 +248,8 @@ export function hostInstallHealth(host) {
 export function installHost(host, opts = {}) {
     const ws = opts.workspace || "personal";
     switch (host) {
+        case "claude-desktop":
+            return installClaudeDesktop(ws);
         case "windsurf":
             return installWindsurf(ws);
         case "continue":

package/dist/kinds.d.ts

@@ -15,4 +15,22 @@ export declare function compactFromNotes(notes: Array<{
     prompt: string;
     answer: string;
 } | null;
+/**
+ * Is this a durable statement about the code, or conversational residue?
+ *
+ * Auto-capture previously accepted any sentence >= 48 chars that mentioned a
+ * path, which stored the user's own questions as facts ("so use luna mcp to
+ * connect to amem and that will do the trick?"). A question is a request, not
+ * a fact, however many files it names.
+ */
+/**
+ * Why an ALREADY STORED claim is clear junk, or null to keep it.
+ *
+ * Deliberately narrower than isFactLike: that gate decides what to admit and
+ * can afford false negatives, this one decides what to DELETE and a false
+ * positive destroys memory. Short, lowercase or oddly-formatted claims are
+ * kept here even though capture would now reject them.
+ */
+export declare function nonFactReason(text: string): string | null;
+export declare function isFactLike(text: string): boolean;
 export declare function isDurableCapture(prompt: string, answer: string | undefined, anchorCount: number): boolean;

package/dist/kinds.js

@@ -47,8 +47,14 @@ export function compactClaimText(prompt, answer) {
         const head = sentences.slice(0, 2).join(" ").slice(0, 400);
         return head || takeaway.slice(0, 400);
     }
-    const q = prompt.replace(/\s+/g, " ").trim().slice(0, 280);
-    return takeaway ? `${q}\n\nPrior outcome: ${takeaway.slice(0, 200)}` : q.slice(0, 400);
+    // Short answer: the fact is still in the ANSWER, so lead with it and keep the
+    // prompt only as trailing context. Leading with the prompt is how questions
+    // ended up stored as durable claims; the trailing "?" is dropped so the
+    // result reads as a statement rather than tripping the question filter.
+    const q = prompt.replace(/\s+/g, " ").trim().replace(/\?+\s*$/, "").slice(0, 280);
+    if (!takeaway)
+        return q.slice(0, 400);
+    return `${takeaway.slice(0, 200)}${q ? ` (context: ${q})` : ""}`.slice(0, 400);
 }
 /** Multi-turn: fold several notes into one compact fact string. */
 export function compactFromNotes(notes) {
@@ -72,10 +78,81 @@ function isUsefulish(text) {
 function scrubCodeNoise(text) {
     return text
         .replace(/```[\s\S]*?```/g, " ")
-        .replace(/`[^`]+`/g, " ")
+        // Keep what is INSIDE an inline span. Deleting it removed the file paths
+        // and identifiers that make a claim worth storing ("lives in `src/x.ts`"
+        // became "lives in and"), and it ran before pickFactSentences, which
+        // scores sentences on exactly those paths.
+        .replace(/`([^`]+)`/g, "$1")
         .replace(/\s+/g, " ")
         .trim();
 }
+const QUESTION_LEAD = /^(can|could|would|should|is|are|was|were|do|does|did|how|what|why|when|where|who|which|will|shall|may|might|am|have|has|had)\b/i;
+const CHAT_LEAD = /^(so|ok|okay|and|but|also|im|i'm|let's|lets|please|thanks|thx|yeah|yep|nope|hmm|wait|actually|btw|oh|hey)\b/i;
+/** Residue of an earlier scrub: "lives in and is", "wired via and included". */
+const DANGLING = /\b(in|at|from|to|via|inside|under|with|into)\s+(and|is|was|the file|what)\b/i;
+/** Interrogative opener plus a subject — a question missing its "?". */
+const QUESTION_SHAPE = /^(can|could|should|would|do|does|did|is|are|will|shall|how|what|why|when|where|who|which)\s+(?:(?:do|does|did|can|could|should|would|is|are|will|shall)\s+)?(we|you|i|amem)\b/i;
+/** Preposition running into punctuation or end of string: the object was deleted. */
+const TRAILING_PREPOSITION = /\b(in|at|from|to|via|inside|under|with|into|through)\s*([.,;:]|$)/i;
+/** A leading token that looks like code (path, dotted or snake_case name). */
+const CODE_LEAD = /^[\w@./-]*[._/][\w@./-]*(\s|$)/;
+/**
+ * Is this a durable statement about the code, or conversational residue?
+ *
+ * Auto-capture previously accepted any sentence >= 48 chars that mentioned a
+ * path, which stored the user's own questions as facts ("so use luna mcp to
+ * connect to amem and that will do the trick?"). A question is a request, not
+ * a fact, however many files it names.
+ */
+/**
+ * Why an ALREADY STORED claim is clear junk, or null to keep it.
+ *
+ * Deliberately narrower than isFactLike: that gate decides what to admit and
+ * can afford false negatives, this one decides what to DELETE and a false
+ * positive destroys memory. Short, lowercase or oddly-formatted claims are
+ * kept here even though capture would now reject them.
+ */
+export function nonFactReason(text) {
+    const t = (text ?? "").replace(/\s+/g, " ").trim();
+    if (t.length === 0)
+        return "empty";
+    // A question is a request someone typed, not a fact about the code.
+    if (t.includes("?"))
+        return "question";
+    // ...and plenty were typed without the question mark ("can we expose amem
+    // data via mcp"). Require an interrogative opener FOLLOWED by a subject, so
+    // this cannot swallow a declarative sentence that merely starts with "Is".
+    if (QUESTION_SHAPE.test(t))
+        return "question";
+    // Left behind by the old scrub that deleted inline code spans.
+    if (DANGLING.test(t))
+        return "scrub-residue";
+    // Same damage, different shape: the span sat at the end of the clause, so a
+    // preposition now runs straight into punctuation ("memory lives under .").
+    if (TRAILING_PREPOSITION.test(t))
+        return "scrub-residue";
+    if (CHAT_LEAD.test(t))
+        return "chat-fragment";
+    return null;
+}
+export function isFactLike(text) {
+    const t = (text ?? "").replace(/\s+/g, " ").trim();
+    if (t.length < 40)
+        return false;
+    if (t.includes("?"))
+        return false;
+    if (QUESTION_LEAD.test(t))
+        return false;
+    if (CHAT_LEAD.test(t))
+        return false;
+    if (DANGLING.test(t))
+        return false;
+    // Mid-thought lowercase openings are transcript fragments — unless the
+    // sentence opens on an identifier, which is normal for a real fact.
+    if (/^[a-z]/.test(t) && !CODE_LEAD.test(t))
+        return false;
+    return true;
+}
 function pickFactSentences(text) {
     const sentences = text.split(/(?<=[.!?])\s+/).filter((s) => s.length > 25);
     const scored = sentences.map((s) => {

package/dist/platforms.js

@@ -2,6 +2,12 @@
 export const KNOWN_PLATFORMS = [
     { id: "cursor", label: "Cursor", hint: "Rules, skills, hooks", installs: "cursor" },
     { id: "claude", label: "Claude Code", hint: "Skills and settings hooks", installs: "claude" },
+    {
+        id: "claude-desktop",
+        label: "Claude Desktop",
+        hint: "MCP config installer",
+        installs: "host",
+    },
     { id: "copilot", label: "GitHub Copilot", hint: "MCP / HTTP API" },
     { id: "codex", label: "ChatGPT / Codex", hint: "MCP / HTTP API" },
     { id: "gemini", label: "Gemini", hint: "MCP / HTTP API" },

package/dist/remember-contract.js

@@ -64,11 +64,17 @@ Generic MCP host recipe. Same tools for every client — do not fork per product
 
 ## Connect
 
-Keep \`amem ui\` running, then attach:
+Two supported transports. Either is fine — pick one.
+
+**stdio (no daemon).** The host spawns amem itself. Let amem write the config:
+
+\`amem init --platform claude-desktop\`
+
+**HTTP (shared daemon).** Keep \`amem ui\` running, then attach:
 
 \`${MCP_URL_TEMPLATE}\`
 
-GUI hosts often cannot see Homebrew on PATH. Prefer the HTTP URL over a bare \`amem\` command.
+Whichever you pick, never configure a GUI host with a bare \`amem\` or \`node\` command. GUI apps are not launched from a login shell, so they inherit a minimal PATH with no Homebrew and no nvm: the connector registers but tool discovery never completes, and the host reports no reason. An absolute path — to the launcher or to the node binary — is what makes stdio work.
 
 ## Tools
 
@@ -88,8 +94,11 @@ ${ruleLines}
 function renderPaste() {
     return `amem remember contract v${REMEMBER_CONTRACT_VERSION}
 
-Connect (any MCP host): ${MCP_URL_TEMPLATE}
-Keep amem ui running. Do not use a bare amem command from GUI apps.
+Connect (any MCP host), either:
+- stdio, no daemon: amem init --platform claude-desktop (or point the host at an absolute launcher path)
+- HTTP, needs amem ui running: ${MCP_URL_TEMPLATE}
+
+Never give a GUI host a bare amem or node command — no login PATH, so tool discovery silently fails.
 
 Every task:
 1. amem_context — read local memory first (pass workspace=<slug>)

package/dist/repo-identity.d.ts

@@ -9,6 +9,16 @@ export declare function findGitRoot(startPath?: string): string | null;
 /** Normalize remotes so ssh/https clones of the same repo share a key. */
 export declare function normalizeRemoteUrl(url: string): string;
 export declare function detectRepoIdentity(cwd?: string): RepoIdentity;
+/**
+ * Why this directory must not become a repo binding, or null if it is fine.
+ *
+ * detectRepoIdentity falls back to the cwd when there is no git root, so
+ * running an init from a home directory would otherwise register the entire
+ * home as a "repo" — a binding that matches everything and can never be the
+ * right answer. Workspace roots under ~/.amem are created deliberately and are
+ * not affected: they are built by workspaceIdentity, not by cwd detection.
+ */
+export declare function unbindableRootReason(rootPath: string): string | null;
 export declare function slugifyWorkspace(name: string): string;
 export declare function workspaceIdentity(name: string, rootPath: string): RepoIdentity;
 export declare function parseWorkspaceSlug(remoteUrl: string | null | undefined): string | null;

package/dist/repo-identity.js

@@ -1,7 +1,8 @@
 import { execFileSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
-import { resolve } from "node:path";
+import { homedir } from "node:os";
+import { parse as parsePath, resolve } from "node:path";
 function runGit(cwd, args) {
     try {
         return execFileSync("git", args, {
@@ -51,6 +52,24 @@ export function detectRepoIdentity(cwd = process.cwd()) {
         defaultBranch,
     };
 }
+/**
+ * Why this directory must not become a repo binding, or null if it is fine.
+ *
+ * detectRepoIdentity falls back to the cwd when there is no git root, so
+ * running an init from a home directory would otherwise register the entire
+ * home as a "repo" — a binding that matches everything and can never be the
+ * right answer. Workspace roots under ~/.amem are created deliberately and are
+ * not affected: they are built by workspaceIdentity, not by cwd detection.
+ */
+export function unbindableRootReason(rootPath) {
+    const resolved = resolve(rootPath);
+    const parsed = parsePath(resolved);
+    if (resolved === parsed.root)
+        return "the filesystem root";
+    if (resolved === resolve(homedir()))
+        return "your home directory";
+    return null;
+}
 export function slugifyWorkspace(name) {
     const slug = name
         .trim()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamem/amem",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Local personal agent memory for Cursor and Claude Code. Private to your machine — never shared.",
   "type": "module",
   "bin": {
@@ -21,6 +21,7 @@
     "templates",
     "docs",
     "ui-static",
+    "scripts/mcp-launch.sh",
     "scripts/mdm-offboard.sh",
     "scripts/postinstall.js"
   ],

package/scripts/mcp-launch.sh

@@ -0,0 +1,26 @@
+#!/bin/sh
+# amem MCP launcher for GUI hosts (Claude Desktop / Cowork).
+#
+# GUI apps are not launched from a login shell, so they inherit a minimal PATH
+# with no Homebrew and no nvm. A host configured with a bare `amem` or `node`
+# command registers the connector but never completes tool discovery. This
+# script resolves node at spawn time and execs the amem stdio MCP server.
+#
+# Set AMEM_NODE to pin a specific node binary. Extra args are passed through.
+DIR=$(cd "$(dirname "$0")/.." && pwd)
+NODE=""
+for c in \
+  "$AMEM_NODE" \
+  "$(command -v node 2>/dev/null)" \
+  /opt/homebrew/bin/node \
+  /usr/local/bin/node \
+  "$HOME/.homebrew/bin/node" \
+  /usr/bin/node
+do
+  if [ -n "$c" ] && [ -x "$c" ]; then NODE="$c"; break; fi
+done
+if [ -z "$NODE" ]; then
+  echo "amem-mcp: node 20+ not found. Set AMEM_NODE=/path/to/node in the host's MCP env." >&2
+  exit 1
+fi
+exec "$NODE" "$DIR/dist/cli.js" mcp "$@"

package/ui-static/app.js

@@ -3108,9 +3108,26 @@ function formatPct(n) {
 
 function formatUsd(n) {
   const v = Number(n);
-  if (!Number.isFinite(v) || v <= 0) return "$0";
-  if (v < 0.01) return `~$${v.toFixed(3)}`;
-  return `~$${v.toLocaleString(undefined, { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+  if (!Number.isFinite(v) || v === 0) return "$0";
+  // Savings can be negative now (a packet that returned little still cost
+  // input tokens). Rendering that as "$0" would hide exactly the case worth
+  // seeing, so show the sign.
+  const sign = v < 0 ? "-" : "~";
+  const abs = Math.abs(v);
+  if (abs < 0.01) return `${sign}$${abs.toFixed(3)}`;
+  return `${sign}$${abs.toLocaleString(undefined, { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+
+/**
+ * How much to trust the savings figures. Until a real reported saving exists
+ * these are model output, and the UI should say so rather than implying the
+ * number was measured.
+ */
+function savingsCaveat(agg) {
+  const p = agg?.pricing;
+  if (p?.calibrated) return "calibrated against reported savings";
+  const perFile = p?.assumedTokensPerFile ?? 4000;
+  return `modelled, never calibrated · assumes ${formatTokens(perFile)} tok per file avoided`;
 }
 
 function formatChartDay(iso) {
@@ -3556,7 +3573,7 @@ function renderDashboard() {
           <b>${esc(String(tier))}</b><span>License</span>
         </div>
         <div class="dash-kpi static">
-          <b>${formatUsd(totals.estimatedUsdSaved)}</b><span>Est. $ saved (proxy)</span>
+          <b>${formatUsd(totals.estimatedUsdSaved)}</b><span>Est. $ saved · ${esc(savingsCaveat(agg))}</span>
         </div>
       </div>
 
@@ -3727,7 +3744,7 @@ function renderAnalytics() {
   const speedCards = $("#speedCards");
   speedCards.innerHTML = `
     <div class="platform-card"><div class="label">Estimated time saved</div><div class="value">~${formatDuration(totals.estimatedMsSaved)}</div><div class="meta">proxy vs tool round-trips · not model latency</div></div>
-    <div class="platform-card"><div class="label">Estimated money saved</div><div class="value">${formatUsd(totals.estimatedUsdSaved)}</div><div class="meta">at $${agg?.pricing?.usdPerMillionInputTokens ?? 3}/1M input tokens · proxy, not a bill</div></div>
+    <div class="platform-card"><div class="label">Estimated money saved</div><div class="value">${formatUsd(totals.estimatedUsdSaved)}</div><div class="meta">at $${agg?.pricing?.usdPerMillionInputTokens ?? 3}/1M input tokens · ${esc(savingsCaveat(agg))}</div></div>
     <div class="platform-card"><div class="label">Local lookup</div><div class="value">${totals.avgLocalMs != null ? formatDuration(totals.avgLocalMs) : "—"}</div><div class="meta">measured SQLite / localhost avg</div></div>
     <div class="platform-card"><div class="label">Hit rate</div><div class="value">${formatPct(totals.hitRate)}</div><div class="meta">${totals.localHits ?? 0} keyword hits · ${totals.serverTrips ?? 0} misses · not model API calls</div></div>
     <div class="platform-card"><div class="label">Avoided file reads</div><div class="value">${formatTokens(totals.anchorsAvoided ?? 0)}</div><div class="meta">unique anchors returned in packets</div></div>`;
@@ -3737,7 +3754,7 @@ function renderAnalytics() {
   const trend = monthly.trendDays || 0;
   monthlyCards.innerHTML = `
     <div class="platform-card accented"><div class="label">Est. tokens / month</div><div class="value">~${formatTokens(monthly.estimatedTokensSaved ?? 0)}</div><div class="meta">${trend ? `from ${monthly.sampleQueries} calls over ${trend} day${trend === 1 ? "" : "s"} × 30` : "no usage yet"} · proxy, not a bill</div></div>
-    <div class="platform-card accented"><div class="label">Est. $ / month</div><div class="value">${formatUsd(monthly.estimatedUsdSaved)}</div><div class="meta">same token proxy at $${agg?.pricing?.usdPerMillionInputTokens ?? 3}/1M input</div></div>
+    <div class="platform-card accented"><div class="label">Est. $ / month</div><div class="value">${formatUsd(monthly.estimatedUsdSaved)}</div><div class="meta">same token proxy at $${agg?.pricing?.usdPerMillionInputTokens ?? 3}/1M input · ${esc(savingsCaveat(agg))}</div></div>
     <div class="platform-card accented"><div class="label">Est. time / month</div><div class="value">~${formatDuration(monthly.estimatedMsSaved)}</div><div class="meta">avoided tool round-trips at current pace</div></div>
     <div class="platform-card accented"><div class="label">Est. calls / month</div><div class="value">${formatTokens(monthly.queries ?? 0)}</div><div class="meta">amem context hits if this rate holds</div></div>
     <div class="platform-card accented"><div class="label">Est. file reads / month</div><div class="value">${formatTokens(monthly.anchorsAvoided ?? 0)}</div><div class="meta">anchors that would be skipped</div></div>`;

package/ui-static/styles.css

@@ -1126,7 +1126,9 @@ a.btn {
 .orbit-host {
   position: relative;
   min-height: 320px;
-  height: 100%;
+  /* No height here: .viz-host's clamp() bounds the canvas. A height:100% (or a
+     fr unit) resolves against the fact list, which can be thousands of rows,
+     and starves the list's grid track down to 0. */
   border-bottom: 1px solid var(--line);
   background:
     radial-gradient(ellipse at 50% 40%, rgba(46, 196, 182, 0.1), transparent 55%),
@@ -1171,6 +1173,13 @@ a.btn {
   background: var(--bg2);
 }
 
+.brain-v2 {
+  flex: 1;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+}
+
 .brain-body {
   display: flex;
   flex-direction: column;
@@ -2348,6 +2357,7 @@ button.linkish:hover code {
     display: none;
   }
   .brain-v2 {
+    flex: 0 0 auto;
     height: auto;
     min-height: 0;
   }