aidimag 1.0.0

package/LICENSE

@@ -0,0 +1,102 @@
+Elastic License 2.0
+
+Copyright (c) 2025 Anup Khanal
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable,
+non-transferable license to use, copy, distribute, make available, and prepare
+derivative works of the software, in each case subject to the limitations and
+conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed service,
+where the service provides users with access to any substantial set of the features
+or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality in
+the software, and you may not remove or obscure any functionality in the software
+that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor's trademarks is subject
+to applicable law.
+
+## Additional Use Grant: Small Team License
+
+**Free for organizations with 10 or fewer total employees/users.**
+
+If your organization has more than 10 employees or users (including all affiliates
+and entities under common control), you must obtain a commercial license from the
+licensor. Contact: https://github.com/anupkhanal/aidimag/issues (commercial licensing inquiries)
+
+For determining the user count, "users" includes anyone who:
+- Runs commands using the software
+- Uses AI agents connected to the software
+- Accesses dashboards or IDE extensions provided by the software
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can license,
+or becomes able to license, to make, have made, use, sell, offer for sale, import
+and have imported the software, in each case subject to the limitations and conditions
+in this license. This license does not cover any patent claims that you cause to be
+infringed by modifications or additions to the software. If you or your company make
+any written claim that the software infringes or contributes to infringement of any
+patent, your patent license for the software granted under these terms ends immediately.
+If your company makes such a claim, your patent license ends immediately for work on
+behalf of your company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also
+gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the software
+prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed, and
+your licenses will automatically terminate. If the licensor provides you with a notice
+of your violation, and you cease all violation of this license no later than 30 days
+after you receive that notice, your licenses will be reinstated retroactively. However,
+if you violate these terms after such reinstatement, any additional violation of these
+terms will cause your licenses to terminate automatically and permanently.
+
+## No Liability
+
+**As far as the law allows, the software comes as is, without any warranty or condition,
+and the licensor will not be liable to you for any damages arising out of these terms
+or the use or nature of the software, under any kind of legal claim.**
+
+## Definitions
+
+The **licensor** is Anup Khanal.
+
+The **software** is the software the licensor makes available under these terms,
+including any portion of it.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization
+that you work for, plus all organizations that have control over, are under the control
+of, or are under common control with that organization. **Control** means ownership of
+substantially all the assets of an entity, or the power to direct its management and
+policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.
+
+**Trademark** means trademarks, service marks, and similar rights.
+

package/README.md

@@ -0,0 +1,113 @@
+# aiDimag
+
+> Persistent, verified memory for AI coding agents. CLI: **`dim`**.
+
+aiDimag gives any MCP-compatible agent (Claude Code, Cursor, Copilot, …) a memory of your
+codebase that survives across sessions — decisions, conventions, gotchas, failed approaches,
+**guardrails**, and reusable **skills** — stored as **falsifiable claims with grounding
+evidence** in `.aidimag/` next to your code. It also generates the static context files
+(`CLAUDE.md`, `.cursorrules`, …) that *non-MCP* tools read, so every AI tool benefits.
+
+What makes it different: **memories are verified, not just stored.** Every memory carries
+evidence (a shell check, an anchored commit, a test) that `dim verify` re-runs against the
+current repo — beliefs that stop being true go **STALE** instead of silently misleading
+your AI.
+
+## Install
+
+```sh
+npm install -g aidimag
+```
+
+Requires Node 18+. Ships two equivalent binaries: `dim` (short) and `aidimag`.
+
+## Quick start
+
+```sh
+cd your-repo
+dim init                    # creates .aidimag/, installs additive git hooks
+dim bootstrap               # optional: LLM-survey the repo into a starter memory set
+dim review                  # approve what enters memory (nothing is stored unreviewed)
+
+dim remember "All DB access goes through src/db/store.ts" -k INVARIANT -p src/db \
+  -e "STATIC_CHECK:grep -rL better-sqlite3 src --include=*.ts"
+dim recall db access
+dim verify                  # re-run all evidence; stale beliefs get flagged
+dim brief                   # session-start briefing: in-scope memory, guardrails, gaps
+
+# For non-MCP tools (Copilot, Cursor without MCP, etc.):
+dim generate-context --format all --auto   # creates .cursorrules, CLAUDE.md, copilot-instructions.md
+```
+
+## Hook it up to your AI agent (MCP)
+
+Add to your agent config (e.g. `.mcp.json` for Claude Code):
+
+```json
+{
+  "mcpServers": {
+    "aidimag": {
+      "command": "npx",
+      "args": ["-y", "aidimag", "mcp"],
+      "env": { "AIDIMAG_REPO": "/path/to/your/repo" }
+    }
+  }
+}
+```
+
+Agents get `memory_search`, `memory_propose`, `context_note` (live in-chat fact capture),
+`memory_critique` (a second critic grounded in verified memory), session-start briefings,
+session-end extraction, and more. For non-MCP tools, `dim generate-context -f all` renders
+verified memory into `CLAUDE.md` / `.cursorrules` / `.github/copilot-instructions.md`
+(`--auto` keeps them refreshed).
+
+## Highlights
+
+- **Human-gated capture** — commits, PRs, AI-chat transcripts, and pasted docs are mined
+  into *proposals*; nothing enters memory until you approve it in `dim review`
+  (auto-triaged best-first, `approve all --min-score 0.7` for batches).
+- **Verification lifecycle** — `STATIC_CHECK` / `COMMIT_REF` / `TEST_RESULT` /
+  `EXEC_TRACE` / `HUMAN_ATTESTED` evidence; failing evidence flips memories to STALE and
+  auto-drafts a recovery proposal. Confidence decays without re-confirmation.
+- **Evidence trust gate** — shell-command evidence that arrives via team sync is **never
+  executed** until you inspect and approve it (`dim verify --trust`).
+- **Hybrid semantic recall** — FTS5 keyword + vector KNN (OpenAI or local Ollama,
+  auto-detected; works keyword-only with neither).
+- **Guardrails & skills** — behavioral rules (`never` / `ask-first` / `always`) and
+  step-by-step procedures, enforced by `dim check` (pre-commit) and `memory_critique`.
+- **Team mode, self-hosted** — `dim serve` + `dim sync`: local-first replicas, device-code
+  login, brain-scoped API keys, hashed credentials, cross-machine verification consensus.
+- **Knowledgebase inbox** — drop design docs / ADRs / PDFs / DOCX into `knowledge/` and
+  they're summarized into reviewed, pinned memories.
+- **Web dashboard** (`dim ui`) plus [VS Code](https://github.com/anupkhanal/aidimag/tree/main/vscode-extension) and
+  [IntelliJ](https://github.com/anupkhanal/aidimag/tree/main/intellij-plugin) extensions.
+
+## Documentation
+
+Full documentation available at: **[github.com/anupkhanal/aidimag](https://github.com/anupkhanal/aidimag)**
+
+- [Getting Started](https://github.com/anupkhanal/aidimag/blob/main/docs/getting-started.md)
+- [Quick Start](https://github.com/anupkhanal/aidimag/blob/main/docs/quickstart.md)
+- [CLI Reference](https://github.com/anupkhanal/aidimag/blob/main/docs/cli-reference.md)
+- [MCP Integration](https://github.com/anupkhanal/aidimag/blob/main/docs/mcp.md)
+- [Team Sync Guide](https://github.com/anupkhanal/aidimag/blob/main/docs/guides/team-sync.md)
+- [Configuration](https://github.com/anupkhanal/aidimag/blob/main/docs/configuration.md)
+
+## Development
+
+```sh
+npm install
+npm run build       # tsc → dist/
+npm test            # node --test (builds first)
+```
+
+Self-hosted sync deployment (Docker / Fly.io): [deploy/](https://github.com/anupkhanal/aidimag/tree/main/deploy).
+
+## Author
+
+**Anup Khanal**
+
+## License
+
+[Elastic License 2.0](./LICENSE) — free for teams of 10 or fewer users. Commercial license required for larger organizations. Cannot be offered as a managed service to third parties. See [pricing & licensing](docs/pricing.md) for details.
+

package/dist/capture/bootstrap.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `dim bootstrap` — instant brain on day one (kills the cold-start problem).
+ *
+ * Surveys the repo (README/docs/ADRs, manifests, directory shape, git churn)
+ * and LLM-extracts an initial set of falsifiable memory candidates, each with
+ * a suggested STATIC_CHECK where one makes sense. Everything lands in the
+ * proposal queue (source `bootstrap`) — `dim review` remains the trust gate.
+ */
+import type { MemoryStore } from "../db/store.js";
+export interface BootstrapResult {
+    proposed: number;
+    duplicates: number;
+    provider: string | null;
+    surveyedFiles: string[];
+    alreadyBootstrapped: boolean;
+}
+/** Top-level directory listing, two levels deep — enough shape without noise. */
+export declare function surveyTree(repoRoot: string): string;
+/** Most-changed files in recent history — where the action (and the gotchas) live. */
+export declare function surveyChurn(repoRoot: string, maxCommits?: number, top?: number): string;
+export declare const BOOTSTRAP_INSTRUCTIONS = "You are bootstrapping a \"repo brain\" for an AI coding assistant memory system. Below is a survey of a codebase: its docs, manifests, directory shape, and most-changed files.\n\nExtract the durable, project-specific knowledge as FALSIFIABLE claims. Rules:\n\n1. Only facts THIS survey supports \u2014 architecture, conventions, decisions, invariants, build/deploy procedures (SKILL), behavioral rules (GUARDRAIL with guardrail_level never|ask-first|always). Do NOT invent or pad; skip anything generic (\"uses TypeScript\" is useless unless there's a rule attached).\n2. Write each claim as a checkable statement scoped with paths when the survey names them.\n3. Where possible, include \"static_check\": a cheap shell command (grep/test/ls) that exits 0 iff the claim holds. Omit it when no honest check exists.\n4. kinds: DECISION, CONVENTION, GOTCHA, FAILED_APPROACH, ARCHITECTURE, INVARIANT, GUARDRAIL, SKILL, TODO_CONTEXT.\n5. Extract 5\u201330 claims depending on how much real signal exists. Quality over quantity.\n\nRespond with ONLY a JSON object:\n{\"claims\":[{\"kind\":\"ARCHITECTURE\",\"claim\":\"...\",\"paths\":[\"src/x\"],\"symbols\":[],\"guardrail_level\":null,\"rationale\":\"from README section ...\",\"static_check\":\"test -f src/x/index.ts\"}]}";
+/** Turn a repo survey into an initial proposal set. */
+export declare function bootstrapRepo(store: MemoryStore, repoRoot: string, opts?: {
+    force?: boolean;
+}): Promise<BootstrapResult>;

package/dist/capture/bootstrap.js

@@ -0,0 +1,188 @@
+/**
+ * `dim bootstrap` — instant brain on day one (kills the cold-start problem).
+ *
+ * Surveys the repo (README/docs/ADRs, manifests, directory shape, git churn)
+ * and LLM-extracts an initial set of falsifiable memory candidates, each with
+ * a suggested STATIC_CHECK where one makes sense. Everything lands in the
+ * proposal queue (source `bootstrap`) — `dim review` remains the trust gate.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { getTextProvider } from "../knowledge/llm.js";
+import { parseClaims } from "../knowledge/extract.js";
+const BOOTSTRAP_DONE_KEY = "bootstrap_done_at";
+const MAX_DOC_CHARS = 12_000;
+const MAX_TOTAL_CHARS = 48_000;
+/** Files worth reading whole (truncated) for the survey. */
+const DOC_CANDIDATES = [
+    "README.md", "readme.md", "ARCHITECTURE.md", "DESIGN.md", "CONTRIBUTING.md",
+    "docs/architecture.md", "docs/adr", "adr", "docs/decisions",
+];
+const MANIFEST_CANDIDATES = [
+    "package.json", "pyproject.toml", "go.mod", "Cargo.toml", "pom.xml",
+    "build.gradle", "build.gradle.kts", "Gemfile", "composer.json", "Makefile",
+    "docker-compose.yml", "Dockerfile", ".github/workflows",
+];
+function git(repoRoot, args) {
+    try {
+        return execFileSync("git", args, { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    }
+    catch {
+        return "";
+    }
+}
+function readCapped(abs) {
+    try {
+        return readFileSync(abs, "utf8").slice(0, MAX_DOC_CHARS);
+    }
+    catch {
+        return "";
+    }
+}
+/** Top-level directory listing, two levels deep — enough shape without noise. */
+export function surveyTree(repoRoot) {
+    const lines = [];
+    const skip = new Set(["node_modules", ".git", "dist", "build", ".aidimag", "coverage", "target", ".idea", ".vscode"]);
+    const walk = (dir, depth, prefix) => {
+        if (depth > 2)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir).filter((e) => !skip.has(e) && !e.startsWith("."));
+        }
+        catch {
+            return;
+        }
+        for (const e of entries.slice(0, 30)) {
+            const abs = path.join(dir, e);
+            let isDir = false;
+            try {
+                isDir = statSync(abs).isDirectory();
+            }
+            catch {
+                continue;
+            }
+            lines.push(`${prefix}${e}${isDir ? "/" : ""}`);
+            if (isDir)
+                walk(abs, depth + 1, prefix + "  ");
+        }
+    };
+    walk(repoRoot, 1, "");
+    return lines.join("\n");
+}
+/** Most-changed files in recent history — where the action (and the gotchas) live. */
+export function surveyChurn(repoRoot, maxCommits = 300, top = 15) {
+    const raw = git(repoRoot, ["log", `--max-count=${maxCommits}`, "--name-only", "--pretty=format:"]);
+    const counts = new Map();
+    for (const f of raw.split("\n").map((l) => l.trim()).filter(Boolean)) {
+        counts.set(f, (counts.get(f) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, top)
+        .map(([f, n]) => `${n}× ${f}`)
+        .join("\n");
+}
+function collectDocs(repoRoot) {
+    const out = [];
+    for (const cand of DOC_CANDIDATES) {
+        const abs = path.join(repoRoot, cand);
+        if (!existsSync(abs))
+            continue;
+        if (statSync(abs).isDirectory()) {
+            for (const f of readdirSync(abs).filter((f) => f.endsWith(".md")).slice(0, 5)) {
+                out.push({ file: path.join(cand, f), content: readCapped(path.join(abs, f)) });
+            }
+        }
+        else {
+            out.push({ file: cand, content: readCapped(abs) });
+        }
+    }
+    for (const cand of MANIFEST_CANDIDATES) {
+        const abs = path.join(repoRoot, cand);
+        if (!existsSync(abs) || statSync(abs).isDirectory())
+            continue;
+        out.push({ file: cand, content: readCapped(abs).slice(0, 4_000) });
+    }
+    // existing hand-written AI context files are pre-distilled knowledge — gold
+    for (const cand of ["CLAUDE.md", ".cursorrules", ".github/copilot-instructions.md"]) {
+        const abs = path.join(repoRoot, cand);
+        if (existsSync(abs) && !statSync(abs).isDirectory())
+            out.push({ file: cand, content: readCapped(abs) });
+    }
+    return out;
+}
+export const BOOTSTRAP_INSTRUCTIONS = `You are bootstrapping a "repo brain" for an AI coding assistant memory system. Below is a survey of a codebase: its docs, manifests, directory shape, and most-changed files.
+
+Extract the durable, project-specific knowledge as FALSIFIABLE claims. Rules:
+
+1. Only facts THIS survey supports — architecture, conventions, decisions, invariants, build/deploy procedures (SKILL), behavioral rules (GUARDRAIL with guardrail_level never|ask-first|always). Do NOT invent or pad; skip anything generic ("uses TypeScript" is useless unless there's a rule attached).
+2. Write each claim as a checkable statement scoped with paths when the survey names them.
+3. Where possible, include "static_check": a cheap shell command (grep/test/ls) that exits 0 iff the claim holds. Omit it when no honest check exists.
+4. kinds: DECISION, CONVENTION, GOTCHA, FAILED_APPROACH, ARCHITECTURE, INVARIANT, GUARDRAIL, SKILL, TODO_CONTEXT.
+5. Extract 5–30 claims depending on how much real signal exists. Quality over quantity.
+
+Respond with ONLY a JSON object:
+{"claims":[{"kind":"ARCHITECTURE","claim":"...","paths":["src/x"],"symbols":[],"guardrail_level":null,"rationale":"from README section ...","static_check":"test -f src/x/index.ts"}]}`;
+/** Turn a repo survey into an initial proposal set. */
+export async function bootstrapRepo(store, repoRoot, opts = {}) {
+    const result = {
+        proposed: 0,
+        duplicates: 0,
+        provider: null,
+        surveyedFiles: [],
+        alreadyBootstrapped: false,
+    };
+    if (!opts.force && store.getMeta(BOOTSTRAP_DONE_KEY)) {
+        result.alreadyBootstrapped = true;
+        return result;
+    }
+    const provider = await getTextProvider();
+    if (!provider)
+        return result;
+    result.provider = `${provider.name}/${provider.model}`;
+    const docs = collectDocs(repoRoot);
+    result.surveyedFiles = docs.map((d) => d.file);
+    const sections = [];
+    sections.push(`## Directory shape\n${surveyTree(repoRoot)}`);
+    const churn = surveyChurn(repoRoot);
+    if (churn)
+        sections.push(`## Most-changed files (recent history)\n${churn}`);
+    for (const d of docs) {
+        if (sections.join("\n").length > MAX_TOTAL_CHARS)
+            break;
+        sections.push(`## File: ${d.file}\n${d.content}`);
+    }
+    let claims = [];
+    try {
+        const raw = await provider.generate(BOOTSTRAP_INSTRUCTIONS, sections.join("\n\n").slice(0, MAX_TOTAL_CHARS));
+        claims = parseClaims(raw);
+    }
+    catch {
+        return result; // provider hiccup — bootstrap can simply be re-run
+    }
+    for (const c of claims) {
+        const evidence = [];
+        if (c.staticCheck)
+            evidence.push({ type: "STATIC_CHECK", payload: c.staticCheck });
+        const p = store.propose({
+            kind: c.kind,
+            claim: c.claim,
+            paths: c.paths,
+            symbols: c.symbols,
+            guardrailLevel: c.guardrailLevel,
+            evidence: evidence.length ? evidence : undefined,
+            rationale: c.rationale ?? "Extracted by repo bootstrap survey.",
+            source: "bootstrap",
+            sourceRef: "initial-survey",
+        });
+        if (p)
+            result.proposed++;
+        else
+            result.duplicates++;
+    }
+    store.setMeta(BOOTSTRAP_DONE_KEY, new Date().toISOString());
+    return result;
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/capture/commit-miner.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Commit miner (Phase 2 capture pipeline).
+ *
+ * Walks git history since the last mined commit and heuristically extracts
+ * memory-worthy candidates from commit messages + touched files. Candidates
+ * land in the proposal queue (human-in-the-loop) — never directly in memory.
+ *
+ * Each proposal is anchored with COMMIT_REF evidence so Phase 3 verification
+ * can re-check it against history.
+ */
+import type { MemoryKind, Proposal } from "../types.js";
+import type { MemoryStore } from "../db/store.js";
+export interface MinedCommit {
+    sha: string;
+    subject: string;
+    body: string;
+    files: string[];
+}
+export interface MineResult {
+    scanned: number;
+    proposed: Proposal[];
+    skippedDuplicates: number;
+    lastSha: string | null;
+    /** True when the repo is a git repo but has no commits yet (HEAD does not exist). */
+    noCommits?: boolean;
+    /** True when incremental mining found no commits newer than the stored cursor. */
+    noNewCommits?: boolean;
+}
+/** False when the repo is initialized but has no commits yet (no HEAD). */
+export declare function hasGitCommits(repoRoot: string): boolean;
+export declare function readCommits(repoRoot: string, sinceSha: string | null, maxCommits?: number): MinedCommit[];
+export declare function classifyCommit(c: MinedCommit): {
+    kind: MemoryKind;
+    matched: string;
+} | null;
+/** Reduce touched files to a few representative scope paths (common directories). */
+export declare function scopeFromFiles(files: string[], maxPaths?: number): string[];
+export declare function mineCommits(store: MemoryStore, repoRoot: string, opts?: {
+    maxCommits?: number;
+    full?: boolean;
+}): MineResult;
+export declare const COMMIT_EXTRACT_INSTRUCTIONS = "You are mining a git commit for durable, project-specific knowledge worth remembering across AI coding sessions: decisions (and rejected alternatives), conventions, gotchas, failed approaches, invariants, architecture facts.\n\nRules:\n1. Most commits contain NOTHING durable \u2014 routine features/fixes/refactors. Return zero claims for those. Do NOT invent.\n2. When there IS signal, SYNTHESIZE a falsifiable claim about the codebase \u2014 do not parrot the commit message. Bad: \"A decision was made: use Redis\". Good: \"Rate limiting uses Redis (src/limits); the in-memory limiter was abandoned because multi-instance deploys need shared counters\".\n3. Use the DIFF, not just the message \u2014 renamed modules, deleted approaches, and added config tell the real story.\n4. kinds: DECISION, CONVENTION, GOTCHA, FAILED_APPROACH, ARCHITECTURE, INVARIANT, GUARDRAIL (guardrail_level never|ask-first|always), SKILL, TODO_CONTEXT.\n5. Scope with the touched paths; add \"static_check\" (cheap shell command, exit 0 iff true) when an honest one exists.\n6. 0\u20132 claims per commit. Zero is the common case.\n\nRespond with ONLY: {\"claims\":[{\"kind\":\"DECISION\",\"claim\":\"...\",\"paths\":[\"src/x\"],\"symbols\":[],\"guardrail_level\":null,\"rationale\":\"...\",\"static_check\":null}]}";
+/**
+ * LLM-powered deep mining: reads message + diff, synthesizes claims with
+ * suggested STATIC_CHECKs. Requires a text provider (OpenAI/Ollama); the
+ * caller falls back to regex mining when none is available. Same cursor as
+ * regex mining — the two modes are alternatives over the same history.
+ */
+export declare function mineCommitsLlm(store: MemoryStore, repoRoot: string, opts?: {
+    maxCommits?: number;
+    full?: boolean;
+}): Promise<MineResult & {
+    provider: string | null;
+}>;
+/** Human-readable summary of a mine run (CLI + MCP). */
+export declare function describeMineResult(r: MineResult, opts?: {
+    llmProvider?: string | null;
+    llmRequested?: boolean;
+}): string;