@fractary/codex 0.12.17 → 0.12.18

package/dist/index.cjs

@@ -7,6 +7,7 @@ var zod = require('zod');
 var fs4 = require('fs/promises');
 var util = require('util');
 var yaml2 = require('js-yaml');
+var fs = require('fs');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -35,6 +36,12 @@ var yaml2__namespace = /*#__PURE__*/_interopNamespace(yaml2);
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
@@ -540,6 +547,22 @@ var init_built_in = __esm({
         defaultTtl: exports.TTL.TWO_WEEKS,
         archiveAfterDays: null,
         archiveStorage: null
+      },
+      memory: {
+        name: "memory",
+        description: "Institutional memory entries (troubleshooting, decisions, patterns)",
+        patterns: [
+          "memory/**",
+          ".fractary/codex/memory/**",
+          "**/knowledge-base/**"
+        ],
+        defaultTtl: exports.TTL.ONE_MONTH,
+        archiveAfterDays: 365,
+        archiveStorage: "cloud",
+        syncPatterns: [
+          "memory/**",
+          ".fractary/codex/memory/**"
+        ]
       }
     };
     exports.DEFAULT_TYPE = {
@@ -6725,6 +6748,583 @@ function createHealthChecker(options = {}) {
   return new HealthChecker(options);
 }
 
+// src/memory/types.ts
+var MEMORY_TYPE_PREFIXES = {
+  "troubleshooting": "TS",
+  "architectural-decision": "AD",
+  "performance": "PF",
+  "pattern": "PT",
+  "integration": "IN",
+  "convention": "CV"
+};
+var DEFAULT_MEMORY_CONFIG = {
+  memoryDir: ".fractary/codex/memory",
+  cacheDir: ".fractary/codex/cache",
+  syncedMemoryPatterns: [
+    ".fractary/codex/cache/projects/*/*/.fractary/codex/memory/**/*.md"
+  ]
+};
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return null;
+  const yaml3 = match[1];
+  const frontmatter = {};
+  let currentKey = "";
+  let inArray = false;
+  let arrayValues = [];
+  for (const line of yaml3.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    if (trimmed.startsWith("- ") && inArray) {
+      let value = trimmed.slice(2).trim();
+      if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+        value = value.slice(1, -1);
+      }
+      arrayValues.push(value);
+      continue;
+    }
+    if (inArray && currentKey) {
+      frontmatter[currentKey] = arrayValues;
+      inArray = false;
+      arrayValues = [];
+      currentKey = "";
+    }
+    const kvMatch = trimmed.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\s*:\s*(.*)$/);
+    if (kvMatch) {
+      const key = kvMatch[1];
+      let value = kvMatch[2].trim();
+      if (value === "" || value === "[]") {
+        currentKey = key;
+        inArray = true;
+        arrayValues = [];
+        if (value === "[]") {
+          frontmatter[key] = [];
+          inArray = false;
+          currentKey = "";
+        }
+        continue;
+      }
+      if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+        value = value.slice(1, -1);
+      }
+      if (value === "true") frontmatter[key] = true;
+      else if (value === "false") frontmatter[key] = false;
+      else if (value === "null") frontmatter[key] = null;
+      else if (/^-?\d+$/.test(value)) frontmatter[key] = parseInt(value, 10);
+      else if (/^-?\d+\.\d+$/.test(value)) frontmatter[key] = parseFloat(value);
+      else frontmatter[key] = value;
+    }
+  }
+  if (inArray && currentKey) {
+    frontmatter[currentKey] = arrayValues;
+  }
+  if (!frontmatter.title && !frontmatter.memory_id && !frontmatter.id) {
+    return null;
+  }
+  return frontmatter;
+}
+function findMarkdownFiles(dir) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path3.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        results.push(...findMarkdownFiles(fullPath));
+      } else if (entry.isFile() && entry.name.endsWith(".md")) {
+        results.push(fullPath);
+      }
+    }
+  } catch {
+  }
+  return results;
+}
+function findSyncedMemoryFiles(cacheDir) {
+  const results = [];
+  const projectsDir = path3.join(cacheDir, "projects");
+  if (!fs.existsSync(projectsDir)) return results;
+  try {
+    const orgs = fs.readdirSync(projectsDir, { withFileTypes: true });
+    for (const org of orgs) {
+      if (!org.isDirectory()) continue;
+      const orgDir = path3.join(projectsDir, org.name);
+      const projects = fs.readdirSync(orgDir, { withFileTypes: true });
+      for (const project of projects) {
+        if (!project.isDirectory()) continue;
+        const memoryDir = path3.join(orgDir, project.name, ".fractary", "codex", "memory");
+        if (!fs.existsSync(memoryDir)) continue;
+        const files = findMarkdownFiles(memoryDir);
+        const source = `${org.name}/${project.name}`;
+        for (const file of files) {
+          results.push({ path: file, source });
+        }
+      }
+    }
+  } catch {
+  }
+  return results;
+}
+var MemorySearcher = class {
+  config;
+  projectRoot;
+  constructor(projectRoot, config) {
+    this.projectRoot = projectRoot;
+    this.config = { ...DEFAULT_MEMORY_CONFIG, ...config };
+  }
+  /**
+   * Search memories with cascading scope
+   *
+   * 1. Project memories (highest priority)
+   * 2. Synced memories from other projects
+   */
+  search(query) {
+    const index = this.loadOrRebuildIndex();
+    let candidates = index.entries.filter((entry) => {
+      const fm = entry.frontmatter;
+      if (query.memory_type && fm.memory_type !== query.memory_type) return false;
+      if (query.category && fm.category !== query.category) return false;
+      if (query.phase) {
+        const phases = fm.phases || (fm.phase ? [fm.phase] : []);
+        if (!phases.includes(query.phase)) return false;
+      }
+      if (query.agent) {
+        const agents = fm.agents || (fm.agent ? [fm.agent] : []);
+        if (!agents.includes(query.agent)) return false;
+      }
+      if (query.tags && query.tags.length > 0) {
+        if (!fm.tags || !query.tags.some((t) => fm.tags.includes(t))) return false;
+      }
+      if (query.status && fm.status !== query.status) return false;
+      return true;
+    });
+    const scored = candidates.map((entry) => ({
+      entry,
+      score: this.calculateRelevanceScore(entry, query),
+      source: entry.source,
+      filePath: entry.file_path
+    }));
+    scored.sort((a, b) => b.score - a.score);
+    const limit = query.limit || 20;
+    return scored.slice(0, limit);
+  }
+  /**
+   * Calculate relevance score for a memory entry
+   */
+  calculateRelevanceScore(entry, query) {
+    const fm = entry.frontmatter;
+    let score = 0;
+    score += Math.min((fm.success_count || 0) * 2, 40);
+    if (fm.status === "verified" || fm.verified === true) {
+      score += 10;
+    }
+    if (query.agent) {
+      const agents = fm.agents || (fm.agent ? [fm.agent] : []);
+      if (agents.includes(query.agent)) {
+        score += 20;
+      }
+    }
+    if (query.phase) {
+      const phases = fm.phases || (fm.phase ? [fm.phase] : []);
+      if (phases.includes(query.phase)) {
+        score += 10;
+      }
+    }
+    score += entry.source === "local" ? 10 : 5;
+    if (query.text) {
+      const queryLower = query.text.toLowerCase();
+      if (fm.symptoms && fm.symptoms.some((s) => s.toLowerCase().includes(queryLower) || queryLower.includes(s.toLowerCase()))) {
+        score += 15;
+      }
+      if (fm.keywords && fm.keywords.some((k) => queryLower.includes(k.toLowerCase()))) {
+        score += 5;
+      }
+      if (fm.description && fm.description.toLowerCase().includes(queryLower)) {
+        score += 8;
+      }
+      if (fm.title && fm.title.toLowerCase().includes(queryLower)) {
+        score += 5;
+      }
+    }
+    return score;
+  }
+  /**
+   * Load the frontmatter index from cache, or rebuild if stale
+   */
+  loadOrRebuildIndex() {
+    const indexPath = path3.join(this.projectRoot, this.config.cacheDir, "memory-index.json");
+    let existingIndex = null;
+    if (fs.existsSync(indexPath)) {
+      try {
+        const raw = fs.readFileSync(indexPath, "utf-8");
+        existingIndex = JSON.parse(raw);
+      } catch {
+        existingIndex = null;
+      }
+    }
+    const memoryDir = path3.join(this.projectRoot, this.config.memoryDir);
+    const localFiles = findMarkdownFiles(memoryDir);
+    const syncedFiles = findSyncedMemoryFiles(path3.join(this.projectRoot, this.config.cacheDir));
+    const needsRebuild = !existingIndex || this.isIndexStale(existingIndex, localFiles, syncedFiles.map((f) => f.path));
+    if (!needsRebuild && existingIndex) {
+      return existingIndex;
+    }
+    return this.rebuildIndex(localFiles, syncedFiles, indexPath);
+  }
+  /**
+   * Check if the index is stale (any source file newer than index)
+   */
+  isIndexStale(index, localFiles, syncedFilePaths) {
+    const indexTime = new Date(index.built_at).getTime();
+    const allFiles = [...localFiles, ...syncedFilePaths];
+    for (const file of allFiles) {
+      try {
+        const stat = fs.statSync(file);
+        if (stat.mtimeMs > indexTime) return true;
+      } catch {
+      }
+    }
+    const indexedPaths = new Set(index.entries.map((e) => e.file_path));
+    for (const file of allFiles) {
+      if (!indexedPaths.has(file)) return true;
+    }
+    return false;
+  }
+  /**
+   * Rebuild the frontmatter index from all memory sources
+   */
+  rebuildIndex(localFiles, syncedFiles, indexPath) {
+    const entries = [];
+    for (const file of localFiles) {
+      const entry = this.indexFile(file, "local");
+      if (entry) entries.push(entry);
+    }
+    for (const { path: path9, source } of syncedFiles) {
+      const entry = this.indexFile(path9, source);
+      if (entry) entries.push(entry);
+    }
+    const index = {
+      version: 1,
+      built_at: (/* @__PURE__ */ new Date()).toISOString(),
+      entries
+    };
+    try {
+      const dir = path3.dirname(indexPath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+      fs.writeFileSync(indexPath, JSON.stringify(index, null, 2), "utf-8");
+    } catch {
+    }
+    return index;
+  }
+  /**
+   * Index a single memory file by parsing its frontmatter
+   */
+  indexFile(filePath, source) {
+    try {
+      const content = fs.readFileSync(filePath, "utf-8");
+      const frontmatter = parseFrontmatter(content);
+      if (!frontmatter) return null;
+      const stat = fs.statSync(filePath);
+      return {
+        file_path: filePath,
+        mtime: stat.mtime.toISOString(),
+        source,
+        frontmatter
+      };
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Invalidate the index cache (call after writing memories)
+   */
+  invalidateIndex() {
+    const indexPath = path3.join(this.projectRoot, this.config.cacheDir, "memory-index.json");
+    try {
+      if (fs.existsSync(indexPath)) {
+        const { unlinkSync } = __require("fs");
+        unlinkSync(indexPath);
+      }
+    } catch {
+    }
+  }
+};
+function sanitizeSlug(text, maxLength = 50) {
+  return text.toLowerCase().replace(/[^a-z0-9\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").slice(0, maxLength);
+}
+function serializeFrontmatter(fm) {
+  const lines = ["---"];
+  for (const [key, value] of Object.entries(fm)) {
+    if (value === void 0 || value === null) continue;
+    if (Array.isArray(value)) {
+      if (value.length === 0) {
+        lines.push(`${key}: []`);
+      } else {
+        lines.push(`${key}:`);
+        for (const item of value) {
+          const itemStr = typeof item === "string" && (item.includes(":") || item.includes('"') || item.includes("'")) ? `"${item.replace(/"/g, '\\"')}"` : String(item);
+          lines.push(`  - ${itemStr}`);
+        }
+      }
+    } else if (typeof value === "string") {
+      if (value.includes(":") || value.includes('"') || value.includes("'") || value.includes("\n")) {
+        lines.push(`${key}: "${value.replace(/"/g, '\\"')}"`);
+      } else {
+        lines.push(`${key}: ${value}`);
+      }
+    } else {
+      lines.push(`${key}: ${value}`);
+    }
+  }
+  lines.push("---");
+  return lines.join("\n");
+}
+function getNextSequence(typeDir, prefix) {
+  if (!fs.existsSync(typeDir)) return 1;
+  let maxSeq = 0;
+  try {
+    const files = fs.readdirSync(typeDir);
+    const pattern = new RegExp(`^MEM-${prefix}-(\\d+)-`);
+    for (const file of files) {
+      const match = file.match(pattern);
+      if (match) {
+        const seq = parseInt(match[1], 10);
+        if (seq > maxSeq) maxSeq = seq;
+      }
+    }
+  } catch {
+  }
+  return maxSeq + 1;
+}
+function calculateSimilarity(existing, newEntry) {
+  let score = 0;
+  let factors = 0;
+  if (existing.title && newEntry.title) {
+    const existingWords = new Set(existing.title.toLowerCase().split(/\s+/));
+    const newWords = new Set(newEntry.title.toLowerCase().split(/\s+/));
+    const intersection = [...existingWords].filter((w) => newWords.has(w)).length;
+    const union = (/* @__PURE__ */ new Set([...existingWords, ...newWords])).size;
+    score += union > 0 ? intersection / union : 0;
+    factors++;
+  }
+  if (existing.symptoms && newEntry.symptoms) {
+    const existingSymptoms = new Set(existing.symptoms.map((s) => s.toLowerCase()));
+    const newSymptoms = new Set(newEntry.symptoms.map((s) => s.toLowerCase()));
+    const intersection = [...existingSymptoms].filter((s) => newSymptoms.has(s)).length;
+    const union = (/* @__PURE__ */ new Set([...existingSymptoms, ...newSymptoms])).size;
+    score += union > 0 ? intersection / union : 0;
+    factors++;
+  }
+  if (existing.category && newEntry.category) {
+    score += existing.category === newEntry.category ? 1 : 0;
+    factors++;
+  }
+  if (existing.memory_type && newEntry.memory_type) {
+    score += existing.memory_type === newEntry.memory_type ? 1 : 0;
+    factors++;
+  }
+  return factors > 0 ? score / factors : 0;
+}
+var MemoryWriter = class {
+  config;
+  projectRoot;
+  searcher;
+  constructor(projectRoot, config) {
+    this.projectRoot = projectRoot;
+    this.config = { ...DEFAULT_MEMORY_CONFIG, ...config };
+    this.searcher = new MemorySearcher(projectRoot, config);
+  }
+  /**
+   * Write a new memory entry
+   *
+   * Handles ID generation, deduplication check, file creation,
+   * and index invalidation.
+   */
+  write(options) {
+    const { memory_type, title, description, body, frontmatter } = options;
+    const dupResult = this.checkDuplicate(frontmatter, memory_type);
+    if (dupResult) {
+      return {
+        memory_id: dupResult.memory_id,
+        file_path: dupResult.file_path,
+        deduplicated: true,
+        existing_id: dupResult.memory_id
+      };
+    }
+    const prefix = MEMORY_TYPE_PREFIXES[memory_type];
+    const typeDir = path3.join(this.projectRoot, this.config.memoryDir, memory_type);
+    const seq = getNextSequence(typeDir, prefix);
+    const slug = sanitizeSlug(title);
+    const memoryId = `MEM-${prefix}-${String(seq).padStart(3, "0")}-${slug}`;
+    const fullFrontmatter = {
+      title,
+      description,
+      memory_type,
+      memory_id: memoryId,
+      status: "draft",
+      created: (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
+      verified: false,
+      success_count: 0,
+      ...frontmatter
+    };
+    fullFrontmatter.memory_type = memory_type;
+    fullFrontmatter.memory_id = memoryId;
+    const fileContent = `${serializeFrontmatter(fullFrontmatter)}
+
+${body}
+`;
+    const fileName = `${memoryId}.md`;
+    const filePath = path3.join(typeDir, fileName);
+    if (!fs.existsSync(typeDir)) {
+      fs.mkdirSync(typeDir, { recursive: true });
+    }
+    fs.writeFileSync(filePath, fileContent, "utf-8");
+    this.searcher.invalidateIndex();
+    return {
+      memory_id: memoryId,
+      file_path: filePath,
+      deduplicated: false
+    };
+  }
+  /**
+   * Update an existing memory's frontmatter
+   */
+  update(memoryId, changes) {
+    const filePath = this.findMemoryFile(memoryId);
+    if (!filePath) {
+      throw new Error(`Memory not found: ${memoryId}`);
+    }
+    const content = fs.readFileSync(filePath, "utf-8");
+    const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!fmMatch) {
+      throw new Error(`Invalid memory file format: ${filePath}`);
+    }
+    const existingContent = fmMatch[1];
+    const bodyContent = fmMatch[2];
+    const lines = existingContent.split("\n");
+    const updatedFm = {};
+    let currentKey = "";
+    let inArray = false;
+    let arrayValues = [];
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      if (trimmed.startsWith("- ") && inArray) {
+        let value = trimmed.slice(2).trim();
+        if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+          value = value.slice(1, -1);
+        }
+        arrayValues.push(value);
+        continue;
+      }
+      if (inArray && currentKey) {
+        updatedFm[currentKey] = arrayValues;
+        inArray = false;
+        arrayValues = [];
+        currentKey = "";
+      }
+      const kvMatch = trimmed.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\s*:\s*(.*)$/);
+      if (kvMatch) {
+        const key = kvMatch[1];
+        let value = kvMatch[2].trim();
+        if (value === "" || value === "[]") {
+          currentKey = key;
+          inArray = true;
+          arrayValues = [];
+          if (value === "[]") {
+            updatedFm[key] = [];
+            inArray = false;
+            currentKey = "";
+          }
+          continue;
+        }
+        if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+          value = value.slice(1, -1);
+        }
+        if (value === "true") updatedFm[key] = true;
+        else if (value === "false") updatedFm[key] = false;
+        else if (value === "null") updatedFm[key] = null;
+        else if (/^-?\d+$/.test(value)) updatedFm[key] = parseInt(value, 10);
+        else if (/^-?\d+\.\d+$/.test(value)) updatedFm[key] = parseFloat(value);
+        else updatedFm[key] = value;
+      }
+    }
+    if (inArray && currentKey) {
+      updatedFm[currentKey] = arrayValues;
+    }
+    const merged = { ...updatedFm, ...changes, updated: (/* @__PURE__ */ new Date()).toISOString().split("T")[0] };
+    const newContent = `${serializeFrontmatter(merged)}
+
+${bodyContent}`;
+    fs.writeFileSync(filePath, newContent, "utf-8");
+    this.searcher.invalidateIndex();
+  }
+  /**
+   * Deprecate a memory
+   */
+  deprecate(memoryId, reason, supersededBy) {
+    const changes = {
+      status: "deprecated",
+      deprecated_reason: reason
+    };
+    if (supersededBy) {
+      changes.superseded_by = supersededBy;
+    }
+    this.update(memoryId, changes);
+  }
+  /**
+   * Check for duplicate memories (>0.95 similarity)
+   */
+  checkDuplicate(frontmatter, memoryType) {
+    const results = this.searcher.search({
+      memory_type: memoryType,
+      category: frontmatter.category,
+      limit: 10
+    });
+    for (const result of results) {
+      const similarity = calculateSimilarity(result.entry.frontmatter, frontmatter);
+      if (similarity > 0.95) {
+        return {
+          memory_id: result.entry.frontmatter.memory_id,
+          file_path: result.filePath
+        };
+      }
+    }
+    return null;
+  }
+  /**
+   * Find a memory file by its ID
+   */
+  findMemoryFile(memoryId) {
+    const memoryDir = path3.join(this.projectRoot, this.config.memoryDir);
+    if (!fs.existsSync(memoryDir)) return null;
+    const files = findMarkdownFilesRecursive(memoryDir);
+    for (const file of files) {
+      if (file.includes(memoryId)) return file;
+    }
+    return null;
+  }
+};
+function findMarkdownFilesRecursive(dir) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path3.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        results.push(...findMarkdownFilesRecursive(fullPath));
+      } else if (entry.isFile() && entry.name.endsWith(".md")) {
+        results.push(fullPath);
+      }
+    }
+  } catch {
+  }
+  return results;
+}
+
 // src/client/codex-client.ts
 var CodexClient = class _CodexClient {
   cache;
@@ -7044,11 +7644,15 @@ exports.CommonRules = CommonRules;
 exports.ConfigManager = ConfigManager;
 exports.DEFAULT_FRACTARY_GITIGNORE = DEFAULT_FRACTARY_GITIGNORE;
 exports.DEFAULT_GLOBAL_EXCLUDES = DEFAULT_GLOBAL_EXCLUDES;
+exports.DEFAULT_MEMORY_CONFIG = DEFAULT_MEMORY_CONFIG;
 exports.DEFAULT_MIGRATION_OPTIONS = DEFAULT_MIGRATION_OPTIONS;
 exports.DEFAULT_PERMISSION_CONFIG = DEFAULT_PERMISSION_CONFIG;
 exports.DEFAULT_SYNC_CONFIG = DEFAULT_SYNC_CONFIG;
 exports.HealthChecker = HealthChecker;
 exports.LEGACY_PATTERNS = LEGACY_PATTERNS;
+exports.MEMORY_TYPE_PREFIXES = MEMORY_TYPE_PREFIXES;
+exports.MemorySearcher = MemorySearcher;
+exports.MemoryWriter = MemoryWriter;
 exports.MetadataSchema = MetadataSchema;
 exports.PERMISSION_LEVEL_ORDER = PERMISSION_LEVEL_ORDER;
 exports.PermissionDeniedError = PermissionDeniedError;