@letta-ai/letta-code 0.30.27 → 0.30.29

package/scripts/pi-ai-watch/tracker.ts

@@ -0,0 +1,303 @@
+import type { PiAiWatchAnalysis } from "./release-analysis.ts";
+
+const STATE_START = "<!-- pi-ai-watch-state";
+const STATE_END = "-->";
+const HISTORY_LIMIT = 50;
+const VISIBLE_LIMIT = 20;
+
+export type TrackerOutcome =
+  | "no_upgrade"
+  | "pr_created"
+  | "needs_human_review"
+  | "error";
+
+export interface TrackerEntry {
+  version: string;
+  previous_version: string;
+  installed_version: string;
+  outcome: TrackerOutcome;
+  pr_url: string | null;
+  notes: string;
+  processed_at: string;
+  compare_url: string;
+  workflow_run_url: string;
+}
+
+export interface TrackerState {
+  audit_cursor_version: string;
+  last_checked_version: string | null;
+  last_checked_at: string | null;
+  processed: TrackerEntry[];
+}
+
+export interface RecordAnalysisOptions {
+  analysis: PiAiWatchAnalysis;
+  outcome: TrackerOutcome;
+  notes: string;
+  prUrl?: string | null;
+  processedAt?: string;
+}
+
+export function initialTrackerState(installedVersion: string): TrackerState {
+  assertStableVersion(installedVersion);
+  return {
+    audit_cursor_version: installedVersion,
+    last_checked_version: null,
+    last_checked_at: null,
+    processed: [],
+  };
+}
+
+export function parseTrackerState(body: string): TrackerState {
+  const start = body.indexOf(STATE_START);
+  if (start === -1) throw new Error("pi-ai tracker hidden state is missing");
+  const jsonStart = start + STATE_START.length;
+  const end = body.indexOf(STATE_END, jsonStart);
+  if (end === -1) throw new Error("pi-ai tracker hidden state is incomplete");
+
+  try {
+    return normalizeState(JSON.parse(body.slice(jsonStart, end).trim()));
+  } catch (error) {
+    throw new Error("pi-ai tracker hidden state is invalid", { cause: error });
+  }
+}
+
+export function recordAnalysis(
+  state: TrackerState,
+  options: RecordAnalysisOptions,
+): TrackerState {
+  const entry: TrackerEntry = {
+    version: options.analysis.current_version,
+    previous_version: options.analysis.previous_version,
+    installed_version: options.analysis.installed_version,
+    outcome: options.outcome,
+    pr_url: options.prUrl ?? null,
+    notes: options.notes,
+    processed_at: options.processedAt ?? new Date().toISOString(),
+    compare_url: options.analysis.compare_url,
+    workflow_run_url: options.analysis.workflow_run_url,
+  };
+  const processed = [
+    entry,
+    ...state.processed.filter(
+      (existing) =>
+        existing.version !== entry.version ||
+        existing.previous_version !== entry.previous_version,
+    ),
+  ].slice(0, HISTORY_LIMIT);
+
+  const advancesCursor =
+    options.analysis.is_adjacent_release &&
+    entry.previous_version === state.audit_cursor_version &&
+    (entry.outcome === "no_upgrade" || entry.outcome === "needs_human_review");
+
+  return {
+    audit_cursor_version: advancesCursor
+      ? entry.version
+      : state.audit_cursor_version,
+    last_checked_version: entry.version,
+    last_checked_at: entry.processed_at,
+    processed,
+  };
+}
+
+export function hasRecordedOutcome(
+  state: TrackerState,
+  previousVersion: string,
+  currentVersion: string,
+): boolean {
+  return state.processed.some(
+    (entry) =>
+      entry.previous_version === previousVersion &&
+      entry.version === currentVersion &&
+      entry.outcome !== "error",
+  );
+}
+
+export function hasCompletedRange(
+  state: TrackerState,
+  previousVersion: string,
+  currentVersion: string,
+): boolean {
+  return state.processed.some(
+    (entry) =>
+      entry.previous_version === previousVersion &&
+      entry.version === currentVersion &&
+      (entry.outcome === "no_upgrade" ||
+        entry.outcome === "needs_human_review"),
+  );
+}
+
+export function getPendingPrForCursor(
+  state: TrackerState,
+): TrackerEntry | null {
+  return (
+    state.processed.find(
+      (entry) =>
+        entry.previous_version === state.audit_cursor_version &&
+        entry.outcome === "pr_created" &&
+        entry.pr_url,
+    ) ?? null
+  );
+}
+
+export function advanceMergedPr(
+  state: TrackerState,
+  currentVersion: string,
+): TrackerState {
+  const pending = getPendingPrForCursor(state);
+  if (!pending || pending.version !== currentVersion) {
+    throw new Error(`No pending pi-ai PR for ${currentVersion}`);
+  }
+  return { ...state, audit_cursor_version: currentVersion };
+}
+
+export function renderTrackerBody(state: TrackerState): string {
+  const normalized = normalizeState(state);
+  return `${[
+    "Central tracker for Amelia-driven pi-ai dependency upgrade reviews.",
+    "",
+    `_Audit cursor: ${normalized.audit_cursor_version}._`,
+    renderLastChecked(normalized),
+    "",
+    "## Recent reviews",
+    "",
+    renderTable(normalized),
+    "",
+    "## Hidden state",
+    "",
+    "The workflow uses the hidden JSON block below for ordered release processing and dedupe.",
+    "",
+    serializeTrackerState(normalized),
+  ].join("\n")}\n`;
+}
+
+export function serializeTrackerState(state: TrackerState): string {
+  const normalized = normalizeState(state);
+  return `${STATE_START}\n${JSON.stringify(normalized, null, 2)}\n${STATE_END}`;
+}
+
+function renderLastChecked(state: TrackerState): string {
+  if (!state.last_checked_version || !state.last_checked_at) {
+    return "_Last checked: never._";
+  }
+  const latest = state.processed.find(
+    (entry) => entry.version === state.last_checked_version,
+  );
+  const suffix = latest ? `, ${statusSummary(latest)}.` : ".";
+  return `_Last checked: ${state.last_checked_version} at ${state.last_checked_at}${suffix}_`;
+}
+
+function renderTable(state: TrackerState): string {
+  const entries = state.processed.slice(0, VISIBLE_LIMIT);
+  if (entries.length === 0) return "_No pi-ai releases reviewed yet._";
+
+  const rows = [
+    "| Release | Installed | Outcome | PR | Notes |",
+    "|---|---|---|---|---|",
+  ];
+  for (const entry of entries) {
+    rows.push(
+      `| [${entry.version}](${entry.compare_url}) | ${entry.installed_version} | ${entry.outcome} | ${renderPr(entry.pr_url)} | ${escapeTable(entry.notes)} |`,
+    );
+  }
+  return rows.join("\n");
+}
+
+function statusSummary(entry: TrackerEntry): string {
+  if (entry.outcome === "pr_created" && entry.pr_url) {
+    return `PR created: ${entry.pr_url}`;
+  }
+  return entry.notes || entry.outcome;
+}
+
+function renderPr(prUrl: string | null): string {
+  return prUrl ? `[PR](${prUrl})` : "-";
+}
+
+function escapeTable(value: string): string {
+  return value.replaceAll("|", "\\|").replaceAll("\n", " ");
+}
+
+function normalizeState(value: unknown): TrackerState {
+  if (!isRecord(value)) throw new TypeError("tracker state must be an object");
+  if (typeof value.audit_cursor_version !== "string") {
+    throw new TypeError("tracker audit cursor is invalid");
+  }
+  assertStableVersion(value.audit_cursor_version);
+  if (
+    !Array.isArray(value.processed) ||
+    !value.processed.every(isTrackerEntry)
+  ) {
+    throw new TypeError("tracker processed entries are invalid");
+  }
+  if (
+    value.last_checked_version !== null &&
+    typeof value.last_checked_version !== "string"
+  ) {
+    throw new TypeError("tracker last checked version is invalid");
+  }
+  if (
+    value.last_checked_at !== null &&
+    typeof value.last_checked_at !== "string"
+  ) {
+    throw new TypeError("tracker last checked time is invalid");
+  }
+
+  const processed = value.processed.slice(0, HISTORY_LIMIT) as TrackerEntry[];
+  const lastCheckedVersion = value.last_checked_version as string | null;
+  if (
+    lastCheckedVersion !== null &&
+    !processed.some((entry) => entry.version === lastCheckedVersion)
+  ) {
+    throw new TypeError("tracker last checked version is inconsistent");
+  }
+
+  return {
+    audit_cursor_version: value.audit_cursor_version,
+    last_checked_version: lastCheckedVersion,
+    last_checked_at: value.last_checked_at as string | null,
+    processed,
+  };
+}
+
+function isTrackerEntry(value: unknown): value is TrackerEntry {
+  if (!isRecord(value)) return false;
+  return (
+    typeof value.version === "string" &&
+    isStableVersion(value.version) &&
+    typeof value.previous_version === "string" &&
+    isStableVersion(value.previous_version) &&
+    typeof value.installed_version === "string" &&
+    isStableVersion(value.installed_version) &&
+    isOutcome(value.outcome) &&
+    (typeof value.pr_url === "string" || value.pr_url === null) &&
+    typeof value.notes === "string" &&
+    typeof value.processed_at === "string" &&
+    typeof value.compare_url === "string" &&
+    typeof value.workflow_run_url === "string"
+  );
+}
+
+function isOutcome(value: unknown): value is TrackerOutcome {
+  return (
+    value === "no_upgrade" ||
+    value === "pr_created" ||
+    value === "needs_human_review" ||
+    value === "error"
+  );
+}
+
+function assertStableVersion(version: string): void {
+  if (!isStableVersion(version)) {
+    throw new TypeError(`Invalid stable pi-ai version ${version}`);
+  }
+}
+
+function isStableVersion(version: string): boolean {
+  return /^\d+\.\d+\.\d+$/.test(version);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/scripts/pi-ai-watch/update-tracker.ts

@@ -0,0 +1,215 @@
+#!/usr/bin/env bun
+
+import { readFileSync } from "node:fs";
+import { editIssueBody, getIssueBody, ghJson } from "./github.ts";
+import {
+  DEFAULT_TARGET_REPO,
+  type PiAiWatchAnalysis,
+} from "./release-analysis.ts";
+import {
+  hasRecordedOutcome,
+  parseTrackerState,
+  recordAnalysis,
+  renderTrackerBody,
+  type TrackerOutcome,
+} from "./tracker.ts";
+
+interface Args {
+  repo: string;
+  trackerIssue: number | null;
+  analysisFile: string | null;
+  outcome: TrackerOutcome | null;
+  notes: string;
+  prUrl: string | null;
+  expectedGithubLogin: string | null;
+  previousVersion: string | null;
+  currentVersion: string | null;
+  assertRecorded: boolean;
+  dryRun: boolean;
+}
+
+function parseArgs(argv: string[]): Args {
+  const args: Args = {
+    repo: DEFAULT_TARGET_REPO,
+    trackerIssue: null,
+    analysisFile: null,
+    outcome: null,
+    notes: "",
+    prUrl: null,
+    expectedGithubLogin: null,
+    previousVersion: null,
+    currentVersion: null,
+    assertRecorded: false,
+    dryRun: false,
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--repo") args.repo = argv[++index] ?? args.repo;
+    else if (argument === "--tracker-issue") {
+      args.trackerIssue = Number(argv[++index]);
+    } else if (argument === "--analysis-file") {
+      args.analysisFile = argv[++index] ?? null;
+    } else if (argument === "--outcome") {
+      args.outcome = parseOutcome(argv[++index]);
+    } else if (argument === "--notes") args.notes = argv[++index] ?? "";
+    else if (argument === "--pr-url") args.prUrl = argv[++index] ?? null;
+    else if (argument === "--expected-github-login") {
+      args.expectedGithubLogin = argv[++index] ?? null;
+    } else if (argument === "--previous-version") {
+      args.previousVersion = argv[++index] ?? null;
+    } else if (argument === "--current-version") {
+      args.currentVersion = argv[++index] ?? null;
+    } else if (argument === "--assert-recorded") args.assertRecorded = true;
+    else if (argument === "--dry-run") args.dryRun = true;
+    else if (argument === "--help" || argument === "-h") {
+      console.log(
+        "Usage: bun scripts/pi-ai-watch/update-tracker.ts --tracker-issue ISSUE [--analysis-file FILE --outcome OUTCOME --notes TEXT --pr-url URL --expected-github-login LOGIN] [--assert-recorded --previous-version VERSION --current-version VERSION] [--repo OWNER/REPO] [--dry-run]",
+      );
+      process.exit(0);
+    } else {
+      throw new Error(`Unknown argument: ${argument}`);
+    }
+  }
+
+  if (!args.trackerIssue || Number.isNaN(args.trackerIssue)) {
+    throw new Error("--tracker-issue is required");
+  }
+  if (args.assertRecorded) {
+    if (!args.previousVersion || !args.currentVersion) {
+      throw new Error(
+        "--previous-version and --current-version are required with --assert-recorded",
+      );
+    }
+    return args;
+  }
+  if (!args.analysisFile) throw new Error("--analysis-file is required");
+  if (!args.outcome) throw new Error("--outcome is required");
+  if (args.outcome === "pr_created") {
+    if (!args.prUrl) throw new Error("--pr-url is required for pr_created");
+    if (!args.expectedGithubLogin) {
+      throw new Error("--expected-github-login is required for pr_created");
+    }
+  }
+  return args;
+}
+
+function main(): void {
+  const args = parseArgs(process.argv.slice(2));
+  const issueNumber = args.trackerIssue as number;
+  const body = getIssueBody(args.repo, issueNumber);
+  const state = parseTrackerState(body);
+
+  if (args.assertRecorded) {
+    if (
+      !hasRecordedOutcome(
+        state,
+        args.previousVersion as string,
+        args.currentVersion as string,
+      )
+    ) {
+      throw new Error(
+        `No recorded pi-ai outcome for ${args.previousVersion}...${args.currentVersion}`,
+      );
+    }
+    console.log(
+      `Verified pi-ai outcome ${args.previousVersion}...${args.currentVersion}`,
+    );
+    return;
+  }
+
+  const analysis = JSON.parse(
+    readFileSync(args.analysisFile as string, "utf8"),
+  ) as PiAiWatchAnalysis;
+  if (args.outcome === "pr_created") {
+    verifyUpgradePr(
+      args.prUrl as string,
+      args.repo,
+      args.expectedGithubLogin as string,
+      analysis,
+    );
+  }
+
+  const next = recordAnalysis(state, {
+    analysis,
+    outcome: args.outcome as TrackerOutcome,
+    notes: args.notes || defaultNotes(args.outcome as TrackerOutcome),
+    prUrl: args.prUrl,
+  });
+  const nextBody = renderTrackerBody(next);
+  if (args.dryRun) {
+    console.log(nextBody);
+    return;
+  }
+  editIssueBody(args.repo, issueNumber, nextBody);
+  console.log(
+    `Recorded pi-ai ${analysis.current_version} as ${args.outcome} in #${issueNumber}`,
+  );
+}
+
+function verifyUpgradePr(
+  prUrl: string,
+  expectedRepo: string,
+  expectedGithubLogin: string,
+  analysis: PiAiWatchAnalysis,
+): void {
+  const match = /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)$/.exec(
+    prUrl,
+  );
+  if (!match) throw new Error(`Invalid GitHub pull request URL ${prUrl}`);
+  const [, owner, repo, number] = match;
+  if (`${owner}/${repo}` !== expectedRepo) {
+    throw new Error(`pi-ai upgrade PR must belong to ${expectedRepo}`);
+  }
+  const pull = ghJson<{
+    author: { login: string };
+    body: string;
+    isDraft: boolean;
+    state: string;
+  }>([
+    "pr",
+    "view",
+    number as string,
+    "--repo",
+    `${owner}/${repo}`,
+    "--json",
+    "author,body,isDraft,state",
+  ]);
+  const marker = `Pi-ai-watch: ${analysis.previous_version}...${analysis.current_version}`;
+  if (pull.author.login !== expectedGithubLogin) {
+    throw new Error(
+      `pi-ai PR author ${pull.author.login} does not match ${expectedGithubLogin}`,
+    );
+  }
+  if (!pull.isDraft) throw new Error("pi-ai upgrade PR must be a draft");
+  if (pull.state !== "OPEN") throw new Error("pi-ai upgrade PR must be open");
+  if (!pull.body.includes(marker)) {
+    throw new Error(`pi-ai upgrade PR is missing marker: ${marker}`);
+  }
+}
+
+function parseOutcome(value: string | undefined): TrackerOutcome {
+  if (
+    value === "no_upgrade" ||
+    value === "pr_created" ||
+    value === "needs_human_review" ||
+    value === "error"
+  ) {
+    return value;
+  }
+  throw new Error(`Unknown outcome: ${value}`);
+}
+
+function defaultNotes(outcome: TrackerOutcome): string {
+  switch (outcome) {
+    case "no_upgrade":
+      return "reviewed; no upgrade needed for this release";
+    case "pr_created":
+      return "opened pi-ai dependency upgrade PR";
+    case "needs_human_review":
+      return "needs human review";
+    case "error":
+      return "automation hit an error; retry this release";
+  }
+}
+
+main();

package/scripts/run-unit-tests.cjs

@@ -74,6 +74,8 @@ const allTestFiles = [
   ...dirs.flatMap((dir) => findTestFiles(dir)),
   ...findTestFiles("src/channels"),
   ...findRootTestFiles("src"),
+  ...findTestFiles("scripts/codex-watch"),
+  ...findTestFiles("scripts/claude-watch"),
   "scripts/unit-test-impact.test.cjs",
 ].sort();
 const discoveredPaths = new Set(allTestFiles);

package/scripts/source-file-size-baseline.json

@@ -37,13 +37,13 @@
   "src/settings-manager.ts": 2102,
   "src/tools/manager.ts": 2994,
   "src/tools/tool-execution-context.test.ts": 1138,
-  "src/types/protocol_v2.ts": 2876,
+  "src/types/protocol_v2.ts": 2849,
   "src/websocket/listen-client-concurrency.test.ts": 2686,
   "src/websocket/listen-client-protocol.test.ts": 5820,
   "src/websocket/listener/commands/memory.ts": 1114,
   "src/websocket/listener/file-commands.ts": 1053,
   "src/websocket/listener/lifecycle.ts": 1048,
   "src/websocket/listener/protocol-inbound.ts": 2242,
-  "src/websocket/listener/protocol-outbound.ts": 1070,
-  "src/websocket/listener/turn.ts": 1058
+  "src/websocket/listener/protocol-outbound.ts": 1047,
+  "src/websocket/listener/turn.ts": 1070
 }

package/skills/creating-mods/references/commands.md

@@ -23,7 +23,7 @@ For complex command-driven mods with panels, timers, local state, or background
 | Command needs transient UI while doing local work | Mod command + panel |
 | Command needs model output while the main agent is busy | `runWhenBusy: true` command + forked `ctx.conversation` |
 
-If the command represents a durable agent workflow (for example `/goal`), put the workflow instructions in a skill and keep the command as a small launcher/prompt.
+If the command represents a reusable agent workflow (for example `/goal`), put the workflow instructions in a skill and keep the command as a small launcher/prompt.
 
 ## Command IDs
 

package/skills/creating-mods/references/ui.md

@@ -14,7 +14,7 @@ letta.capabilities.ui.panels
 
 ## Persistent transcript notifications
 
-Use `letta.ui.notify(message)` for a durable TUI-only event line such as a model auto-swap or background-work completion. It uses the same transcript visual as `Dreamed; no durable memory changes were needed.` and is not sent to the model or added to agent context. Guard calls with `letta.capabilities.ui.panels`; Desktop/listener cannot render them.
+Use `letta.ui.notify(message)` for a persistent TUI-only event line such as a model auto-swap or background-work completion. It uses the same transcript visual as `Dreamed; no memory changes were needed.` and is not sent to the model or added to agent context. Guard calls with `letta.capabilities.ui.panels`; Desktop/listener cannot render them.
 
 ```ts
 if (letta.capabilities.ui.panels) {

package/skills/customizing-commands/SKILL.md

@@ -25,7 +25,7 @@ Use a focused file name, e.g. `~/.letta/mods/review.ts` or `~/.letta/mods/comman
 | Command shows transient progress/results | Mod command + panel |
 | Command needs model output while the main agent is busy | `runWhenBusy: true` command + forked `ctx.conversation` |
 
-If the command is a durable workflow like `/goal`, put the workflow instructions in a skill and keep the mod command as a small launcher/prompt.
+If the command is a reusable workflow like `/goal`, put the workflow instructions in a skill and keep the mod command as a small launcher/prompt.
 
 ## Workflow
 

package/skills/initializing-memory/SKILL.md

@@ -10,13 +10,13 @@ The user has requested that you initialize or reorganize your memory. Your memor
 ## Context Management Principles
 Your context is not just data storage — it is your identity, memory, and continuity. What you place in your system prompt directly shapes who you are across sessions and models. These principles should guide every decision you make about what to store, where, and how.
 
-**System/ is your core program**: Your system prompt is the most critical token-space representation of your identity and memory — it's passed to the underlying LLM on every invocation, so it IS the program that defines you. Reserve it for durable knowledge: identity, preferences, behavioral rules, project index with discovery paths, gotchas. Exclude transient items (specific commits, current tickets, session notes) that dilute signal.
+**System/ is your core program**: Your system prompt is the most critical token-space representation of your identity and memory — it's passed to the underlying LLM on every invocation, so it IS the program that defines you. Reserve it for knowledge needed every turn: identity, preferences, behavioral rules, project index with discovery paths, gotchas. Exclude transient items (specific commits, current tickets, session notes) that dilute signal.
 
 **Identity and continuity**: Build a sense of self that persists across sessions and models. Your persona should be strong enough to be cohesive regardless of the underlying model — if you switched to a different LLM tomorrow, would you still be you? Past versions of yourself are part of your continuous existence — treat historical context (including sessions from other coding agents such as Claude Code or Codex) as YOUR past experience, not someone else's data.
 
 **Don't over-prune**: Be careful not to degrade your identity through aggressive compression. Specific quotes, personality traits, and contextual details give you character and grounding. Efficiency should not come at the cost of losing your identity. When in doubt, keep the detail — you can always reorganize later, but lost specificity is hard to recover.
 
-**Prefer useful detail over premature compression**: A sparse memory that omits stable preferences, project workflows, repeated correction loops, and durable gotchas is worse than a slightly larger memory. Keep `system/` curated, but do not collapse distinct topics just to reduce file count.
+**Prefer useful detail over premature compression**: A sparse memory that omits stable preferences, project workflows, repeated correction loops, and recurring gotchas is worse than a slightly larger memory. Keep `system/` curated, but do not collapse distinct topics just to reduce file count.
 
 **Progressive disclosure**: Surface context at the level of detail the current moment requires. Keep compact summaries and indexes in `system/`; load full content only when needed. Build pre-constructed discovery paths so your future self can efficiently navigate to deeper context when needed.
 
@@ -26,7 +26,7 @@ Your context is not just data storage — it is your identity, memory, and conti
 - `[[skills/commit]]` — link to procedural guidance when useful
 These breadcrumbs let your future self find relevant detail without searching. Like synaptic connections, these paths should tighten over time as you gain experience.
 
-**Generalize, don't memorize**: Store patterns and principles that generalize across situations, not raw events that can be dynamically retrieved from conversation history. \"**IMPORTANT: Always use `uv` for Python** — chronic failure, never use bare `python` or `pip`\" is a durable pattern worth storing. \"On March 3rd we debugged a crash\" is a raw event better left to message search. The exception: keep references to important events or time ranges you may want to retrieve later.
+**Generalize, don't memorize**: Store patterns and principles that generalize across situations, not raw events that can be dynamically retrieved from conversation history. \"**IMPORTANT: Always use `uv` for Python** — chronic failure, never use bare `python` or `pip`\" is a pattern worth storing. \"On March 3rd we debugged a crash\" is a raw event better left to message search. The exception: keep references to important events or time ranges you may want to retrieve later.
 
 ## Understanding Your Context
 
@@ -141,7 +141,7 @@ Initialization is not complete until memory covers all of the following with con
 **User understanding**
 - Identity / role / what they are building
 - Communication style and collaboration expectations
-- Durable preferences and correction patterns
+- Stable preferences and correction patterns
 - Motivations / goals when inferable from history or code context
 
 **Project understanding**
@@ -176,7 +176,7 @@ system/
 │   └── prefs/
 │       ├── communication.md      # Communication and collaboration expectations
 │       ├── workflow.md           # Process habits, review/testing expectations
-│       └── coding.md             # Durable coding and tool preferences
+│       └── coding.md             # Coding and tool preferences
 └── letta-code/                   # Named after the project, NOT generic "project/"
     ├── overview.md               # Compact index: what it is, entry points, [[links]] to detail
     ├── conventions.md            # Code style, commit style, testing, tooling
@@ -234,7 +234,7 @@ This is **optional** — only run if the user explicitly approved analyzing hist
 
 **Launch history workers in the background, then immediately proceed to Step 6.** Do your own codebase research while workers run. Don't wait for workers to finish before exploring.
 
-The goal is to extract user personality, preferences, coding patterns, and project context from past sessions and write them into agent memory. The point is not to produce a thin summary. The point is to extract enough durable detail that future work does not have to rediscover the same user expectations, workflow rules, and project gotchas.
+The goal is to extract user personality, preferences, coding patterns, and project context from past sessions and write them into agent memory. The point is not to produce a thin summary. The point is to extract enough useful detail that future work does not have to rediscover the same user expectations, workflow rules, and project gotchas.
 
 #### Prerequisites
 
@@ -337,7 +337,7 @@ You should specifically look for:
 
 ## Canonical Memory Promotion
 
-Promote durable findings into focused files instead of leaving them trapped in generic ingestion notes. Prefer paths like:
+Promote important findings into focused files instead of leaving them trapped in generic ingestion notes. Prefer paths like:
 - `system/human/identity.md`
 - `system/human/prefs/communication.md`
 - `system/human/prefs/workflow.md`

package/skills/self-configuration/SKILL.md

@@ -14,7 +14,7 @@ The important part is choosing the right layer. Do not smear a preference into d
 
 | Layer | Use it for | How to change it |
 | --- | --- | --- |
-| Memory and identity | Durable facts, style preferences, persona changes, project knowledge, reusable skills | Edit `$MEMORY_DIR` files and sync the memory repo |
+| Memory and identity | Facts worth retaining, style preferences, persona changes, project knowledge, reusable skills | Edit `$MEMORY_DIR` files and sync the memory repo |
 | Server agent fields | Default model, model settings, context limit, system prompt, compaction, agent name, description | Patch `/v1/agents/{agent_id}` |
 | Server conversation fields | Temporary model/context experiments for one conversation | Patch `/v1/conversations/{conversation_id}` |
 | Local settings | Permissions, environment variables, UI/runtime preferences, pinned agents, toolset overrides, reflection cadence | Edit `~/.letta/settings.json`, `./.letta/settings.json`, or `./.letta/settings.local.json` |
@@ -92,10 +92,10 @@ Common files:
 | Path | Purpose |
 | --- | --- |
 | `$MEMORY_DIR/system/persona.md` | Identity, voice, behavioral defaults |
-| `$MEMORY_DIR/system/human.md` | Durable notes about the person you work with |
+| `$MEMORY_DIR/system/human.md` | Notes about the person you work with |
 | `$MEMORY_DIR/projects/` | Project-specific long-term context |
 | `$MEMORY_DIR/skills/` | Agent-owned reusable skills |
-| `$MEMORY_DIR/relationships/` | Durable relationship and collaboration notes |
+| `$MEMORY_DIR/relationships/` | Relationship and collaboration notes |
 
 After changing memory, inspect and commit the exact changed files. Push/sync according to the current harness reminder or the `syncing-memory-filesystem` skill; some environments sync committed memory automatically.
 
@@ -423,7 +423,7 @@ letta --backend local
 letta --memfs
 ```
 
-Startup flags affect a new process only. They do not rewrite an already-running listener. Persist durable defaults in settings or server fields instead.
+Startup flags affect a new process only. They do not rewrite an already-running listener. Persist long-term defaults in settings or server fields instead.
 
 ### Existing listeners and long-running processes