@agentprojectcontext/apx 1.31.0 → 1.31.2

package/README.md

@@ -64,7 +64,6 @@ Runtime state — local machine only, never committed:
 
 ```text
 ~/.apx/projects/<project-id>/
-├── project.db             ← regenerable SQLite cache
 ├── messages/              ← local message history
 └── agents/
     ├── <slug>/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.31.0",
+  "version": "1.31.2",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"

package/skills/apc-context/SKILL.md

@@ -81,7 +81,6 @@ Do not store:
 .apc/sessions/
 .apc/conversations/
 .apc/messages/
-.apc/project.db
 .apc/cache/
 .apc/tmp/
 .apc/private/

package/skills/apx-agency-agents/SKILL.md

@@ -59,7 +59,7 @@ apx agent vault list --all
 # Create a new template (writes ~/.apx/agents/<slug>.md)
 apx agent vault add reviewer \
   --role "Code reviewer" \
-  --model claude-haiku-4-5 \
+  --model ollama:llama3.2:3b \
   --language es \
   --skills code-review,git \
   --description "Reviews PRs and pushes back on hand-wavy diffs."

package/skills/apx-agent/SKILL.md

@@ -5,7 +5,7 @@ description: How to create, configure, and use project agents in APX. Load when
 
 # apx-agent
 
-A project agent is a named persona inside an APC project. Canonical definition: `.apc/agents/<slug>.md` (flat file). `AGENTS.md` is auto-regenerated for discovery. Per-agent runtime data: `.apc/agents/<slug>/memory.md` (and optional `sessions/` only when using external runtimes that write APC session stubs — APX-native sessions live under `~/.apx/projects/<id>/`).
+A project agent is a named persona inside an APC project. Canonical definition: `.apc/agents/<slug>.md` (flat file). `AGENTS.md` is auto-regenerated for discovery. Per-agent runtime data (memory, conversations, sessions) lives under `~/.apx/projects/<apx_id>/agents/<slug>/` and is never committed. APX still reads legacy `.apc/agents/<slug>/memory.md` as a migration fallback only.
 
 ## Concrete CLI calls
 
@@ -13,10 +13,10 @@ A project agent is a named persona inside an APC project. Canonical definition:
 # List agents in a project
 apx agent list --project iacrmar
 
-# Create a new agent (writes .apc/agents/<slug>.md + regenerates AGENTS.md)
+# Create a new agent (writes .apc/agents/<slug>.md, creates runtime dir, regenerates AGENTS.md)
 apx agent add reviewer \
   --role "Code reviewer" \
-  --model claude-haiku-4-5 \
+  --model ollama:llama3.2:3b \
   --language es \
   --description "Reviews PRs and pushes back on hand-wavy diffs." \
   --tools read,write,run \
@@ -45,7 +45,7 @@ apx memory <slug> --project iacrmar --replace < file.md       # full replace fro
 2. Description (from AGENTS.md).
 3. Role + Language fields.
 4. Invocation context: `engine | telegram | routine | runtime` — the channel calling the agent.
-5. Memory: `.apc/agents/<slug>/memory.md` if it exists.
+5. Memory: `~/.apx/projects/<apx_id>/agents/<slug>/memory.md` if it exists, with legacy `.apc/agents/<slug>/memory.md` as a migration fallback.
 6. Skills declared in the agent's `Skills:` field, each loaded from `.apc/skills/<slug>.md` or the bundled set.
 7. The `apx` meta-skill (so the agent knows how to operate APX).
 8. ACTION_DISCIPLINE_RULES (fixed footer — anti-ghost, anti-disclaimer, action-first).
@@ -54,13 +54,13 @@ That's the prompt the engine sees on every `apx exec <agent>` or `apx chat <agen
 
 ## Models per agent
 
-Each agent can set `Model:` in its `AGENT.md` to override the global super-agent model. Useful when a particular agent should use a cheaper / smaller / specialized model.
+Each agent can set `Model:` in its `AGENT.md` to override the global super-agent model. Leave it empty when the agent should follow the project/global default.
 
 ```markdown
 # .apc/agents/reviewer.md
 ---
 Role: Code reviewer
-Model: claude-haiku-4-5      ← this agent always uses Haiku, independent of super_agent.model
+Model: ollama:llama3.2:3b    ← this agent uses this model, independent of super_agent.model
 Language: es
 ---
 ```

package/skills/apx-project/SKILL.md

@@ -57,7 +57,6 @@ The CLI calls `resolveProjectId()` which does fuzzy id-or-name-or-path matching.
 └── .apc/
     ├── project.json                            ← { apxId, name, ... }
     ├── agents/<slug>.md
-    ├── agents/<slug>/memory.md
     ├── skills/<slug>.md or <slug>/SKILL.md
     ├── mcps.json                               ← shared MCPs (committed)
     ├── commands/                               ← custom slash-commands
@@ -65,7 +64,7 @@ The CLI calls `resolveProjectId()` which does fuzzy id-or-name-or-path matching.
 
 ~/.apx/projects/<apxId>/                        ← runtime state (never committed)
 ├── messages/YYYY-MM-DD.jsonl
-├── agents/<slug>/{sessions/, conversations/}
+├── agents/<slug>/{memory.md, sessions/, conversations/}
 ├── routines.json
 ├── tasks/YYYY-MM.jsonl
 ├── artifacts/

package/src/core/agent/self-memory.js

@@ -2,7 +2,7 @@
 //
 // This is distinct from:
 //   - identity.json   → who Roby is (name, personality, owner)
-//   - project agents' .apc/agents/<slug>/memory.md → per-agent, per-project
+//   - project agents' ~/.apx/projects/<apx_id>/agents/<slug>/memory.md → per-agent, per-project
 //   - sessions        → raw transcripts of past work (search_sessions)
 //
 // It is a single free-form markdown file at ~/.apx/memory.md that Roby keeps

package/src/core/agent-memory.js

@@ -0,0 +1,64 @@
+import fs from "node:fs";
+import path from "node:path";
+import { projectStorageRoot } from "./config.js";
+import { getOrCreateApxId } from "./scaffold.js";
+
+const EMPTY_MEMORY = (slug) =>
+  `# Memory — ${slug}\n\n` +
+  `## Identity\n- \n\n` +
+  `## Long-term facts\n- \n\n` +
+  `## Recent context\n- \n`;
+
+export function agentRuntimeDir(projectOrRoot, slug) {
+  const storagePath =
+    typeof projectOrRoot === "object" && projectOrRoot?.storagePath
+      ? projectOrRoot.storagePath
+      : null;
+  const root =
+    typeof projectOrRoot === "string"
+      ? projectOrRoot
+      : projectOrRoot?.path;
+  const base = storagePath || projectStorageRoot(getOrCreateApxId(root));
+  return path.join(base, "agents", slug);
+}
+
+export function agentMemoryPath(projectOrRoot, slug) {
+  return path.join(agentRuntimeDir(projectOrRoot, slug), "memory.md");
+}
+
+export function legacyAgentMemoryPath(projectRoot, slug) {
+  return path.join(projectRoot, ".apc", "agents", slug, "memory.md");
+}
+
+export function ensureAgentRuntimeDir(projectOrRoot, slug, { createMemory = false } = {}) {
+  const dir = agentRuntimeDir(projectOrRoot, slug);
+  fs.mkdirSync(dir, { recursive: true });
+  if (createMemory) {
+    const memory = path.join(dir, "memory.md");
+    if (!fs.existsSync(memory)) fs.writeFileSync(memory, EMPTY_MEMORY(slug));
+  }
+  return dir;
+}
+
+export function readAgentMemory(projectOrRoot, slug) {
+  const primary = agentMemoryPath(projectOrRoot, slug);
+  if (fs.existsSync(primary)) return fs.readFileSync(primary, "utf8");
+
+  const root =
+    typeof projectOrRoot === "string"
+      ? projectOrRoot
+      : projectOrRoot?.path;
+  if (root) {
+    const legacy = legacyAgentMemoryPath(root, slug);
+    if (fs.existsSync(legacy)) return fs.readFileSync(legacy, "utf8");
+  }
+
+  return "";
+}
+
+export function writeAgentMemory(projectOrRoot, slug, body) {
+  ensureAgentRuntimeDir(projectOrRoot, slug);
+  const memory = agentMemoryPath(projectOrRoot, slug);
+  fs.writeFileSync(memory, body);
+  return memory;
+}

package/src/core/agent-system.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { readAgentMemory } from "./agent-memory.js";
 
 // ---------------------------------------------------------------------------
 // Anti-ghost-response rules injected into every agent system prompt.
@@ -62,8 +63,8 @@ export function buildAgentSystem(project, agent, {
 
   parts.push(buildInvocationContext({ invocation, runtime, channel, caller, routine }));
 
-  const memPath = path.join(project.path, ".apc", "agents", agent.slug, "memory.md");
-  if (fs.existsSync(memPath)) parts.push("## Memory\n" + fs.readFileSync(memPath, "utf8"));
+  const memory = readAgentMemory(project, agent.slug);
+  if (memory) parts.push("## Memory\n" + memory);
 
   const apxSkill = path.join(project.path, ".apc", "skills", "apx.md");
   if (fs.existsSync(apxSkill)) parts.push("## APX\n" + fs.readFileSync(apxSkill, "utf8"));

package/src/core/confirmation/adapters/code.js

@@ -0,0 +1,41 @@
+// Code-surface confirmation adapter.
+//
+// Same stdin readline pattern as terminal, but formatted for the code TUI:
+// more structured output so it's visually distinct from agent output in the
+// split-pane Build mode. Uses stderr to avoid polluting the code output stream.
+
+import readline from "node:readline";
+
+const SEPARATOR = "─".repeat(60);
+
+/**
+ * Creates a requestConfirmation function for the code channel.
+ *
+ * @returns {(tool: string, args: object, description: string) => Promise<boolean>}
+ */
+export function createCodeConfirmAdapter() {
+  return async function requestConfirmation(_tool, _args, description) {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stderr,
+      terminal: false,
+    });
+
+    return new Promise((resolve) => {
+      process.stderr.write(
+        `\n${SEPARATOR}\n` +
+        `[apx] CONFIRM ACTION\n` +
+        `  ${description}\n` +
+        `  Answer [y = yes / N = no]: `
+      );
+      rl.once("line", (answer) => {
+        rl.close();
+        const confirmed = /^(y|yes|ok)$/i.test(answer.trim());
+        process.stderr.write(confirmed ? "✓ Confirmed\n" : "✗ Cancelled\n");
+        process.stderr.write(`${SEPARATOR}\n`);
+        resolve(confirmed);
+      });
+      rl.once("close", () => resolve(false));
+    });
+  };
+}

package/src/core/confirmation/adapters/telegram.js

@@ -0,0 +1,134 @@
+// Telegram confirmation adapter — async inline keyboard.
+//
+// Flow (why a Promise survives across two independent HTTP calls):
+//
+//   1. requestConfirmation() is called by the agent loop mid-tool-execution.
+//      It creates a pending entry in the shared store, embeds the correlationId
+//      in the button callback_data, sends the keyboard to Telegram, and returns
+//      a Promise that is NOT yet resolved.
+//
+//   2. The agent loop is now suspended at `await requestConfirmation(...)`.
+//      The Telegram bot's polling loop keeps running independently.
+//
+//   3. When the user taps a button, Telegram sends a callback_query update.
+//      The plugin's _handleUpdate() routes it to handleCallbackQuery() here.
+//
+//   4. handleCallbackQuery() calls pendingStore.resolve(correlationId, value),
+//      which finds the Promise's resolve function in the in-memory map and
+//      calls it. The agent loop resumes with true or false.
+//
+// Idempotency: once the promise resolves the entry is removed from the store.
+// Any subsequent tap on the same button won't find an entry and is a no-op.
+//
+// Post-restart stale buttons: if the process restarted after sending the
+// keyboard but before the user tapped, pendingStore.wasKnown() detects the
+// SQLite row with no memory entry and we show "Expirado" instead of an error.
+
+const API_BASE = "https://api.telegram.org";
+const TIMEOUT_MS = 60_000; // 60 s — long enough for a human, short enough to not block forever
+
+/**
+ * @param {{ token: string, chatId: string|number, pendingStore: ConfirmationPendingStore }} opts
+ * @returns {{ requestConfirmation, handleCallbackQuery }}
+ */
+export function createTelegramConfirmAdapter({ token, chatId, pendingStore }) {
+  async function requestConfirmation(tool, _args, description) {
+    const { correlationId, promise } = pendingStore.create({ timeoutMs: TIMEOUT_MS });
+
+    await sendConfirmKeyboard(token, chatId, description, correlationId, TIMEOUT_MS);
+
+    return promise;
+  }
+
+  // Called by ChannelPoller._handleUpdate() when a callback_query arrives.
+  // Returns true if the callback matched our pattern (consumed it), false otherwise.
+  async function handleCallbackQuery(callbackQuery) {
+    const data = callbackQuery.data || "";
+    const match = data.match(/^apx:confirm:([a-f0-9]{16}):(yes|no)$/);
+    if (!match) return false;
+
+    const [, correlationId, answer] = match;
+    const confirmed = answer === "yes";
+
+    // ACK the callback immediately to clear the loading spinner on the button.
+    // Fire-and-forget — a slow ACK is annoying but not fatal.
+    await answerCallbackQuery(token, callbackQuery.id, confirmed ? "✅ Confirmed" : "❌ Cancelled");
+
+    const resolved = pendingStore.resolve(correlationId, confirmed);
+
+    // If not resolved, the entry timed out or the process restarted — show "Expired"
+    // so the user knows the button is no longer actionable.
+    const inlineKeyboard = resolved
+      ? [[{ text: confirmed ? "✅ Confirmed" : "❌ Cancelled", callback_data: "apx:noop" }]]
+      : [[{ text: "⏱ Expired", callback_data: "apx:noop" }]];
+
+    if (callbackQuery.message?.chat?.id && callbackQuery.message?.message_id) {
+      await editMessageButtons(
+        token,
+        callbackQuery.message.chat.id,
+        callbackQuery.message.message_id,
+        inlineKeyboard
+      );
+    }
+
+    return true;
+  }
+
+  return { requestConfirmation, handleCallbackQuery };
+}
+
+// ---------- Telegram API helpers --------------------------------------------
+
+async function sendConfirmKeyboard(token, chatId, description, correlationId, timeoutMs) {
+  const timeoutSec = Math.round(timeoutMs / 1000);
+  await fetch(`${API_BASE}/bot${token}/sendMessage`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      chat_id: chatId,
+      text:
+        `⚠️ *Confirm action*\n\n${escapeMarkdown(description)}\n\n` +
+        `_Expires in ${timeoutSec}s. No response → cancelled._`,
+      parse_mode: "Markdown",
+      reply_markup: {
+        inline_keyboard: [[
+          { text: "✅ Yes", callback_data: `apx:confirm:${correlationId}:yes` },
+          { text: "❌ No",  callback_data: `apx:confirm:${correlationId}:no` },
+        ]],
+      },
+    }),
+  });
+}
+
+async function answerCallbackQuery(token, callbackQueryId, text) {
+  try {
+    await fetch(`${API_BASE}/bot${token}/answerCallbackQuery`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ callback_query_id: callbackQueryId, text }),
+    });
+  } catch {
+    // best-effort — Telegram gives only 30s to answer; after that it's already cleared
+  }
+}
+
+async function editMessageButtons(token, chatId, messageId, inlineKeyboard) {
+  try {
+    await fetch(`${API_BASE}/bot${token}/editMessageReplyMarkup`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        chat_id: chatId,
+        message_id: messageId,
+        reply_markup: { inline_keyboard: inlineKeyboard },
+      }),
+    });
+  } catch {
+    // best-effort
+  }
+}
+
+// Escape Markdown special chars so description text doesn't break Telegram markup.
+function escapeMarkdown(text) {
+  return String(text || "").replace(/[_*[\]()~`>#+\-=|{}.!]/g, "\\$&");
+}

package/src/core/confirmation/adapters/terminal.js

@@ -0,0 +1,35 @@
+// Terminal confirmation adapter — synchronous stdin readline.
+//
+// The agent loop blocks here while waiting for user input. This is fine on
+// the terminal surface because the whole process is interactive and
+// single-threaded from the user's perspective.
+
+import readline from "node:readline";
+
+/**
+ * Creates a requestConfirmation function for the terminal channel.
+ * Uses stderr so stdout remains clean (useful when output is piped).
+ *
+ * @returns {(tool: string, args: object, description: string) => Promise<boolean>}
+ */
+export function createTerminalConfirmAdapter() {
+  return async function requestConfirmation(_tool, _args, description) {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stderr,
+      terminal: false,
+    });
+
+    return new Promise((resolve) => {
+      process.stderr.write(
+        `\n⚠  Confirmation required\n   ${description}\n   Continue? [y/N] `
+      );
+      rl.once("line", (answer) => {
+        rl.close();
+        resolve(/^(y|yes|ok)$/i.test(answer.trim()));
+      });
+      // Covers Ctrl+C / EOF while waiting.
+      rl.once("close", () => resolve(false));
+    });
+  };
+}

package/src/core/confirmation/adapters/web.js

@@ -0,0 +1,53 @@
+// Web / TUI confirmation adapter — async SSE + HTTP confirm endpoint.
+//
+// How the Promise resolves across two separate HTTP calls:
+//
+//   1. The agent loop (running inside an SSE request handler) calls
+//      requestConfirmation(). This emits a "confirmation_required" SSE event
+//      containing the correlationId and description, then suspends by awaiting
+//      the pending store's Promise.
+//
+//   2. The browser / TUI receives the SSE event and renders a confirm/cancel
+//      dialog. The dialog is keyed by correlationId.
+//
+//   3. The user responds → frontend POSTs to
+//      POST /super-agent/confirm/:correlationId  { confirmed: boolean }
+//
+//   4. The API handler (api/confirm.js) calls pendingStore.resolve(correlationId,
+//      value). This finds the in-memory resolve callback and calls it, unblocking
+//      the agent loop. The SSE stream receives the next event and continues.
+//
+// `onEvent` is the SSE emitter for the current turn. It's injected at adapter
+// creation time (each turn gets its own adapter instance) so the "please show
+// a dialog" event reaches the right open SSE connection.
+
+import { getConfirmationStore } from "../pending-store.js";
+
+const TIMEOUT_MS = 120_000; // 2 min — humans on screens are slower than keyboard
+
+/**
+ * Factory — call once per SSE turn, passing the turn's `onEvent` emitter.
+ *
+ * @param {{ onEvent: (event: object) => Promise<void>|void }} opts
+ * @returns {(tool: string, args: object, description: string) => Promise<boolean>}
+ */
+export function createWebConfirmAdapter({ onEvent }) {
+  return async function requestConfirmation(tool, _args, description) {
+    const store = getConfirmationStore();
+
+    const { correlationId, promise } = store.create({ timeoutMs: TIMEOUT_MS });
+
+    // Push a structured event to the open SSE stream so the frontend knows
+    // to render a confirmation dialog. The correlationId is the shared key
+    // between this pending promise and the POST /confirm/:correlationId call.
+    await onEvent({
+      type: "confirmation_required",
+      correlationId,
+      tool,
+      description,
+      timeout_ms: TIMEOUT_MS,
+    });
+
+    return promise;
+  };
+}

package/src/core/confirmation/index.js

@@ -0,0 +1,44 @@
+// Human-in-the-loop confirmation system.
+//
+// Public surface:
+//   getConfirmationStore()          shared SQLite-backed pending store
+//   buildConfirmDescription(t, a)   human-readable action summary
+//   isConfirmationRequired(err)     true when a tool threw requires_confirmation:
+//
+// Adapters (one per channel type) live under ./adapters/.
+
+export { getConfirmationStore, ConfirmationPendingStore } from "./pending-store.js";
+
+/**
+ * Returns true when `error` was thrown by createPermissionGuard() to signal
+ * that this tool call needs explicit user approval before proceeding.
+ */
+export function isConfirmationRequired(error) {
+  return (
+    error != null &&
+    typeof error.message === "string" &&
+    error.message.startsWith("requires_confirmation:")
+  );
+}
+
+/**
+ * Build a short, human-readable description of the action being confirmed.
+ * Shown in all confirmation channels (terminal prompt, Telegram message, web dialog).
+ */
+export function buildConfirmDescription(tool, args) {
+  const text = (s, max = 150) => String(s || "").slice(0, max);
+
+  const builders = {
+    send_telegram: (a) => `Send Telegram message: "${text(a.text)}"`,
+    run_shell:     (a) => `Run shell command: \`${text(a.command)}\``,
+    write_file:    (a) => `Write file: ${a.path || a.file || "(no path)"}`,
+    edit_file:     (a) => `Edit file: ${a.path || a.file || "(no path)"}`,
+    create_task:   (a) => `Create task: "${a.title || a.name || "?"}"`,
+    add_project:   (a) => `Add project: ${a.path || a.name || "?"}`,
+    set_identity:  (a) => `Change agent identity to: "${a.name || "?"}"`,
+    call_runtime:  (a) => `Call runtime: ${a.runtime || a.name || "?"}`,
+  };
+
+  const fn = builders[tool];
+  return fn ? fn(args) : `Run tool: \`${tool}\``;
+}

package/src/core/confirmation/pending-store.js

@@ -0,0 +1,68 @@
+// Pending confirmation store: in-memory map of unresolved confirmations.
+//
+// Each entry holds a Promise's resolve callback and a timeout timer.
+// When the user responds (any channel), resolve() is called and the agent
+// loop that was suspended at `await requestConfirmation(...)` resumes.
+//
+// No persistence needed: confirmations are ephemeral (30–120s window).
+// If the daemon restarts, the agent runs that created them are also dead,
+// so there is nothing to resume. Stale Telegram buttons simply won't find
+// an entry and the handleCallbackQuery path shows "Expired" gracefully.
+
+import { randomBytes } from "node:crypto";
+
+function generateId() {
+  return randomBytes(8).toString("hex"); // 16 hex chars, URL-safe
+}
+
+export class ConfirmationPendingStore {
+  constructor() {
+    // correlationId -> { resolve: (boolean) => void, timer: NodeJS.Timeout }
+    this._pending = new Map();
+  }
+
+  /**
+   * Register a new pending confirmation.
+   *
+   * Returns { correlationId, promise } where:
+   *   - correlationId: embed in the reply (button callback_data, SSE event…)
+   *   - promise: resolves to true (confirmed) or false (denied / timeout)
+   *
+   * After timeoutMs with no response the promise auto-resolves to false.
+   */
+  create({ timeoutMs = 30_000 } = {}) {
+    const correlationId = generateId();
+
+    const promise = new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this._pending.delete(correlationId);
+        resolve(false);
+      }, timeoutMs);
+      this._pending.set(correlationId, { resolve, timer });
+    });
+
+    return { correlationId, promise };
+  }
+
+  /**
+   * Resolve a pending confirmation.
+   * Returns true if found and resolved, false if not found (timed out, already
+   * resolved, or stale button after a process restart).
+   */
+  resolve(correlationId, value) {
+    const entry = this._pending.get(correlationId);
+    if (!entry) return false;
+    clearTimeout(entry.timer);
+    this._pending.delete(correlationId);
+    entry.resolve(value);
+    return true;
+  }
+}
+
+// Singleton — one store per daemon process, shared by all adapters.
+let _store = null;
+
+export function getConfirmationStore() {
+  if (!_store) _store = new ConfirmationPendingStore();
+  return _store;
+}

package/src/core/scaffold.js

@@ -325,24 +325,60 @@ const AGENTS_MD_TEMPLATE = `# AGENTS.md
 <!-- Hard constraints: what agents must always / never do here. -->
 `;
 
-const APC_GITIGNORE = `# APC runtime data — never in the repository
-# Chat conversations and runtime sessions belong in ~/.apx/projects/<id>/
-agents/*/sessions/
-agents/*/conversations/
+const APC_GITIGNORE = `# APC repository-safe context only.
+# Runtime state belongs in ~/.apx/projects/<id>/, not in .apc/.
+
+# Legacy per-agent runtime dirs (agent definitions are flat: agents/<slug>.md)
+agents/*/
+
+# Runtime sessions / conversations / messages
 sessions/
 conversations/
 messages/
 chats/
+threads/
+transcripts/
+runs/
+
+# Runtime memory, indexes, databases, and caches
+memory.local.md
+auto-memory.md
 cache/
 tmp/
 private/
 secrets/
+*.db
+*.db-*
+*.sqlite
+*.sqlite3
+project.db
+memory.db
+memory-index.jsonl
+memory-cursor.json
+
+# Local config and secrets
+.env
 *.local.json
 *.secret.json
 *.env
 *.env.*
-project.db
+*.key
+*.pem
+*.p12
+*.crt
+credentials.json
+service-account*.json
+token*.json
+mcps.local.json
+config.local.json
+
+# Scratch planning state
+plans/scratch/
+plans/*.local.md
+
+# Migration marker and OS noise
 migrate.md
+.DS_Store
 `;
 
 function nowIso() {
@@ -448,19 +484,8 @@ export function initApf(directory, { name } = {}) {
 }
 
 export function ensureAgentDir(root, slug) {
-  const dir = path.join(root, ".apc", "agents", slug);
-  fs.mkdirSync(dir, { recursive: true });
-  const memory = path.join(dir, "memory.md");
-  if (!fs.existsSync(memory)) {
-    fs.writeFileSync(
-      memory,
-      `# Memory — ${slug}\n\n` +
-        `## Identity\n- \n\n` +
-        `## Long-term facts\n- \n\n` +
-        `## Recent context\n- \n`
-    );
-  }
-  return dir;
+  fs.mkdirSync(path.join(root, ".apc", "agents"), { recursive: true });
+  return path.join(root, ".apc", "agents");
 }
 
 // Write .apc/agents/<slug>.md — the canonical agent definition file.