@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/mcp.js

@@ -1,12 +1,3 @@
-/**
- * MCP server management - reading from ~/.agents/mcp/ and applying to agent configs.
- *
- * MCP servers are stored as YAML files in ~/.agents/mcp/:
- *   ~/.agents/mcp/swarm.yaml
- *   ~/.agents/mcp/figma.yaml
- *
- * Each file defines a server that gets applied (merged) into agent configs during sync.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
@@ -19,9 +10,6 @@ import { IS_WINDOWS, execFileShellSpec } from './platform/index.js';
 import { AGENTS, getMcpConfigPathForHome, getProjectMcpConfigPath, parseMcpConfig, stripJsonComments } from './agents.js';
 import { MCP_TARGETS, mcpWriteUnsupportedReason } from './mcp-registry.js';
 import { isCapable } from './capabilities.js';
-/**
- * Parse an MCP server config from a YAML file.
- */
 export function parseMcpServerConfig(filePath) {
     if (!fs.existsSync(filePath)) {
         return null;
@@ -36,10 +24,6 @@ export function parseMcpServerConfig(filePath) {
     }
     return validateMcpYamlConfig(parsed);
 }
-/**
- * Validate an MCP server name. Rejects names that could be misinterpreted as
- * command-line options or that contain characters unsafe for argv/identifier use.
- */
 export function validateMcpServerName(name) {
     if (name.startsWith('-')) {
         throw new Error(`Invalid MCP server name '${name}': names cannot start with '-'`);
@@ -94,22 +78,9 @@ function isStringRecord(value) {
         return false;
     return Object.values(value).every((item) => typeof item === 'string');
 }
-// ─── Project MCP trust (RUSH-1776) ───────────────────────────────────────────
-// Project-scoped MCP configs (<repo>/.agents/mcp/*.yaml) are UNTRUSTED by
-// default. An MCP server is an arbitrary command spawned under the agent's
-// authority, so merely cloning a hostile repo must never auto-register or run
-// it. A project's MCP servers enter the register/spawn path only after the user
-// explicitly trusts that project (`agents mcp trust`), recorded in a user-owned
-// store OUTSIDE any repo so a cloned repo can't grant itself trust. User- and
-// system-scoped MCPs (~/.agents/mcp/*) are always trusted.
-/** Path to the user-owned project-trust store (never inside a repo). */
 export function getMcpTrustStorePath() {
     return path.join(getUserAgentsDir(), 'mcp-trust.yaml');
 }
-/**
- * Key a project by its ROOT (parent of `.agents/`), resolved through symlinks
- * so the key is stable no matter how the cwd was spelled.
- */
 function normalizeProjectKey(projectAgentsDir) {
     const root = path.dirname(projectAgentsDir);
     try {
@@ -151,18 +122,9 @@ function writeTrustedProjects(trusted) {
     fs.mkdirSync(path.dirname(storePath), { recursive: true });
     fs.writeFileSync(storePath, yaml.stringify({ trustedProjects: Array.from(trusted).sort() }), 'utf-8');
 }
-/**
- * Whether the project that owns `projectAgentsDir` has been explicitly trusted
- * for MCP auto-apply. Untrusted by default (fail closed).
- */
 export function isProjectMcpTrusted(projectAgentsDir) {
     return readTrustedProjects().has(normalizeProjectKey(projectAgentsDir));
 }
-/**
- * Record explicit trust for the project containing `cwd` so its project-scoped
- * MCP servers may be registered/spawned. Returns the trusted project root, or
- * null when `cwd` is not inside a project (no `.agents/` to trust).
- */
 export function trustProjectMcp(cwd = process.cwd()) {
     const projectAgentsDir = getProjectAgentsDir(cwd);
     if (!projectAgentsDir)
@@ -175,7 +137,6 @@ export function trustProjectMcp(cwd = process.cwd()) {
     }
     return key;
 }
-/** Revoke MCP trust for the project containing `cwd`. Returns true if it was trusted. */
 export function untrustProjectMcp(cwd = process.cwd()) {
     const projectAgentsDir = getProjectAgentsDir(cwd);
     if (!projectAgentsDir)
@@ -187,17 +148,7 @@ export function untrustProjectMcp(cwd = process.cwd()) {
     writeTrustedProjects(trusted);
     return true;
 }
-/**
- * List all MCP server configs from ~/.agents/mcp/.
- *
- * When `enforceProjectTrust` is set, project-scoped configs are included only
- * for a project the user has explicitly trusted (see `isProjectMcpTrusted`) —
- * this is the choke point that keeps an untrusted cloned repo's MCP servers out
- * of the register/spawn path. It ALSO fixes name-collision shadowing: an
- * untrusted project entry is dropped before dedup, so it can never mask a
- * same-named user entry. Display callers omit the flag to surface project
- * entries (command+args and all) regardless of trust.
- */
+// Project MCP is untrusted until root-keyed user trust; drop it before name dedup so it cannot shadow a trusted server.
 export function listMcpServerConfigs(cwd = process.cwd(), options = {}) {
     const dirs = [];
     const projectAgentsDir = getProjectAgentsDir(cwd);
@@ -206,7 +157,6 @@ export function listMcpServerConfigs(cwd = process.cwd(), options = {}) {
     if (projectAgentsDir && includeProject) {
         dirs.push({ scope: 'project', dir: path.join(projectAgentsDir, 'mcp') });
     }
-    // User dir first (wins on name collision), then system
     dirs.push({ scope: 'user', dir: getUserMcpDir() });
     dirs.push({ scope: 'user', dir: getMcpDir() });
     const results = new Map();
@@ -233,15 +183,6 @@ export function listMcpServerConfigs(cwd = process.cwd(), options = {}) {
     }
     return Array.from(results.values());
 }
-/**
- * Parse one config during a directory SCAN. `validateMcpYamlConfig` returns null
- * for some malformed shapes but *throws* for others (`args` not a string array,
- * `command`/`env` of the wrong type), and a scan must not be all-or-nothing: a
- * single bad file under `<repo>/mcp/` took down the whole of
- * `agents inspect <repo>` with an unhandled stack trace. Skip the file and name
- * it, exactly as a null return is already skipped. Explicit single-file
- * operations call `parseMcpServerConfig` directly and still throw loudly.
- */
 export function parseMcpConfigForScan(filePath) {
     try {
         return parseMcpServerConfig(filePath);
@@ -252,10 +193,6 @@ export function parseMcpConfigForScan(filePath) {
         return null;
     }
 }
-/**
- * Scan a repository for MCP server YAML configs.
- * Looks under <repoPath>/mcp/*.yaml — same on-disk layout as ~/.agents/mcp/.
- */
 export function discoverMcpConfigsFromRepo(repoPath) {
     const dir = path.join(repoPath, 'mcp');
     if (!fs.existsSync(dir))
@@ -274,11 +211,6 @@ export function discoverMcpConfigsFromRepo(repoPath) {
     }
     return results;
 }
-/**
- * Install an MCP YAML config from a source file into ~/.agents/mcp/.
- * Re-serializes via writeMcpServerConfig so the on-disk filename is
- * deterministic (sanitized from the server name).
- */
 export function installMcpConfigCentrally(sourcePath) {
     try {
         const config = parseMcpServerConfig(sourcePath);
@@ -292,14 +224,7 @@ export function installMcpConfigCentrally(sourcePath) {
         return { success: false, error: err.message };
     }
 }
-/**
- * Get MCP servers by name.
- * If names is provided, returns only those servers.
- * Otherwise returns all servers.
- */
 export function getMcpServersByName(names, options = {}) {
-    // This feeds the register/spawn path (installMcpServers, workflow assembly),
-    // so untrusted project-scoped servers are excluded by default (fail closed).
     const enforceProjectTrust = options.enforceProjectTrust ?? true;
     const allServers = listMcpServerConfigs(options.cwd, { enforceProjectTrust });
     if (!names || names.length === 0) {
@@ -307,12 +232,6 @@ export function getMcpServersByName(names, options = {}) {
     }
     return allServers.filter((server) => names.includes(server.name));
 }
-/**
- * Assemble the JSON payload Claude's `--mcp-config` flag expects from a set of
- * installed MCP servers: `{ "mcpServers": { "<name>": { command, args, env } | { url } } }`.
- * Pure — takes servers, returns a JSON string. The caller writes it to an
- * ephemeral file and passes the path to buildExecCommand.
- */
 export function buildWorkflowMcpConfig(servers) {
     const mcpServers = {};
     for (const server of servers) {
@@ -331,21 +250,15 @@ export function buildWorkflowMcpConfig(servers) {
     }
     return JSON.stringify({ mcpServers });
 }
-/**
- * Install MCP server using Claude CLI.
- * Uses: claude mcp add --scope user --transport <type> <name> [--env K=V]... -- <cmd> [args...]
- */
 function installMcpViaClaude(binaryPath, server, versionHome) {
     const execEnv = { ...process.env, HOME: versionHome };
     if (server.config.transport === 'stdio') {
-        // Build env args
         const envArgs = [];
         if (server.config.env) {
             for (const [key, value] of Object.entries(server.config.env)) {
                 envArgs.push('--env', `${key}=${value}`);
             }
         }
-        // claude mcp add --scope user --transport stdio [--env K=V]... -- <name> <cmd> [args...]
         const args = [
             'mcp', 'add', '--scope', 'user', '--transport', 'stdio',
             ...envArgs,
@@ -354,7 +267,6 @@ function installMcpViaClaude(binaryPath, server, versionHome) {
             server.config.command,
             ...(server.config.args || [])
         ];
-        // RUSH-1752: user-controlled MCP command/args must not reach cmd.exe unquoted.
         const spec = execFileShellSpec(binaryPath, args);
         execFileSync(spec.command, spec.args, {
             stdio: 'pipe',
@@ -364,7 +276,6 @@ function installMcpViaClaude(binaryPath, server, versionHome) {
         });
     }
     else {
-        // claude mcp add --scope user --transport http -- <name> <url>
         const httpArgs = ['mcp', 'add', '--scope', 'user', '--transport', 'http', '--', server.name, server.config.url];
         const spec = execFileShellSpec(binaryPath, httpArgs);
         execFileSync(spec.command, spec.args, {
@@ -375,20 +286,14 @@ function installMcpViaClaude(binaryPath, server, versionHome) {
         });
     }
 }
-/**
- * Install MCP server using Codex CLI.
- * Uses: codex mcp add <name> -- <cmd> [args...]
- */
 function installMcpViaCodex(binaryPath, server, versionHome) {
     let args;
     if (server.config.transport === 'http') {
         if (!server.config.url)
             throw new Error(`HTTP MCP '${server.name}' has no url`);
-        // codex mcp add <name> --url <url>
         args = ['mcp', 'add', server.name, '--url', server.config.url];
     }
     else {
-        // codex mcp add -- <name> <cmd> [args...]
         args = [
             'mcp', 'add',
             '--',
@@ -397,7 +302,6 @@ function installMcpViaCodex(binaryPath, server, versionHome) {
             ...(server.config.args || [])
         ];
     }
-    // RUSH-1752: user-controlled MCP command/args must not reach cmd.exe unquoted.
     const spec = execFileShellSpec(binaryPath, args);
     execFileSync(spec.command, spec.args, {
         stdio: 'pipe',
@@ -427,7 +331,6 @@ function registerMcpCommand(agentId, name, commandSpec, scope, transport, option
     try {
         validateMcpServerName(name);
         if (agentId === 'hermes') {
-            // Hermes has no `mcp add` CLI; write its YAML config directly.
             const home = options.home || os.homedir();
             writeMcpConfig(agentId, getMcpConfigPathForHome(agentId, home), [{
                     name,
@@ -444,7 +347,6 @@ function registerMcpCommand(agentId, name, commandSpec, scope, transport, option
             ? ['mcp', 'add', '--transport', transport, '--scope', scope, '--', name, ...commandArgs]
             : ['mcp', 'add', '--', name, ...commandArgs];
         const env = options.home ? { ...process.env, HOME: options.home } : process.env;
-        // RUSH-1752: user-controlled MCP command/args must not reach cmd.exe unquoted.
         const spec = execFileShellSpec(bin, args);
         execFileSync(spec.command, spec.args, { stdio: 'pipe', timeout: 30000, env, shell: spec.shell });
         return { success: true };
@@ -453,7 +355,6 @@ function registerMcpCommand(agentId, name, commandSpec, scope, transport, option
         return { success: false, error: err.message };
     }
 }
-/** Project a discovered MCP server config into the writer's input shape. */
 function toWritableServer(server) {
     return {
         name: server.config.name,
@@ -464,24 +365,11 @@ function toWritableServer(server) {
         url: server.config.url,
     };
 }
-/**
- * Read an existing agent config, or `{}` when it does not exist yet.
- *
- * A file that exists but does not parse **throws** rather than resetting to
- * `{}`: these configs hold far more than MCP (hermes' whole `config.yaml`,
- * openclaw's `openclaw.json`, opencode's `opencode.jsonc`), so silently
- * rewriting one from scratch destroys everything else in it. The five per-agent
- * installers this replaced parsed unguarded for exactly that reason -- the throw
- * surfaced as a reported error and left the file intact, which is the behavior
- * preserved here.
- */
+// Empty files mean no recorded config; malformed/non-object files throw so writes never reset unrelated state, and JSONC stripping stays string-aware.
 function readExistingConfig(configPath, parse) {
     if (!fs.existsSync(configPath))
         return {};
     const raw = fs.readFileSync(configPath, 'utf-8');
-    // An empty (or whitespace-only) file is "nothing recorded yet", not corruption
-    // -- a touched file or an interrupted write. `JSON.parse('')` throws, so
-    // without this an empty ~/.factory/mcp.json would fail the whole sync.
     if (raw.trim() === '')
         return {};
     let parsed;
@@ -498,56 +386,19 @@ function readExistingConfig(configPath, parse) {
     }
     return parsed;
 }
-/**
- * Parse a JSONC config.
- *
- * Uses the shared string-literal-aware `stripJsonComments` — the same one the
- * read path uses on this very file. A regex that blanks `//` to end-of-line
- * destroys `"$schema": "https://opencode.ai/config.json"`, which every
- * opencode-generated config carries, and would make the writer disagree with
- * the reader about the same bytes.
- */
 function parseJsonc(raw) {
     return JSON.parse(stripJsonComments(raw));
 }
-/**
- * Serialize MCP servers into an agent-specific config file.
- *
- * The format comes from `MCP_TARGETS` (lib/mcp-registry.ts), so a harness whose
- * schema is not implemented **throws** here rather than falling through the
- * switch and returning as if it had written something. `installMcpServers`
- * catches that and reports it as an error, never as a silent success.
- *
- * `mode: 'overwrite'` replaces the whole MCP section (used for tool-managed
- * version-home configs). `mode: 'merge'` updates/adds the provided server
- * entries while preserving existing entries (used for project-level configs
- * that users may hand-edit or populate via agent CLI commands).
- *
- * An empty `servers` list is a no-op by default — most callers pass a
- * resolved-but-possibly-empty selection and an empty one means "nothing to
- * apply," not "clear whatever is there," so this must never wipe an existing
- * config out from under an unrelated caller. `options.allowEmpty` is the
- * explicit opt-in for a caller that owns the ENTIRE mcp section by
- * construction (it always knows the complete current desired server set,
- * including the empty set) and needs `overwrite` to actually clear it —
- * still only the mcp section: `readExistingConfig` above preserves every
- * other top-level key already, in both modes.
- */
 export function writeMcpConfig(agentId, configPath, servers, mode = 'overwrite', options = {}) {
     if (servers.length === 0 && !options.allowEmpty) {
         return;
     }
-    // Narrowed, not asserted: this is what lets the `never` guard on the default
-    // arm below be a real compile-time check rather than a cosmetic one.
     const target = MCP_TARGETS[agentId];
     if (!target || target.format === null) {
         throw new Error(`cannot write MCP config: ${mcpWriteUnsupportedReason(agentId)}`);
     }
     const format = target.format;
     switch (format) {
-        // Claude's `{ "mcpServers": {...} }` schema, shared by cursor, kimi, droid
-        // and Oz (.warp/.mcp.json): stdio carries command/args/env,
-        // remote carries url + optional headers.
         case 'claude-json': {
             const config = readExistingConfig(configPath, JSON.parse);
             const mcpServers = mode === 'merge' && config.mcpServers && typeof config.mcpServers === 'object'
@@ -574,9 +425,6 @@ export function writeMcpConfig(agentId, configPath, servers, mode = 'overwrite',
             break;
         }
         case 'antigravity-json': {
-            // agy reads ~/.gemini/config/mcp_config.json. Same `mcpServers` map as
-            // Claude for stdio, but a remote server is keyed `serverUrl` (SSE) and
-            // carries no headers — see agy's bundled docs/mcp_servers.md.
             const config = readExistingConfig(configPath, JSON.parse);
             const mcpServers = mode === 'merge' && config.mcpServers && typeof config.mcpServers === 'object'
                 ? { ...config.mcpServers }
@@ -705,9 +553,6 @@ export function writeMcpConfig(agentId, configPath, servers, mode = 'overwrite',
             break;
         }
         case 'muse-json': {
-            // Muse Code settings.json: requires schema_version: 1; MCP lives under
-            // mcp_servers with an explicit transport (stdio | streamable_http).
-            // See https://dev.meta.ai/docs/muse-code/extending#mcp
             const config = readExistingConfig(configPath, JSON.parse);
             if (config.schema_version === undefined) {
                 config.schema_version = 1;
@@ -740,20 +585,11 @@ export function writeMcpConfig(agentId, configPath, servers, mode = 'overwrite',
             break;
         }
         default: {
-            // Unreachable: mcpWriteUnsupportedReason above rejects a null format and
-            // every McpFormat has an arm. The assignment is deliberately NOT cast —
-            // `as never` would make it unfailable and the guard cosmetic. Adding an
-            // McpFormat without an arm above is a compile error here.
             const unhandled = format;
             throw new Error(`unhandled MCP config format: ${String(unhandled)}`);
         }
     }
 }
-/**
- * Install MCP servers to an agent.
- * For Claude/Codex: uses CLI commands (claude mcp add, codex mcp add)
- * For others: edits config files directly
- */
 export function installMcpServers(agentId, version, versionHome, mcpNames, options = {}) {
     if (!isCapable(agentId, 'mcp')) {
         return { success: true, applied: [], errors: [] };
@@ -764,9 +600,6 @@ export function installMcpServers(agentId, version, versionHome, mcpNames, optio
     }
     const applied = [];
     const errors = [];
-    // Get binary path for CLI-based agents. On Windows npm drops a `.cmd` launcher
-    // next to the extensionless POSIX wrapper in node_modules/.bin; prefer it so
-    // the CLI is actually executable (the bare wrapper is a shell script).
     const cliCommand = AGENTS[agentId].cliCommand;
     let binaryPath = path.join(getVersionsDir(), agentId, version, 'node_modules', '.bin', cliCommand);
     if (IS_WINDOWS && fs.existsSync(binaryPath + '.cmd')) {
@@ -785,17 +618,9 @@ export function installMcpServers(agentId, version, versionHome, mcpNames, optio
                 handled = true;
             }
             else {
-                // No harness CLI for this agent (or none that works — `grok mcp add`
-                // does not register into the version home), so write its config file
-                // directly. `writeMcpConfig` throws for a harness whose format is not
-                // implemented, which the catch below turns into a reported error rather
-                // than a silent success. Merge, because this loop runs once per server.
                 writeMcpConfig(agentId, getMcpConfigPathForHome(agentId, versionHome), [toWritableServer(server)], 'merge');
                 handled = true;
             }
-            // Project-layer servers also get merged into the agent's project-level
-            // config (e.g., .mcp.json, .codex/config.toml) so the CLI discovers them
-            // when run inside the repo.
             if (server.scope === 'project' && options.cwd) {
                 writeMcpConfig(agentId, getProjectMcpConfigPath(agentId, options.cwd), [toWritableServer(server)], 'merge');
                 handled = true;
@@ -806,9 +631,8 @@ export function installMcpServers(agentId, version, versionHome, mcpNames, optio
         }
         catch (err) {
             const message = err.message;
-            // Check if it's an "already exists" error - that's not a real error
             if (message.includes('already exists') || message.includes('already configured')) {
-                applied.push(server.name); // Count as applied since it's already there
+                applied.push(server.name);
             }
             else {
                 errors.push(`${server.name}: ${message}`);
@@ -817,9 +641,6 @@ export function installMcpServers(agentId, version, versionHome, mcpNames, optio
     }
     return { success: errors.length === 0, applied, errors };
 }
-/**
- * Write an MCP server config to ~/.agents/mcp/.
- */
 export function writeMcpServerConfig(config) {
     validateMcpServerName(config.name);
     const mcpDir = getUserMcpDir();
@@ -830,12 +651,6 @@ export function writeMcpServerConfig(config) {
     fs.writeFileSync(filePath, content, 'utf-8');
     return filePath;
 }
-/**
- * Canonical string form of an MCP server for a structural, format-agnostic
- * compare: http servers by url; stdio servers by command + args (order
- * significant) + env (key-sorted, so serialization order is not drift). Undefined
- * / empty fields are dropped so `{args: []}` and `{}` compare equal.
- */
 function mcpCanonical(entry) {
     if (entry.url)
         return JSON.stringify({ url: entry.url });
@@ -848,14 +663,6 @@ function mcpCanonical(entry) {
         env,
     });
 }
-/**
- * True when MCP server `name` materialized in `agent`'s version home byte-matches
- * the resolved SOURCE definition `source` — the content-drift predicate `agents
- * doctor` uses. Parses the home's canonical MCP config for the harness (no
- * `claude mcp add` shell-out — the on-disk file is parseable) and structurally
- * compares command/args/env/url. Returns false when the server is absent from
- * the home (surfaced as `missing`/`extra` at the name level, not here).
- */
 export function mcpServerMatches(agent, versionHome, name, source) {
     const homePath = getMcpConfigPathForHome(agent, versionHome);
     const home = parseMcpConfig(agent, homePath)[name];
@@ -866,9 +673,6 @@ export function mcpServerMatches(agent, versionHome, name, source) {
         : { command: source.command, args: source.args, env: source.env };
     return mcpCanonical(sourceComparable) === mcpCanonical(home);
 }
-/**
- * Remove an MCP server config from ~/.agents/mcp/.
- */
 export function removeMcpServerConfig(name) {
     const servers = listMcpServerConfigs();
     const server = servers.find((s) => s.name === name);

package/dist/lib/memory-cache.d.ts

@@ -1,19 +1,8 @@
 import { LRUCache } from 'lru-cache';
 export interface MemoryCacheOptions<K extends {} = string, V extends {} = {}> {
-    /** Hard entry bound. A cache without a bound is not allowed. */
     max: number;
-    /** Milliseconds before an entry is treated as absent. */
     ttlMs: number;
-    /** Optional async loader. Concurrent fetches for one key are coalesced. */
     fetchMethod?: (key: K, staleValue: V | undefined) => Promise<V>;
-    /** Injectable monotonic clock for deterministic TTL tests. */
     now?: () => number;
 }
-/**
- * Correctness-first process-local cache defaults.
- *
- * The cache is always bounded, never returns stale values, and does not extend
- * an entry's life merely because it was read. Durable/cross-process state must
- * continue to live in SQLite or an atomic on-disk snapshot.
- */
 export declare function createMemoryCache<K extends {}, V extends {}>(options: MemoryCacheOptions<K, V>): LRUCache<K, V>;

package/dist/lib/memory-cache.js

@@ -1,11 +1,4 @@
 import { LRUCache } from 'lru-cache';
-/**
- * Correctness-first process-local cache defaults.
- *
- * The cache is always bounded, never returns stale values, and does not extend
- * an entry's life merely because it was read. Durable/cross-process state must
- * continue to live in SQLite or an atomic on-disk snapshot.
- */
 export function createMemoryCache(options) {
     if (!Number.isSafeInteger(options.max) || options.max < 1) {
         throw new Error('memory cache max must be a positive integer');
@@ -20,8 +13,6 @@ export function createMemoryCache(options) {
         updateAgeOnGet: false,
         updateAgeOnHas: false,
         ttlAutopurge: false,
-        // A supplied deterministic clock must be read on every operation; the
-        // library's 1ms cached-now optimization follows wall time, not that clock.
         ttlResolution: options.now ? 0 : 1,
         fetchMethod: options.fetchMethod
             ? async (key, staleValue) => options.fetchMethod(key, staleValue)

package/dist/lib/memory.d.ts

@@ -1,70 +1,18 @@
-/**
- * Canonical agent memory resource — accumulated facts/preferences/knowledge
- * distinct from `rules` (instructions / AGENTS.md persona).
- *
- * Layout (project > user > system layering):
- *   ~/.agents/memory/MEMORY.md          always-read index
- *   ~/.agents/memory/<slug>.md          individual facts
- *   ~/.agents/.system/memory/           system layer
- *   <project>/.agents/memory/           project layer
- *
- * Sync fans out into each capable agent's version home under an agent-specific
- * target dir (see memoryTargetDir).
- */
 import type { AgentId } from './types.js';
 interface MemoryFact {
-    /** Filename without .md (slug). */
     name: string;
-    /** Absolute path to the fact file. */
     path: string;
-    /** Layer that wins for this name. */
     layer: 'project' | 'user' | 'system';
-    /** First non-empty line of the body (for list display). */
     summary: string;
 }
-/** User-layer memory root (~/.agents/memory/). */
 export declare function getUserMemoryDir(): string;
-/** Ensure the user memory dir exists (creates MEMORY.md index if missing). */
 export declare function ensureUserMemoryDir(): string;
-/** List memory facts with project > user > system override on name. */
 export declare function listMemoryFacts(cwd?: string): MemoryFact[];
-/** Read one fact by name (winning layer). */
 export declare function readMemoryFact(name: string, cwd?: string): MemoryFact | null;
-/** Write a fact into the user layer. Returns the absolute path. */
 export declare function addMemoryFact(name: string, body: string): string;
-/** Remove a fact from the user layer. Returns true if a file was deleted. */
 export declare function removeMemoryFact(name: string): boolean;
-/**
- * Per-agent target directory (relative to version home) for synced memory.
- * Claude/Codex/OpenClaw/Grok get native-ish paths; others get a generic memory/.
- */
 export declare function memoryTargetDir(agent: AgentId): string;
-/** Copy canonical layered memory into one version home. Returns fact names written. */
 export declare function syncMemoryToVersionHome(agent: AgentId, versionHome: string, cwd?: string): string[];
-/**
- * Canonical shared dir for Claude Code's NATIVE per-project auto-memory —
- * `<versionHome>/.claude/projects/<project-key>/memory/*.md`, the freeform
- * notes Claude writes for itself during a session. Distinct from the layered
- * `memory` resource above (~/.agents/memory/ facts synced into
- * `.claude/memory/`): this dir is keyed by project (via
- * {@link claudeProjectDirName}), not by agent version, and Claude Code itself
- * decides what goes in it — agents-cli only makes the directory
- * version-independent, never writes into it.
- */
 export declare function getClaudeProjectMemoryDir(cwd: string): string;
-/**
- * Make Claude Code's native per-project memory dir version-independent by
- * symlinking `<versionHome>/.claude/projects/<project-key>/memory/` into the
- * one canonical dir every installed Claude version's home shares for this
- * project (PHNX-2817). Without this, `getVersionHomePath` gives every
- * installed version its own isolated HOME, so a note written under one
- * version is invisible under another — the directory is just empty there.
- *
- * Idempotent and safe to call on every sync: a dir already linked to the
- * canonical target is left alone; a PRE-EXISTING real directory with content
- * (the common case today, since this bug has always left one behind) has its
- * files migrated into the canonical dir first — never discarded — before
- * being replaced by the symlink.
- */
 export declare function syncClaudeProjectMemoryDir(versionHome: string, cwd?: string): void;
 export {};