@sayansr26/agent-os 0.5.0

package/plugins/agent-os/skills/init/scripts/audit.mjs

@@ -0,0 +1,328 @@
+#!/usr/bin/env node
+/**
+ * agent-os audit — one call, whole picture.
+ *
+ * The audit is deterministic: line counts, frontmatter presence, file
+ * existence, JSON keys. Having a model discover that with a dozen Read and
+ * Grep round trips costs tokens on every one. This emits the lot in a single
+ * tool result.
+ *
+ * Read-only. Never writes, never mutates. Exits 0 even on failures so a
+ * partial audit still reaches the caller.
+ *
+ * Usage: node audit.mjs [projectDir]   (defaults to cwd)
+ */
+import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { join, basename } from "node:path";
+import { homedir } from "node:os";
+
+const ROOT = process.argv[2] || process.cwd();
+const HOME = process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
+const out = [];
+const findings = [];
+const say = (s = "") => out.push(s);
+const flag = (sev, msg) => findings.push(`${sev}  ${msg}`);
+
+const read = (p) => { try { return readFileSync(p, "utf8"); } catch { return null; } };
+const lines = (s) => (s ? s.split("\n").length : 0);
+const ls = (p) => { try { return readdirSync(p); } catch { return []; } };
+const size = (p) => { try { return statSync(p).size; } catch { return 0; } };
+const dirBytes = (p) => ls(p).reduce((n, f) => {
+  const fp = join(p, f);
+  try { return n + (statSync(fp).isDirectory() ? dirBytes(fp) : statSync(fp).size); } catch { return n; }
+}, 0);
+const frontmatter = (t) => (t && t.startsWith("---\n")) ? t.slice(4).split("\n---")[0] : "";
+
+say(`AGENT-OS AUDIT   ${ROOT}`);
+say(`                 ${new Date().toISOString().slice(0, 10)}`);
+say();
+
+// ---------------------------------------------------------- always-loaded
+let residentBytes = 0;
+say("ALWAYS-LOADED  (cost on every turn)");
+for (const f of ["CLAUDE.md", ".claude/CLAUDE.md", "CLAUDE.local.md"]) {
+  const t = read(join(ROOT, f));
+  if (!t) continue;
+  const n = lines(t), b = t.length;
+  residentBytes += b;
+  const over = n > 200;
+  say(`  ${f.padEnd(30)} ${String(n).padStart(4)} lines  ${String(b).padStart(6)} B  ${over ? "OVER BUDGET (>200)" : "ok"}`);
+  if (over) flag("WARN", `${f} is ${n} lines; budget is 200. Move path-scoped content to .claude/rules/.`);
+}
+if (!residentBytes) flag("WARN", "No CLAUDE.md at all — this project has no always-loaded instructions.");
+
+// ---------------------------------------------------------- rules
+const rulesDir = join(ROOT, ".claude/rules");
+const ruleFiles = ls(rulesDir).filter((f) => f.endsWith(".md"));
+say();
+say(`RULES  .claude/rules/  — ${ruleFiles.length} file(s)`);
+if (!ruleFiles.length && existsSync(rulesDir) === false) say("  (no rules directory)");
+for (const f of ruleFiles) {
+  const t = read(join(rulesDir, f)) || "";
+  const fm = frontmatter(t);
+  const scoped = /^paths:/m.test(fm);
+  const globs = (fm.match(/-\s+["']/g) || []).length;
+  say(`  ${scoped ? "ok  " : "WARN"} ${f.padEnd(26)} ${String(lines(t)).padStart(4)} lines  ${scoped ? `paths: ${globs}` : "NO paths: — loads every session"}`);
+  if (!scoped) { residentBytes += t.length; flag("WARN", `.claude/rules/${f} has no paths: frontmatter, so it loads every session like CLAUDE.md.`); }
+}
+
+// ---------------------------------------------------------- hooks
+const readJson = (p) => { const t = read(p); if (!t) return null; try { return JSON.parse(t); } catch { return "INVALID"; } };
+const projSettingsPath = join(ROOT, ".claude/settings.json");
+const projSettings = readJson(projSettingsPath);
+say();
+say("HOOKS  .claude/settings.json");
+if (projSettings === null) say("  (no project settings.json)");
+else if (projSettings === "INVALID") flag("FAIL", ".claude/settings.json is not valid JSON.");
+else {
+  const hooks = projSettings.hooks || {};
+  if (!Object.keys(hooks).length) say("  (none)");
+  for (const [evt, entries] of Object.entries(hooks)) {
+    for (const e of entries) for (const h of e.hooks || []) {
+      const cmd = h.command || "";
+      const m = cmd.match(/\$\{CLAUDE_PROJECT_DIR\}\/([^"']+)/);
+      if (!m) { say(`  ok   ${evt.padEnd(14)} ${cmd.slice(0, 60)}`); continue; }
+      const target = m[1], exists = existsSync(join(ROOT, target));
+      say(`  ${exists ? "ok  " : "FAIL"} ${evt.padEnd(14)} ${target}${exists ? "" : "  <- TARGET MISSING"}`);
+      if (!exists) flag("FAIL", `${evt} hook points at ${target}, which does not exist. It fires at a missing path every session.`);
+    }
+  }
+}
+
+// ---------------------------------------------------------- legacy stores
+say();
+say("LEGACY STORES");
+const legacy = [
+  ["memory-bank/", join(ROOT, "memory-bank")],
+  [".serena/memories/", join(ROOT, ".serena/memories")],
+  [".cursorrules", join(ROOT, ".cursorrules")],
+  [".cursor/rules/", join(ROOT, ".cursor/rules")],
+  [".windsurfrules", join(ROOT, ".windsurfrules")],
+  [".clinerules", join(ROOT, ".clinerules")],
+];
+// A store this tool generated is not legacy — telling someone to fold their
+// own compiled output back into CLAUDE.md and delete it would destroy the
+// thing `sync` just wrote. Generated files carry the banner; check for it.
+const generated = (p) => {
+  const files = statSync(p).isDirectory() ? ls(p).map((f) => join(p, f)) : [p];
+  const readable = files.filter((f) => statSync(f).isFile());
+  return readable.length > 0 &&
+    readable.every((f) => (read(f) || "").includes("agent-os: generated from .agent-os/"));
+};
+
+let anyLegacy = false, anyListed = false;
+for (const [label, p] of legacy) {
+  if (!existsSync(p)) continue;
+  const isDir = statSync(p).isDirectory();
+  const n = isDir ? ls(p).length : 1, b = isDir ? dirBytes(p) : size(p);
+  if (generated(p)) {
+    say(`  ${label.padEnd(22)} ${n} file(s)  ${b} B  — generated by agent-os, not legacy`);
+    anyListed = true;
+    continue;
+  }
+  anyLegacy = true;
+  anyListed = true;
+  say(`  FOUND ${label.padEnd(22)} ${n} file(s)  ${b} B`);
+  flag("INFO", `${label} exists — preserve its content into CLAUDE.md or .claude/rules/ before deleting anything.`);
+}
+const mcp = readJson(join(ROOT, ".mcp.json"));
+if (mcp && mcp !== "INVALID") {
+  const servers = Object.keys(mcp.mcpServers || {});
+  const graphy = servers.filter((s) => /graphiti|memory|knowledge|mem0|zep|serena/i.test(s));
+  say(`  .mcp.json servers: ${servers.join(", ") || "(none)"}`);
+  if (graphy.length) flag("INFO", `.mcp.json has memory-ish server(s): ${graphy.join(", ")}. Check they are still wanted.`);
+}
+if (!anyListed) say("  none");
+
+// ---------------------------------------------------------- auto memory + agent memory
+say();
+say("MEMORY");
+for (const [label, dir] of [["agent memory", join(ROOT, ".claude/agent-memory")], ["agent memory (local)", join(ROOT, ".claude/agent-memory-local")]]) {
+  if (!existsSync(dir)) continue;
+  for (const agent of ls(dir)) {
+    const adir = join(dir, agent);
+    const files = ls(adir).filter((f) => f.endsWith(".md"));
+    const idx = read(join(adir, "MEMORY.md"));
+    const idxLines = idx ? idx.split("\n").filter((l) => l.trim()).length : 0;
+    const topics = files.filter((f) => f !== "MEMORY.md");
+    say(`  ${agent.padEnd(34)} index ${String(idxLines).padStart(3)} line(s)   ${topics.length} topic file(s)`);
+    if (idxLines < topics.length) flag("WARN", `${agent}: ${topics.length} topic files but only ${idxLines} indexed in MEMORY.md — the unindexed ones are invisible next session.`);
+    const slugs = topics.map((f) => basename(f, ".md").replace(/[-_]/g, ""));
+    const dupes = slugs.filter((s, i) => slugs.indexOf(s) !== i);
+    if (dupes.length) flag("WARN", `${agent}: near-duplicate topic filenames (hyphen/underscore variants). Merge them.`);
+    if (idx && idx.split("\n").length > 200) flag("WARN", `${agent}: MEMORY.md over 200 lines — everything past that is dropped at startup.`);
+  }
+}
+if (!existsSync(join(ROOT, ".claude/agent-memory")) && !existsSync(join(ROOT, ".claude/agent-memory-local")))
+  say("  no agent memory yet (agents have not run in this project)");
+
+// ---------------------------------------------------------- machine layer
+say();
+say("MACHINE  " + HOME);
+const g = (p) => join(HOME, p);
+const gClaude = read(g("CLAUDE.md"));
+say(`  CLAUDE.md${" ".repeat(24)}${gClaude ? `present  ${gClaude.length} B` : "ABSENT"}`);
+if (!gClaude && residentBytes) {
+  const pc = read(join(ROOT, "CLAUDE.md")) || "";
+  if (/~\/\.claude\/CLAUDE\.md/.test(pc)) flag("FAIL", "Project CLAUDE.md refers to ~/.claude/CLAUDE.md, which does not exist — a dangling reference.");
+}
+for (const d of ["agents", "skills"]) {
+  const names = ls(g(d)).map((f) => basename(f, ".md"));
+  say(`  ${(d + "/").padEnd(33)}${names.length ? names.join(", ") : "absent"}`);
+  const plugin = ["orchestrator", "architect", "builder", "reviewer", "tester", "documenter", "feature-cartographer", "init"];
+  const clash = names.filter((n) => plugin.includes(n));
+  if (clash.length) flag("FAIL", `~/.claude/${d}/ contains ${clash.join(", ")} — user scope OVERRIDES the plugin's copy, so plugin updates stop reaching you.`);
+}
+const projAgents = ls(join(ROOT, ".claude/agents")).map((f) => basename(f, ".md"));
+const pluginNames = ["orchestrator", "architect", "builder", "reviewer", "tester", "documenter", "feature-cartographer"];
+const projClash = projAgents.filter((n) => pluginNames.includes(n));
+if (projClash.length) flag("FAIL", `.claude/agents/ contains ${projClash.join(", ")} — shadows the plugin agent of the same name.`);
+
+const gs = readJson(g("settings.json"));
+if (gs === "INVALID") flag("FAIL", "~/.claude/settings.json is not valid JSON.");
+else if (gs) {
+  const perms = gs.permissions || {};
+  const deny = perms.deny || [];
+  const mode = perms.defaultMode || "(unset)";
+  say(`  permissions.defaultMode${" ".repeat(10)}${mode}`);
+  say(`  permissions.deny${" ".repeat(17)}${deny.length} rule(s)`);
+  if (/auto|accept/i.test(mode) && !deny.length)
+    flag("WARN", `defaultMode is "${mode}" with an empty deny list. A CLAUDE.md rule is context, not enforcement — see references/git-permissions.md.`);
+  const gHooks = JSON.stringify((gs.hooks || {}).SessionStart || []);
+  if (gHooks.includes("session-resume"))
+    flag("FAIL", "~/.claude/settings.json also registers session-resume — the plugin registers it too, so the resume block prints twice. Remove the user-scope copy.");
+  say(`  SessionStart in user scope${" ".repeat(7)}${(gs.hooks || {}).SessionStart ? "yes" : "no"}`);
+} else say("  settings.json                    absent");
+
+// ---------------------------------------------------------- stack + scale
+say();
+say("PROJECT");
+const pkg = readJson(join(ROOT, "package.json"));
+const stacks = [];
+const dep = (n) => {
+  if (!pkg || pkg === "INVALID") return false;
+  return !!((pkg.dependencies || {})[n] || (pkg.devDependencies || {})[n]);
+};
+if (pkg && pkg !== "INVALID") {
+  if (dep("next")) stacks.push("Next.js");
+  else if (dep("react")) stacks.push("React");
+  if (dep("vue")) stacks.push("Vue");
+  if (dep("@nestjs/core")) stacks.push("NestJS");
+  else if (dep("express")) stacks.push("Express");
+  if (dep("typescript")) stacks.push("TypeScript");
+  if (dep("prisma") || dep("@prisma/client")) stacks.push("Prisma");
+}
+for (const [f, label] of [["pyproject.toml", "Python"], ["requirements.txt", "Python"],
+                          ["go.mod", "Go"], ["Cargo.toml", "Rust"], ["pom.xml", "Java/Maven"],
+                          ["Gemfile", "Ruby"], ["composer.json", "PHP"]])
+  if (existsSync(join(ROOT, f)) && !stacks.includes(label)) stacks.push(label);
+
+// source scale — cheap walk, skips the usual noise
+const SKIP = new Set(["node_modules", ".git", "dist", "build", "vendor", ".next", "target", "__pycache__", ".venv", "coverage"]);
+const CODE = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|rb|php|vue|svelte|kt|swift|cs)$/;
+let srcFiles = 0, srcBytes = 0, deepest = 0;
+(function walk(d, depth) {
+  if (depth > 8 || srcFiles > 20000) return;
+  for (const e of ls(d)) {
+    if (SKIP.has(e) || e.startsWith(".")) continue;
+    const fp = join(d, e);
+    let st; try { st = statSync(fp); } catch { continue; }
+    if (st.isDirectory()) { deepest = Math.max(deepest, depth + 1); walk(fp, depth + 1); }
+    else if (CODE.test(e)) { srcFiles++; srcBytes += st.size; }
+  }
+})(ROOT, 0);
+say(`  stack${" ".repeat(28)}${stacks.join(", ") || "not detected"}`);
+say(`  source files${" ".repeat(21)}${srcFiles}  (~${Math.round(srcBytes / 1024)} KB)`);
+
+// LSP — the official plugins answer "find the definition" without reading files
+const LSP = { TypeScript: "typescript-lsp", Python: "pyright-lsp", Go: "gopls-lsp", Rust: "rust-analyzer-lsp", "Java/Maven": "jdtls-lsp", Ruby: "ruby-lsp", PHP: "php-lsp" };
+const wantLsp = stacks.map((s) => LSP[s]).filter(Boolean);
+if (wantLsp.length && srcFiles > 50)
+  flag("INFO", `Install code intelligence: /plugin install ${wantLsp[0]}@claude-plugins-official — lets Claude jump to a definition instead of scanning files.`);
+
+// generated/vendored code that is checked in costs reads
+const genDirs = ["dist", "build", "vendor", "generated", "src/generated", ".next"].filter((d) => existsSync(join(ROOT, d)));
+const gi = read(join(ROOT, ".gitignore")) || "";
+const unignored = genDirs.filter((d) => !gi.split("\n").some((l) => l.trim().replace(/\/$/, "") === d));
+if (unignored.length)
+  flag("INFO", `Checked-in generated/vendored dirs (${unignored.join(", ")}) — add Read deny rules so Claude never opens them.`);
+
+// ---------------------------------------------------------- what to add
+// Signals for each extension mechanism Claude Code offers. Only suggest one
+// when the repo shows evidence it would help — an unused mechanism is cost.
+say();
+say("WHAT THIS PROJECT COULD ADD");
+const rec = [];
+
+// per-directory CLAUDE.md for monorepos
+const pkgDirs = ["packages", "apps", "services", "libs"].filter((d) => existsSync(join(ROOT, d)));
+if (pkgDirs.length) {
+  const subs = pkgDirs.flatMap((d) => ls(join(ROOT, d)).filter((s) => { try { return statSync(join(ROOT, d, s)).isDirectory(); } catch { return false; } }));
+  if (subs.length >= 3) rec.push(["CLAUDE.md (nested)", `${subs.length} packages under ${pkgDirs.join("/")} — a per-package CLAUDE.md loads only when Claude reads there`]);
+}
+
+// hooks: a linter exists but nothing runs it
+const lintCfg = ["eslint.config.js", ".eslintrc", ".eslintrc.json", "biome.json", "ruff.toml", ".golangci.yml"].find((f) => existsSync(join(ROOT, f)));
+const hookEvents = projSettings && projSettings !== "INVALID" ? Object.keys(projSettings.hooks || {}) : [];
+if (lintCfg && !hookEvents.includes("PostToolUse"))
+  rec.push(["hook: PostToolUse", `${lintCfg} exists but nothing lints after an edit — a PostToolUse hook feeds errors straight back`]);
+if (ruleFiles.length && !hookEvents.includes("PreToolUse"))
+  rec.push(["hook: PreToolUse", "rules are written but nothing enforces them — a PreToolUse guard blocks the violation instead of describing it"]);
+
+// MCP: dependencies that postdate model training
+if (pkg && pkg !== "INVALID") {
+  const fast = ["react", "next", "tailwindcss", "react-router-dom", "vue", "svelte", "@angular/core"].filter(dep);
+  const servers = mcp && mcp !== "INVALID" ? Object.keys(mcp.mcpServers || {}) : [];
+  if (fast.length && !servers.includes("context7"))
+    rec.push(["MCP: context7", `${fast.slice(0, 3).join(", ")} move faster than model training — context7 serves current API docs`]);
+}
+
+// skills: repeated procedures worth capturing
+const skillDirs = ls(join(ROOT, ".claude/skills"));
+if (!skillDirs.length && srcFiles > 100)
+  rec.push(["skills", "no project skills — a multi-step procedure you repeat (scaffolding a feature, a release) belongs in one, loaded on invoke not every turn"]);
+
+// agents: only when there is a real repeated specialised review
+const projAgentFiles = ls(join(ROOT, ".claude/agents"));
+if (!projAgentFiles.length && ruleFiles.length >= 4)
+  rec.push(["agents (project)", `${ruleFiles.length} rule files — if one area needs auditing after every change, a project subagent enforces it`]);
+
+// settings: worktree/read hygiene
+if (srcFiles > 500 && !(projSettings && projSettings !== "INVALID" && projSettings.permissions?.deny?.length))
+  rec.push(["settings: Read deny", "large tree with no Read deny rules — block generated and vendored paths"]);
+
+if (!rec.length) say("  nothing obvious — the mechanisms in use look proportionate");
+for (const [what, why] of rec) say(`  ${what.padEnd(24)} ${why}`);
+if (rec.length) flag("INFO", `${rec.length} extension(s) this project could use — see the list above. Each one costs context, so add only what earns it.`);
+
+// ---------------------------------------------------------- mode
+const hasLayer = residentBytes > 0 || ruleFiles.length > 0;
+const mapped = existsSync(join(ROOT, ".claude/agent-memory/agent-os-feature-cartographer"));
+let MODE;
+if (srcFiles < 5 && !hasLayer) MODE = "TOO-EARLY";
+else if (!hasLayer) MODE = "ESTABLISH";
+else if (anyLegacy || findings.some((f) => f.startsWith("WARN") || f.startsWith("FAIL"))) MODE = "MIGRATE";
+else if (!mapped) MODE = "MAP";
+else MODE = "MAINTAIN";
+say();
+say(`MODE  ${MODE}`);
+say({
+  "TOO-EARLY": "  Barely any source yet. Do not build a context layer over nothing —\n  write code first, then run Claude Code's own /init, then come back.",
+  ESTABLISH:   "  Real code, no context layer. Build one FROM THE CODE: read\n  references/establishing.md. Do not invent conventions.",
+  MIGRATE:     "  A layer exists but has problems. Fix the findings below;\n  read references/migrating.md for anything legacy.",
+  MAP:         "  Layer is healthy but the codebase has never been mapped. Build the\n  architecture map: read references/establishing.md, 'Map the architecture'.",
+  MAINTAIN:    "  Layer is healthy and the codebase is mapped. Nothing to set up.",
+}[MODE]);
+
+// ---------------------------------------------------------- verdict
+say();
+say(`STARTUP COST  ~${residentBytes} B  ~= ${Math.round(residentBytes / 4)} tokens  (always-loaded files only)`);
+say();
+if (!findings.length) say("VERDICT  no findings — setup is clean.");
+else {
+  say(`VERDICT  ${findings.length} finding(s), worst first:`);
+  const order = { FAIL: 0, WARN: 1, INFO: 2 };
+  findings.sort((a, b) => order[a.split(" ")[0]] - order[b.split(" ")[0]]);
+  for (const f of findings) say("  " + f);
+}
+process.stdout.write(out.join("\n") + "\n");

package/plugins/agent-os/skills/map/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: map
+description: Build or refresh the architecture map so changes run off known structure instead of rediscovering the codebase. Use for "map this codebase", "build the architecture map", "how is this project structured", "map the login flow", "refresh the map", or before changing a feature you have not touched before.
+---
+
+# Map the codebase
+
+A map written once is an answer given free for the rest of the project's life.
+This is what makes a request like *"change the login flow from email to OTP"*
+start from known structure instead of a cold grep.
+
+You do not do the exploring. `feature-cartographer` does, in its own context
+window, and returns a summary. That is the whole point — the file reads never
+enter this conversation.
+
+## `$ARGUMENTS`
+
+| Argument | Do |
+|---|---|
+| *(none)* or `architecture` | Build or refresh `_architecture.md`, the system-level map |
+| `<feature or area>` | Map that feature — "map the login flow", "map checkout" |
+| `refresh` | Re-map whatever `/agent-os:memory stale` flagged as drifted |
+
+## The architecture map
+
+Dispatch `feature-cartographer` with a system-level brief, not a feature
+question:
+
+> Map this codebase at the system level. Produce `_architecture.md`: stack and
+> versions, the layers and what each owns, where a request enters and how it
+> reaches data, state management, the network edge, the auth and permission
+> model, build and run commands, and the three or four files a newcomer must read
+> first. Name real files. State what you could not determine.
+
+Everything in it must be observed in this repository. Versions come from a
+manifest, not from what the model knows about the framework.
+
+Build this once per project. Refresh it when the architecture actually changes —
+a new service, a swapped data layer, a routing migration — not on a schedule.
+
+## Mapping one feature
+
+Dispatch the cartographer with the feature name. It reads `_architecture.md`
+first, so it explores a fraction of what it would cold, and returns entry point,
+the files that matter, state, network edge, what gates it, and the blast radius.
+
+Then it writes the map to disk and indexes it, so the next question about that
+area is near free.
+
+## After the map exists
+
+Point the user at the change workflow — the map only pays off if changes actually
+use it: `references/changing-a-feature.md` in the `init` skill. In short:
+cartographer answers *how is it built*, the path-scoped rules load themselves,
+`builder` works from the map and the nearest precedent rather than the one-line
+request, `reviewer` checks against written rules, and the cartographer updates
+the map in the same turn.
+
+That last step is the one people skip. A map that was right last week and is
+wrong today is worse than no map, because it gets trusted.
+
+## Verify before trusting it
+
+Ask the cartographer something about the codebase you already know the answer to,
+and check it. Do this the first time a map is built. A confidently wrong map is
+the failure mode worth catching early, and this is the cheapest moment to catch
+it.

package/plugins/agent-os/skills/memory/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: memory
+description: Inspect, repair or edit what this project remembers — agent memory, Claude Code auto memory, and path-scoped rules. Use for "show my memories", "what does Claude remember about this project", "clean up agent memory", "forget X", "my agent memory is a mess", "which maps are stale", or when memory looks duplicated, orphaned or wrong.
+---
+
+# Project memory
+
+Every durable store this project has, in one place: per-agent memory, Claude
+Code's own auto memory, and `.claude/rules/`.
+
+## Run the inspection first
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/skills/memory/scripts/memory.mjs"
+```
+
+Add `--stale` to also compare each map's `mapped:` date against the last commit
+that touched the file it describes — that is how you find maps the code has
+moved past. Pass a path as the first argument for a project other than the
+working directory. Read-only.
+
+It prints every store, every topic file with line counts and map dates, and a
+health list: topic files missing from their index, hyphen/underscore duplicates
+of the same subject, oversized indexes, and unscoped rules.
+
+Show the output before changing anything.
+
+## `$ARGUMENTS`
+
+| Argument | Do |
+|---|---|
+| *(none)* or `list` | Run the inspection, report, stop |
+| `show <name>` | Read that topic file or index and summarise it |
+| `clean` | Fix everything in the health list — see below |
+| `forget <subject>` | Delete that topic file **and** its index line, and anything derived solely from it |
+| `stale` | Run with `--stale` and report only what has drifted |
+
+## `clean` — what to actually do
+
+Work through the health list in this order. Show the user each change before
+making it; this is their accumulated knowledge, not scratch.
+
+1. **Merge duplicates.** Two files for one subject (`defect-patterns.md` and
+   `defect_patterns.md`) hold different content written in different sessions —
+   the agent thought it was updating one file. **Read both fully and merge**,
+   keeping every distinct fact. Do not pick one and delete the other. Keep the
+   kebab-case name.
+2. **Index the orphans.** A topic file missing from `MEMORY.md` is invisible: the
+   agent will not find it next session, will write the same knowledge again under
+   a new name, and the copies will diverge. Add one line per file.
+3. **Trim an oversized index.** Only the first 200 lines of `MEMORY.md` load at
+   startup. Everything past that is silently dropped. One line per topic file,
+   detail in the topic files.
+4. **Scope unscoped rules.** A `.claude/rules/` file without `paths:` frontmatter
+   loads every session, exactly like `CLAUDE.md`. Either give it `paths:` or move
+   its content into `CLAUDE.md` where it belongs.
+5. **Refresh stale maps.** For anything `--stale` flagged, dispatch
+   `feature-cartographer` to re-map that area. Do not edit a map by hand from
+   memory — that is how a map becomes confidently wrong.
+
+## Where a fact belongs
+
+If the user is adding something rather than repairing, route it:
+
+| Kind of fact | Store |
+|---|---|
+| True in every session, every file | project `CLAUDE.md`, ≤200 lines |
+| Durable but scoped to some files | `.claude/rules/<topic>.md` with `paths:` |
+| How a feature is built | agent memory — let the cartographer write it, do not hand-author |
+| A correction the user gave you, a preference, a decision | Claude Code auto memory — it writes this itself |
+| Work in flight | the project's task vault, not memory |
+| Derivable by reading the code | **nowhere** |
+
+Never hand-write into an agent's memory directory. That directory is the agent's
+working knowledge and it maintains its own index; writing into it from outside
+produces exactly the orphan-and-duplicate mess this skill exists to clean up. If
+the cartographer's map is wrong, re-dispatch the cartographer.
+
+## What this will not do
+
+It will not delete a store because it looks untidy. Duplicates get merged, not
+dropped. `forget` removes only what the user named.

package/plugins/agent-os/skills/memory/scripts/memory.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * Inspect every memory store this project has, and check each one's health.
+ * Read-only. The deterministic half of `/agent-os:memory`.
+ *
+ * Usage: node memory.mjs [projectDir] [--stale]
+ *   --stale  also compare each map's `mapped:` date against git's last commit
+ *            touching the file it describes, so you can see what has drifted.
+ */
+import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { join, basename } from "node:path";
+import { homedir } from "node:os";
+
+const ROOT = process.argv.find((a, i) => i > 1 && !a.startsWith("--")) || process.cwd();
+const STALE = process.argv.includes("--stale");
+const HOME = process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
+const read = (p) => { try { return readFileSync(p, "utf8"); } catch { return null; } };
+const ls = (p) => { try { return readdirSync(p); } catch { return []; } };
+const git = (c) => { try { return execSync(c, { cwd: ROOT, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 4000 }).trim(); } catch { return ""; } };
+
+const out = [], issues = [];
+const say = (s = "") => out.push(s);
+
+say(`MEMORY STORES   ${ROOT}\n`);
+
+// ---- agent memory ----
+for (const [scope, dir] of [["project", join(ROOT, ".claude/agent-memory")], ["local", join(ROOT, ".claude/agent-memory-local")]]) {
+  if (!existsSync(dir)) continue;
+  for (const agent of ls(dir).sort()) {
+    const adir = join(dir, agent);
+    const files = ls(adir).filter((f) => f.endsWith(".md"));
+    const topics = files.filter((f) => f !== "MEMORY.md");
+    const idxRaw = read(join(adir, "MEMORY.md"));
+    const idx = idxRaw ? idxRaw.split("\n").filter((l) => l.trim().startsWith("-")) : [];
+
+    say(`${agent}  (${scope})`);
+    say(`  index: ${idx.length} entr${idx.length === 1 ? "y" : "ies"}   topics: ${topics.length} file(s)`);
+
+    // which topic files are not referenced anywhere in the index
+    const orphans = topics.filter((f) => !idxRaw || !idxRaw.includes(basename(f, ".md")));
+    // hyphen/underscore collisions — the same subject written twice
+    const norm = (f) => basename(f, ".md").replace(/[-_]/g, "").toLowerCase();
+    const seen = {};
+    const dupes = [];
+    for (const f of topics) { const k = norm(f); if (seen[k]) dupes.push([seen[k], f]); else seen[k] = f; }
+
+    for (const f of topics.sort()) {
+      const t = read(join(adir, f)) || "";
+      const mapped = (t.match(/^mapped:\s*(\S+)/m) || [])[1];
+      const entry = (t.match(/^entry:\s*(\S+)/m) || [])[1];
+      let note = "";
+      if (orphans.includes(f)) note += "  NOT IN INDEX";
+      if (STALE && mapped && entry) {
+        const last = git(`git log -1 --format=%cs -- ${JSON.stringify(entry)}`);
+        if (last && last > mapped) note += `  STALE (mapped ${mapped}, code changed ${last})`;
+      }
+      say(`    ${f.padEnd(34)} ${String(t.split("\n").length).padStart(4)} lines${mapped ? `  mapped ${mapped}` : ""}${note}`);
+    }
+    if (orphans.length) issues.push(`${agent}: ${orphans.length} topic file(s) not in MEMORY.md — invisible next session: ${orphans.join(", ")}`);
+    for (const [a, b] of dupes) issues.push(`${agent}: "${a}" and "${b}" are the same subject — merge them`);
+    if (idxRaw && idxRaw.split("\n").length > 200) issues.push(`${agent}: MEMORY.md over 200 lines — everything past that is dropped at startup`);
+    say();
+  }
+}
+if (!out.some((l) => l.includes("index:"))) say("no agent memory yet — agents have not run in this project\n");
+
+// ---- Claude Code auto memory ----
+const repo = git("git rev-parse --show-toplevel") || ROOT;
+const slug = repo.replace(/\//g, "-");
+const autoDir = join(HOME, "projects", slug, "memory");
+say("auto memory (Claude Code's own)");
+if (!existsSync(autoDir)) say(`  none yet at ${autoDir}`);
+else {
+  const idx = read(join(autoDir, "MEMORY.md"));
+  const topics = ls(autoDir).filter((f) => f.endsWith(".md") && f !== "MEMORY.md");
+  say(`  ${autoDir}`);
+  say(`  MEMORY.md: ${idx ? idx.split("\n").length + " lines" : "absent"}   topics: ${topics.length}`);
+  for (const f of topics.sort()) say(`    ${f}`);
+  if (idx && idx.split("\n").length > 200) issues.push("auto memory MEMORY.md over 200 lines — content past that is dropped at startup");
+}
+
+// ---- rules, the other durable store ----
+const rules = ls(join(ROOT, ".claude/rules")).filter((f) => f.endsWith(".md"));
+say();
+say(`project rules  .claude/rules/  — ${rules.length} file(s)`);
+for (const f of rules.sort()) {
+  const t = read(join(ROOT, ".claude/rules", f)) || "";
+  const scoped = /^paths:/m.test(t.split("---")[1] || "");
+  say(`  ${scoped ? "scoped  " : "UNSCOPED"} ${f}`);
+  if (!scoped) issues.push(`.claude/rules/${f} has no paths: — it loads every session`);
+}
+
+say();
+if (!issues.length) say("HEALTH  no issues.");
+else { say(`HEALTH  ${issues.length} issue(s):`); for (const i of issues) say("  - " + i); }
+process.stdout.write(out.join("\n") + "\n");