jeo-code 0.6.11 → 0.6.12

package/CHANGELOG.md

@@ -6,6 +6,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 The README mirrors the latest 5 entries — regenerate with `bun run changelog:sync`.
 
+## [0.6.12] - 2026-06-16
+_OKF-backed memory distillation — session learnings become structured concept files._
+
+### Added
+- **OKF-backed memory distillation (OKF Sprint 02).** Session distillation now emits structured OKF v0.1 concept files — each with `type` / `title` / `description` / `body` / `tags` / `confidence` / `links` — filed into typed directories (unknown types fall back to `facts/`), deduped by title, merged with the existing concept bundle, then indexed and logged. The distiller prompts the model for a `{ concepts: [...] }` payload and parses it leniently (`tryExtractJsonObject`) so text-only providers still land. Builds on the 0.6.10 OKF format layer.
+
 ## [0.6.11] - 2026-06-16
 _Larger reasoning budgets, and terminal capability-response sequences kept out of the prompt._
 

package/README.ja.md

@@ -158,11 +158,11 @@ CI は `.github/workflows/npm-publish.yml` で公開します — GitHub リリ
 ## 変更履歴 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.6.12]** (2026-06-16) — OKF-backed memory distillation — session learnings become structured concept files.
 - **[0.6.11]** (2026-06-16) — Larger reasoning budgets, and terminal capability-response sequences kept out of the prompt.
 - **[0.6.10]** (2026-06-16) — OKF memory-format foundation and a hardened bashTool subprocess drain.
 - **[0.6.9]** (2026-06-16) — Live streaming blocks size to their content and the viewport instead of a fixed rectangle.
 - **[0.6.8]** (2026-06-16) — OAuth loopback callback host pinned to `localhost` to match provider-registered redirect URIs.
-- **[0.6.7]** (2026-06-16) — Mouse-report input corruption fixed under `jeo --tmux`, and a full-width TUI at one consistent width.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.ko.md

@@ -158,11 +158,11 @@ CI는 `.github/workflows/npm-publish.yml`로 배포합니다 — GitHub 릴리
 ## 변경 이력 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.6.12]** (2026-06-16) — OKF-backed memory distillation — session learnings become structured concept files.
 - **[0.6.11]** (2026-06-16) — Larger reasoning budgets, and terminal capability-response sequences kept out of the prompt.
 - **[0.6.10]** (2026-06-16) — OKF memory-format foundation and a hardened bashTool subprocess drain.
 - **[0.6.9]** (2026-06-16) — Live streaming blocks size to their content and the viewport instead of a fixed rectangle.
 - **[0.6.8]** (2026-06-16) — OAuth loopback callback host pinned to `localhost` to match provider-registered redirect URIs.
-- **[0.6.7]** (2026-06-16) — Mouse-report input corruption fixed under `jeo --tmux`, and a full-width TUI at one consistent width.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.md

@@ -158,11 +158,11 @@ Required npm token permissions (repository secret `NPM_TOKEN`):
 ## Changelog
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.6.12]** (2026-06-16) — OKF-backed memory distillation — session learnings become structured concept files.
 - **[0.6.11]** (2026-06-16) — Larger reasoning budgets, and terminal capability-response sequences kept out of the prompt.
 - **[0.6.10]** (2026-06-16) — OKF memory-format foundation and a hardened bashTool subprocess drain.
 - **[0.6.9]** (2026-06-16) — Live streaming blocks size to their content and the viewport instead of a fixed rectangle.
 - **[0.6.8]** (2026-06-16) — OAuth loopback callback host pinned to `localhost` to match provider-registered redirect URIs.
-- **[0.6.7]** (2026-06-16) — Mouse-report input corruption fixed under `jeo --tmux`, and a full-width TUI at one consistent width.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.zh.md

@@ -158,11 +158,11 @@ CI 通过 `.github/workflows/npm-publish.yml` 发布 — GitHub 发布 release
 ## 更新日志 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.6.12]** (2026-06-16) — OKF-backed memory distillation — session learnings become structured concept files.
 - **[0.6.11]** (2026-06-16) — Larger reasoning budgets, and terminal capability-response sequences kept out of the prompt.
 - **[0.6.10]** (2026-06-16) — OKF memory-format foundation and a hardened bashTool subprocess drain.
 - **[0.6.9]** (2026-06-16) — Live streaming blocks size to their content and the viewport instead of a fixed rectangle.
 - **[0.6.8]** (2026-06-16) — OAuth loopback callback host pinned to `localhost` to match provider-registered redirect URIs.
-- **[0.6.7]** (2026-06-16) — Mouse-report input corruption fixed under `jeo --tmux`, and a full-width TUI at one consistent width.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jeo-code",
-  "version": "0.6.11",
+  "version": "0.6.12",
   "description": "Clean, highly optimized AI coding agent using spec-first loop",
   "type": "module",
   "main": "src/cli.ts",

package/src/agent/memory.ts

@@ -13,6 +13,8 @@ import { spawn as nodeSpawn } from "node:child_process";
 import * as path from "node:path";
 import { callLlm, type Message } from "./loop";
 import { jeoEnv } from "../util/env";
+import { parseConcept, serializeConcept, slugify, isReservedFile } from "./memory-okf";
+import { tryExtractJsonObject } from "./json";
 
 /** On-disk document cap — the distill prompt instructs the model to stay under it. */
 export const MEMORY_MAX_CHARS = 6_000;
@@ -22,6 +24,16 @@ export const MEMORY_INJECT_MAX_CHARS = 3_000;
 const TRANSCRIPT_MAX_CHARS = 12_000;
 /** A session shorter than this has nothing durable to learn. */
 const MIN_HISTORY_MESSAGES = 4;
+/** Single source of truth for the four jeo concept types the distiller files:
+ *  type → on-disk subdir → index.md section header, in display order. Add a
+ *  row here (one place) to introduce a new filed/rendered type. */
+const TYPE_LAYOUT = [
+  { type: "RepoFact", dir: "facts", header: "Repo Facts" },
+  { type: "Command", dir: "commands", header: "Commands" },
+  { type: "Gotcha", dir: "gotchas", header: "Gotchas" },
+  { type: "UserPreference", dir: "preferences", header: "User Preferences" },
+] as const;
+const DIR_BY_TYPE: Record<string, string> = Object.fromEntries(TYPE_LAYOUT.map(t => [t.type, t.dir]));
 
 export function memoryFilePath(cwd: string): string {
   return path.join(cwd, ".jeo", "memory", "MEMORY.md");
@@ -83,6 +95,135 @@ export interface DistillResult {
  * Best-effort by design: any failure is reported in the result, never thrown —
  * a memory write must not be able to break session exit.
  */
+
+async function findMarkdownFiles(dir: string): Promise<string[]> {
+  const files: string[] = [];
+  async function recurse(currentDir: string) {
+    let entries;
+    try {
+      entries = await fs.readdir(currentDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === "raw") continue;
+        await recurse(fullPath);
+      } else if (entry.isFile() && entry.name.endsWith(".md")) {
+        files.push(fullPath);
+      }
+    }
+  }
+  await recurse(dir);
+  return files;
+}
+
+async function rebuildIndex(bundleDir: string): Promise<void> {
+  const files = await findMarkdownFiles(bundleDir);
+  const concepts: { type: string; title: string; relPath: string }[] = [];
+  for (const file of files) {
+    const relPath = path.relative(bundleDir, file);
+    if (isReservedFile(relPath)) continue;
+    try {
+      const content = await fs.readFile(file, "utf-8");
+      const parsed = parseConcept(content);
+      concepts.push({
+        type: (parsed.frontmatter.type as string) || "RepoFact",
+        title: (parsed.frontmatter.title as string) || path.basename(file, ".md"),
+        relPath,
+      });
+    } catch {
+      // ignore
+    }
+  }
+
+  let body = "# Index\n\n";
+  for (const { type, header } of TYPE_LAYOUT) {
+    const list = concepts.filter(c => c.type === type);
+    if (list.length === 0) continue;
+    body += `## ${header}\n`;
+    for (const c of list) {
+      body += `- [${c.title}](/${c.relPath.replace(/\\/g, "/")})\n`;
+    }
+    body += "\n";
+  }
+
+  const indexContent = serializeConcept({ okf_version: "0.1" }, body.trim());
+  const indexPath = path.join(bundleDir, "index.md");
+  const tmpPath = `${indexPath}.tmp-${process.pid}`;
+  await fs.writeFile(tmpPath, indexContent, "utf-8");
+  await fs.rename(tmpPath, indexPath);
+}
+
+async function updateLog(bundleDir: string, updatedConcepts: { title: string; type: string }[]): Promise<void> {
+  const logPath = path.join(bundleDir, "log.md");
+  let existingContent = "";
+  try {
+    existingContent = await fs.readFile(logPath, "utf-8");
+  } catch {
+    existingContent = "# Directory Update Log\n";
+  }
+
+  const today = new Date().toISOString().split("T")[0];
+  const heading = `## ${today}`;
+
+  let entry = "";
+  for (const c of updatedConcepts) {
+    entry += `* **${c.type}**: ${c.title}\n`;
+  }
+  if (!entry) return;
+
+  let newContent = "";
+  if (existingContent.includes(heading)) {
+    const lines = existingContent.split("\n");
+    const idx = lines.findIndex(l => l.trim() === heading);
+    lines.splice(idx + 1, 0, entry.trim());
+    newContent = lines.join("\n");
+  } else {
+    const lines = existingContent.split("\n");
+    let insertIdx = 0;
+    if (lines[0]?.startsWith("# ")) {
+      insertIdx = 1;
+      while (insertIdx < lines.length && lines[insertIdx].trim() === "") {
+        insertIdx++;
+      }
+    }
+    lines.splice(insertIdx, 0, `${heading}\n${entry}`);
+    newContent = lines.join("\n");
+  }
+
+  const tmpPath = `${logPath}.tmp-${process.pid}`;
+  await fs.writeFile(tmpPath, newContent, "utf-8");
+  await fs.rename(tmpPath, logPath);
+}
+
+export async function saveRawPayload(bundleDir: string, payload: any): Promise<void> {
+  const rawDir = path.join(bundleDir, "raw");
+  await fs.mkdir(rawDir, { recursive: true });
+  const filename = `session-${Date.now()}-${process.pid}.json`;
+  const filePath = path.join(rawDir, filename);
+  await fs.writeFile(filePath, JSON.stringify(payload, null, 2), "utf-8");
+}
+
+async function cleanupStalePendingFiles(dir: string): Promise<void> {
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    const now = Date.now();
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.startsWith("pending-distill-") && entry.name.endsWith(".json")) {
+        const filePath = path.join(dir, entry.name);
+        const stat = await fs.stat(filePath);
+        if (now - stat.mtimeMs > 24 * 60 * 60 * 1000) {
+          await fs.unlink(filePath).catch(() => {});
+        }
+      }
+    }
+  } catch {
+    // ignore
+  }
+}
+
 export async function distillSessionMemory(
   history: Message[],
   cwd: string,
@@ -92,44 +233,154 @@ export async function distillSessionMemory(
   const body = history.filter(m => m.role !== "system");
   if (body.length < MIN_HISTORY_MESSAGES) return { updated: false, skipped: "session too short" };
   try {
-    const existing = await loadMemory(cwd);
+    const bundleDir = path.join(cwd, ".jeo", "memory");
+    const existingConcepts: any[] = [];
+    try {
+      const files = await findMarkdownFiles(bundleDir);
+      for (const file of files) {
+        const relPath = path.relative(bundleDir, file);
+        if (isReservedFile(relPath)) continue;
+        try {
+          const content = await fs.readFile(file, "utf-8");
+          const parsed = parseConcept(content);
+          existingConcepts.push({
+            type: parsed.frontmatter.type,
+            title: parsed.frontmatter.title || "",
+            description: parsed.frontmatter.description,
+            body: parsed.body,
+            tags: parsed.frontmatter.tags,
+            confidence: parsed.frontmatter.confidence,
+            links: parsed.frontmatter.links,
+            path: relPath,
+          });
+        } catch {}
+      }
+    } catch {}
+
     const prompt: Message[] = [
       {
         role: "system",
         content:
-          "You maintain a compact project memory document for a coding agent. " +
-          "Merge durable learnings from the session transcript into the existing memory. " +
+          "You maintain a compact project memory bundle for a coding agent. " +
+          "Extract durable learnings from the session transcript and merge them with the existing concepts. " +
           "Keep ONLY what helps future sessions in THIS repository: repo facts (structure, conventions, key files), " +
           "commands that work (build/test/run), gotchas (failures and their fixes), and user preferences. " +
           "Drop session-specific noise (one-off tasks, transient errors, conversational detail). " +
-          `Output the FULL updated document as markdown bullets under those four headings, max ${MEMORY_MAX_CHARS} characters. ` +
-          "Output ONLY the document — no preamble, no fences.",
+          "You must output a JSON object with a single key \"concepts\", which is an array of concept objects. " +
+          "Each concept object must have the following fields:\n" +
+          "  - \"type\": one of \"RepoFact\", \"Command\", \"Gotcha\", \"UserPreference\"\n" +
+          "  - \"title\": a short, descriptive title (e.g., \"Bun test runner\")\n" +
+          "  - \"description\": a brief one-line summary of the concept\n" +
+          "  - \"body\": the detailed markdown content/body of the concept\n" +
+          "  - \"tags\": an array of string tags (optional)\n" +
+          "  - \"confidence\": one of \"high\", \"medium\", \"low\" (optional)\n" +
+          "  - \"links\": an array of other concept paths/IDs this concept links to (optional)\n\n" +
+          "Output ONLY the JSON object. Do not include any markdown formatting, preamble, or explanation."
       },
       {
         role: "user",
         content:
-          `Existing memory document:\n${existing || "(empty)"}\n\n` +
-          `Session transcript (tail):\n${transcriptTail(history)}`,
-      },
+          `Existing concepts:\n${JSON.stringify(existingConcepts, null, 2)}\n\n` +
+          `Session transcript (tail):\n${transcriptTail(history)}`
+      }
     ];
+
     const timeoutMs = opts.timeoutMs ?? 20_000;
     const distilled = await Promise.race([
-      callLlm(prompt, { model: opts.model, jsonMode: false, maxTokens: 2_000 }),
+      callLlm(prompt, { model: opts.model, jsonMode: true, maxTokens: 2_000 }),
       new Promise<never>((_, reject) => setTimeout(() => reject(new Error(`memory distill timed out after ${timeoutMs}ms`)), timeoutMs)),
     ]);
-    const doc = distilled.trim().slice(0, MEMORY_MAX_CHARS);
-    if (!doc) return { updated: false, skipped: "model returned an empty document" };
-    const file = memoryFilePath(cwd);
-    await fs.mkdir(path.dirname(file), { recursive: true });
-    const tmp = `${file}.tmp-${process.pid}`;
-    await fs.writeFile(tmp, doc + "\n", "utf-8");
-    await fs.rename(tmp, file); // atomic: a crash mid-write never corrupts the doc
-    return { updated: true };
+
+    // Robust extraction: the distill prompt requests JSON, but text-only providers
+    // (the default antigravity backend) routinely wrap it in prose or  fences.
+    // tryExtractJsonObject recovers the first balanced {...}, tolerating that noise;
+    // a null result means the model gave plain text → old MEMORY.md fallback below.
+    const parsedJson = tryExtractJsonObject<{ concepts?: unknown }>(distilled);
+
+
+    if (parsedJson && Array.isArray(parsedJson.concepts)) {
+      await fs.mkdir(bundleDir, { recursive: true });
+      const updatedConcepts: { title: string; type: string }[] = [];
+
+      for (const concept of parsedJson.concepts) {
+        if (!concept.type || !concept.title) continue;
+        // Unknown types fall back to facts/ (lenient — OKF tolerates extra types).
+        const dir = DIR_BY_TYPE[concept.type] ?? "facts";
+
+        const targetDir = path.join(bundleDir, dir);
+        await fs.mkdir(targetDir, { recursive: true });
+
+        let slug = slugify(concept.title);
+        let relPath = `${dir}/${slug}.md`;
+        let fullPath = path.join(bundleDir, relPath);
+
+        let suffix = 1;
+        while (true) {
+          try {
+            const existingContent = await fs.readFile(fullPath, "utf-8");
+            const parsed = parseConcept(existingContent);
+            const existingTitle = parsed.frontmatter.title || "";
+            if (existingTitle === concept.title) {
+              break;
+            }
+            slug = `${slugify(concept.title)}-${suffix}`;
+            relPath = `${dir}/${slug}.md`;
+            fullPath = path.join(bundleDir, relPath);
+            suffix++;
+          } catch {
+            break;
+          }
+        }
+
+        let existingFm = {};
+        try {
+          const existingContent = await fs.readFile(fullPath, "utf-8");
+          existingFm = parseConcept(existingContent).frontmatter;
+        } catch {}
+
+        const frontmatter = {
+          ...existingFm,
+          type: concept.type,
+          title: concept.title,
+          description: concept.description || "",
+          tags: concept.tags || [],
+          timestamp: new Date().toISOString(),
+          confidence: concept.confidence || "high",
+          last_verified: new Date().toISOString().split("T")[0],
+          links: concept.links || [],
+        };
+
+        const serialized = serializeConcept(frontmatter, concept.body || "");
+        const tmpPath = `${fullPath}.tmp-${process.pid}`;
+        await fs.writeFile(tmpPath, serialized, "utf-8");
+        await fs.rename(tmpPath, fullPath);
+
+        updatedConcepts.push({ title: concept.title, type: concept.type });
+      }
+
+      await rebuildIndex(bundleDir);
+      if (updatedConcepts.length > 0) {
+        await updateLog(bundleDir, updatedConcepts);
+      }
+      await cleanupStalePendingFiles(bundleDir);
+      return { updated: true };
+    } else {
+      const doc = distilled.trim().slice(0, MEMORY_MAX_CHARS);
+      if (!doc) return { updated: false, skipped: "model returned an empty document" };
+      const file = memoryFilePath(cwd);
+      await fs.mkdir(path.dirname(file), { recursive: true });
+      const tmp = `${file}.tmp-${process.pid}`;
+      await fs.writeFile(tmp, doc + "\n", "utf-8");
+      await fs.rename(tmp, file);
+      return { updated: true };
+    }
   } catch (err: any) {
     return { updated: false, skipped: `distill failed: ${err?.message ?? String(err)}` };
   }
 }
 
+
+
 // ── Detached background distillation (round-16) ──
 // The exit-path `await distillSessionMemory(...)` blocked /exit and ^C^C for up
 // to 20s on a final LLM call. Quitting must be INSTANT: the parent now writes a
@@ -189,7 +440,10 @@ export async function runMemoryDistillCommand(args: string[]): Promise<void> {
   const payloadPath = (args[0] ?? "").trim();
   if (!payloadPath) return;
   try {
-    const payload = JSON.parse(await fs.readFile(payloadPath, "utf-8")) as { model?: string; messages?: Message[] };
+    const payloadContent = await fs.readFile(payloadPath, "utf-8");
+    const payload = JSON.parse(payloadContent) as { model?: string; messages?: Message[] };
+    const bundleDir = path.join(process.cwd(), ".jeo", "memory");
+    await saveRawPayload(bundleDir, payload);
     if (Array.isArray(payload.messages)) {
       await distillSessionMemory(payload.messages, process.cwd(), { model: payload.model });
     }
@@ -199,3 +453,4 @@ export async function runMemoryDistillCommand(args: string[]): Promise<void> {
     await fs.unlink(payloadPath).catch(() => {});
   }
 }
+