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

package/CHANGELOG.md

@@ -6,23 +6,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
-## [0.9.0-beta.28] — 2026-06-20
+## [0.9.0-beta.29] — 2026-06-20
 
-### Added
+### Reverted
 
-- **#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`.
+- **#630 — `fact` asset type phase 2 reverted (#631).** The pinned-core assembly +
+  `akm fact` CLI shipped in beta.28 was reverted pending rework. Phase 1 (#629, the
+  `fact` asset type itself) remains in place.
 
 ## [0.9.0-beta.27] — 2026-06-20
 

package/dist/cli.js

@@ -63,7 +63,6 @@ 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";
@@ -520,7 +519,6 @@ export const main = defineCommand({
         secret: secretCommand,
         wiki: wikiCommand,
         tasks: tasksCommand,
-        fact: factCommand,
     },
 });
 // ── Exit codes ──────────────────────────────────────────────────────────────

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

@@ -29,7 +29,6 @@ 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";
@@ -58,11 +57,6 @@ 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 () => {
@@ -91,20 +85,6 @@ 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/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, TYPE_DIRS } from "../../core/asset/asset-spec.js";
+import { resolveAssetPathFromName } 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,9 +109,7 @@ export async function readKnowledgeInput(source) {
 }
 // ── Asset writing ────────────────────────────────────────────────────────────
 /**
- * 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.
+ * Write a markdown asset (knowledge or memory) to the resolved write target.
  *
  * Resolves the write target via the v1 precedence chain (`--target` →
  * `defaultWriteTarget` → working stash), validates the path is within the
@@ -122,7 +120,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, TYPE_DIRS[options.type] ?? options.type);
+    const typeRoot = path.join(source.path, options.type === "knowledge" ? "knowledge" : "memories");
     // `--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);
@@ -136,8 +134,7 @@ export async function writeMarkdownAsset(options) {
         throw new UsageError(`Resolved ${options.type} path escapes the stash: "${normalizedName}"`);
     }
     if (fs.existsSync(assetPath) && !options.force) {
-        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");
+        throw new UsageError(`${options.type === "knowledge" ? "Knowledge" : "Memory"} "${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,9 +31,6 @@ 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.28",
+  "version": "0.9.0-beta.29",
   "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": [

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

@@ -1,155 +0,0 @@
-// 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

@@ -1,149 +0,0 @@
-// 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);
-}