jeo-code 0.6.15 → 0.6.17

package/CHANGELOG.md

@@ -6,6 +6,18 @@ 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.17] - 2026-06-17
+_Legacy MEMORY.md migrates losslessly into the OKF concept bundle, with a one-shot command and a rollback toggle._
+
+### Added
+- **`jeo memory-migrate` — legacy memory → OKF bundle migration (OKF Sprint 05).** A one-shot, idempotent migration converts the legacy single-doc `.jeo/memory/MEMORY.md` into the type-partitioned OKF concept bundle: `parseLegacyMemory` maps each `## heading` to a concept type (commands/gotchas/preferences/repo-facts, unknown → RepoFact) and splits top-level bullets into concepts (`**title**: description` form recognized, indented continuation lines become the body — lossless), then `migrateLegacyMemory` writes each concept atomically under `facts/`/`commands/`/`gotchas/`/`preferences/`, (re)builds `index.md`/`log.md`, and renames the legacy doc to `MEMORY.md.bak` for rollback. Re-running is a no-op once the bundle has concepts. The bundle is the default read path; `JEO_MEMORY_LEGACY=1` is a new rollback toggle that ignores the bundle and reads the legacy doc (or its `.bak` backup) through the same injection-hardening, while `JEO_NO_MEMORY=1` still wins over everything.
+
+## [0.6.16] - 2026-06-17
+_OKF memory grows a concept cross-link graph: 1-hop search expansion, bundle lint, graphify-optional._
+
+### Added
+- **Concept cross-link graph for the memory bundle (OKF Sprint 04).** A new zero-dependency `src/agent/memory-graph.ts` treats the OKF bundle as a first-class link graph — nodes are concept IDs, edges are the markdown links a concept's body points at another concept, and broken links are tolerated (captured for lint, never thrown). It powers `buildConceptGraph` / `expandByGraph` / `resolveLinkTarget` / `lintConceptGraph` / `graphifyAvailable`. Memory injection now applies **1-hop graph expansion**: a concept the task query directly hits lifts its link-neighbours ahead of unrelated noise (still within `MEMORY_INJECT_MAX_CHARS`). New `lintMemoryBundle(cwd)` reports orphan concepts, broken links, and duplicate-title merge candidates. The optional `graphify` tool is a best-effort enrichment layer only — every feature runs fully on the built-in graph when it is absent (graceful degradation), and `graphify update` is never run against the markdown bundle.
+
 ## [0.6.15] - 2026-06-17
 _Query-aware OKF memory injection with budget-priority selection, and a truthful end-of-turn Todos receipt._
 

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.17]** (2026-06-17) — Legacy MEMORY.md migrates losslessly into the OKF concept bundle, with a one-shot command and a rollback toggle.
+- **[0.6.16]** (2026-06-17) — OKF memory grows a concept cross-link graph: 1-hop search expansion, bundle lint, graphify-optional.
 - **[0.6.15]** (2026-06-17) — Query-aware OKF memory injection with budget-priority selection, and a truthful end-of-turn Todos receipt.
 - **[0.6.14]** (2026-06-16) — Memory distillation survives malformed model output, and stream-idle stalls retry instead of failing the turn.
 - **[0.6.13]** (2026-06-16) — `team` engine: concrete uncommitted-work reporting and stricter empty-run handling.
-- **[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.
 
 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.17]** (2026-06-17) — Legacy MEMORY.md migrates losslessly into the OKF concept bundle, with a one-shot command and a rollback toggle.
+- **[0.6.16]** (2026-06-17) — OKF memory grows a concept cross-link graph: 1-hop search expansion, bundle lint, graphify-optional.
 - **[0.6.15]** (2026-06-17) — Query-aware OKF memory injection with budget-priority selection, and a truthful end-of-turn Todos receipt.
 - **[0.6.14]** (2026-06-16) — Memory distillation survives malformed model output, and stream-idle stalls retry instead of failing the turn.
 - **[0.6.13]** (2026-06-16) — `team` engine: concrete uncommitted-work reporting and stricter empty-run handling.
-- **[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.
 
 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.17]** (2026-06-17) — Legacy MEMORY.md migrates losslessly into the OKF concept bundle, with a one-shot command and a rollback toggle.
+- **[0.6.16]** (2026-06-17) — OKF memory grows a concept cross-link graph: 1-hop search expansion, bundle lint, graphify-optional.
 - **[0.6.15]** (2026-06-17) — Query-aware OKF memory injection with budget-priority selection, and a truthful end-of-turn Todos receipt.
 - **[0.6.14]** (2026-06-16) — Memory distillation survives malformed model output, and stream-idle stalls retry instead of failing the turn.
 - **[0.6.13]** (2026-06-16) — `team` engine: concrete uncommitted-work reporting and stricter empty-run handling.
-- **[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.
 
 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.17]** (2026-06-17) — Legacy MEMORY.md migrates losslessly into the OKF concept bundle, with a one-shot command and a rollback toggle.
+- **[0.6.16]** (2026-06-17) — OKF memory grows a concept cross-link graph: 1-hop search expansion, bundle lint, graphify-optional.
 - **[0.6.15]** (2026-06-17) — Query-aware OKF memory injection with budget-priority selection, and a truthful end-of-turn Todos receipt.
 - **[0.6.14]** (2026-06-16) — Memory distillation survives malformed model output, and stream-idle stalls retry instead of failing the turn.
 - **[0.6.13]** (2026-06-16) — `team` engine: concrete uncommitted-work reporting and stricter empty-run handling.
-- **[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.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jeo-code",
-  "version": "0.6.15",
+  "version": "0.6.17",
 
   "description": "Clean, highly optimized AI coding agent using spec-first loop",
   "type": "module",

package/src/agent/AGENTS.md

@@ -17,7 +17,9 @@ The core runtime loop, tool registry, session management, and state persistence
 | `hooks.ts` | Brief description of purpose |
 | `json.ts` | Brief description of purpose |
 | `loop.ts` | The primary execution loop orchestrating model calls and tool execution |
-| `memory.ts` | Brief description of purpose |
+| `memory.ts` | OKF concept-bundle memory: session distill, query-aware budget injection, legacy MEMORY.md migration (`migrateLegacyMemory`) + `JEO_MEMORY_LEGACY` rollback toggle |
+| `memory-okf.ts` | OKF v0.1 format layer: frontmatter parse/serialize, concept IDs, conformance validation |
+| `memory-graph.ts` | Concept cross-link graph: build/expand (1-hop search), broken-link-tolerant lint, optional graphify detection |
 | `model-recency.ts` | Brief description of purpose |
 | `output-minimizer.ts` | Brief description of purpose |
 | `output-util.ts` | Brief description of purpose |

package/src/agent/memory-graph.ts

@@ -0,0 +1,198 @@
+/**
+ * Concept cross-link graph for the OKF memory bundle — OKF Sprint 04 (Graph Layer).
+ *
+ * A first-class, zero-dependency link graph over the concept bundle: nodes are
+ * concept IDs (bundle-relative path minus `.md`), edges are the markdown links a
+ * concept's body points at another concept. Broken links (targets with no node)
+ * are TOLERATED — OKF's lenient model treats them as "knowledge not yet written"
+ * and the lint pass reports them rather than failing.
+ *
+ * Used to (1) strengthen Sprint 03 search by 1-hop graph expansion (a concept
+ * the query directly hits pulls in its neighbours as injection candidates) and
+ * (2) lint the bundle (orphans / broken links / duplicate-title candidates).
+ *
+ * graphify (the external graph tool) is an OPTIONAL second layer: when present
+ * it can enrich, but every feature here runs fully on the built-in graph so the
+ * bundle works with graphify absent (graceful degradation). Note: `graphify
+ * update` is for CODE repos only — never run it against this markdown bundle.
+ *
+ * Design contract: docs/okf_mem/sprint-04-graph-layer/index.md
+ */
+import * as posix from "node:path/posix";
+import { conceptId } from "./memory-okf";
+
+/** Minimal shape the graph needs from a concept (a `Concept` satisfies it). */
+export interface GraphConcept {
+  /** Bundle-relative path, e.g. `commands/bun-test.md`. */
+  relPath: string;
+  /** Markdown body; scanned for `](target)` links. */
+  body: string;
+  /** Optional concept title (for duplicate-title lint). */
+  title?: string;
+}
+
+/** A directed cross-link graph over concept IDs. */
+export interface ConceptGraph {
+  /** All concept IDs present in the bundle. */
+  nodes: Set<string>;
+  /** from-ID → set of to-IDs that resolve to a real node. */
+  edges: Map<string, Set<string>>;
+  /** from-ID → set of link targets that have NO node (tolerated broken links). */
+  broken: Map<string, Set<string>>;
+}
+
+/** A markdown inline link `](target)` — captures the target, not the label. */
+const LINK_RE = /\]\(([^)\s]+)\)/g;
+
+function addEdge(map: Map<string, Set<string>>, from: string, to: string): void {
+  const set = map.get(from) ?? new Set<string>();
+  set.add(to);
+  map.set(from, set);
+}
+
+/**
+ * Resolve a markdown link target (as written in `from`'s body) to a concept ID,
+ * or `null` when it is not an in-bundle concept reference. Handles:
+ *  - external/protocol links (`http://…`, `mailto:`) → null
+ *  - pure anchors (`#section`) → null
+ *  - bundle-absolute (`/commands/x.md`) → `commands/x`
+ *  - relative (`../facts/x.md`) → resolved against `from`'s directory
+ * Anchors and query strings are stripped before ID normalization.
+ */
+export function resolveLinkTarget(fromId: string, rawTarget: string): string | null {
+  let t = rawTarget.trim();
+  if (!t || t.startsWith("#") || /^[a-z][a-z0-9+.-]*:/i.test(t)) return null; // external/protocol/anchor
+  t = t.split("#")[0]!.split("?")[0]!.trim();
+  if (!t) return null;
+  let full: string;
+  if (t.startsWith("/")) {
+    full = t.replace(/^\/+/, "");
+  } else {
+    const slash = fromId.lastIndexOf("/");
+    const fromDir = slash === -1 ? "" : fromId.slice(0, slash);
+    full = fromDir ? posix.normalize(`${fromDir}/${t}`) : posix.normalize(t);
+  }
+  if (!full || full.startsWith("..")) return null; // escaped the bundle — not a concept ref
+  const id = conceptId(full);
+  return id || null;
+}
+
+/** Build the cross-link graph from a set of concepts. Broken links are kept
+ *  (in `broken`) rather than dropped, so lint can surface them. */
+export function buildConceptGraph(concepts: GraphConcept[]): ConceptGraph {
+  const nodes = new Set(concepts.map(c => conceptId(c.relPath)));
+  const edges = new Map<string, Set<string>>();
+  const broken = new Map<string, Set<string>>();
+  for (const c of concepts) {
+    const from = conceptId(c.relPath);
+    LINK_RE.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = LINK_RE.exec(c.body)) !== null) {
+      const to = resolveLinkTarget(from, m[1]!);
+      if (!to || to === from) continue;
+      if (nodes.has(to)) addEdge(edges, from, to);
+      else addEdge(broken, from, to);
+    }
+  }
+  return { nodes, edges, broken };
+}
+
+/** Undirected adjacency (links are navigable both ways for discovery). */
+function undirectedAdjacency(graph: ConceptGraph): Map<string, Set<string>> {
+  const adj = new Map<string, Set<string>>();
+  for (const [from, tos] of graph.edges) {
+    for (const to of tos) {
+      addEdge(adj, from, to);
+      addEdge(adj, to, from);
+    }
+  }
+  return adj;
+}
+
+/**
+ * Expand a set of seed concept IDs along the (undirected) link graph by up to
+ * `hops` steps, returning seeds + reachable neighbours. Seeds not present as
+ * nodes are dropped. With `hops` 0 this is just the valid seeds.
+ */
+export function expandByGraph(seedIds: Iterable<string>, graph: ConceptGraph, hops = 1): Set<string> {
+  const adj = undirectedAdjacency(graph);
+  const result = new Set<string>();
+  for (const id of seedIds) if (graph.nodes.has(id)) result.add(id);
+  let frontier = [...result];
+  for (let h = 0; h < hops && frontier.length > 0; h++) {
+    const next: string[] = [];
+    for (const id of frontier) {
+      for (const nb of adj.get(id) ?? []) {
+        if (!result.has(nb)) {
+          result.add(nb);
+          next.push(nb);
+        }
+      }
+    }
+    frontier = next;
+  }
+  return result;
+}
+
+/** A lenient lint report over the concept graph (warnings, never hard failures). */
+export interface GraphLintReport {
+  /** Concept IDs with no incoming or outgoing edges. */
+  orphans: string[];
+  /** Links whose target resolves to no concept node. */
+  brokenLinks: { from: string; to: string }[];
+  /** Concepts that share a (case-insensitive) title — merge/contradiction candidates. */
+  duplicates: { title: string; ids: string[] }[];
+}
+
+/** Lint the bundle's graph: orphan concepts, broken links, duplicate titles.
+ *  Purely advisory — mirrors llm-wiki's lint pass (broken/orphan/contradiction). */
+export function lintConceptGraph(concepts: GraphConcept[], graph: ConceptGraph): GraphLintReport {
+  const linked = new Set<string>();
+  for (const [from, tos] of graph.edges) {
+    if (tos.size > 0) linked.add(from);
+    for (const to of tos) linked.add(to);
+  }
+  const orphans = [...graph.nodes].filter(id => !linked.has(id)).sort();
+
+  const brokenLinks: { from: string; to: string }[] = [];
+  for (const [from, tos] of graph.broken) {
+    for (const to of tos) brokenLinks.push({ from, to });
+  }
+  brokenLinks.sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to));
+
+  const byTitle = new Map<string, string[]>();
+  for (const c of concepts) {
+    const title = (c.title ?? "").trim();
+    if (!title) continue;
+    const key = title.toLowerCase();
+    const ids = byTitle.get(key) ?? [];
+    ids.push(conceptId(c.relPath));
+    byTitle.set(key, ids);
+  }
+  const duplicates: { title: string; ids: string[] }[] = [];
+  for (const ids of byTitle.values()) {
+    if (ids.length > 1) duplicates.push({ title: ids.length ? (concepts.find(c => conceptId(c.relPath) === ids[0])?.title ?? "").trim() : "", ids: ids.sort() });
+  }
+  duplicates.sort((a, b) => a.title.localeCompare(b.title));
+
+  return { orphans, brokenLinks, duplicates };
+}
+
+/**
+ * Whether the optional graphify tool is available on PATH. The built-in graph
+ * is always the primary layer; graphify is a best-effort enrichment, so callers
+ * degrade gracefully when this is false. `detect` is injectable for testing.
+ */
+export function graphifyAvailable(detect: () => boolean = defaultGraphifyDetect): boolean {
+  try {
+    return detect();
+  } catch {
+    return false;
+  }
+}
+
+function defaultGraphifyDetect(): boolean {
+  // Bun.which resolves a binary on PATH without spawning it.
+  const which = (globalThis as { Bun?: { which?: (cmd: string) => string | null } }).Bun?.which;
+  return typeof which === "function" ? which("graphify") != null : false;
+}

package/src/agent/memory.ts

@@ -15,8 +15,9 @@ 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 { parseConcept, serializeConcept, slugify, isReservedFile, conceptId } from "./memory-okf";
 import { tryExtractJsonObject } from "./json";
+import { buildConceptGraph, expandByGraph, lintConceptGraph, type GraphLintReport } from "./memory-graph";
 
 /** On-disk document cap — the distill prompt instructs the model to stay under it. */
 export const MEMORY_MAX_CHARS = 6_000;
@@ -49,6 +50,129 @@ export async function loadMemory(cwd: string): Promise<string> {
   }
 }
 
+/** A concept extracted from a legacy single-doc MEMORY.md during migration. */
+export interface MigratedConcept {
+  type: string;
+  title: string;
+  description: string;
+  body: string;
+}
+
+/** Map a legacy `## heading` to a jeo concept type. Lenient keyword match —
+ *  unknown headings default to RepoFact so nothing is dropped. */
+function headingToType(heading: string): string {
+  const h = heading.toLowerCase();
+  if (/\bcommand/.test(h)) return "Command";
+  if (/gotcha|pitfall|caveat/.test(h)) return "Gotcha";
+  if (/pref/.test(h)) return "UserPreference";
+  if (/repo|fact/.test(h)) return "RepoFact";
+  return "RepoFact";
+}
+
+/** Parse a legacy 4-heading MEMORY.md into concepts: each `## heading` sets the
+ *  type, each top-level bullet becomes a concept (`**title**: description` form
+ *  recognized, indented continuation lines become the body). Lossless: a plain
+ *  bullet keeps its whole text as the title. */
+export function parseLegacyMemory(doc: string): MigratedConcept[] {
+  const concepts: MigratedConcept[] = [];
+  let currentType = "RepoFact";
+  let cur: MigratedConcept | null = null;
+  const flush = () => {
+    if (cur) {
+      cur.body = cur.body.replace(/\n+$/, "");
+      concepts.push(cur);
+      cur = null;
+    }
+  };
+  for (const line of doc.split("\n")) {
+    const heading = line.match(/^#{1,6}\s+(.*)$/);
+    if (heading) {
+      flush();
+      currentType = headingToType(heading[1]!.trim());
+      continue;
+    }
+    const bullet = line.match(/^\s*[-*]\s+(.*)$/);
+    if (bullet) {
+      flush();
+      const text = bullet[1]!.trim();
+      const bold = text.match(/^\*\*(.+?)\*\*\s*:?\s*(.*)$/);
+      cur = bold
+        ? { type: currentType, title: bold[1]!.trim(), description: bold[2]!.trim(), body: "" }
+        : { type: currentType, title: text, description: "", body: "" };
+      continue;
+    }
+    // Continuation line (typically 2-space indented) belongs to the open concept.
+    if (cur && line.trim() !== "") {
+      cur.body += (cur.body ? "\n" : "") + line.replace(/^ {2}/, "");
+    }
+  }
+  flush();
+  return concepts.filter(c => c.title);
+}
+
+/** Outcome of a one-shot legacy → OKF bundle migration. */
+export interface MigrationResult {
+  migrated: boolean;
+  conceptCount: number;
+  /** Why nothing was migrated (already a bundle / no legacy doc / nothing parsed). */
+  skipped?: string;
+  /** Where the legacy MEMORY.md was preserved for rollback, if migrated. */
+  backupPath?: string;
+}
+
+/**
+ * Migrate a legacy single-doc `.jeo/memory/MEMORY.md` into the OKF concept bundle.
+ * One-shot and IDEMPOTENT: a bundle that already holds concept docs is left
+ * untouched. On success each legacy bullet becomes a type-partitioned concept,
+ * index.md/log.md are (re)built, and the legacy doc is renamed to `MEMORY.md.bak`
+ * so the active path is the bundle while a rollback copy survives.
+ */
+export async function migrateLegacyMemory(cwd: string): Promise<MigrationResult> {
+  const bundleDir = path.join(cwd, ".jeo", "memory");
+  // Idempotent: an existing concept bundle wins — never double-migrate.
+  if ((await loadConcepts(cwd)).length > 0) {
+    return { migrated: false, conceptCount: 0, skipped: "bundle already has concepts" };
+  }
+  const doc = await loadMemory(cwd);
+  if (!doc) return { migrated: false, conceptCount: 0, skipped: "no legacy MEMORY.md to migrate" };
+  const parsed = parseLegacyMemory(doc);
+  if (parsed.length === 0) return { migrated: false, conceptCount: 0, skipped: "no concepts parsed from MEMORY.md" };
+
+  await fs.mkdir(bundleDir, { recursive: true });
+  const written: { title: string; type: string }[] = [];
+  const usedSlugs = new Set<string>();
+  for (const c of parsed) {
+    const dir = DIR_BY_TYPE[c.type] ?? "facts";
+    await fs.mkdir(path.join(bundleDir, dir), { recursive: true });
+    let slug = slugify(c.title);
+    let suffix = 1;
+    while (usedSlugs.has(`${dir}/${slug}`)) slug = `${slugify(c.title)}-${suffix++}`;
+    usedSlugs.add(`${dir}/${slug}`);
+    const frontmatter = {
+      type: c.type,
+      title: c.title,
+      description: c.description,
+      tags: [] as string[],
+      timestamp: new Date().toISOString(),
+      confidence: "high",
+      last_verified: new Date().toISOString().split("T")[0]!,
+      links: [] as string[],
+    };
+    const serialized = serializeConcept(frontmatter, c.body);
+    const fullPath = path.join(bundleDir, dir, `${slug}.md`);
+    const tmpPath = `${fullPath}.tmp-${process.pid}`;
+    await fs.writeFile(tmpPath, serialized, "utf-8");
+    await fs.rename(tmpPath, fullPath);
+    written.push({ title: c.title, type: c.type });
+  }
+  await rebuildIndex(bundleDir);
+  await updateLog(bundleDir, written);
+  // Preserve the legacy doc as a rollback backup, off the active read path.
+  const backupPath = `${memoryFilePath(cwd)}.bak`;
+  await fs.rename(memoryFilePath(cwd), backupPath).catch(() => {});
+  return { migrated: true, conceptCount: written.length, backupPath };
+}
+
 /** Render a single index.md-style section: a `## header` followed by one bullet
  *  per concept (`**title**: description`), with the concept body indented beneath. */
 function renderConceptSection(header: string, list: { title: string; description: string; body: string }[]): string {
@@ -82,6 +206,14 @@ export async function loadConcepts(cwd: string): Promise<Concept[]> {
   return loadConceptsFromBundle(path.join(cwd, ".jeo", "memory"));
 }
 
+/** Lint the concept bundle's cross-link graph (Sprint 04): orphan concepts,
+ *  broken links, and duplicate-title merge candidates. Advisory only — mirrors
+ *  llm-wiki's lint pass. Returns empty lists for an empty/absent bundle. */
+export async function lintMemoryBundle(cwd: string): Promise<GraphLintReport> {
+  const concepts = await loadConcepts(cwd);
+  return lintConceptGraph(concepts, buildConceptGraph(concepts));
+}
+
 async function loadConceptsFromBundle(bundleDir: string): Promise<Concept[]> {
   const files = await findMarkdownFiles(bundleDir);
   const concepts: Concept[] = [];
@@ -146,14 +278,31 @@ export function searchConcepts(concepts: Concept[], query: string): { concept: C
 }
 
 /** Priority order for injection: high-confidence "core" concepts first, then by
- *  query relevance (descending), preserving input order as a stable tiebreak. */
+ *  query relevance (descending), then concepts the relevant ones LINK TO (1-hop
+ *  graph expansion — Sprint 04: a directly-hit concept pulls its neighbours in as
+ *  context ahead of unrelated noise), preserving input order as a stable tiebreak. */
 function priorityOrder(concepts: Concept[], query?: string): Concept[] {
   const tokens = tokenize(query);
+  // 1-hop graph expansion: seed from concepts the query directly hits, then mark
+  // their link-neighbours as "related" so they outrank unrelated zero-score noise.
+  const related = new Set<string>();
+  if (tokens.length > 0) {
+    const graph = buildConceptGraph(concepts);
+    const seeds = concepts.filter(c => scoreConcept(c, tokens) > 0).map(c => conceptId(c.relPath));
+    for (const id of expandByGraph(seeds, graph, 1)) related.add(id);
+  }
   return concepts
-    .map((concept, i) => ({ concept, i, core: concept.confidence === "high", score: scoreConcept(concept, tokens) }))
+    .map((concept, i) => ({
+      concept,
+      i,
+      core: concept.confidence === "high",
+      score: scoreConcept(concept, tokens),
+      related: related.has(conceptId(concept.relPath)),
+    }))
     .sort((a, b) => {
       if (a.core !== b.core) return a.core ? -1 : 1;
       if (b.score !== a.score) return b.score - a.score;
+      if (a.related !== b.related) return a.related ? -1 : 1;
       return a.i - b.i;
     })
     .map(s => s.concept);
@@ -214,12 +363,26 @@ function selectWithinBudget(concepts: Concept[], query: string | undefined, budg
  *  reports: tag-breakout sequences are neutralized and the block is framed as DATA. */
 export async function memoryPromptSection(cwd: string, query?: string): Promise<string> {
   if (jeoEnv("NO_MEMORY") === "1") return "";
+  // Rollback toggle (Sprint 05): JEO_MEMORY_LEGACY=1 forces the legacy single-doc
+  // path, ignoring any concept bundle — reads MEMORY.md, or its migration backup.
+  if (jeoEnv("MEMORY_LEGACY") === "1") {
+    let memory = await loadMemory(cwd);
+    if (!memory) memory = (await fs.readFile(`${memoryFilePath(cwd)}.bak`, "utf-8").catch(() => "")).trim();
+    return memory ? frameMemory(memory) : "";
+  }
   // Prefer the OKF concept bundle (budget-selected); fall back to legacy MEMORY.md.
   const concepts = await loadConcepts(cwd);
   let memory = concepts.length > 0
     ? renderConcepts(selectWithinBudget(concepts, query, MEMORY_INJECT_MAX_CHARS))
     : await loadMemory(cwd);
   if (!memory) return "";
+  return frameMemory(memory);
+}
+
+/** Wrap distilled memory text in the hardened `<project_memory>` block: hard char
+ *  cap, fence-tag neutralization, and DATA framing. Shared by the bundle path and
+ *  the legacy/rollback path so neither can bypass the injection-hardening. */
+function frameMemory(memory: string): string {
   // Backstop: legacy MEMORY.md is a single blob (not concept-selectable), and a
   // pathological single concept can exceed the budget — hard-cap either way.
   if (memory.length > MEMORY_INJECT_MAX_CHARS) {

package/src/cli/runner.ts

@@ -146,6 +146,15 @@ export const COMMANDS: readonly CommandSpec[] = [
       return args => m.runMemoryDistillCommand(args);
     },
   },
+  {
+    name: "memory-migrate",
+    summary: "Migrate a legacy MEMORY.md into the OKF concept bundle (one-shot, idempotent).",
+    usage: "memory-migrate",
+    loader: async () => {
+      const m = await import("../commands/memory-migrate");
+      return args => m.runMemoryMigrateCommand(args);
+    },
+  },
   {
     name: "state",
     summary: "Read or update workflow state receipts under .jeo/state (gjc-state parity).",

package/src/commands/memory-migrate.ts

@@ -0,0 +1,19 @@
+/**
+ * `jeo memory-migrate` — one-shot, idempotent migration of a legacy single-doc
+ * `.jeo/memory/MEMORY.md` into the OKF concept bundle (Sprint 05).
+ *
+ * Safe to re-run: if the bundle already holds concepts it is left untouched.
+ * The legacy doc is preserved as `MEMORY.md.bak` for rollback; set
+ * `JEO_MEMORY_LEGACY=1` to read that backup again if a rollback is needed.
+ */
+import { migrateLegacyMemory } from "../agent/memory";
+
+export async function runMemoryMigrateCommand(_args: string[]): Promise<void> {
+  const result = await migrateLegacyMemory(process.cwd());
+  if (result.migrated) {
+    console.log(`migrated ${result.conceptCount} concept(s) from MEMORY.md → OKF bundle (.jeo/memory/).`);
+    if (result.backupPath) console.log(`legacy doc preserved at ${result.backupPath} (rollback: JEO_MEMORY_LEGACY=1).`);
+  } else {
+    console.log(`nothing to migrate — ${result.skipped}.`);
+  }
+}