useathena 0.1.0 → 0.2.1

package/dist/serve/auto-learn.js

@@ -0,0 +1,56 @@
+import { spawn } from "node:child_process";
+import { mkdirSync, openSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { dbPath } from "../config.js";
+/**
+ * Keeps the loop from stalling on a forgotten `athena learn`: every sensor
+ * entry point calls maybeAutoLearn after ingesting, and once enough new
+ * evidence has accumulated a detached `athena learn` runs in the background.
+ *
+ * Guards, in order: a kill switch (ATHENA_AUTO_LEARN=off), an evidence
+ * threshold (don't spend inference on every capture), and a cooldown (don't
+ * stack runs while one is still thinking). Never throws — a broken trigger
+ * must never break capture.
+ */
+/** Stamped by cmdLearn on every completed run (manual or automatic). */
+export const LAST_LEARN_AT = "learn.lastRunAt";
+const LAST_ATTEMPT_AT = "autoLearn.lastAttemptAt";
+export const AUTO_LEARN_THRESHOLD = 5;
+const COOLDOWN_MS = 30 * 60 * 1000;
+export function autoLearnEnabled(env = process.env) {
+    const value = (env.ATHENA_AUTO_LEARN ?? "").toLowerCase();
+    return !["0", "false", "off", "no"].includes(value);
+}
+export function maybeAutoLearn(store, options = {}) {
+    const now = options.now ?? (() => new Date());
+    try {
+        const pending = store.countInstancesSince(store.getMeta(LAST_LEARN_AT));
+        if (!autoLearnEnabled(options.env)) {
+            return { launched: false, reason: "disabled via ATHENA_AUTO_LEARN", pending };
+        }
+        if (pending < AUTO_LEARN_THRESHOLD) {
+            return { launched: false, reason: `below threshold (${pending}/${AUTO_LEARN_THRESHOLD})`, pending };
+        }
+        const lastAttempt = store.getMeta(LAST_ATTEMPT_AT);
+        if (lastAttempt && now().getTime() - new Date(lastAttempt).getTime() < COOLDOWN_MS) {
+            return { launched: false, reason: "cooling down", pending };
+        }
+        store.setMeta(LAST_ATTEMPT_AT, now().toISOString());
+        (options.launch ?? launchDetachedLearn)();
+        return { launched: true, reason: "threshold reached", pending };
+    }
+    catch {
+        return { launched: false, reason: "trigger error (ignored)", pending: 0 };
+    }
+}
+/** Spawn `athena learn` detached so the calling sensor returns immediately. */
+function launchDetachedLearn() {
+    const packageRoot = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+    const bin = join(packageRoot, "bin", "athena");
+    const logDir = dirname(dbPath());
+    mkdirSync(logDir, { recursive: true });
+    const log = openSync(join(logDir, "auto-learn.log"), "a");
+    const child = spawn(process.execPath, [bin, "learn"], { detached: true, stdio: ["ignore", log, log] });
+    child.unref();
+}

package/dist/serve/auto-outcome.js

@@ -0,0 +1,63 @@
+import { changedRatio, ingestSensorEvent } from "../capture/ingest.js";
+import { recordOutcome } from "./outcome.js";
+/**
+ * Closes the loop without anyone reporting: an agent registers the draft it
+ * produced from a brief (athena_record type=output); when a sensor later
+ * captures what the human actually did with it, the instance is matched back
+ * to the draft and the outcome records itself — approval → uncorrected,
+ * correction → corrected with the instance as the counterexample.
+ *
+ * Matching is conservative: same domain, recent, and the captured "before"
+ * must be essentially the registered draft. A miss costs nothing (outcomes
+ * can still be recorded explicitly); a false match would corrupt trust.
+ */
+const MATCH_WINDOW_HOURS = 72;
+/** Captured before-text may differ from the draft by at most this much. */
+const MATCH_RATIO = 0.15;
+/**
+ * What every sensor should call: ingest the event, then see whether the new
+ * evidence resolves a registered draft into an outcome.
+ */
+export function ingestAndMatch(store, event, options = {}, now = () => new Date()) {
+    expireStaleDrafts(store, now);
+    const instance = ingestSensorEvent(store, event, options);
+    const autoOutcome = matchDraftToInstance(store, instance, now);
+    return autoOutcome ? { instance, autoOutcome } : { instance };
+}
+/**
+ * Drafts that outlive the match window resolve to result "unknown": the loop
+ * closes honestly instead of leaving them "awaiting" forever, and rule trust
+ * is untouched (only uncorrected/corrected adjust it). Swept opportunistically
+ * on every ingest.
+ */
+export function expireStaleDrafts(store, now = () => new Date()) {
+    const cutoff = new Date(now().getTime() - MATCH_WINDOW_HOURS * 3600 * 1000).toISOString();
+    return store
+        .listUnmatchedDrafts({})
+        .filter((draft) => draft.recordedAt < cutoff)
+        .map((draft) => {
+        const outcome = recordOutcome(store, { briefId: draft.briefId, result: "unknown" }, now);
+        draft.matchedOutcomeId = outcome.id;
+        store.saveDraft(draft);
+        return outcome;
+    });
+}
+export function matchDraftToInstance(store, instance, now = () => new Date()) {
+    if (instance.kind !== "correction" && instance.kind !== "override" && instance.kind !== "approval") {
+        return undefined;
+    }
+    const captured = instance.before?.content;
+    if (!captured)
+        return undefined;
+    const since = new Date(now().getTime() - MATCH_WINDOW_HOURS * 3600 * 1000).toISOString();
+    const candidates = store.listUnmatchedDrafts({ domain: instance.situation.domain, since });
+    const draft = candidates.find((candidate) => changedRatio(candidate.content, captured) <= MATCH_RATIO);
+    if (!draft)
+        return undefined;
+    const outcome = recordOutcome(store, instance.kind === "approval"
+        ? { briefId: draft.briefId, result: "uncorrected" }
+        : { briefId: draft.briefId, result: "corrected", correctionInstanceId: instance.id }, now);
+    draft.matchedOutcomeId = outcome.id;
+    store.saveDraft(draft);
+    return outcome;
+}

package/dist/serve/brief.js

@@ -12,8 +12,9 @@ import { parseRef, refTo } from "../core/refs.js";
  *   ask_human         athena knows nothing useful for this task
  */
 const MAX_RULES = 5;
-const MAX_FACTS = 3;
+const MAX_FACTS = 5;
 const MAX_OPEN_QUESTIONS = 3;
+const MAX_MAP_ENTRIES = 8;
 const HIGH_CONFIDENCE = 0.7;
 export function compileBrief(store, request, now = () => new Date()) {
     const inScope = collectHypotheses(store, request);
@@ -32,16 +33,7 @@ export function compileBrief(store, request, now = () => new Date()) {
         boundaries: h.doesNotApplyWhen,
         ref: refTo(h.id),
     }));
-    const facts = store
-        .search(request.task, "source", MAX_FACTS)
-        .flatMap((hit) => {
-        const source = store.getSource(parseRef(hit.ref).id);
-        return source ? [source] : [];
-    })
-        .map((source) => ({
-        statement: `${source.title}: ${source.content.slice(0, 160)}`,
-        ref: refTo(source.id),
-    }));
+    const facts = collectFacts(store, request, now);
     const doNotAssume = stale.map((h) => `A previously learned rule is stale — do not assume it still holds: "${h.rule}"`);
     const openQuestions = unvalidated
         .slice(0, MAX_OPEN_QUESTIONS)
@@ -49,6 +41,7 @@ export function compileBrief(store, request, now = () => new Date()) {
     const brief = {
         id: newId("brf", now().getTime()),
         task: request.task,
+        ...(request.domain !== undefined ? { domain: request.domain } : {}),
         compiledAt: now().toISOString(),
         rules,
         facts,
@@ -56,6 +49,7 @@ export function compileBrief(store, request, now = () => new Date()) {
         openQuestions,
         readiness: readinessFor(rules, facts, doNotAssume, openQuestions),
         refs: [...rules.map((r) => r.ref), ...facts.map((f) => f.ref), ...unvalidated.slice(0, MAX_OPEN_QUESTIONS).map((h) => refTo(h.id))],
+        map: knowledgeMap(store),
     };
     // Serving is an event: fires feed the outcome loop.
     for (const rule of rules) {
@@ -69,6 +63,65 @@ export function compileBrief(store, request, now = () => new Date()) {
     store.saveBrief(brief);
     return brief;
 }
+/**
+ * Facts reach a brief three ways: the task names a known entity (alias match),
+ * the task's domain produced facts, or lexical search hits. Stale and
+ * superseded facts never serve.
+ */
+function collectFacts(store, request, now) {
+    const byId = new Map();
+    const task = ` ${request.task.toLowerCase()} `;
+    for (const object of store.listObjects()) {
+        const aliases = [object.name, ...object.aliases].filter((alias) => alias.length >= 3);
+        if (!aliases.some((alias) => task.includes(alias.toLowerCase())))
+            continue;
+        for (const fact of store.listFacts({ objectId: object.id }))
+            byId.set(fact.id, fact);
+    }
+    if (request.domain) {
+        for (const fact of store.listFacts({ domain: request.domain }))
+            byId.set(fact.id, fact);
+    }
+    for (const hit of store.search(request.task, "fact", MAX_FACTS)) {
+        const fact = store.getFact(parseRef(hit.ref).id);
+        if (fact)
+            byId.set(fact.id, fact);
+    }
+    const nowIso = now().toISOString();
+    const live = [...byId.values()]
+        .filter((fact) => !fact.supersededById && fact.staleAfter > nowIso)
+        .sort((a, b) => b.lastConfirmedAt.localeCompare(a.lastConfirmedAt))
+        .slice(0, MAX_FACTS)
+        .map((fact) => ({ statement: fact.statement, ref: refTo(fact.id) }));
+    if (live.length >= MAX_FACTS)
+        return live;
+    // Raw sources fill remaining slots — weaker than extracted facts, still cited.
+    const sources = store
+        .search(request.task, "source", MAX_FACTS - live.length)
+        .flatMap((hit) => {
+        const source = store.getSource(parseRef(hit.ref).id);
+        return source ? [source] : [];
+    })
+        .map((source) => ({
+        statement: `${source.title}: ${source.content.slice(0, 160)}`,
+        ref: refTo(source.id),
+    }));
+    return [...live, ...sources];
+}
+/** The coordinates: what athena knows about and how to retrieve each slice. */
+function knowledgeMap(store) {
+    const entries = [];
+    for (const { domain, count } of store.hypothesisCountsByDomain()) {
+        entries.push({ label: `${count} rule${count === 1 ? "" : "s"} in ${domain}`, count, query: domain });
+    }
+    for (const { objectId, count } of store.factCountsByObject()) {
+        const object = store.getObject(objectId);
+        if (!object)
+            continue;
+        entries.push({ label: `${count} fact${count === 1 ? "" : "s"} about ${object.name}`, count, query: object.name });
+    }
+    return entries.sort((a, b) => b.count - a.count).slice(0, MAX_MAP_ENTRIES);
+}
 function collectHypotheses(store, request) {
     const byId = new Map();
     if (request.domain) {

package/dist/store/open.js

@@ -15,5 +15,9 @@ export function openRef(store, ref) {
             return store.getBrief(parsed.id);
         case "outcome":
             return store.getOutcome(parsed.id);
+        case "fact":
+            return store.getFact(parsed.id);
+        case "draft":
+            return store.getDraft(parsed.id);
     }
 }

package/dist/store/store.js

@@ -55,6 +55,19 @@ export class AthenaStore {
       CREATE TABLE IF NOT EXISTS briefs (
         id TEXT PRIMARY KEY, compiled_at TEXT NOT NULL, data TEXT NOT NULL
       );
+      CREATE TABLE IF NOT EXISTS facts (
+        id TEXT PRIMARY KEY, object_id TEXT NOT NULL, domain TEXT NOT NULL,
+        last_confirmed_at TEXT NOT NULL, data TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_facts_object ON facts(object_id);
+      CREATE TABLE IF NOT EXISTS drafts (
+        id TEXT PRIMARY KEY, brief_id TEXT NOT NULL, domain TEXT NOT NULL,
+        recorded_at TEXT NOT NULL, matched_outcome_id TEXT, data TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_drafts_unmatched ON drafts(domain, recorded_at) WHERE matched_outcome_id IS NULL;
+      CREATE TABLE IF NOT EXISTS meta (
+        key TEXT PRIMARY KEY, value TEXT NOT NULL
+      );
       CREATE VIRTUAL TABLE IF NOT EXISTS search_index USING fts5(ref, lane, text);
     `);
     }
@@ -97,6 +110,13 @@ export class AthenaStore {
       ORDER BY observed_at DESC LIMIT ${filter.limit ?? 200}`;
         return this.db.prepare(sql).all(...params).map((rowData));
     }
+    /** Instances observed strictly after `since` (all instances when omitted). */
+    countInstancesSince(since) {
+        const row = since
+            ? this.db.prepare("SELECT COUNT(*) AS n FROM instances WHERE observed_at > ?").get(since)
+            : this.db.prepare("SELECT COUNT(*) AS n FROM instances").get();
+        return row.n;
+    }
     // --- hypotheses (revisable views over evidence) ---
     saveHypothesis(hypothesis) {
         if (hypothesis.supportingInstanceIds.length === 0) {
@@ -170,6 +190,77 @@ export class AthenaStore {
             .all(objectId, objectId)
             .map((rowData));
     }
+    // --- facts (revisable views over evidence, like hypotheses) ---
+    saveFact(fact) {
+        if (fact.supportingInstanceIds.length === 0) {
+            throw new Error(`fact ${fact.id} has no supporting instances — everything cites`);
+        }
+        const object = this.getObject(fact.objectId);
+        if (!object) {
+            throw new Error(`fact ${fact.id} references unknown object ${fact.objectId}`);
+        }
+        this.upsert("facts", "INSERT INTO facts (id, object_id, domain, last_confirmed_at, data) VALUES (?, ?, ?, ?, ?) " +
+            "ON CONFLICT(id) DO UPDATE SET object_id = excluded.object_id, domain = excluded.domain, " +
+            "last_confirmed_at = excluded.last_confirmed_at, data = excluded.data", [fact.id, fact.objectId, fact.domain, fact.lastConfirmedAt, JSON.stringify(fact)]);
+        this.index(`athena://fact/${fact.id}`, "fact", [fact.statement, fact.domain, object.name, object.aliases.join(" ")].join("\n"));
+    }
+    getFact(id) {
+        return this.getData("facts", id);
+    }
+    listFacts(filter = {}) {
+        const where = [];
+        const params = [];
+        if (filter.objectId) {
+            where.push("object_id = ?");
+            params.push(filter.objectId);
+        }
+        if (filter.domain) {
+            where.push("domain = ?");
+            params.push(filter.domain);
+        }
+        const sql = `SELECT data FROM facts ${where.length ? `WHERE ${where.join(" AND ")}` : ""}
+      ORDER BY last_confirmed_at DESC LIMIT ${filter.limit ?? 200}`;
+        return this.db.prepare(sql).all(...params).map((rowData));
+    }
+    /** Per-entity fact counts for the brief's knowledge map. */
+    factCountsByObject() {
+        return this.db
+            .prepare("SELECT object_id AS objectId, COUNT(*) AS count FROM facts GROUP BY object_id ORDER BY count DESC")
+            .all();
+    }
+    /** Per-domain servable-rule counts for the brief's knowledge map. */
+    hypothesisCountsByDomain() {
+        return this.db
+            .prepare("SELECT domain, COUNT(*) AS count FROM hypotheses WHERE status IN ('validated','active') GROUP BY domain ORDER BY count DESC")
+            .all();
+    }
+    // --- agent drafts (outputs awaiting an observed outcome) ---
+    saveDraft(draft) {
+        this.upsert("drafts", "INSERT INTO drafts (id, brief_id, domain, recorded_at, matched_outcome_id, data) VALUES (?, ?, ?, ?, ?, ?) " +
+            "ON CONFLICT(id) DO UPDATE SET matched_outcome_id = excluded.matched_outcome_id, data = excluded.data", [draft.id, draft.briefId, draft.domain, draft.recordedAt, draft.matchedOutcomeId ?? null, JSON.stringify(draft)]);
+    }
+    getDraft(id) {
+        return this.getData("drafts", id);
+    }
+    listUnmatchedDrafts(filter = {}) {
+        const where = ["matched_outcome_id IS NULL"];
+        const params = [];
+        if (filter.domain) {
+            where.push("domain = ?");
+            params.push(filter.domain);
+        }
+        if (filter.since) {
+            where.push("recorded_at >= ?");
+            params.push(filter.since);
+        }
+        return this.db
+            .prepare(`SELECT data FROM drafts WHERE ${where.join(" AND ")} ORDER BY recorded_at DESC LIMIT 100`)
+            .all(...params)
+            .map((rowData));
+    }
+    listDrafts() {
+        return this.db.prepare("SELECT data FROM drafts ORDER BY recorded_at DESC LIMIT 500").all().map((rowData));
+    }
     // --- serving layer ---
     saveBrief(brief) {
         this.upsert("briefs", "INSERT INTO briefs (id, compiled_at, data) VALUES (?, ?, ?) ON CONFLICT(id) DO UPDATE SET data = excluded.data", [brief.id, brief.compiledAt, JSON.stringify(brief)]);
@@ -190,6 +281,22 @@ export class AthenaStore {
             : this.db.prepare("SELECT data FROM outcomes ORDER BY recorded_at DESC").all();
         return rows.map((rowData));
     }
+    listBriefs(limit = 500) {
+        return this.db
+            .prepare(`SELECT data FROM briefs ORDER BY compiled_at DESC LIMIT ${limit}`)
+            .all()
+            .map((rowData));
+    }
+    // --- meta (operational state: last learn run, cooldowns) ---
+    getMeta(key) {
+        const row = this.db.prepare("SELECT value FROM meta WHERE key = ?").get(key);
+        return row ? row.value : undefined;
+    }
+    setMeta(key, value) {
+        this.db
+            .prepare("INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value")
+            .run(key, value);
+    }
     // --- stats ---
     counts() {
         const byColumn = (table, column) => {
@@ -205,6 +312,8 @@ export class AthenaStore {
             sources: total("sources"),
             outcomes: total("outcomes"),
             briefs: total("briefs"),
+            facts: total("facts"),
+            unmatchedDrafts: this.db.prepare("SELECT COUNT(*) AS n FROM drafts WHERE matched_outcome_id IS NULL").get().n,
         };
     }
     // --- search (lexical lane) ---

package/docs/schema.md

@@ -29,7 +29,8 @@ Mission framing: athena captures **tacit knowledge** from real work so agents be
 ## IDs
 
 Prefixed ULIDs: `ins_` instance, `hyp_` hypothesis, `obj_` object, `src_` source,
-`out_` outcome, `brf_` brief, `act_` actor, `sen_` sensor. Sortable by creation time.
+`out_` outcome, `brf_` brief, `act_` actor, `sen_` sensor, `fct_` fact, `drf_` agent
+draft. Sortable by creation time.
 
 ---
 
@@ -268,6 +269,30 @@ type ObjectRelation = {
 };
 ```
 
+### Fact — the explicit counterpart of a hypothesis
+
+A declarative, entity-grounded statement extracted from evidence ("Acme's renewal
+is in September" vs the tacit "be formal with Acme execs"). Facts are never entered
+manually and agents cannot write them: the engine extracts them during learn, and
+`materializeFacts` is the only write path — it resolves or creates the entity and
+dedupes near-identical statements into a confirmation instead of a duplicate.
+
+```ts
+type Fact = {
+  id: FactId;                  // fct_…
+  objectId: ObjectId;          // every fact is about exactly one entity
+  statement: string;
+  domain: string;              // domain of the evidence cluster it came from
+  supportingInstanceIds: InstanceId[];  // facts cite, like everything else
+  confidence: number;
+  firstSeenAt: string;
+  lastConfirmedAt: string;     // bumped when new evidence restates the fact
+  staleAfter: string;          // unconfirmed past this → no longer served
+  supersededById?: FactId;
+  visibility: Exclude<Visibility, "user_private_raw">;
+};
+```
+
 Markdown pages (per object, per domain) are **projections** generated from sources +
 hypotheses + relations. Stored in `.athena/pages/` for humans and git; rebuilt, never edited
 as truth.
@@ -284,6 +309,7 @@ Compact payload + dereferenceable pointers. Persisted for audit and outcome link
 type Brief = {
   id: BriefId;
   task: string;                // as the agent stated it
+  domain?: string;             // when given — drafts registered against this brief match captures in it
   compiledAt: string;
 
   rules: {
@@ -305,6 +331,12 @@ type Brief = {
 
   readiness: "act" | "act_with_caveats" | "inspect_first" | "ask_human";
   refs: Ref[];                 // additional evidence worth opening, ranked
+
+  map?: {                      // coordinates into everything else athena knows:
+    label: string;             //   "12 rules in email.outreach", "4 facts about Acme"
+    count: number;
+    query: string;             //   pass to athena_search — agents pull, never flooded
+  }[];
 };
 
 type Ref = string;             // athena://hypothesis/hyp_x | athena://instance/ins_x
@@ -332,14 +364,39 @@ type AgentOutcome = {
 This closes the loop: **brief → action → outcome → instance → hypothesis update**, and
 gives us the north-star metric directly: correction rate per served brief, over time.
 
+### AgentDraft — outcomes that record themselves
+
+The artifact an agent produced from a brief, registered (`athena_record type=output`)
+so athena can detect the outcome without anyone reporting: when a sensor later
+captures what the human actually did with it, the instance matches back —
+approval → `uncorrected`, correction → `corrected` with the instance as the
+counterexample.
+
+```ts
+type AgentDraft = {
+  id: DraftId;                 // drf_…
+  briefId: BriefId;
+  content: string;             // the artifact, verbatim
+  contentHash: string;
+  mediaType: string;
+  domain: string;
+  recordedAt: string;
+  matchedOutcomeId?: OutcomeId; // set once resolved (matched or expired)
+};
+```
+
+Matching is conservative — same domain, within 72h, captured before-text within
+15% of the draft — because a false match would corrupt trust; a miss costs nothing.
+Drafts that outlive the window expire to `result: "unknown"` (rule trust untouched).
+
 ### MCP surface (4 tools, not 19)
 
 | Tool | Does |
 |---|---|
 | `athena_brief(task, domain?)` | compile + persist a Brief |
 | `athena_open(ref)` | dereference any `athena://` ref |
-| `athena_record(event)` | SensorEvent in: outcome, correction, manual note, rule *proposal* |
-| `athena_search(query, lane?)` | direct lexical+semantic search when the agent wants to explore |
+| `athena_record(event)` | outcome report, draft registration (`type=output`), or SensorEvent: correction, manual note, rule *proposal* |
+| `athena_search(query, lane?)` | direct search (lanes: instance, hypothesis, source, fact) when the agent wants to explore |
 
 No durable-mutation tools. `athena_record` proposals enter the review queue like any sensor event.
 
@@ -348,9 +405,11 @@ No durable-mutation tools. `athena_record` proposals enter the review queue like
 ## 5. Storage mapping
 
 SQLite, one file per workspace (`.athena/athena.db`):
-- `instances`, `hypotheses`, `sources`, `objects`, `relations`, `outcomes`, `briefs`
-  — JSON column + extracted indexed columns (id, kind, domain, status, observedAt, visibility).
-- FTS5 over instance summaries/diffs, hypothesis rules, source content.
+- `instances`, `hypotheses`, `sources`, `objects`, `relations`, `outcomes`, `briefs`,
+  `facts`, `drafts` — JSON column + extracted indexed columns (id, kind, domain, status,
+  observedAt, visibility).
+- `meta` — key/value operational state (last learn run, auto-learn cooldown).
+- FTS5 over instance summaries/diffs, hypothesis rules, source content, fact statements.
 - `sqlite-vec` over situation/rule/source embeddings (optional lane — everything works without it).
 - WAL mode; single-writer per file is acceptable for local; server mode serializes per workspace.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "useathena",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "athena captures tacit knowledge from real work so agents become truly autonomous and reliable.",
   "license": "UNLICENSED",
   "repository": {