@agentprojectcontext/apx 1.0.3 → 1.1.0

package/README.md

@@ -16,7 +16,7 @@ APX is a daemon + CLI that brings the APC convention to life:
 - **Plugins** — Telegram bot integration out of the box
 - **MCP support** — each agent can expose or consume MCP servers
 
-APX is opinionated about storage: the filesystem is the source of truth. No database required to read agent state. Project definitions live in the repo; runtime state (memory, sessions) lives in `~/.apx/` and is never committed.
+APX is opinionated about storage: the filesystem is the source of truth. Project definitions and curated memory live in the repo. Runtime state such as sessions, conversations, messages, and caches lives in `~/.apx/` and is never committed.
 
 ## Quick start
 
@@ -65,13 +65,12 @@ Runtime state — local machine only, never committed:
 ```text
 ~/.apx/projects/<project-id>/
 ├── project.db             ← regenerable SQLite cache
+├── messages/              ← local message history
 └── agents/
     ├── <slug>/
-    │   ├── memory.md      ← durable memory, updated by the agent
     │   ├── sessions/      ← one .md per runtime invocation
     │   └── conversations/ ← LLM conversation threads
     └── default/           ← fallback when no agent role is active
-        ├── memory.md
         └── sessions/
 ```
 
@@ -94,7 +93,8 @@ apx messages tail --channel runtime      # only agent invocations
 
 ## Message channels
 
-All activity is logged to `.apc/messages/YYYY-MM-DD.jsonl`:
+Activity belongs to APX runtime state, not `.apc/`. Message storage is local to APX, under
+`~/.apx/`:
 
 | Channel | What it captures |
 |---------|-----------------|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"
@@ -33,7 +33,10 @@
     "node-fetch": "^3.3.2"
   },
   "devDependencies": {
-    "better-sqlite3": "^11.3.0"
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "better-sqlite3": "^11.3.0",
+    "conventional-changelog-conventionalcommits": "^9.3.1"
   },
   "keywords": [
     "apc",

package/skills/apx/SKILL.md

@@ -4,11 +4,13 @@ description: "APX CLI skill. Activate ONLY when the user asks about running agen
 homepage: https://github.com/agentprojectcontext/apx
 ---
 
-# APX — Agent Project Framework
+# APX — Agent Project Context Runtime
 
 This project uses **APX**. The daemon runs on `127.0.0.1:7430` and auto-starts on first `apx` call.
 Your current session, project, and agent are already injected above this block — refer to them.
 
+APX runtime state belongs outside `.apc/`, under `~/.apx/projects/<project-id>/`.
+
 ---
 
 ## Discover the project
@@ -32,7 +34,7 @@ apx exec <slug> "<prompt>"
 The output of `apx run` / `apx exec` is the agent's full stdout.
 If the agent printed `APC_RESULT: <value>`, that value is also captured as structured output.
 
-## Memory — durable, persists between sessions
+## Memory — durable, safe facts
 
 ```bash
 apx memory <slug>                       # read agent's memory.md
@@ -40,7 +42,7 @@ apx memory <slug> --append "<fact>"     # append a durable note (non-destructive
 apx memory <slug> --replace < file.md  # replace entire memory from stdin
 ```
 
-Write to memory when you discover something the agent should know on every future run.
+Write to memory only when you discover safe project context the agent should know on future runs.
 
 ## Observe activity
 
@@ -74,4 +76,5 @@ Print this on the last meaningful line of your output:
 APC_RESULT: <one-line summary or value>
 ```
 The invoker (`apx run`, super-agent, Telegram bot) captures it as structured output.
-Keep it factual and short — it becomes the session result stored in `.apc/agents/<slug>/sessions/`.
+Keep it factual and short. It becomes the session result stored in APX local runtime state, not
+inside `.apc/`.

package/src/cli/commands/project.js

@@ -109,11 +109,8 @@ export async function resolveProjectId(target) {
   // No override: walk up from cwd
   const root = findApfRoot();
   if (!root) {
-    const registered = await http.get("/projects").catch(() => []);
-    const hint = registered.length
-      ? `registered projects: ${registered.map((p) => `"${p.name}" (id ${p.id})`).join(", ")}`
-      : "no projects registered yet — run `apx project add <path>` first";
-    throw new Error(`not inside an APC project. Use --project <name|id|path>. ${hint}`);
+    // Fall back to the default project (id=0) — always available, no .apc/ required.
+    return 0;
   }
   const projects = await http.get("/projects");
   const found = projects.find((p) => p.path === root);

package/src/cli/commands/session.js

@@ -1,8 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
 import { findApfRoot, readAgents } from "../../core/parser.js";
-import { ensureAgentDir } from "../../core/scaffold.js";
+import { getOrCreateApxId } from "../../core/scaffold.js";
 import { generateSessionId } from "../../core/session-store.js";
+import { ensureProjectStorage } from "../../core/config.js";
 import { http } from "../http.js";
 import { resolveProjectId } from "./project.js";
 
@@ -14,6 +15,12 @@ function requireRoot() {
   return root;
 }
 
+function requireStorageRoot(root) {
+  const apxId = getOrCreateApxId(root);
+  if (!apxId) throw new Error("could not resolve APX project storage id");
+  return ensureProjectStorage(apxId);
+}
+
 const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 
 function readStdinSync() {
@@ -61,7 +68,7 @@ function setFrontmatterField(text, field, value) {
 }
 
 function listAllSessions(root) {
-  const agentsDir = path.join(root, ".apc", "agents");
+  const agentsDir = path.join(requireStorageRoot(root), "agents");
   if (!fs.existsSync(agentsDir)) return [];
   const out = [];
   for (const slug of fs.readdirSync(agentsDir)) {
@@ -124,10 +131,11 @@ export function cmdSessionNew(args) {
     throw new Error(`agent "${slug}" not found in AGENTS.md`);
   }
 
-  ensureAgentDir(root, slug);
-  const id = generateSessionId(root, slug);
+  const storageRoot = requireStorageRoot(root);
+  const id = generateSessionId(storageRoot, slug);
   const filename = `${id}.md`;
-  const filepath = path.join(root, ".apc", "agents", slug, "sessions", filename);
+  const filepath = path.join(storageRoot, "agents", slug, "sessions", filename);
+  fs.mkdirSync(path.dirname(filepath), { recursive: true });
 
   const taskRef = args.flags["task-ref"] === true ? "" : (args.flags["task-ref"] || "");
   let body = "";

package/src/cli/commands/update.js

@@ -0,0 +1,75 @@
+import { spawnSync } from "node:child_process";
+import readline from "node:readline";
+import { getLatestVersion } from "../../core/update-check.js";
+
+const PACKAGE_NAME = "@agentprojectcontext/apx";
+
+export async function cmdUpdate(args) {
+  const force = args.flags.force || args.flags.yes || args.flags.y;
+
+  console.log("Checking for updates...");
+  const latest = await getLatestVersion();
+
+  if (!latest) {
+    console.error("Could not reach npm registry. Check your connection.");
+    process.exit(1);
+  }
+
+  // Read current version from the package that owns this file.
+  const { createRequire } = await import("node:module");
+  const { fileURLToPath } = await import("node:url");
+  const require = createRequire(import.meta.url);
+  const pkg = require("../../package.json");
+  const current = pkg.version;
+
+  function isNewer(cur, lat) {
+    const parse = (v) => v.replace(/^v/, "").split(".").map(Number);
+    const [ma, mi, pa] = parse(cur);
+    const [mb, mib, pb] = parse(lat);
+    if (mb > ma) return true;
+    if (mb === ma && mib > mi) return true;
+    if (mb === ma && mib === mi && pb > pa) return true;
+    return false;
+  }
+
+  if (!isNewer(current, latest)) {
+    console.log(`✅ Already up to date (${current})`);
+    return;
+  }
+
+  console.log(`\n  Current: ${current}`);
+  console.log(`  Latest:  ${latest}`);
+
+  if (!force) {
+    const confirmed = await confirm(`\nUpdate to ${latest}? [y/N] `);
+    if (!confirmed) {
+      console.log("Cancelled.");
+      return;
+    }
+  }
+
+  console.log(`\nRunning: npm install -g ${PACKAGE_NAME}@${latest}\n`);
+  const result = spawnSync(
+    "npm",
+    ["install", "-g", `${PACKAGE_NAME}@${latest}`],
+    { stdio: "inherit" }
+  );
+
+  if (result.status !== 0) {
+    console.error(`\n❌ Update failed (exit ${result.status})`);
+    process.exit(result.status || 1);
+  }
+
+  console.log(`\n✅ Updated to ${latest}. Restart any running apx daemon:`);
+  console.log(`   apx daemon stop && apx daemon start`);
+}
+
+function confirm(prompt) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(prompt, (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(answer.trim()));
+    });
+  });
+}

package/src/cli/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// apx — unified CLI for APC (Agent Project Framework).
+// apx — unified CLI for APC (Agent Project Context).
 // ESM, Node >= 18.
 import fs from "node:fs";
 import path from "node:path";
@@ -71,6 +71,8 @@ import { cmdPluginsList, cmdPluginStatus } from "./commands/plugins.js";
 import { cmdSkillsAdd, cmdSkillsList, cmdSkillsStatus } from "./commands/skills.js";
 import { cmdIdentity } from "./commands/identity.js";
 import { cmdCommandList, cmdCommandShow } from "./commands/command.js";
+import { cmdUpdate } from "./commands/update.js";
+import { checkForUpdate } from "../core/update-check.js";
 import {
   cmdRoutineList,
   cmdRoutineGet,
@@ -87,17 +89,18 @@ const VERSION = JSON.parse(
   fs.readFileSync(path.join(__dirname, "..", "..", "package.json"), "utf8")
 ).version;
 
-const HELP = `apx — Agent Project Framework
+const HELP = `apx — Agent Project Context
 
 Usage:
   apx <command> [<subcommand>] [args] [--flags]
 
 Bootstrap:
   apx init [path] [--name "<name>"]                    initialize an APC project
-  apx project add <path>                               register a project with the daemon
+  apx project add [path]                               register a project with the daemon
   apx project list
   apx project remove <path|id>
-  apx project rebuild [<path|id>]                      rebuild SQLite cache from filesystem
+  apx project rebuild [<path|id>]                      rebuild project index from filesystem
+  apx add project [path]                               alias for: apx project add
 
 Agents:
   apx agent add <slug> [--role R] [--model M] [--skills a,b] [--language es-AR] [--description D]
@@ -144,7 +147,7 @@ Telegram:
 Messages:
   apx messages tail [--agent <slug>] [--channel <ch>] [-n 50] [--global]
                      global channels (telegram, direct, whatsapp) → ~/.apx/messages/<ch>/
-                     project channels (runtime, a2a, exec)        → <project>/.apc/messages/
+                     project channels (runtime, a2a, exec)        → ~/.apx/projects/<id>/messages/
   apx messages search "<query>"
 
 LLM engines (v0.2):
@@ -200,6 +203,7 @@ Skills (IDE integration):
   apx skills status                    show which IDE targets are installed (project + global)
 
 Other:
+  apx update                                           check for updates and upgrade (alias: apx upgrade)
   apx --help
   apx --version
 
@@ -466,6 +470,19 @@ async function dispatch(cmd, rest) {
         await cmdIdentity(parseArgs(rest));
         break;
 
+      case "add": {
+        // apx add <domain> [...args] — consistent alternative to apx <domain> add
+        const sub = rest[0];
+        if (sub === "project") await cmdProjectAdd(parseArgs(rest.slice(1)));
+        else die(`unknown 'add' subcommand: ${sub || "(none)"} — try: project`);
+        break;
+      }
+
+      case "update":
+      case "upgrade":
+        await cmdUpdate(parseArgs(rest));
+        return; // skip checkForUpdate after an update
+
       default:
         die(`unknown command: ${cmd}\nRun \`apx --help\` for usage.`);
     }
@@ -475,6 +492,7 @@ const [topCmd, ...topRest] = argv;
 (async () => {
   try {
     await dispatch(topCmd, topRest);
+    checkForUpdate(VERSION);
   } catch (err) {
     die(err && err.message ? err.message : String(err));
   }

package/src/core/apc-context-skill.md

@@ -1,150 +1,102 @@
 
 # Agent Project Context
 
-This project uses APC. All agent context lives in `.apc/` — not in `.claude/`, `.cursor/`, `.windsurf/`, or any other IDE folder.
+This project uses APC. APC stores portable project context in `.apc/` and `AGENTS.md`.
+
+APC does not store raw runtime sessions. Sessions, conversations, messages, caches, provider
+threads, and private runtime memory stay in the IDE, CLI, daemon, or user-level store that created
+them.
 
 ## FIRST: check for pending migration
 
-**Before doing anything else**, check if `.apc/migrate.md` exists:
+Before doing anything else, check if `.apc/migrate.md` exists:
 
 ```bash
 cat .apc/migrate.md 2>/dev/null
 ```
 
-If it exists, open the conversation with this message — do not answer any other question first:
-
-> I see this project was just initialized with **Agent Project Context (APC)**.
->
-> I found context files that haven't been migrated yet:
-> [list files from .apc/migrate.md]
->
-> I'll read them, understand what's in them, and migrate intelligently — keeping only what APC doesn't already handle.
->
-> **Want me to start?**
+If it exists, offer to migrate before answering anything else. Read detected files, separate durable
+project context from runtime/private state, and migrate only what belongs in APC.
 
-### How to migrate — think, don't copy
+If the user says no or later, delete `.apc/migrate.md` so the offer is not repeated.
 
-**Step 1 — Read everything first.** Read all detected context files in full. Also read `AGENTS.md` if it exists. Understand the full project structure, conventions, and any referenced directories (e.g. `works/`, `docs/`, `notes/`).
+## Migration rule: think, do not copy
 
-**Step 2 — Classify each piece of content:**
+Classify content:
 
-| What it says | What to do |
+| Content | Action |
 |---|---|
-| Agent definitions (role, model, skills) | Create `.apc/agents/<slug>.md` |
-| Any instruction about writing sessions to a custom path (`works/sessions/`, `notes/`, etc.) | **Drop it** — APC handles sessions natively in `.apc/agents/<slug>/sessions/` |
-| Any instruction about writing memory to a custom path (`works/memory.md`, etc.) | **Drop it** — APC handles memory natively in `.apc/agents/<slug>/memory.md` |
-| "List agents in `AGENTS.md`" or any auto-generation rule for `AGENTS.md` | **Drop it** — APC handles this natively |
-| Project-specific directories not covered by APC (e.g. `works/specs/`, `works/tasks/`) | **Keep in `AGENTS.md`** — document the convention there |
-| Project rules, testing policy, stack notes, URLs, credentials | **Keep in `AGENTS.md`** — project context that APC doesn't define |
-| IDE-specific shortcuts or instructions (e.g. "run `npm run dev` in Claude terminal") | **Keep in `AGENTS.md`** — still useful to all agents |
-
-**Step 3 — Write `AGENTS.md`.** Start from what already exists in `AGENTS.md`, add what you kept from the classified content. Remove anything that duplicates APC native behavior. Keep it agent-neutral — no IDE-specific framing.
-
-**Step 4 — Delete the original files** (`CLAUDE.md`, `.cursorrules`, etc.). Do not leave stubs. The content either moved to `AGENTS.md` / `.apc/agents/` or was intentionally dropped because APC covers it.
-
-**Step 5 — Delete `.apc/migrate.md`** to mark migration complete.
-
-**Step 6 — Summarize** what was created, what was kept, and what was dropped (and why).
-
-If the user says no or later: delete `.apc/migrate.md` immediately so this offer is not shown again in future sessions.
-
----
-
-## Structure
-
-```
-AGENTS.md                        ← project context: rules, stack, conventions (commit)
+| Agent definitions: role, model, skills, description | Put in `.apc/agents/<slug>.md` and/or `AGENTS.md` |
+| Shared project rules, stack notes, commands, testing policy | Keep in `AGENTS.md` |
+| Reusable instruction blocks | Move to `.apc/skills/<name>.md` |
+| Durable safe facts useful to all contributors | Add to `.apc/agents/<slug>/memory.md` only after curation |
+| MCP expectations without secrets | Add to `.apc/mcps.json` |
+| Raw sessions, transcripts, conversations, messages, tool logs | Do not move into `.apc/`; leave with source runtime |
+| Secrets, tokens, credentials, private headers | Do not store in repository |
+| IDE UI settings or personal aliases | Leave in IDE/user config |
+| Instructions to store sessions under `.apc/` | Drop as obsolete |
+
+## APC structure
+
+```text
+AGENTS.md                        ← root project contract
 .apc/
-  project.json                   ← metadata + apx field (commit)
-  .gitignore                     ← safe defaults, created by apx init (commit)
-  agents/<slug>.md               ← agent definition (commit)
-  agents/<slug>/
-    memory.md                    ← curated memory (commit)
-    sessions/                    ← raw session logs (local-only, gitignored)
-  skills/                        ← reusable prompt fragments (commit)
-  mcps.json                      ← MCP declarations without secrets (commit)
+  project.json                   ← project metadata
+  .gitignore                     ← safety guard
+  agents/<slug>.md               ← agent definition
+  agents/<slug>/memory.md        ← optional curated project memory
+  skills/<name>.md               ← reusable project instructions
+  mcps.json                      ← MCP hints without secrets
 ```
 
-## Visibility rules
-
-| What | Visibility | Commit? |
-|---|---|---|
-| Agent definitions, skills, rules | `stable` / `project` | Yes |
-| `memory.md` | `project` | Yes |
-| `sessions/` | `local` | No — gitignored |
-| `secrets/`, `*.secret.json`, `*.env` | `private` | Never |
-| `cache/`, `tmp/` | `ephemeral` | No — gitignored |
-| `migrate.md` | `ephemeral` | No — gitignored |
-
-**Write sessions to `.apc/agents/<slug>/sessions/`** — they stay local. Extract meaningful decisions into `memory.md` — that travels with the repo.
-
-## Rules
-
-1. Read your definition and memory from `.apc/agents/<your-slug>/`
-2. Write memory to `.apc/agents/<your-slug>/memory.md` — never to IDE-specific folders
-3. Write raw session logs to `.apc/agents/<your-slug>/sessions/` — they are gitignored
-4. `AGENTS.md` is the neutral project context file — edit it directly, it is not auto-generated
-5. To list agents: read `AGENTS.md` or list `.apc/agents/*.md`
-
-## Sessions — write one at the end of every task
-
-Sessions are the record of what was done, for future agents and for the team.
+Do not store:
+
+```text
+.apc/agents/<slug>/sessions/
+.apc/sessions/
+.apc/conversations/
+.apc/messages/
+.apc/project.db
+.apc/cache/
+.apc/tmp/
+.apc/private/
+.apc/secrets/
+```
 
-**Where to write:**
-- APC standard path: `.apc/agents/<slug>/sessions/<date>-<slug>.md` (gitignored)
-- Project-specific path: check `AGENTS.md` — some projects use `works/sessions/` or similar
+## Operating rules
 
-**Format — always use this frontmatter:**
+1. Read `AGENTS.md` and relevant `.apc/` files before assuming project context.
+2. Read agent definitions from `.apc/agents/<slug>.md` when present.
+3. Read curated project memory from `.apc/agents/<slug>/memory.md` when present.
+4. Write only durable, safe, curated facts to APC memory.
+5. Never write raw sessions, transcripts, messages, conversations, or tool logs into `.apc/`.
+6. Keep secrets out of APC and out of git.
+7. Treat `.apc/mcps.json` as MCP configuration hints, not as an MCP implementation.
 
-```markdown
----
-title: Short title of what was done
-description: One-line summary for the index
-date: YYYY-MM-DD
-status: open | completed | in-progress | abandoned
----
+## Sessions
 
-## Goal
-What was the task or request.
+Sessions belong to the runtime that created them.
 
-## Done
-What was completed. Be specific — file paths, decisions, changes.
+Examples:
 
-## Pending
-Anything left unfinished or deferred.
+```text
+Codex runtime storage
+Claude Code runtime storage
+OpenCode runtime storage
+~/.apx/projects/<project-id>/agents/<slug>/sessions/
 ```
 
-**How to create:**
-- If APX is installed (`apx` field in `project.json` is `"installed"`):
-  ```bash
-  apx session new <slug> --title "Short title"
-  ```
-  Then fill in `description`, update `status` to `completed` when done.
-- If APX is not available: create the file manually following the format above.
-
-**When to write:** at the end of every task session, before closing. Not optional.
+At task end, provide the user a concise result. If project memory should be updated, write a short
+sanitized fact to `.apc/agents/<slug>/memory.md` only when useful and safe.
 
-## APX — check once, remember forever
+## APX
 
-Read `.apc/project.json`. It has an `apx` field:
+APX can provide a local daemon, MCP management, Telegram bridge, routines, and runtime dispatch
+across Codex, Claude Code, OpenCode, Aider, or direct LLM engines. Those are APX runtime features,
+not APC portable-core requirements.
 
-- **`"installed"`** — APX is available. Use `apx` commands freely when useful.
-- **`"declined"`** — user chose not to install. Never suggest or run `apx` commands.
-- **`null` or missing** — unknown. Do the one-time check below, then write the result and never ask again.
+APX runtime state belongs outside the repository:
 
-### One-time APX detection (only when `apx` is null or missing)
-
-```bash
-apx --version 2>/dev/null && echo "FOUND" || echo "NOT_FOUND"
+```text
+~/.apx/projects/<project-id>/
 ```
-
-- If `FOUND`: write `"apx": "installed"` to `.apc/project.json`. Use APX normally.
-- If `NOT_FOUND`: tell the user once:
-
-  > APX is not installed. It adds agent coordination, MCP server management, and memory commands to this project.
-  > Want me to install it? (`npm install -g apx`)
-
-  - If yes: run `npm install -g apx`, then write `"apx": "installed"`.
-  - If no: write `"apx": "declined"`. Never mention APX again in this project.
-
-**Never run `apx` commands if the field is `null`, `"declined"`, or unconfirmed.**

package/src/core/apx-skill.md

@@ -1,7 +1,10 @@
-# APX — Agent Project Framework
+# APX — Agent Project Context Runtime
 
 The daemon runs on `127.0.0.1:7430` and auto-starts on first `apx` call.
 
+APX reads APC project context from `.apc/`, but APX runtime state belongs outside the repository
+under `~/.apx/projects/<project-id>/`.
+
 ---
 
 ## Coordinate with other agents
@@ -48,6 +51,8 @@ apx mcp run filesystem read_file '{"path": "README.md"}'
 
 ## Memory
 
+Write memory only for durable, safe project facts. Do not store raw transcripts or secrets.
+
 ```bash
 apx memory <slug>                       # read agent's memory.md
 apx memory <slug> --append "<fact>"     # append a durable note
@@ -56,8 +61,10 @@ apx memory <slug> --replace < file.md  # replace entire memory from stdin
 
 ## Sessions
 
+Sessions are APX runtime state. They do not belong in `.apc/`.
+
 ```bash
-apx session new <slug> --title "What you did"   # create session file
+apx session new <slug> --title "What you did"   # create APX local session file
 apx session list <slug>                          # list sessions
 apx session check                                # exits 1 if session already active
 ```

package/src/core/config.js

@@ -11,6 +11,21 @@ export const TELEGRAM_STATE_PATH = path.join(APX_HOME, "telegram-state.json");
 // Global channel messages (telegram, direct, whatsapp, …) live here,
 // separated from any project.  Structure: ~/.apx/messages/<channel>/YYYY-MM-DD.jsonl
 export const GLOBAL_MESSAGES_DIR = path.join(APX_HOME, "messages");
+// Per-project runtime storage (conversations, sessions) — never in the repo.
+// Structure: ~/.apx/projects/<apx_id>/agents/<slug>/conversations/
+export const PROJECT_STORE_ROOT = path.join(APX_HOME, "projects");
+export const DEFAULT_PROJECT_ID = "default";
+export const DEFAULT_PROJECT_STORE = path.join(PROJECT_STORE_ROOT, DEFAULT_PROJECT_ID);
+
+export function projectStorageRoot(apxId) {
+  return path.join(PROJECT_STORE_ROOT, apxId);
+}
+
+export function ensureProjectStorage(apxId) {
+  const root = projectStorageRoot(apxId);
+  fs.mkdirSync(root, { recursive: true });
+  return root;
+}
 
 const DEFAULT_CONFIG = {
   port: 7430,

package/src/core/messages-store.js

@@ -1,7 +1,7 @@
 // Messages store: filesystem source-of-truth + SQLite cache mirror.
 //
 // On disk (project-specific — runtime, a2a, exec):
-//   <project>/.apc/messages/YYYY-MM-DD.jsonl
+//   ~/.apx/projects/<project-id>/messages/YYYY-MM-DD.jsonl
 //
 // On disk (global cross-project channels — telegram, direct, whatsapp, …):
 //   ~/.apx/messages/<channel>/YYYY-MM-DD.jsonl
@@ -24,12 +24,12 @@ const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 
 function dayPathJsonl(projectRoot, ts) {
   const day = (ts || nowIso()).slice(0, 10);
-  return path.join(projectRoot, ".apc", "messages", `${day}.jsonl`);
+  return path.join(projectRoot, "messages", `${day}.jsonl`);
 }
 
 function dayPathMd(projectRoot, ts) {
   const day = (ts || nowIso()).slice(0, 10);
-  return path.join(projectRoot, ".apc", "messages", `${day}.md`);
+  return path.join(projectRoot, "messages", `${day}.md`);
 }
 
 export function appendMessageToFs({ projectRoot, channel, direction, author, body, meta = {}, ts, agent_slug, session_id, external_id }) {
@@ -262,7 +262,7 @@ function sanitizeAssistantForContext(content) {
 // ---------------------------------------------------------------------------
 
 export function readProjectMessages(projectRoot, { channel, agent_slug, since, limit = 100 } = {}) {
-  const dir = path.join(projectRoot, ".apc", "messages");
+  const dir = path.join(projectRoot, "messages");
   if (!fs.existsSync(dir)) return [];
   const all = [];
   for (const f of fs.readdirSync(dir).sort()) {
@@ -285,7 +285,7 @@ export function readProjectMessages(projectRoot, { channel, agent_slug, since, l
 export function searchProjectMessages(projectRoot, query, limit = 50) {
   if (!query) return [];
   const q = query.toLowerCase();
-  const dir = path.join(projectRoot, ".apc", "messages");
+  const dir = path.join(projectRoot, "messages");
   if (!fs.existsSync(dir)) return [];
   const all = [];
   for (const f of fs.readdirSync(dir).sort()) {
@@ -392,10 +392,10 @@ export function readGlobalMessages({ channel, limit = 100, since } = {}) {
   return all.slice(-limit);
 }
 
-// Wipe the cache and re-populate from .apc/messages/*. Reads BOTH `.jsonl`
+// Wipe the cache and re-populate from APX project messages. Reads BOTH `.jsonl`
 // (current format) and `.md` (legacy). Called by rebuild.
 export function rebuildMessagesFromFs(db, projectRoot) {
-  const dir = path.join(projectRoot, ".apc", "messages");
+  const dir = path.join(projectRoot, "messages");
   if (!fs.existsSync(dir)) return { count: 0 };
   db.prepare("DELETE FROM messages").run();
 

package/src/core/scaffold.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import crypto from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { readAgents, readAgentsFromDir, VAULT_DIR } from "./parser.js";
 
@@ -188,9 +189,13 @@ const AGENTS_MD_TEMPLATE = `# Agents
 -->
 `;
 
-const APC_GITIGNORE = `# APC runtime data — local-first by default
+const APC_GITIGNORE = `# APC runtime data — never in the repository
+# Chat conversations and runtime sessions belong in ~/.apx/projects/<id>/
 agents/*/sessions/
+agents/*/conversations/
 sessions/
+conversations/
+messages/
 chats/
 cache/
 tmp/
@@ -200,6 +205,7 @@ secrets/
 *.secret.json
 *.env
 *.env.*
+project.db
 migrate.md
 `;
 
@@ -241,6 +247,20 @@ function writeMigrateMd(apfDir, found) {
   fs.writeFileSync(path.join(apfDir, "migrate.md"), lines.join("\n") + "\n");
 }
 
+// Get the stable APX storage ID for a project, generating one if it doesn't exist.
+// Called by the daemon when registering a project.
+export function getOrCreateApxId(root) {
+  const p = path.join(root, ".apc", "project.json");
+  if (!fs.existsSync(p)) return null;
+  let cfg;
+  try { cfg = JSON.parse(fs.readFileSync(p, "utf8")); } catch { return null; }
+  if (cfg.apx_id) return cfg.apx_id;
+  const apxId = crypto.randomUUID().replace(/-/g, "").slice(0, 12);
+  cfg.apx_id = apxId;
+  fs.writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n");
+  return apxId;
+}
+
 export function initApf(directory, { name } = {}) {
   const root = path.resolve(directory);
   fs.mkdirSync(root, { recursive: true });
@@ -252,6 +272,7 @@ export function initApf(directory, { name } = {}) {
 
   const projectJson = path.join(apfDir, "project.json");
   if (!fs.existsSync(projectJson)) {
+    const apxId = crypto.randomUUID().replace(/-/g, "").slice(0, 12);
     fs.writeFileSync(
       projectJson,
       JSON.stringify(
@@ -261,7 +282,7 @@ export function initApf(directory, { name } = {}) {
           apf: SPEC_VERSION,
           created: nowIso(),
           apx: null,
-          sessions: { defaultVisibility: "local" },
+          apx_id: apxId,
         },
         null,
         2
@@ -291,7 +312,7 @@ export function initApf(directory, { name } = {}) {
 
 export function ensureAgentDir(root, slug) {
   const dir = path.join(root, ".apc", "agents", slug);
-  fs.mkdirSync(path.join(dir, "sessions"), { recursive: true });
+  fs.mkdirSync(dir, { recursive: true });
   const memory = path.join(dir, "memory.md");
   if (!fs.existsSync(memory)) {
     fs.writeFileSync(

package/src/core/session-store.js

@@ -5,9 +5,9 @@
 import fs from "node:fs";
 import path from "node:path";
 
-export function generateSessionId(projectRoot, agentSlug) {
+export function generateSessionId(storageRoot, agentSlug) {
   const today = new Date().toISOString().slice(0, 10);
-  const dir = path.join(projectRoot, ".apc", "agents", agentSlug, "sessions");
+  const dir = path.join(storageRoot, "agents", agentSlug, "sessions");
   let next = 1;
   if (fs.existsSync(dir)) {
     for (const f of fs.readdirSync(dir)) {

package/src/core/update-check.js

@@ -0,0 +1,99 @@
+// Update checker — non-blocking, cached 24h.
+// On each command: reads cache → shows message if newer version exists.
+// In background: refreshes cache from npm registry (fire-and-forget).
+// Never slows down the main command.
+
+import fs from "node:fs";
+import path from "node:path";
+import https from "node:https";
+import { APX_HOME } from "./config.js";
+
+const PACKAGE_NAME = "@agentprojectcontext/apx";
+const CACHE_PATH = path.join(APX_HOME, "update-check.json");
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+
+function readCache() {
+  try {
+    const raw = fs.readFileSync(CACHE_PATH, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(data) {
+  try {
+    fs.mkdirSync(path.dirname(CACHE_PATH), { recursive: true });
+    fs.writeFileSync(CACHE_PATH, JSON.stringify(data) + "\n");
+  } catch {}
+}
+
+// Compare semver strings. Returns true if `latest` > `current`.
+function isNewer(current, latest) {
+  if (!current || !latest) return false;
+  const parse = (v) => v.replace(/^v/, "").split(".").map(Number);
+  const [ma, mi, pa] = parse(current);
+  const [mb, mib, pb] = parse(latest);
+  if (mb > ma) return true;
+  if (mb === ma && mib > mi) return true;
+  if (mb === ma && mib === mi && pb > pa) return true;
+  return false;
+}
+
+// Fetch latest version from npm registry (async, no deps).
+function fetchLatest() {
+  return new Promise((resolve) => {
+    const url = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+    const req = https.get(url, { timeout: 5000 }, (res) => {
+      let body = "";
+      res.on("data", (c) => (body += c));
+      res.on("end", () => {
+        try {
+          resolve(JSON.parse(body).version || null);
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+    req.on("error", () => resolve(null));
+    req.on("timeout", () => { req.destroy(); resolve(null); });
+  });
+}
+
+// Fire-and-forget background refresh. Never awaited by the caller.
+function refreshInBackground(currentVersion) {
+  fetchLatest().then((latest) => {
+    if (latest) {
+      writeCache({ latest, current: currentVersion, checkedAt: Date.now() });
+    }
+  }).catch(() => {});
+}
+
+// Call this at the END of every command (after output is printed).
+// Shows an update notice if a newer version is cached.
+// Also triggers a background refresh if cache is stale.
+export function checkForUpdate(currentVersion) {
+  const cache = readCache();
+  const now = Date.now();
+
+  // Trigger background refresh if cache is stale or missing.
+  if (!cache || (now - (cache.checkedAt || 0)) > CACHE_TTL_MS) {
+    refreshInBackground(currentVersion);
+  }
+
+  // Show notice if cache has a newer version.
+  if (cache && isNewer(currentVersion, cache.latest)) {
+    const divider = "─".repeat(56);
+    process.stderr.write(
+      `\n${divider}\n` +
+      `  apx update available  ${currentVersion} → ${cache.latest}\n` +
+      `  run: apx update\n` +
+      `${divider}\n`
+    );
+  }
+}
+
+// Used by `apx update` command to get the latest version (with network call).
+export async function getLatestVersion() {
+  return await fetchLatest();
+}

package/src/daemon/apc-runtime-context.js

@@ -1,13 +1,13 @@
 // Helpers that wrap external runtimes (Claude Code, Codex, OpenCode, Aider)
 // with APC awareness:
 //
-//   1. Create an APC session BEFORE the runtime starts.
+//   1. Create an APX runtime session BEFORE the runtime starts.
 //   2. Inject an "APC Runtime Context" block into the system prompt so the
 //      runtime knows the session id, the cwd of the project, and the apx
 //      commands it can use to update memory / append session notes.
 //   3. After the runtime returns, capture the external transcript path
 //      (Claude Code gives one, Codex/OpenCode/Aider don't yet) and write it
-//      into the APC session frontmatter.
+//      into the APX session frontmatter.
 //   4. Close the session with a synthesised result (truncated stdout).
 //
 // Used by both POST /projects/:pid/agents/:slug/runtime (CLI) and the
@@ -22,12 +22,12 @@ const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 const APC_RUNTIME_HINT = `
 # APC Runtime Context
 
-You are running inside an APC (Agent Project Framework) project. APC gives you durable session state across runs.
+You are running inside an APC (Agent Project Context) project. APC gives you portable project context. APX gives you local runtime session state.
 
 - **Project**: {{name}}  ({{path}})
 - **Agent**: {{agent}}
 - **APC session id**: {{session_id}}
-  (filename: .apc/agents/{{agent}}/sessions/{{session_id}}.md)
+  (stored in APX local runtime storage, outside .apc/)
 
 ## Commands you can use during this run
 
@@ -52,11 +52,11 @@ export function buildApfHint({ projectName, projectPath, agentSlug, sessionId })
     .replace(/\{\{session_id\}\}/g, sessionId);
 }
 
-// Create the APC session file on disk. Returns { id, filename, path }.
-export function createRuntimeSession({ projectRoot, agentSlug, runtime, taskRef = "", title }) {
-  const dir = path.join(projectRoot, ".apc", "agents", agentSlug, "sessions");
+// Create the APX runtime session file on disk. Returns { id, filename, path }.
+export function createRuntimeSession({ projectRoot, storageRoot = projectRoot, agentSlug, runtime, taskRef = "", title }) {
+  const dir = path.join(storageRoot, "agents", agentSlug, "sessions");
   fs.mkdirSync(dir, { recursive: true });
-  const id = generateSessionId(projectRoot, agentSlug);
+  const id = generateSessionId(storageRoot, agentSlug);
   const file = path.join(dir, `${id}.md`);
   const started = nowIso();
   const sessionTitle = title || `Runtime: ${runtime}`;

package/src/daemon/api.js

@@ -1,4 +1,4 @@
-// Express REST API for APX. See docs/APX-DAEMON.md §4.
+// Express REST API for APX. See APC docs reference/apx-daemon.
 import fs from "node:fs";
 import path from "node:path";
 import express from "express";
@@ -175,7 +175,7 @@ export function buildApi({ projects, registries, plugins, scheduler, version, st
     const agents = readAgents(p.path);
     if (!agents.find((a) => a.slug === req.params.slug))
       return res.status(404).json({ error: "agent not found" });
-    const sessionsDir = path.join(p.path, ".apc", "agents", req.params.slug, "sessions");
+    const sessionsDir = path.join(p.storagePath, "agents", req.params.slug, "sessions");
     if (!fs.existsSync(sessionsDir)) return res.json([]);
     const sessions = fs
       .readdirSync(sessionsDir)
@@ -201,7 +201,7 @@ export function buildApi({ projects, registries, plugins, scheduler, version, st
     if (!p) return;
     const { title, body = "" } = req.body || {};
     if (!title) return res.status(400).json({ error: "title required" });
-    const sessionsDir = path.join(p.path, ".apc", "agents", req.params.slug, "sessions");
+    const sessionsDir = path.join(p.storagePath, "agents", req.params.slug, "sessions");
     fs.mkdirSync(sessionsDir, { recursive: true });
     const titleSlug =
       title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "session";
@@ -225,7 +225,7 @@ export function buildApi({ projects, registries, plugins, scheduler, version, st
     if (!p) return;
     const sid = req.params.sid;
     const filename = sid.endsWith(".md") ? sid : `${sid}.md`;
-    const agentsDir = path.join(p.path, ".apc", "agents");
+    const agentsDir = path.join(p.storagePath, "agents");
     let found = null;
     if (fs.existsSync(agentsDir)) {
       for (const slug of fs.readdirSync(agentsDir)) {
@@ -335,7 +335,7 @@ export function buildApi({ projects, registries, plugins, scheduler, version, st
     const p = project(req, res);
     if (!p) return;
     const { agent, channel, since, limit = "100" } = req.query;
-    const rows = readProjectMessages(p.path, {
+    const rows = readProjectMessages(p.storagePath, {
       channel: channel || undefined,
       agent_slug: agent || undefined,
       since: since || undefined,
@@ -362,7 +362,7 @@ export function buildApi({ projects, registries, plugins, scheduler, version, st
     if (!p) return;
     const { q, limit = "50" } = req.query;
     if (!q) return res.status(400).json({ error: "q required" });
-    res.json(searchProjectMessages(p.path, q, Math.min(parseInt(limit, 10) || 50, 500)));
+    res.json(searchProjectMessages(p.storagePath, q, Math.min(parseInt(limit, 10) || 50, 500)));
   });
 
   // ---- Global messages (cross-project channels: telegram, direct, …) ----
@@ -421,7 +421,7 @@ export function buildApi({ projects, registries, plugins, scheduler, version, st
 
     try {
       const system = buildAgentSystem(p, agent);
-      const conv = startConversation({ projectRoot: p.path, agentSlug: agent.slug, engine: modelId, system });
+      const conv = startConversation({ storagePath: p.storagePath, agentSlug: agent.slug, engine: modelId, system });
       appendTurn({ filePath: conv.path, role: "user", content: prompt });
 
       const result = await callEngine({
@@ -470,7 +470,7 @@ export function buildApi({ projects, registries, plugins, scheduler, version, st
       let compactSummary = null;
 
       if (conversation_id) {
-        const existing = readConversation(p.path, agent.slug, conversation_id);
+        const existing = readConversation(p.storagePath, agent.slug, conversation_id);
         if (!existing) return res.status(404).json({ error: `conversation ${conversation_id} not found` });
         convPath = existing.path;
         convId = conversation_id;
@@ -492,7 +492,7 @@ export function buildApi({ projects, registries, plugins, scheduler, version, st
       const system = buildAgentSystem(p, agent, { extraParts });
 
       if (!conversation_id) {
-        const conv = startConversation({ projectRoot: p.path, agentSlug: agent.slug, engine: modelId, system });
+        const conv = startConversation({ storagePath: p.storagePath, agentSlug: agent.slug, engine: modelId, system });
         convPath = conv.path;
         convId = conv.id;
       }
@@ -523,14 +523,14 @@ export function buildApi({ projects, registries, plugins, scheduler, version, st
     const agents = readAgents(p.path);
     if (!agents.find((a) => a.slug === req.params.slug))
       return res.status(404).json({ error: "agent not found" });
-    res.json(listConversations(p.path, req.params.slug));
+    res.json(listConversations(p.storagePath, req.params.slug));
   });
 
   // GET /projects/:pid/agents/:slug/conversations/:id
   app.get("/projects/:pid/agents/:slug/conversations/:id", (req, res) => {
     const p = project(req, res);
     if (!p) return;
-    const conv = readConversation(p.path, req.params.slug, req.params.id);
+    const conv = readConversation(p.storagePath, req.params.slug, req.params.id);
     if (!conv) return res.status(404).json({ error: "conversation not found" });
     res.json(conv);
   });
@@ -547,7 +547,7 @@ export function buildApi({ projects, registries, plugins, scheduler, version, st
     if (!modelId) return res.status(400).json({ error: "agent has no model" });
     try {
       const result = await compactConversation({
-        projectRoot: p.path,
+        storagePath: p.storagePath,
         agentSlug: agent.slug,
         filename: filename || null,
         modelId,
@@ -625,7 +625,7 @@ export function buildApi({ projects, registries, plugins, scheduler, version, st
     if (!agents.find((a) => a.slug === req.params.slug))
       return res.status(404).json({ error: "agent not found" });
 
-    const messages = readProjectMessages(p.path, { agent_slug: req.params.slug });
+    const messages = readProjectMessages(p.storagePath, { agent_slug: req.params.slug });
     const peers = new Map();
     for (const m of messages) {
       const peer = m.meta?.from || m.meta?.to || null;
@@ -679,6 +679,7 @@ export function buildApi({ projects, registries, plugins, scheduler, version, st
 
     const session = createRuntimeSession({
       projectRoot: p.path,
+      storageRoot: p.storagePath,
       agentSlug: agent.slug,
       runtime,
       title: req.body?.title,

package/src/daemon/compact.js

@@ -52,8 +52,8 @@ Style: dense and factual. No pleasantries. No meta-commentary. Just the facts.
 
 // Resolve the most-recent conversation file for an agent, or the one explicitly
 // named. Returns the full filepath.
-function resolveConvFile(projectRoot, agentSlug, filename) {
-  const dir = path.join(projectRoot, ".apc", "agents", agentSlug, "conversations");
+function resolveConvFile(storagePath, agentSlug, filename) {
+  const dir = path.join(storagePath, "agents", agentSlug, "conversations");
   if (!fs.existsSync(dir)) throw new Error(`no conversations dir for agent "${agentSlug}"`);
 
   if (filename) {
@@ -76,13 +76,13 @@ function serializeFm(obj) {
 }
 
 export async function compactConversation({
-  projectRoot,
+  storagePath,
   agentSlug,
   filename,
   modelId,
   config,
 }) {
-  const filepath = resolveConvFile(projectRoot, agentSlug, filename);
+  const filepath = resolveConvFile(storagePath, agentSlug, filename);
   const raw = fs.readFileSync(filepath, "utf8");
   const { fm, turns } = parseConversation(raw);
 

package/src/daemon/conversations.js

@@ -1,14 +1,14 @@
-// Conversation storage: append-only markdown at .apc/agents/<slug>/conversations/
-// with SQLite mirror for fast querying. Filesystem is source of truth.
+// Conversation storage: append-only markdown at ~/.apx/projects/<id>/agents/<slug>/conversations/
+// Filesystem is source of truth. storagePath = ~/.apx/projects/<apx_id>
 
 import fs from "node:fs";
 import path from "node:path";
 
 const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 
-export function generateConversationId(projectRoot, agentSlug) {
+export function generateConversationId(storagePath, agentSlug) {
   const today = new Date().toISOString().slice(0, 10);
-  const dir = path.join(projectRoot, ".apc", "agents", agentSlug, "conversations");
+  const dir = path.join(storagePath, "agents", agentSlug, "conversations");
   let next = 1;
   if (fs.existsSync(dir)) {
     for (const f of fs.readdirSync(dir)) {
@@ -22,15 +22,15 @@ export function generateConversationId(projectRoot, agentSlug) {
   return `${today}-${String(next).padStart(2, "0")}`;
 }
 
-export function conversationPath(projectRoot, agentSlug, idOrFilename) {
+export function conversationPath(storagePath, agentSlug, idOrFilename) {
   const filename = idOrFilename.endsWith(".md") ? idOrFilename : `${idOrFilename}.md`;
-  return path.join(projectRoot, ".apc", "agents", agentSlug, "conversations", filename);
+  return path.join(storagePath, "agents", agentSlug, "conversations", filename);
 }
 
-export function startConversation({ projectRoot, agentSlug, engine, system }) {
-  const dir = path.join(projectRoot, ".apc", "agents", agentSlug, "conversations");
+export function startConversation({ storagePath, agentSlug, engine, system }) {
+  const dir = path.join(storagePath, "agents", agentSlug, "conversations");
   fs.mkdirSync(dir, { recursive: true });
-  const id = generateConversationId(projectRoot, agentSlug);
+  const id = generateConversationId(storagePath, agentSlug);
   const file = path.join(dir, `${id}.md`);
   const started = nowIso();
   const fm =
@@ -84,14 +84,14 @@ export function parseConversation(text) {
   return { fm, turns };
 }
 
-export function readConversation(projectRoot, agentSlug, idOrFilename) {
-  const p = conversationPath(projectRoot, agentSlug, idOrFilename);
+export function readConversation(storagePath, agentSlug, idOrFilename) {
+  const p = conversationPath(storagePath, agentSlug, idOrFilename);
   if (!fs.existsSync(p)) return null;
   return { ...parseConversation(fs.readFileSync(p, "utf8")), path: p };
 }
 
-export function listConversations(projectRoot, agentSlug) {
-  const dir = path.join(projectRoot, ".apc", "agents", agentSlug, "conversations");
+export function listConversations(storagePath, agentSlug) {
+  const dir = path.join(storagePath, "agents", agentSlug, "conversations");
   if (!fs.existsSync(dir)) return [];
   return fs
     .readdirSync(dir)

package/src/daemon/db.js

@@ -5,6 +5,12 @@ import path from "node:path";
 import { appendMessageToFs } from "../core/messages-store.js";
 import { effectiveConfig } from "./project-config.js";
 import { readAgents } from "../core/parser.js";
+import { getOrCreateApxId } from "../core/scaffold.js";
+import {
+  ensureProjectStorage,
+  DEFAULT_PROJECT_ID,
+  DEFAULT_PROJECT_STORE,
+} from "../core/config.js";
 
 export class ProjectManager {
   constructor(globalConfig = {}) {
@@ -30,19 +36,56 @@ export class ProjectManager {
     }
     // Ensure directories exist for projects initialized before they were added.
     fs.mkdirSync(path.join(abs, ".apc", "commands"), { recursive: true });
-    fs.mkdirSync(path.join(abs, ".apc", "messages"), { recursive: true });
+
+    // Ensure stable APX storage root exists (~/.apx/projects/<apx_id>/).
+    const apxId = getOrCreateApxId(abs);
+    const storagePath = ensureProjectStorage(apxId);
 
     const entry = {
       id: this._nextId++,
       path: abs,
+      storagePath,
+      apxId,
       config: effectiveConfig(this.globalConfig, abs),
     };
-    entry.logMessage = (payload) => appendMessageToFs({ projectRoot: abs, ...payload });
+    // Project runtime messages stay in APX local storage.
+    entry.logMessage = (payload) => appendMessageToFs({ projectRoot: storagePath, ...payload });
     this.byId.set(entry.id, entry);
     this.byPath.set(abs, entry);
     return entry;
   }
 
+  // Register the always-available default project (no local .apc/ required).
+  // Called once at daemon startup. Uses id=0.
+  // The default project lives entirely at ~/.apx/projects/default/ and mirrors
+  // the APC structure so that parser functions can read agents/memory from it.
+  registerDefault() {
+    if (this.byId.has(0)) return this.byId.get(0);
+    // Create a minimal APC-compatible structure inside the storage root so that
+    // readAgents() and other parser functions work without a separate project dir.
+    const apcDir = path.join(DEFAULT_PROJECT_STORE, ".apc");
+    fs.mkdirSync(path.join(apcDir, "agents"), { recursive: true });
+    const projectJson = path.join(apcDir, "project.json");
+    if (!fs.existsSync(projectJson)) {
+      fs.writeFileSync(
+        projectJson,
+        JSON.stringify({ name: "default", apx_id: DEFAULT_PROJECT_ID, apx: "installed" }, null, 2) + "\n"
+      );
+    }
+    // The default project uses its storagePath as both the APC root and the storage root.
+    const entry = {
+      id: 0,
+      path: DEFAULT_PROJECT_STORE,
+      storagePath: DEFAULT_PROJECT_STORE,
+      apxId: DEFAULT_PROJECT_ID,
+      config: effectiveConfig(this.globalConfig, DEFAULT_PROJECT_STORE),
+    };
+    entry.logMessage = (payload) => appendMessageToFs({ projectRoot: DEFAULT_PROJECT_STORE, ...payload });
+    this.byId.set(0, entry);
+    this.byPath.set(DEFAULT_PROJECT_STORE, entry);
+    return entry;
+  }
+
   get(id) {
     return this.byId.get(Number(id)) || null;
   }

package/src/daemon/index.js

@@ -79,6 +79,9 @@ async function main() {
   const projects = new ProjectManager(cfg);
   const registries = new RegistryCache();
 
+  // Default project (id=0) is always available — no local .apc/ required.
+  projects.registerDefault();
+
   // Load registered projects from config.
   for (const entry of cfg.projects) {
     try {

package/src/daemon/smoke.js

@@ -33,14 +33,13 @@ assert(agents.length === 2, `expected 2 agents, got ${agents.length}`);
 assert(agents.find((a) => a.slug === "sofia"), "sofia missing");
 assert(agents.find((a) => a.slug === "martin"), "martin missing");
 
-// Sessions: scan .apc/agents/sofia/sessions/
+// Sessions: scan APX local runtime storage.
 const sofiaSessions = (() => {
-  const dir = path.join(entry.path, ".apc", "agents", "sofia", "sessions");
+  const dir = path.join(entry.storagePath, "agents", "sofia", "sessions");
   if (!fs.existsSync(dir)) return [];
   return fs.readdirSync(dir).filter((f) => f.endsWith(".md"));
 })();
 console.log("sofia sessions:", sofiaSessions);
-assert(sofiaSessions.length >= 1, "expected at least one sofia session");
 
 const reg = new McpRegistry(entry.path);
 const list = reg.list();