packmind 0.1.0

package/dist/state/maintain.js

@@ -0,0 +1,25 @@
+import * as path from "node:path";
+import { brain } from "./files.js";
+import { readTextOr, writeText, appendLine } from "../util/fs-atomic.js";
+const MAX_JOURNAL_LINES = 1500;
+const KEEP_JOURNAL_LINES = 600;
+/**
+ * Keep journal.md from growing without bound: once it exceeds a threshold, move
+ * the oldest entries into journal.archive.md and keep the recent tail. Returns
+ * the number of lines archived (0 if no action needed). Non-destructive — the
+ * archived lines are appended, never dropped.
+ */
+export function consolidateJournal(projectRoot) {
+    const b = brain(projectRoot);
+    const lines = readTextOr(b.journal).split(/\r?\n/);
+    if (lines.length <= MAX_JOURNAL_LINES)
+        return 0;
+    const header = lines.slice(0, 3);
+    const body = lines.slice(3);
+    const cut = body.length - KEEP_JOURNAL_LINES;
+    const archived = body.slice(0, cut);
+    const kept = body.slice(cut);
+    appendLine(path.join(b.dir, "journal.archive.md"), archived.join("\n") + "\n");
+    writeText(b.journal, [...header, "", `> (${cut} older lines archived to journal.archive.md)`, "", ...kept].join("\n"));
+    return cut;
+}

package/dist/state/mapper.js

@@ -0,0 +1,56 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { walkProject } from "./walk.js";
+import { describeFile } from "./describe.js";
+import { parseMap, serializeMap } from "./formats.js";
+import { brain } from "./files.js";
+import { writeText, readTextOr } from "../util/fs-atomic.js";
+import { estimateTokens } from "../cost/estimator.js";
+import { inputCost } from "../cost/pricing.js";
+function sectionFor(rel) {
+    const dir = path.posix.dirname(rel);
+    return dir === "." ? "./" : dir + "/";
+}
+export function buildMap(projectRoot, config) {
+    const sections = new Map();
+    for (const { abs, rel } of walkProject(projectRoot, config)) {
+        let content;
+        try {
+            content = fs.readFileSync(abs, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const tokens = estimateTokens(content, rel);
+        const key = sectionFor(rel);
+        if (!sections.has(key))
+            sections.set(key, []);
+        sections.get(key).push({
+            file: path.posix.basename(rel),
+            description: describeFile(rel, content),
+            tokens,
+            cost: inputCost(config.model, tokens),
+        });
+    }
+    let fileCount = 0;
+    for (const [, list] of sections)
+        fileCount += list.length;
+    return {
+        content: serializeMap(sections, { fileCount, updated: new Date().toISOString() }),
+        fileCount,
+    };
+}
+export function scanProject(projectRoot, config) {
+    const { content, fileCount } = buildMap(projectRoot, config);
+    writeText(brain(projectRoot).map, content);
+    return fileCount;
+}
+export function countMapEntries(content) {
+    let n = 0;
+    for (const [, list] of parseMap(content))
+        n += list.length;
+    return n;
+}
+export function currentMapEntries(projectRoot) {
+    return countMapEntries(readTextOr(brain(projectRoot).map));
+}

package/dist/state/project.js

@@ -0,0 +1,33 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { homeDirectory } from "../util/platform.js";
+import { STATE_DIR } from "../util/paths.js";
+const ROOT_MARKERS = [
+    ".git", "package.json", "pyproject.toml", "Cargo.toml", "go.mod", "deno.json",
+    "pom.xml", "build.gradle", "composer.json", "Gemfile", "Makefile",
+];
+/**
+ * Resolve the project root. Honors an explicit env override
+ * (PACKMIND_ROOT / CLAUDE_PROJECT_DIR), then walks up to a marker or an existing
+ * `.packmind/`. Never ascends above the user's home directory.
+ */
+export function findRoot(start) {
+    const override = process.env.PACKMIND_ROOT || process.env.CLAUDE_PROJECT_DIR;
+    let dir = path.resolve(override || start || process.cwd());
+    const fsRoot = path.parse(dir).root;
+    const home = homeDirectory();
+    for (let i = 0; i < 30; i++) {
+        if (fs.existsSync(path.join(dir, STATE_DIR)))
+            return dir;
+        if (ROOT_MARKERS.some((m) => fs.existsSync(path.join(dir, m))))
+            return dir;
+        const up = path.dirname(dir);
+        if (up === dir || up === fsRoot || dir === home)
+            break;
+        dir = up;
+    }
+    return path.resolve(override || start || process.cwd());
+}
+export function isHome(dir) {
+    return path.resolve(dir) === path.resolve(homeDirectory());
+}

package/dist/state/schema.js

@@ -0,0 +1,47 @@
+import { readJsonOr } from "../util/fs-atomic.js";
+export const DEFAULT_CONFIG = {
+    version: 1,
+    model: "claude-opus-4-8",
+    map: {
+        autoScanOnInit: true,
+        maxFiles: 600,
+        respectGitignore: true,
+        excludeDirs: [
+            "node_modules", ".git", ".packmind", ".claude", "dist", "build", "out",
+            ".next", ".nuxt", ".svelte-kit", "coverage", "__pycache__", ".cache",
+            "target", ".venv", "vendor", ".turbo", ".vercel", ".idea", ".vscode",
+        ],
+        extraSecretGlobs: [],
+    },
+    cost: { exact: "auto" },
+    recall: {
+        enabled: true,
+        embedModel: "Xenova/all-MiniLM-L6-v2",
+        chunkChars: 1200,
+        topK: 6,
+    },
+    guard: { blockSecrets: false },
+    claude: {
+        settingsPath: ".claude/settings.json",
+        claudeMdPath: "CLAUDE.md",
+    },
+};
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Recursively merge `patch` onto `base`; arrays and scalars are replaced. */
+export function deepMerge(base, patch) {
+    if (!isPlainObject(base) || !isPlainObject(patch)) {
+        return patch === undefined ? base : patch;
+    }
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(patch)) {
+        merged[key] = isPlainObject(value) && isPlainObject(merged[key])
+            ? deepMerge(merged[key], value)
+            : value;
+    }
+    return merged;
+}
+export function loadConfig(configPath) {
+    return deepMerge(DEFAULT_CONFIG, readJsonOr(configPath, {}));
+}

package/dist/state/snapshot.js

@@ -0,0 +1,69 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { brain } from "./files.js";
+import { userRoot } from "../util/platform.js";
+/** Root for all project backups: ~/.packmind/backups/<project>/<timestamp>/ */
+export function backupsRoot() {
+    return path.join(userRoot(), "backups");
+}
+function projectBackupDir(projectRoot) {
+    return path.join(backupsRoot(), path.basename(path.resolve(projectRoot)));
+}
+function timestamp() {
+    return new Date().toISOString().replace(/[:.]/g, "-");
+}
+/**
+ * Snapshot the project's `.packmind/` into a timestamped backup. The large,
+ * fully-regenerable vector index is skipped (rebuild with `packmind index`),
+ * along with transient lock/temp files. Returns the backup path.
+ */
+export function createSnapshot(projectRoot, label) {
+    const src = brain(projectRoot).dir;
+    const dest = path.join(projectBackupDir(projectRoot), label ?? timestamp());
+    fs.mkdirSync(dest, { recursive: true });
+    fs.cpSync(src, dest, {
+        recursive: true,
+        filter: (from) => {
+            const base = path.basename(from);
+            if (base.endsWith(".lock") || base.endsWith(".tmp"))
+                return false;
+            if (from.endsWith(`${path.sep}recall${path.sep}vectors.json`))
+                return false;
+            return true;
+        },
+    });
+    return dest;
+}
+export function listSnapshots(projectRoot) {
+    try {
+        return fs
+            .readdirSync(projectBackupDir(projectRoot))
+            .filter((d) => fs.statSync(path.join(projectBackupDir(projectRoot), d)).isDirectory())
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+export function restoreSnapshot(projectRoot, label) {
+    const src = path.join(projectBackupDir(projectRoot), label);
+    if (!fs.existsSync(src))
+        return false;
+    fs.cpSync(src, brain(projectRoot).dir, { recursive: true });
+    return true;
+}
+/** Keep only the most recent `keep` snapshots; returns how many were removed. */
+export function pruneSnapshots(projectRoot, keep) {
+    const dir = projectBackupDir(projectRoot);
+    const all = listSnapshots(projectRoot);
+    const toRemove = all.slice(0, Math.max(0, all.length - keep));
+    for (const d of toRemove) {
+        try {
+            fs.rmSync(path.join(dir, d), { recursive: true, force: true });
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    return toRemove.length;
+}

package/dist/state/walk.js

@@ -0,0 +1,75 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import ignore from "ignore";
+import { relativePosix } from "../util/paths.js";
+import { looksSecret } from "../guard/secrets.js";
+const BINARY_EXT = new Set([
+    ".png", ".jpg", ".jpeg", ".gif", ".bmp", ".ico", ".webp", ".avif",
+    ".woff", ".woff2", ".ttf", ".eot", ".otf",
+    ".zip", ".tar", ".gz", ".bz2", ".7z", ".rar", ".jar",
+    ".exe", ".dll", ".so", ".dylib", ".bin", ".wasm",
+    ".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx",
+    ".mp3", ".mp4", ".avi", ".mov", ".webm", ".ogg", ".flac",
+    ".sqlite", ".db", ".lock",
+]);
+/**
+ * Walk the project, yielding text source files. Honors `.gitignore`, the config
+ * exclude list, the secrets denylist, a per-file size cap, and a max-file cap.
+ * Used by both the map scanner and the recall indexer so they always agree on
+ * which files exist.
+ */
+export function walkProject(projectRoot, config) {
+    const c = config.map;
+    const ig = ignore().add([".git", ".packmind"]);
+    if (c.respectGitignore) {
+        try {
+            ig.add(fs.readFileSync(path.join(projectRoot, ".gitignore"), "utf8"));
+        }
+        catch {
+            /* no .gitignore */
+        }
+    }
+    const excluded = new Set(c.excludeDirs);
+    const results = [];
+    const walk = (dir) => {
+        if (results.length >= c.maxFiles)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of entries) {
+            if (results.length >= c.maxFiles)
+                return;
+            const abs = path.join(dir, entry.name);
+            const rel = relativePosix(projectRoot, abs);
+            if (c.respectGitignore && ig.ignores(entry.isDirectory() ? rel + "/" : rel))
+                continue;
+            if (entry.isDirectory()) {
+                if (excluded.has(entry.name))
+                    continue;
+                walk(abs);
+            }
+            else if (entry.isFile()) {
+                if (BINARY_EXT.has(path.extname(entry.name).toLowerCase()))
+                    continue;
+                if (looksSecret(entry.name, c.extraSecretGlobs))
+                    continue;
+                try {
+                    if (fs.statSync(abs).size > 1_048_576)
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                results.push({ abs, rel });
+            }
+        }
+    };
+    walk(projectRoot);
+    return results;
+}

package/dist/util/fs-atomic.js

@@ -0,0 +1,106 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+/**
+ * Crash-safe, concurrency-safe file IO.
+ *
+ * Writes go to a temp sibling and are atomically renamed into place. A coarse
+ * advisory lock (an exclusively-created `<file>.lock` directory) serializes
+ * writers so concurrent hook processes can't interleave and corrupt a shared
+ * file. Stale locks (older than LOCK_TTL_MS) are reclaimed.
+ */
+const FALLBACK_CODES = new Set(["EBUSY", "EACCES", "EPERM", "EXDEV"]);
+const LOCK_TRIES = 60;
+const LOCK_WAIT_MS = 20;
+const LOCK_TTL_MS = 10_000;
+function busyWait(ms) {
+    const until = Date.now() + ms;
+    while (Date.now() < until) {
+        /* hooks are short synchronous scripts; a brief spin is acceptable */
+    }
+}
+export function withLock(target, body) {
+    const parent = path.dirname(target);
+    fs.mkdirSync(parent, { recursive: true });
+    const lock = `${target}.lock`;
+    let held = false;
+    for (let i = 0; i < LOCK_TRIES; i++) {
+        try {
+            fs.mkdirSync(lock);
+            held = true;
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            try {
+                if (Date.now() - fs.statSync(lock).mtimeMs > LOCK_TTL_MS) {
+                    fs.rmSync(lock, { recursive: true, force: true });
+                    continue;
+                }
+            }
+            catch {
+                /* lock disappeared; loop and retry */
+            }
+            busyWait(LOCK_WAIT_MS);
+        }
+    }
+    try {
+        return body();
+    }
+    finally {
+        if (held) {
+            try {
+                fs.rmSync(lock, { recursive: true, force: true });
+            }
+            catch {
+                /* best effort */
+            }
+        }
+    }
+}
+function writeAtomic(target, data) {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const temp = `${target}.${crypto.randomBytes(5).toString("hex")}.tmp`;
+    try {
+        fs.writeFileSync(temp, data, "utf8");
+        fs.renameSync(temp, target);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(temp);
+        }
+        catch {
+            /* temp may not exist */
+        }
+        if (!FALLBACK_CODES.has(err.code ?? ""))
+            throw err;
+        fs.writeFileSync(target, data, "utf8");
+    }
+}
+export function readTextOr(target, fallback = "") {
+    try {
+        return fs.readFileSync(target, "utf8");
+    }
+    catch {
+        return fallback;
+    }
+}
+export function writeText(target, data) {
+    withLock(target, () => writeAtomic(target, data));
+}
+export function appendLine(target, line) {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    withLock(target, () => fs.appendFileSync(target, line, "utf8"));
+}
+export function readJsonOr(target, fallback) {
+    try {
+        return JSON.parse(fs.readFileSync(target, "utf8"));
+    }
+    catch {
+        return fallback;
+    }
+}
+export function writeJson(target, value) {
+    withLock(target, () => writeAtomic(target, JSON.stringify(value, null, 2) + "\n"));
+}

package/dist/util/logger.js

@@ -0,0 +1,17 @@
+const RANK = { debug: 0, info: 1, warn: 2, error: 3 };
+let threshold = process.env.PACKMIND_LOG || "info";
+export function setLogLevel(level) {
+    threshold = level;
+}
+function line(level, msg) {
+    if (RANK[level] < RANK[threshold])
+        return;
+    const stream = level === "warn" || level === "error" ? process.stderr : process.stdout;
+    stream.write(`[packmind] ${msg}\n`);
+}
+export const log = {
+    debug: (m) => line("debug", m),
+    info: (m) => line("info", m),
+    warn: (m) => line("warn", m),
+    error: (m) => line("error", m),
+};

package/dist/util/paths.js

@@ -0,0 +1,20 @@
+import * as path from "node:path";
+import * as fs from "node:fs";
+/** Name of PackMind's per-project state directory. */
+export const STATE_DIR = ".packmind";
+/** Convert OS-specific separators to POSIX slashes for stable comparisons. */
+export function toPosix(p) {
+    return p.split(path.sep).join("/");
+}
+export function stateDirFor(projectRoot) {
+    return path.join(projectRoot, STATE_DIR);
+}
+export function stateFile(projectRoot, ...parts) {
+    return path.join(projectRoot, STATE_DIR, ...parts);
+}
+export function ensureDir(dir) {
+    fs.mkdirSync(dir, { recursive: true });
+}
+export function relativePosix(from, to) {
+    return toPosix(path.relative(from, to));
+}

package/dist/util/platform.js

@@ -0,0 +1,10 @@
+import * as os from "node:os";
+export const onWindows = process.platform === "win32";
+export const onMac = process.platform === "darwin";
+export function homeDirectory() {
+    return os.homedir();
+}
+/** PackMind's user-global cache/config root (models, registry). */
+export function userRoot() {
+    return `${os.homedir()}/.packmind`;
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "packmind",
+  "version": "0.1.0",
+  "description": "A second brain for Claude Code: project memory, real token & cost accounting, semantic recall, and active guardrails.",
+  "type": "module",
+  "bin": {
+    "packmind": "./dist/bin/packmind.js"
+  },
+  "scripts": {
+    "prebuild": "node -e \"const fs=require('fs');if(fs.existsSync('dist'))fs.rmSync('dist',{recursive:true})\"",
+    "build": "tsc && tsc -p tsconfig.hooks.json",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "ignore": "^6.0.2"
+  },
+  "optionalDependencies": {
+    "@xenova/transformers": "^2.17.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild",
+      "onnxruntime-node",
+      "sharp",
+      "protobufjs"
+    ]
+  },
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Michael Scherding",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mchl-schrdng/packmind.git"
+  },
+  "homepage": "https://github.com/mchl-schrdng/packmind",
+  "bugs": {
+    "url": "https://github.com/mchl-schrdng/packmind/issues"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "mcp",
+    "ai",
+    "context",
+    "tokens",
+    "cost",
+    "memory",
+    "developer-tools"
+  ],
+  "files": [
+    "dist/",
+    "src/templates/",
+    "LICENSE",
+    "README.md"
+  ]
+}

package/src/templates/PACKMIND.md

@@ -0,0 +1,42 @@
+# PACKMIND.md — Operating Protocol
+
+PackMind gives you (Claude) a persistent second brain for this project, stored in
+`.packmind/`. It surfaces context automatically through hooks and exposes tools
+through the **packmind** MCP server. Follow this protocol each session.
+
+## Before reading a file
+- Check `map.md` first — if a file's description and token/cost estimate answer
+  your question, don't open the whole file.
+- Don't re-read a file you already read this session unless it changed.
+
+## Before writing code
+- Heed any guardrail warnings (they reference `policy.json` and the secrets
+  denylist). A blocked write means policy forbids it — choose another path.
+- Honor the `## Never Do` list in `knowledge.md`.
+
+## Use the MCP tools
+- `recall("…")` — semantic search across project memory. Use it before
+  investigating a bug or re-deriving how something works.
+- `remember(note, kind)` — save a preference, decision, never-do rule, or note.
+- `record_solution(error, cause, fix, tags)` — log a fix so it's never
+  rediscovered.
+- `project_map(filter?)` — list files with descriptions and token estimates.
+- `usage_report()` — token usage and dollar cost so far.
+- `handoff("get"|"set", content?)` — read or update the resume note.
+
+## When you finish meaningful work
+- `remember` durable lessons/preferences/decisions.
+- `record_solution` for any real bug you fixed.
+- `handoff("set", …)` with where things stand and what's next.
+
+## Files in `.packmind/`
+| File | Purpose |
+|------|---------|
+| `map.md` | File map: description, token estimate, est. read cost |
+| `knowledge.md` | Preferences, decisions, never-do list, notes |
+| `journal.md` | Chronological action log + session summaries |
+| `solutions.json` | Known bugs and their fixes |
+| `usage.json` | Token + dollar-cost ledger |
+| `handoff.md` | Session resume note |
+| `policy.json` | Guardrail rules |
+| `recall/` | Local semantic index (never leaves your machine) |

package/src/templates/claude-md-snippet.md

@@ -0,0 +1,9 @@
+<!-- PACKMIND:START -->
+## PackMind
+
+This project uses **PackMind** — a second brain for Claude Code. Read
+`.packmind/PACKMIND.md` and follow it: consult `.packmind/map.md` before reading
+files, heed guardrail warnings before writing, and use the **packmind** MCP tools
+(`recall`, `remember`, `record_solution`, `project_map`, `usage_report`,
+`handoff`) to read and update project memory.
+<!-- PACKMIND:END -->

package/src/templates/config.json

@@ -0,0 +1,48 @@
+{
+  "version": 1,
+  "model": "claude-opus-4-8",
+  "map": {
+    "autoScanOnInit": true,
+    "maxFiles": 600,
+    "respectGitignore": true,
+    "excludeDirs": [
+      "node_modules",
+      ".git",
+      ".packmind",
+      ".claude",
+      "dist",
+      "build",
+      "out",
+      ".next",
+      ".nuxt",
+      ".svelte-kit",
+      "coverage",
+      "__pycache__",
+      ".cache",
+      "target",
+      ".venv",
+      "vendor",
+      ".turbo",
+      ".vercel",
+      ".idea",
+      ".vscode"
+    ],
+    "extraSecretGlobs": []
+  },
+  "cost": {
+    "exact": "auto"
+  },
+  "recall": {
+    "enabled": true,
+    "embedModel": "Xenova/all-MiniLM-L6-v2",
+    "chunkChars": 1200,
+    "topK": 6
+  },
+  "guard": {
+    "blockSecrets": false
+  },
+  "claude": {
+    "settingsPath": ".claude/settings.json",
+    "claudeMdPath": "CLAUDE.md"
+  }
+}