@letta-ai/letta-code 0.14.3 → 0.14.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.14.3",
+  "version": "0.14.4",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
   "bin": {
@@ -30,7 +30,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@letta-ai/letta-client": "^1.7.6",
+    "@letta-ai/letta-client": "^1.7.7",
     "glob": "^13.0.0",
     "ink-link": "^5.0.0",
     "open": "^10.2.0",

package/skills/syncing-memory-filesystem/scripts/lib/frontmatter.ts

@@ -0,0 +1,47 @@
+import { createHash } from "node:crypto";
+import { READ_ONLY_BLOCK_LABELS } from "../../../../../agent/memoryConstants";
+
+/**
+ * Read-only block labels. These are API-authoritative.
+ */
+export const READ_ONLY_LABELS = new Set(
+  READ_ONLY_BLOCK_LABELS as readonly string[],
+);
+
+/**
+ * Parse MDX-style frontmatter from content.
+ * This is a copy of parseMdxFrontmatter from src/agent/memory.ts.
+ * The test ensures this stays in sync with the original.
+ */
+export function parseFrontmatter(content: string): {
+  frontmatter: Record<string, string>;
+  body: string;
+} {
+  const frontmatterRegex = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
+  const match = content.match(frontmatterRegex);
+
+  if (!match || !match[1] || !match[2]) {
+    return { frontmatter: {}, body: content };
+  }
+
+  const frontmatterText = match[1];
+  const body = match[2];
+  const frontmatter: Record<string, string> = {};
+
+  // Parse YAML-like frontmatter (simple key: value pairs)
+  for (const line of frontmatterText.split("\n")) {
+    const colonIndex = line.indexOf(":");
+    if (colonIndex > 0) {
+      const key = line.slice(0, colonIndex).trim();
+      const value = line.slice(colonIndex + 1).trim();
+      frontmatter[key] = value;
+    }
+  }
+
+  return { frontmatter, body: body.trim() };
+}
+
+export function hashFileBody(content: string): string {
+  const { body } = parseFrontmatter(content);
+  return createHash("sha256").update(body).digest("hex");
+}

package/skills/syncing-memory-filesystem/scripts/memfs-diff.ts

@@ -18,6 +18,7 @@ import { readdir, readFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { homedir } from "node:os";
 import { join, normalize, relative } from "node:path";
+import { hashFileBody, READ_ONLY_LABELS } from "./lib/frontmatter";
 
 const require = createRequire(import.meta.url);
 const Letta = require("@letta-ai/letta-client")
@@ -45,12 +46,11 @@ function getApiKey(): string {
 
 const MEMORY_FS_STATE_FILE = ".sync-state.json";
 
+// Unified sync state format (matches main memoryFilesystem.ts)
 type SyncState = {
-  systemBlocks: Record<string, string>;
-  systemFiles: Record<string, string>;
-  detachedBlocks: Record<string, string>;
-  detachedFiles: Record<string, string>;
-  detachedBlockIds: Record<string, string>;
+  blockHashes: Record<string, string>;
+  fileHashes: Record<string, string>;
+  blockIds: Record<string, string>;
   lastSync: string | null;
 };
 
@@ -58,6 +58,8 @@ function hashContent(content: string): string {
   return createHash("sha256").update(content).digest("hex");
 }
 
+// parseFrontmatter/hashFileBody provided by shared helper
+
 function getMemoryRoot(agentId: string): string {
   return join(homedir(), ".letta", "agents", agentId, "memory");
 }
@@ -66,49 +68,45 @@ function loadSyncState(agentId: string): SyncState {
   const statePath = join(getMemoryRoot(agentId), MEMORY_FS_STATE_FILE);
   if (!existsSync(statePath)) {
     return {
-      systemBlocks: {},
-      systemFiles: {},
-      detachedBlocks: {},
-      detachedFiles: {},
-      detachedBlockIds: {},
+      blockHashes: {},
+      fileHashes: {},
+      blockIds: {},
       lastSync: null,
     };
   }
 
   try {
     const raw = readFileSync(statePath, "utf-8");
-    const parsed = JSON.parse(raw) as Partial<SyncState> & {
-      blocks?: Record<string, string>;
-      files?: Record<string, string>;
-    };
+    const parsed = JSON.parse(raw);
     return {
-      systemBlocks: parsed.systemBlocks || parsed.blocks || {},
-      systemFiles: parsed.systemFiles || parsed.files || {},
-      detachedBlocks: parsed.detachedBlocks || {},
-      detachedFiles: parsed.detachedFiles || {},
-      detachedBlockIds: parsed.detachedBlockIds || {},
+      blockHashes: parsed.blockHashes || {},
+      fileHashes: parsed.fileHashes || {},
+      blockIds: parsed.blockIds || {},
       lastSync: parsed.lastSync || null,
     };
   } catch {
     return {
-      systemBlocks: {},
-      systemFiles: {},
-      detachedBlocks: {},
-      detachedFiles: {},
-      detachedBlockIds: {},
+      blockHashes: {},
+      fileHashes: {},
+      blockIds: {},
       lastSync: null,
     };
   }
 }
 
-async function scanMdFiles(dir: string, baseDir = dir): Promise<string[]> {
+async function scanMdFiles(
+  dir: string,
+  baseDir = dir,
+  excludeDirs: string[] = [],
+): Promise<string[]> {
   if (!existsSync(dir)) return [];
   const entries = await readdir(dir, { withFileTypes: true });
   const results: string[] = [];
   for (const entry of entries) {
     const fullPath = join(dir, entry.name);
     if (entry.isDirectory()) {
-      results.push(...(await scanMdFiles(fullPath, baseDir)));
+      if (excludeDirs.includes(entry.name)) continue;
+      results.push(...(await scanMdFiles(fullPath, baseDir, excludeDirs)));
     } else if (entry.isFile() && entry.name.endsWith(".md")) {
       results.push(relative(baseDir, fullPath));
     }
@@ -122,8 +120,9 @@ function labelFromPath(relativePath: string): string {
 
 async function readMemoryFiles(
   dir: string,
+  excludeDirs: string[] = [],
 ): Promise<Map<string, { content: string }>> {
-  const files = await scanMdFiles(dir);
+  const files = await scanMdFiles(dir, dir, excludeDirs);
   const entries = new Map<string, { content: string }>();
   for (const rel of files) {
     const label = labelFromPath(rel);
@@ -133,11 +132,8 @@ async function readMemoryFiles(
   return entries;
 }
 
-const MANAGED_LABELS = new Set([
-  "memory_filesystem",
-  "skills",
-  "loaded_skills",
-]);
+// Only memory_filesystem is managed by memfs itself
+const MEMFS_MANAGED_LABELS = new Set(["memory_filesystem"]);
 
 interface Conflict {
   label: string;
@@ -145,6 +141,12 @@ interface Conflict {
   blockContent: string;
 }
 
+interface MetadataChange {
+  label: string;
+  fileContent: string;
+  blockContent: string;
+}
+
 /**
  * Get the overflow directory following the same pattern as tool output overflow.
  * Pattern: ~/.letta/projects/<project-path>/agent-tools/
@@ -160,122 +162,163 @@ function getOverflowDirectory(): string {
   return join(homedir(), ".letta", "projects", sanitizedPath, "agent-tools");
 }
 
-async function findConflicts(agentId: string): Promise<Conflict[]> {
+async function findConflicts(agentId: string): Promise<{
+  conflicts: Conflict[];
+  metadataOnly: MetadataChange[];
+}> {
   const baseUrl = process.env.LETTA_BASE_URL || "https://api.letta.com";
   const client = new Letta({ apiKey: getApiKey(), baseUrl });
 
   const root = getMemoryRoot(agentId);
   const systemDir = join(root, "system");
-  // Detached files go at root level (flat structure)
   const detachedDir = root;
 
   for (const dir of [root, systemDir]) {
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   }
 
+  // Read files from both locations
   const systemFiles = await readMemoryFiles(systemDir);
-  const detachedFiles = await readMemoryFiles(detachedDir);
-  systemFiles.delete("memory_filesystem");
+  const detachedFiles = await readMemoryFiles(detachedDir, ["system", "user"]);
 
+  // Fetch attached blocks
   const blocksResponse = await client.agents.blocks.list(agentId, {
     limit: 1000,
   });
-  const blocks = Array.isArray(blocksResponse)
+  const attachedBlocks = Array.isArray(blocksResponse)
     ? blocksResponse
     : ((blocksResponse as { items?: unknown[] }).items as Array<{
+        id?: string;
         label?: string;
         value?: string;
+        read_only?: boolean;
       }>) || [];
 
-  const systemBlockMap = new Map(
-    blocks
-      .filter((b: { label?: string }) => b.label)
-      .map((b: { label?: string; value?: string }) => [
-        b.label as string,
-        b.value || "",
-      ]),
-  );
-  systemBlockMap.delete("memory_filesystem");
-
-  const lastState = loadSyncState(agentId);
-
-  const detachedBlockMap = new Map<string, string>();
-  for (const [label, blockId] of Object.entries(lastState.detachedBlockIds)) {
-    try {
-      const block = await client.blocks.retrieve(blockId);
-      detachedBlockMap.set(label, block.value || "");
-    } catch {
-      // Block no longer exists
+  const systemBlockMap = new Map<
+    string,
+    { value: string; id: string; read_only?: boolean }
+  >();
+  for (const block of attachedBlocks) {
+    if (block.label && block.id) {
+      systemBlockMap.set(block.label, {
+        value: block.value || "",
+        id: block.id,
+        read_only: block.read_only,
+      });
     }
   }
 
-  const conflicts: Conflict[] = [];
+  // Fetch detached blocks via owner tag
+  const ownedBlocksResponse = await client.blocks.list({
+    tags: [`owner:${agentId}`],
+    limit: 1000,
+  });
+  const ownedBlocks = Array.isArray(ownedBlocksResponse)
+    ? ownedBlocksResponse
+    : ((ownedBlocksResponse as { items?: unknown[] }).items as Array<{
+        id?: string;
+        label?: string;
+        value?: string;
+        read_only?: boolean;
+      }>) || [];
 
-  function checkConflict(
-    label: string,
-    fileContent: string | null,
-    blockValue: string | null,
-    lastFileHash: string | null,
-    lastBlockHash: string | null,
-  ) {
-    if (fileContent === null || blockValue === null) return;
-    const fileHash = hashContent(fileContent);
-    const blockHash = hashContent(blockValue);
-    if (fileHash === blockHash) return;
-    const fileChanged = fileHash !== lastFileHash;
-    const blockChanged = blockHash !== lastBlockHash;
-    if (fileChanged && blockChanged) {
-      conflicts.push({ label, fileContent, blockContent: blockValue });
+  const attachedIds = new Set(attachedBlocks.map((b) => b.id));
+  const detachedBlockMap = new Map<
+    string,
+    { value: string; id: string; read_only?: boolean }
+  >();
+  for (const block of ownedBlocks) {
+    if (block.label && block.id && !attachedIds.has(block.id)) {
+      if (!systemBlockMap.has(block.label)) {
+        detachedBlockMap.set(block.label, {
+          value: block.value || "",
+          id: block.id,
+          read_only: block.read_only,
+        });
+      }
     }
   }
 
-  // Check system labels
-  const systemLabels = new Set([
+  const lastState = loadSyncState(agentId);
+  const conflicts: Conflict[] = [];
+  const metadataOnly: MetadataChange[] = [];
+
+  // Collect all labels
+  const allLabels = new Set<string>([
     ...systemFiles.keys(),
+    ...detachedFiles.keys(),
     ...systemBlockMap.keys(),
-    ...Object.keys(lastState.systemBlocks),
-    ...Object.keys(lastState.systemFiles),
+    ...detachedBlockMap.keys(),
+    ...Object.keys(lastState.blockHashes),
+    ...Object.keys(lastState.fileHashes),
   ]);
 
-  for (const label of [...systemLabels].sort()) {
-    if (MANAGED_LABELS.has(label)) continue;
-    checkConflict(
-      label,
-      systemFiles.get(label)?.content ?? null,
-      systemBlockMap.get(label) ?? null,
-      lastState.systemFiles[label] ?? null,
-      lastState.systemBlocks[label] ?? null,
-    );
-  }
+  for (const label of [...allLabels].sort()) {
+    if (MEMFS_MANAGED_LABELS.has(label)) continue;
 
-  // Check user labels
-  const userLabels = new Set([
-    ...detachedFiles.keys(),
-    ...detachedBlockMap.keys(),
-    ...Object.keys(lastState.detachedBlocks),
-    ...Object.keys(lastState.detachedFiles),
-  ]);
+    const systemFile = systemFiles.get(label);
+    const detachedFile = detachedFiles.get(label);
+    const attachedBlock = systemBlockMap.get(label);
+    const detachedBlock = detachedBlockMap.get(label);
 
-  for (const label of [...userLabels].sort()) {
-    checkConflict(
-      label,
-      detachedFiles.get(label)?.content ?? null,
-      detachedBlockMap.get(label) ?? null,
-      lastState.detachedFiles[label] ?? null,
-      lastState.detachedBlocks[label] ?? null,
-    );
+    const fileEntry = systemFile || detachedFile;
+    const blockEntry = attachedBlock || detachedBlock;
+
+    if (!fileEntry || !blockEntry) continue;
+
+    // read_only blocks are API-authoritative; no conflicts possible
+    const effectiveReadOnly =
+      !!blockEntry.read_only || READ_ONLY_LABELS.has(label);
+    if (effectiveReadOnly) continue;
+
+    // Full file hash for "file changed" check
+    const fileHash = hashContent(fileEntry.content);
+    // Body hash for "content matches" check
+    const fileBodyHash = hashFileBody(fileEntry.content);
+    const blockHash = hashContent(blockEntry.value);
+
+    const lastFileHash = lastState.fileHashes[label] ?? null;
+    const lastBlockHash = lastState.blockHashes[label] ?? null;
+    const fileChanged = fileHash !== lastFileHash;
+    const blockChanged = blockHash !== lastBlockHash;
+
+    // Content matches - check for frontmatter-only changes
+    if (fileBodyHash === blockHash) {
+      if (fileChanged) {
+        metadataOnly.push({
+          label,
+          fileContent: fileEntry.content,
+          blockContent: blockEntry.value,
+        });
+      }
+      continue;
+    }
+
+    // Conflict only if both changed
+    if (fileChanged && blockChanged) {
+      conflicts.push({
+        label,
+        fileContent: fileEntry.content,
+        blockContent: blockEntry.value,
+      });
+    }
   }
 
-  return conflicts;
+  return { conflicts, metadataOnly };
 }
 
-function formatDiffFile(conflicts: Conflict[], agentId: string): string {
+function formatDiffFile(
+  conflicts: Conflict[],
+  metadataOnly: MetadataChange[],
+  agentId: string,
+): string {
   const lines: string[] = [
     `# Memory Filesystem Diff`,
     ``,
     `Agent: ${agentId}`,
     `Generated: ${new Date().toISOString()}`,
     `Conflicts: ${conflicts.length}`,
+    `Metadata-only changes: ${metadataOnly.length}`,
     ``,
     `---`,
     ``,
@@ -298,6 +341,32 @@ function formatDiffFile(conflicts: Conflict[], agentId: string): string {
     lines.push(``);
   }
 
+  if (metadataOnly.length > 0) {
+    lines.push(`## Metadata-only Changes`);
+    lines.push(``);
+    lines.push(
+      `Frontmatter changed while body content stayed the same (file wins).`,
+    );
+    lines.push(``);
+
+    for (const change of metadataOnly) {
+      lines.push(`### ${change.label}`);
+      lines.push(``);
+      lines.push(`#### File Version (with frontmatter)`);
+      lines.push(`\`\`\``);
+      lines.push(change.fileContent);
+      lines.push(`\`\`\``);
+      lines.push(``);
+      lines.push(`#### Block Version (body only)`);
+      lines.push(`\`\`\``);
+      lines.push(change.blockContent);
+      lines.push(`\`\`\``);
+      lines.push(``);
+      lines.push(`---`);
+      lines.push(``);
+    }
+  }
+
   return lines.join("\n");
 }
 
@@ -329,13 +398,13 @@ Output: Path to the diff file, or a message if no conflicts exist.
   }
 
   findConflicts(agentId)
-    .then((conflicts) => {
-      if (conflicts.length === 0) {
+    .then(({ conflicts, metadataOnly }) => {
+      if (conflicts.length === 0 && metadataOnly.length === 0) {
         console.log("No conflicts found. Memory filesystem is clean.");
         return;
       }
 
-      const diffContent = formatDiffFile(conflicts, agentId);
+      const diffContent = formatDiffFile(conflicts, metadataOnly, agentId);
 
       // Write to overflow directory (same pattern as tool output overflow)
       const overflowDir = getOverflowDirectory();
@@ -348,7 +417,7 @@ Output: Path to the diff file, or a message if no conflicts exist.
       writeFileSync(diffPath, diffContent, "utf-8");
 
       console.log(
-        `Diff (${conflicts.length} conflict${conflicts.length === 1 ? "" : "s"}) written to: ${diffPath}`,
+        `Diff (${conflicts.length} conflict${conflicts.length === 1 ? "" : "s"}, ${metadataOnly.length} metadata-only change${metadataOnly.length === 1 ? "" : "s"}) written to: ${diffPath}`,
       );
     })
     .catch((error) => {