akm-cli 0.9.0-beta.27 → 0.9.0-beta.28

package/CHANGELOG.md

@@ -6,6 +6,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.0-beta.28] — 2026-06-20
+
+### Added
+
+- **#630 — `fact` asset type phase 2: pinned-core assembly + `akm fact` CLI.**
+  Phase 1 (#629) added the `fact` type; phase 2 delivers the "pinned core +
+  just-in-time retrieval" model. `collectPinnedFacts()` reads `fact` entries from
+  the index (pre-filtered on the `pinned` search hint), excludes
+  `stale`/`superseded`/`archived` facts from the core (they stay searchable), and
+  **fails soft** — a missing index or unreadable file yields an empty list, so
+  collection never blocks a dispatch. `buildPinnedFactsBlock()` assembles a
+  deterministic, category-grouped `## Stash facts` block, and `akm agent`
+  prepends it to the system prompt for user-facing runs (only when a task or agent
+  asset is present; bare interactive launches stay clean; opt out with
+  `--no-facts`). New `akm fact` CLI: `add <name> [body] --category <c> [--pinned]`
+  (hot-capture à la `akm remember`), `list [--category] [--pinned]`, and `context`
+  (print the assembled pinned core). Design note: `docs/design/fact-asset-type.md`.
+
 ## [0.9.0-beta.27] — 2026-06-20
 
 All new behavior is **opt-in / default-preserving** — default runs are byte-identical.

package/dist/cli.js

@@ -63,6 +63,7 @@ import { generateBashCompletions, installBashCompletions } from "./commands/comp
 import { configCommand } from "./commands/config-cli.js";
 import { envCommand } from "./commands/env/env-cli.js";
 import { secretCommand } from "./commands/env/secret-cli.js";
+import { factCommand } from "./commands/fact/fact-cli.js";
 import { feedbackCommand } from "./commands/feedback-cli.js";
 import { graphCommand } from "./commands/graph/graph-cli.js";
 import { akmHealth, parseWindowSpec, renderRunsDetailMd, renderWindowCompareMd, } from "./commands/health.js";
@@ -519,6 +520,7 @@ export const main = defineCommand({
         secret: secretCommand,
         wiki: wikiCommand,
         tasks: tasksCommand,
+        fact: factCommand,
     },
 });
 // ── Exit codes ──────────────────────────────────────────────────────────────

package/dist/commands/agent/contribute-cli.js

@@ -29,6 +29,7 @@ import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "
 import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { getHyphenatedArg } from "../../output/context.js";
+import { buildPinnedFactsContext } from "../fact/fact-context.js";
 import { akmLint } from "../lint.js";
 import { akmPropose } from "../proposal/propose.js";
 import { akmAgentDispatch } from "./agent-dispatch.js";
@@ -57,6 +58,11 @@ export const agentCommand = defineCommand({
             description: "Model override — accepts aliases (opus, sonnet, haiku) or exact platform model IDs. Overrides the model specified in the agent asset.",
         },
         "timeout-ms": { type: "string", description: "Override the agent CLI timeout in milliseconds" },
+        "no-facts": {
+            type: "boolean",
+            description: "Do not prepend the pinned stash facts (fact: assets with `pinned: true`) to the system prompt",
+            default: false,
+        },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
@@ -85,6 +91,20 @@ export const agentCommand = defineCommand({
             const promptText = getStringArg(args, "prompt");
             const commandRef = getStringArg(args, "command");
             const workflowRef = getStringArg(args, "workflow");
+            // Phase 2: prepend the pinned-fact "core" (fact assets with
+            // `pinned: true`) to the system prompt for user-facing agent runs, so
+            // durable stash facts and conventions are always in context. Only injects
+            // when there is actually a task or agent asset — bare interactive launches
+            // (`akm agent claude`) stay clean. Opt out with --no-facts. Fails soft:
+            // buildPinnedFactsContext never throws, so fact collection can't block a
+            // dispatch.
+            if (getHyphenatedArg(args, "no-facts") !== true &&
+                (promptText ?? commandRef ?? workflowRef ?? agentRef)) {
+                const factsBlock = buildPinnedFactsContext();
+                if (factsBlock) {
+                    systemPrompt = systemPrompt ? `${factsBlock}\n\n${systemPrompt}` : factsBlock;
+                }
+            }
             // Only build a dispatch request when there is something to dispatch — a
             // prompt, an agent asset, or a model override. When none of these are
             // present the agent is launched interactively (no injected prompt, no

package/dist/commands/fact/fact-cli.js

@@ -0,0 +1,155 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * `akm fact` — manage durable stash-level facts (the `fact` asset type, phase 2).
+ *
+ * Subcommands:
+ *   - `add <name> [content]` — hot-capture a fact (à la `akm remember`), writing
+ *     `facts/<category>/<name>.md` with `category` + optional `pinned`.
+ *   - `list` — list indexed facts, optionally filtered by `--category` / `--pinned`.
+ *   - `context` — print the assembled "pinned core" block (the same block the
+ *     `akm agent` dispatch prepends to a system prompt). Useful for previewing
+ *     or piping into an AGENTS.md / CLAUDE.md.
+ */
+import { defineCommand } from "citty";
+import { defineJsonCommand, output } from "../../cli/shared.js";
+import { serializeFrontmatter } from "../../core/asset/asset-serialize.js";
+import { toErrorMessage, tryReadStdinText } from "../../core/common.js";
+import { UsageError } from "../../core/errors.js";
+import { appendEvent } from "../../core/events.js";
+import { closeDatabase, getAllEntries, openExistingDatabase } from "../../indexer/db/db.js";
+import { assertFlatAssetName, writeMarkdownAsset } from "../read/knowledge.js";
+import { buildPinnedFactsBlock, collectPinnedFacts } from "./fact-context.js";
+/** Recommended categories (mirrors the fact linter). Free values are allowed but linted. */
+const KNOWN_CATEGORIES = ["personal", "team", "project", "convention", "meta"];
+function buildFactFrontmatter(fields) {
+    const obj = { category: fields.category };
+    if (fields.description?.trim())
+        obj.description = fields.description.trim();
+    if (fields.pinned)
+        obj.pinned = true;
+    obj.updated = new Date().toISOString().slice(0, 10);
+    return `---\n${serializeFrontmatter(obj)}\n---`;
+}
+const addCommand = defineJsonCommand({
+    meta: { name: "add", description: "Record a durable stash fact (facts/<category>/<name>.md)" },
+    args: {
+        name: {
+            type: "positional",
+            description: "Fact name (flat, no '/'; use --category for the subdirectory)",
+            required: false,
+        },
+        content: { type: "positional", description: "Fact body. Omit to read markdown from stdin.", required: false },
+        category: {
+            type: "string",
+            description: `Fact category — scopes the fact (one of: ${KNOWN_CATEGORIES.join(", ")}; free values allowed but linted)`,
+        },
+        pinned: { type: "boolean", description: "Mark this fact as always-injected core context", default: false },
+        description: { type: "string", description: "Short description written to frontmatter" },
+        path: { type: "string", description: "Subdirectory under facts/ (defaults to --category)" },
+        force: { type: "boolean", description: "Overwrite an existing fact with the same name", default: false },
+        target: { type: "string", description: "Override the write destination (a configured source name)" },
+    },
+    async run({ args }) {
+        if (!args.name || typeof args.name !== "string") {
+            throw new UsageError("Usage: akm fact add <name> [content] --category <category>", "MISSING_REQUIRED_ARGUMENT", "Provide a flat fact name; pass the body as a quoted argument or via stdin.");
+        }
+        assertFlatAssetName(args.name);
+        const category = typeof args.category === "string" ? args.category.trim() : "";
+        if (!category) {
+            throw new UsageError(`A --category is required (one of: ${KNOWN_CATEGORIES.join(", ")}).`, "MISSING_REQUIRED_ARGUMENT");
+        }
+        const body = (typeof args.content === "string" ? args.content : undefined) ?? tryReadStdinText();
+        if (!body?.trim()) {
+            throw new UsageError("Fact content is required. Pass quoted text or pipe markdown into stdin.");
+        }
+        const description = typeof args.description === "string" ? args.description : undefined;
+        const pinned = args.pinned === true;
+        const frontmatter = buildFactFrontmatter({ description, category, pinned });
+        const subPath = typeof args.path === "string" && args.path.trim() ? args.path.trim() : category;
+        const result = await writeMarkdownAsset({
+            type: "fact",
+            content: `${frontmatter}\n${body}`,
+            name: args.name,
+            fallbackPrefix: "fact",
+            force: args.force === true,
+            target: typeof args.target === "string" ? args.target : undefined,
+            path: subPath,
+        });
+        appendEvent({
+            eventType: "fact_add",
+            ref: result.ref,
+            metadata: { path: result.path, category, pinned, force: args.force === true },
+        });
+        output("fact-add", { ok: true, ...result, category, pinned });
+    },
+});
+/** Pull the `category:<x>` value out of an entry's search hints, if present. */
+function categoryFromHints(hints) {
+    const hit = hints?.find((h) => h.startsWith("category:"));
+    return hit ? hit.slice("category:".length) : undefined;
+}
+const listCommand = defineJsonCommand({
+    meta: { name: "list", description: "List indexed facts (optionally filtered by --category / --pinned)" },
+    args: {
+        category: { type: "string", description: "Only list facts in this category" },
+        pinned: { type: "boolean", description: "Only list pinned (always-injected core) facts", default: false },
+    },
+    run({ args }) {
+        const categoryFilter = typeof args.category === "string" ? args.category.trim() : undefined;
+        const pinnedOnly = args.pinned === true;
+        let db;
+        let facts = [];
+        try {
+            db = openExistingDatabase();
+            facts = getAllEntries(db, "fact")
+                .map((row) => {
+                const category = categoryFromHints(row.entry.searchHints);
+                return {
+                    ref: `fact:${row.entry.name}`,
+                    name: row.entry.name,
+                    ...(category ? { category } : {}),
+                    pinned: row.entry.searchHints?.includes("pinned") ?? false,
+                    ...(row.entry.description ? { description: row.entry.description } : {}),
+                };
+            })
+                .filter((f) => (categoryFilter ? f.category === categoryFilter : true))
+                .filter((f) => (pinnedOnly ? f.pinned : true))
+                .sort((a, b) => a.name.localeCompare(b.name));
+        }
+        catch (err) {
+            // No index yet → empty list rather than a hard error.
+            void toErrorMessage(err);
+            facts = [];
+        }
+        finally {
+            if (db)
+                closeDatabase(db);
+        }
+        output("fact-list", { ok: true, facts, totalCount: facts.length });
+    },
+});
+const contextCommand = defineJsonCommand({
+    meta: {
+        name: "context",
+        description: "Print the assembled pinned-fact core block (what `akm agent` injects into the system prompt)",
+    },
+    run() {
+        const facts = collectPinnedFacts();
+        output("fact-context", { ok: true, content: buildPinnedFactsBlock(facts), count: facts.length });
+    },
+});
+const factSubCommands = {
+    add: addCommand,
+    list: listCommand,
+    context: contextCommand,
+};
+export const FACT_SUBCOMMAND_SET = new Set(Object.keys(factSubCommands));
+export const factCommand = defineCommand({
+    meta: {
+        name: "fact",
+        description: "Manage durable stash-level facts (the `fact` asset type): personal/team/project details, coding conventions, and stash-meta. Subcommands: add, list, context.",
+    },
+    subCommands: factSubCommands,
+});

package/dist/commands/fact/fact-context.js

@@ -0,0 +1,149 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Pinned-fact context assembly (fact asset type, phase 2).
+ *
+ * The `fact` type (see docs/design/fact-asset-type.md) stores durable
+ * stash-level semantic knowledge. Facts marked `pinned: true` form the small
+ * always-injected "core" — the handful of high-signal facts an agent should
+ * always have in context (personal identity, team conventions, the
+ * "constitution"). Everything else stays on "disk" and is reached via normal
+ * `akm search` / `akm curate` just-in-time retrieval.
+ *
+ * This module collects the pinned core from the index and assembles it into a
+ * compact markdown block that the `akm agent` dispatch prepends to the agent's
+ * system prompt. The pure assembly + parse helpers are exported so they can be
+ * unit-tested without a database.
+ */
+import fs from "node:fs";
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { asNonEmptyString } from "../../core/common.js";
+import { closeDatabase, getAllEntries, openExistingDatabase } from "../../indexer/db/db.js";
+/**
+ * Fact `status` values that EXCLUDE a fact from the always-injected core.
+ * Durable facts go stale; rather than delete them, an author can mark a fact
+ * `status: stale` (or `superseded`) and it drops out of the pinned context
+ * while remaining searchable. (Design note phase 2 — staleness handling.)
+ */
+const EXCLUDED_STATUSES = new Set(["stale", "superseded", "archived"]);
+/**
+ * Parse a single fact file into a {@link PinnedFact}, or return `null` when the
+ * fact is NOT part of the pinned core: not `pinned: true`, or carrying an
+ * excluded `status`. Pure — takes the raw file content so it is unit-testable
+ * without touching disk.
+ */
+export function parsePinnedFact(name, raw) {
+    const parsed = parseFrontmatter(raw);
+    const fm = parsed.data;
+    if (fm.pinned !== true)
+        return null;
+    const status = asNonEmptyString(fm.status)?.toLowerCase();
+    if (status && EXCLUDED_STATUSES.has(status))
+        return null;
+    const body = parsed.content.trim();
+    return {
+        ref: `fact:${name}`,
+        name,
+        ...(asNonEmptyString(fm.category) ? { category: asNonEmptyString(fm.category) } : {}),
+        ...(asNonEmptyString(fm.description) ? { description: asNonEmptyString(fm.description) } : {}),
+        body,
+    };
+}
+/**
+ * Render a list of pinned facts into a compact markdown context block, grouped
+ * by category. Returns `""` for an empty list so callers can treat "no facts"
+ * uniformly. Pure.
+ */
+export function buildPinnedFactsBlock(facts) {
+    if (facts.length === 0)
+        return "";
+    // Stable order: by category then name, so the block is deterministic.
+    const sorted = [...facts].sort((a, b) => {
+        const ca = a.category ?? "";
+        const cb = b.category ?? "";
+        if (ca !== cb)
+            return ca.localeCompare(cb);
+        return a.name.localeCompare(b.name);
+    });
+    const lines = [
+        "## Stash facts",
+        "",
+        "Durable, authoritative facts about this user / team / project. Treat them as background context and follow any conventions they state.",
+        "",
+    ];
+    let lastCategory;
+    for (const fact of sorted) {
+        const category = fact.category ?? "general";
+        if (category !== lastCategory) {
+            lines.push(`### ${category}`, "");
+            lastCategory = category;
+        }
+        const heading = fact.description ? `${fact.name} — ${fact.description}` : fact.name;
+        lines.push(`- **${heading}**`);
+        if (fact.body) {
+            // Indent the body two spaces so it reads as part of the bullet.
+            for (const bodyLine of fact.body.split("\n")) {
+                lines.push(bodyLine.length > 0 ? `  ${bodyLine}` : "");
+            }
+        }
+        lines.push("");
+    }
+    return lines.join("\n").trimEnd();
+}
+/**
+ * Collect the pinned core from the index. Opens the existing index DB (unless
+ * one is injected for tests), reads every `fact` entry whose `pinned` search
+ * hint is set, then parses each file from disk. Fails soft: any error (missing
+ * index, unreadable file) yields an empty list rather than throwing, so callers
+ * on the hot path (agent dispatch) are never broken by fact collection.
+ */
+export function collectPinnedFacts(injectedDb) {
+    let db;
+    let ownsDb = false;
+    try {
+        db = injectedDb ?? openExistingDatabase();
+        ownsDb = injectedDb === undefined;
+    }
+    catch {
+        return [];
+    }
+    try {
+        const entries = getAllEntries(db, "fact");
+        const facts = [];
+        for (const row of entries) {
+            // Fast pre-filter on the indexed `pinned` search hint so we only read
+            // files for facts that are actually part of the core.
+            if (!row.entry.searchHints?.includes("pinned"))
+                continue;
+            let raw;
+            try {
+                raw = fs.readFileSync(row.filePath, "utf8");
+            }
+            catch {
+                continue;
+            }
+            const fact = parsePinnedFact(row.entry.name, raw);
+            if (fact)
+                facts.push(fact);
+        }
+        return facts;
+    }
+    catch {
+        return [];
+    }
+    finally {
+        if (ownsDb && db)
+            closeDatabase(db);
+    }
+}
+/**
+ * Convenience for the agent-dispatch seam: collect the pinned core and return
+ * the assembled markdown block, or `undefined` when there are no pinned facts.
+ */
+export function buildPinnedFactsContext(injectedDb) {
+    const facts = collectPinnedFacts(injectedDb);
+    if (facts.length === 0)
+        return undefined;
+    return buildPinnedFactsBlock(facts);
+}

package/dist/commands/read/knowledge.js

@@ -11,7 +11,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../../core/asset/asset-create.js";
-import { resolveAssetPathFromName } from "../../core/asset/asset-spec.js";
+import { resolveAssetPathFromName, TYPE_DIRS } from "../../core/asset/asset-spec.js";
 import { isHttpUrl, isWithin, tryReadStdinText } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
@@ -109,7 +109,9 @@ export async function readKnowledgeInput(source) {
 }
 // ── Asset writing ────────────────────────────────────────────────────────────
 /**
- * Write a markdown asset (knowledge or memory) to the resolved write target.
+ * Write a markdown asset (knowledge, memory, or fact) to the resolved write
+ * target. The type's stash subdirectory is resolved from the asset registry
+ * (`TYPE_DIRS`), so adding a markdown type here needs no further changes.
  *
  * Resolves the write target via the v1 precedence chain (`--target` →
  * `defaultWriteTarget` → working stash), validates the path is within the
@@ -120,7 +122,7 @@ export async function writeMarkdownAsset(options) {
     const cfg = loadConfig();
     const target = resolveWriteTarget(cfg, options.target);
     const { source, config } = target;
-    const typeRoot = path.join(source.path, options.type === "knowledge" ? "knowledge" : "memories");
+    const typeRoot = path.join(source.path, TYPE_DIRS[options.type] ?? options.type);
     // `--name` is the flat asset name; `--path` is the subdirectory under the
     // type root. Combine them into the nested name the path resolver expects.
     const subPath = normalizeCreateSubPath(options.path);
@@ -134,7 +136,8 @@ export async function writeMarkdownAsset(options) {
         throw new UsageError(`Resolved ${options.type} path escapes the stash: "${normalizedName}"`);
     }
     if (fs.existsSync(assetPath) && !options.force) {
-        throw new UsageError(`${options.type === "knowledge" ? "Knowledge" : "Memory"} "${normalizedName}" already exists. Re-run with --force to overwrite it.`, "RESOURCE_ALREADY_EXISTS");
+        const label = `${options.type.charAt(0).toUpperCase()}${options.type.slice(1)}`;
+        throw new UsageError(`${label} "${normalizedName}" already exists. Re-run with --force to overwrite it.`, "RESOURCE_ALREADY_EXISTS");
     }
     const ref = { type: options.type, name: normalizedName };
     const result = await writeAssetToSource(source, config, ref, options.content);

package/dist/output/shapes/passthrough.js

@@ -31,6 +31,9 @@ const PASSTHROUGH_COMMANDS = [
     "env-remove",
     "env-set",
     "env-unset",
+    "fact-add",
+    "fact-context",
+    "fact-list",
     "feedback",
     "graph-entities",
     "graph-entity",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.0-beta.27",
+  "version": "0.9.0-beta.28",
   "type": "module",
   "description": "akm (Agent Knowledge Management) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [