@fingerskier/augment 0.4.0 → 0.5.1

package/integrations/pi/skills/augment-decoction/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: augment-decoction
+description: Distill recurring cross-project Augment memory into generic SPEC/ARCH records and optionally remove fully subsumed originals from Pi. Use when the user asks to "decoct", "glean", generalize, or clean up repeated memories across projects.
+---
+
+# Augment Decoction for Pi
+
+Decoction extracts durable, project-independent knowledge from recurring
+memories. It is separate from sleep: sleep consolidates settled work within one
+project, while decoction finds patterns across projects and writes them under
+`.generic/`.
+
+1. Call `augment_decoction_glean` with `action: "discover"`. If no cluster
+   spans at least four distinct projects, report that and stop.
+2. Pick a cluster and call `augment_read_memory` for every source. Synthesize
+   one generic record:
+   - use SPEC for a reusable contract or rule;
+   - use ARCH for a reusable decision or tradeoff;
+   - retain only claims supported across the projects;
+   - put every source used in `derived_from`.
+3. Suggest source removal only when the generic preserves the original's entire
+   durable content. Do not suggest a source that also contains project-specific
+   facts, history, caveats, or unresolved work.
+4. Call `augment_decoction_glean` with `action: "write"`, the complete draft,
+   and the reasoned `suggested_removals`. For an existing generic, read it fresh
+   and pass both of its expected hashes.
+5. Report the generic path and any warnings. Warnings are advisory and do not
+   block the write.
+6. Show each suggested cleanup path and reason verbatim. Ask for explicit user
+   approval of the exact paths; never infer approval from approval of the
+   generic itself.
+7. Only after approval, call `augment_decoction_cleanup` with the generic path
+   and the approved source paths. Report every deletion and any failure.
+
+Cleanup hard-deletes the selected originals after retargeting inbound links to
+the generic. It has no journal or rollback. The user may approve a subset or
+decline cleanup entirely.

package/integrations/pi/skills/augment-dream/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: augment-dream
+description: Explore globally recalled Augment memories and propose speculative memories or links for explicit user approval. Use when the user asks to "dream" over memory, imagine hypotheses, or surface hidden connections across the current, generic, or foreign projects.
+---
+
+# Augment Dream
+
+Dreams are hypotheses, not established facts. Discover and draft freely, but
+never mutate the corpus before the user explicitly approves a named proposal.
+Use a real project as the active project; `.generic` is inspiration or a link
+target only.
+
+1. Call `augment_search` separately for each exploratory query, always passing
+   the active `project_name` and singular `query` argument. Use normal global
+   results as ranked: the current project receives its normal priority, while
+   generic and foreign memories remain eligible. Do not reserve a generic
+   quota or add a generic fallback.
+2. Call `augment_read_memory` with each useful result's numeric memory id, and
+   retain its returned relative path for provenance. Imagine 1-5 coherent
+   candidates:
+   - dream memory: a new record in the active project, with `derived_from`
+     equal to the exact inspiration paths;
+   - dream link: a link from an active-project memory to any current, generic,
+     or foreign memory.
+   Generic-only and foreign-only inspiration are valid.
+3. Call `augment_dream_propose` for each worthwhile candidate. State the
+   speculation plainly in the content and rationale; do not present it as
+   settled truth.
+4. Show each proposal to the user. Only after explicit approval call
+   `augment_dream_apply` with its filename. Call `augment_dream_reject` when
+   the user rejects it. If approval is unclear, leave the proposal pending.
+5. Report the applied speculative memory or link and its `dream:` commit.
+
+Keep evidence and conjecture distinguishable. Do not invent supporting source
+paths, and do not rewrite a foreign memory: foreign projects are inspiration
+and link targets only.

package/package.json

@@ -1,84 +1,85 @@
-{
-  "name": "@fingerskier/augment",
-  "version": "0.4.0",
-  "description": "Local RAG memory system for coding agents",
-  "keywords": [
-    "pi-package",
-    "pi",
-    "opencode",
-    "memory",
-    "rag",
-    "mcp",
-    "coding-agent"
-  ],
-  "type": "module",
-  "main": "./dist/opencode/plugin.js",
-  "types": "./dist/opencode/plugin.d.ts",
-  "publishConfig": {
-    "access": "public"
-  },
-  "bin": {
-    "augment": "./dist/bin/augment.js",
-    "augment-daemon": "./dist/bin/augment-daemon.js",
-    "augment-mcp": "./dist/bin/augment-mcp.js"
-  },
-  "pi": {
-    "extensions": [
-      "./dist/pi/extension.js"
-    ],
-    "skills": [
-      "./integrations/pi/skills"
-    ]
-  },
-  "files": [
-    "dist",
-    "docs",
-    "integrations",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "node --import tsx --test \"test/**/*.test.ts\"",
-    "test:model": "node --import tsx --import ./test/setup-real-model.mjs --test \"test/**/*.model.ts\"",
-    "check": "npm run build && npm test",
-    "prepack": "npm run check",
-    "prepublishOnly": "npm run check"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "typebox": "*"
-  },
-  "peerDependenciesMeta": {
-    "@earendil-works/pi-ai": {
-      "optional": true
-    },
-    "@earendil-works/pi-coding-agent": {
-      "optional": true
-    },
-    "typebox": {
-      "optional": true
-    }
-  },
-  "dependencies": {
-    "@huggingface/transformers": "^3.8.0",
-    "@libsql/client": "^0.15.15",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "chokidar": "^4.0.3",
-    "cytoscape": "^3.34.0",
-    "gray-matter": "^4.0.3",
-    "zod": "^3.25.76"
-  },
-  "devDependencies": {
-    "@opencode-ai/plugin": "^1.17.15",
-    "@types/node": "^24.3.0",
-    "tsx": "^4.20.5",
-    "typebox": "^1.1.38",
-    "typescript": "^5.9.2"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "license": "Apache-2.0"
-}
+{
+  "name": "@fingerskier/augment",
+  "version": "0.5.1",
+  "description": "Local RAG memory system for coding agents",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "opencode",
+    "memory",
+    "rag",
+    "mcp",
+    "coding-agent"
+  ],
+  "type": "module",
+  "main": "./dist/opencode/plugin.js",
+  "types": "./dist/opencode/plugin.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "augment": "./dist/bin/augment.js",
+    "augment-daemon": "./dist/bin/augment-daemon.js",
+    "augment-mcp": "./dist/bin/augment-mcp.js"
+  },
+  "pi": {
+    "extensions": [
+      "./dist/pi/extension.js"
+    ],
+    "skills": [
+      "./integrations/pi/skills"
+    ]
+  },
+  "files": [
+    "dist",
+    "docs",
+    "integrations",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "node --eval \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "test": "node --import tsx --test \"test/**/*.test.ts\"",
+    "test:model": "node --import tsx --import ./test/setup-real-model.mjs --test \"test/**/*.model.ts\"",
+    "check": "npm run build && npm test",
+    "prepack": "npm run check",
+    "prepublishOnly": "npm run check"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^3.8.0",
+    "@libsql/client": "^0.15.15",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "chokidar": "^4.0.3",
+    "cytoscape": "^3.34.0",
+    "gray-matter": "^4.0.3",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.17.15",
+    "@types/node": "^24.3.0",
+    "tsx": "^4.20.5",
+    "typebox": "^1.1.38",
+    "typescript": "^5.9.2"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "Apache-2.0"
+}

package/dist/tally.d.ts

@@ -1,46 +0,0 @@
-/**
- * Phase-2 dogfood tally (council 2026-06-30): ~30 human-scored datapoints over
- * ~2 weeks of real use, per injection surface, never a CI gate. Data lives as
- * JSONL under `<stateDir>/tally/` — deliberately OUTSIDE the memory corpus so
- * the corpus Phase 2 measures stays clean.
- */
-export declare const TALLY_TARGET = 30;
-export declare const TALLY_VERDICTS: readonly ["helpful", "harmless", "harmful", "correct-abstention"];
-export type TallyVerdict = (typeof TALLY_VERDICTS)[number];
-/** One human rating of a recall outcome. */
-export interface TallyRating {
-    ts: string;
-    verdict: TallyVerdict;
-    /** Injection surface being rated: user-prompt-submit | pre-tool-use | mcp-search | cli-recall | unknown. */
-    surface: string;
-    note?: string;
-}
-/** One automatically-logged injection event (what search actually returned). */
-export interface TallyEvent {
-    ts: string;
-    surface: string;
-    project?: string;
-    /** Query text, truncated by the writer — context for later audit, not for ranking. */
-    query: string;
-    abstained: boolean;
-    result_count: number;
-    top_score?: number;
-    /** Durable relative paths of the memories injected. */
-    paths: string[];
-}
-export interface TallySummary {
-    total: number;
-    target: number;
-    by_verdict: Record<TallyVerdict, number>;
-    by_surface: Record<string, number>;
-    first_at?: string;
-    last_at?: string;
-}
-export declare function isTallyVerdict(value: unknown): value is TallyVerdict;
-export declare function ratingsPath(stateDir: string): string;
-export declare function eventsPath(stateDir: string): string;
-export declare function appendTallyRating(stateDir: string, rating: TallyRating): Promise<void>;
-export declare function appendTallyEvent(stateDir: string, event: TallyEvent): Promise<void>;
-export declare function readTallyRatings(stateDir: string): Promise<TallyRating[]>;
-export declare function summarizeTally(ratings: TallyRating[]): TallySummary;
-export declare function renderTallySummary(summary: TallySummary): string;

package/dist/tally.js

@@ -1,94 +0,0 @@
-import { appendFile, mkdir, readFile } from "node:fs/promises";
-import path from "node:path";
-/**
- * Phase-2 dogfood tally (council 2026-06-30): ~30 human-scored datapoints over
- * ~2 weeks of real use, per injection surface, never a CI gate. Data lives as
- * JSONL under `<stateDir>/tally/` — deliberately OUTSIDE the memory corpus so
- * the corpus Phase 2 measures stays clean.
- */
-export const TALLY_TARGET = 30;
-export const TALLY_VERDICTS = ["helpful", "harmless", "harmful", "correct-abstention"];
-export function isTallyVerdict(value) {
-    return typeof value === "string" && TALLY_VERDICTS.includes(value);
-}
-export function ratingsPath(stateDir) {
-    return path.join(stateDir, "tally", "ratings.jsonl");
-}
-export function eventsPath(stateDir) {
-    return path.join(stateDir, "tally", "events.jsonl");
-}
-async function appendLine(file, record) {
-    await mkdir(path.dirname(file), { recursive: true });
-    await appendFile(file, `${JSON.stringify(record)}\n`, "utf8");
-}
-export async function appendTallyRating(stateDir, rating) {
-    await appendLine(ratingsPath(stateDir), rating);
-}
-export async function appendTallyEvent(stateDir, event) {
-    await appendLine(eventsPath(stateDir), event);
-}
-export async function readTallyRatings(stateDir) {
-    let raw;
-    try {
-        raw = await readFile(ratingsPath(stateDir), "utf8");
-    }
-    catch {
-        return [];
-    }
-    const ratings = [];
-    for (const line of raw.split("\n")) {
-        if (!line.trim()) {
-            continue;
-        }
-        try {
-            const parsed = JSON.parse(line);
-            if (isTallyVerdict(parsed.verdict)) {
-                ratings.push(parsed);
-            }
-        }
-        catch {
-            // A corrupt line loses one datapoint, never the tally.
-        }
-    }
-    return ratings;
-}
-export function summarizeTally(ratings) {
-    const by_verdict = {
-        helpful: 0,
-        harmless: 0,
-        harmful: 0,
-        "correct-abstention": 0,
-    };
-    const by_surface = {};
-    for (const rating of ratings) {
-        by_verdict[rating.verdict] += 1;
-        by_surface[rating.surface || "unknown"] = (by_surface[rating.surface || "unknown"] ?? 0) + 1;
-    }
-    return {
-        total: ratings.length,
-        target: TALLY_TARGET,
-        by_verdict,
-        by_surface,
-        ...(ratings.length > 0
-            ? { first_at: ratings[0].ts, last_at: ratings[ratings.length - 1].ts }
-            : {}),
-    };
-}
-export function renderTallySummary(summary) {
-    const lines = [
-        `Dogfood tally: ${summary.total}/${summary.target} datapoints`,
-        `  helpful: ${summary.by_verdict.helpful}  harmless: ${summary.by_verdict.harmless}  ` +
-            `harmful: ${summary.by_verdict.harmful}  correct-abstention: ${summary.by_verdict["correct-abstention"]}`,
-    ];
-    const surfaces = Object.entries(summary.by_surface)
-        .map(([surface, count]) => `${surface}:${count}`)
-        .join("  ");
-    if (surfaces) {
-        lines.push(`  by surface: ${surfaces}`);
-    }
-    if (summary.first_at && summary.last_at) {
-        lines.push(`  window: ${summary.first_at} .. ${summary.last_at}`);
-    }
-    return lines.join("\n");
-}
-//# sourceMappingURL=tally.js.map

package/dist/tally.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"tally.js","sourceRoot":"","sources":["../src/tally.ts"],"names":[],"mappings":"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"}