#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
import { existsSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { homedir } from "node:os";
import pc from "picocolors";
import type {
AgentMemoryConfig,
ProviderConfig,
EmbeddingConfig,
FallbackConfig,
ClaudeBridgeConfig,
TeamConfig,
} from "./types.js";
// Import-side ceiling for observations in a single session (enforced by mem::import).
// This is independent of MAX_OBS_PER_SESSION, which controls runtime writes.
export const MAX_IMPORT_OBS_PER_SESSION = 5_000;
function safeParseInt(value: string | undefined, fallback: number): number {
if (!value) return fallback;
const parsed = parseInt(value, 10);
return Number.isNaN(parsed) ? fallback : parsed;
}
const DATA_DIR = process.env["AGENTMEMORY_DATA_DIR"] || join(homedir(), ".agentmemory");
const ENV_FILE = process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env");
let warnPremiumModelShown = false;
let providerNoticeShown = false;
let obsCapImportCeilingWarned = false;
function writeProviderNoticeOnce(text: string): void {
if (providerNoticeShown) return;
providerNoticeShown = true;
process.stderr.write(text);
}
// Parsed ~/.agentmemory/.env, memoized for the process lifetime. getMergedEnv()
// runs on every config getter (~20 of them), so without this cache a single
// request would readFileSync + reparse the file dozens of times. The file is
// boot-static, so read it from disk once and reuse the result. Tests that
// mutate the file between cases reset the module (clearing this via reload) or
// call __resetEnvFileCache().
let envFileCache: Record<string, string> | undefined;
function loadEnvFile(): Record<string, string> {
if (envFileCache) return envFileCache;
if (!existsSync(ENV_FILE)) {
envFileCache = {};
return envFileCache;
}
envFileCache = parseEnvContent(readFileSync(ENV_FILE, "utf-8"));
return envFileCache;
}
export function parseEnvContent(content: string): Record<string, string> {
const vars: Record<string, string> = {};
for (const line of content.split("\n")) {
const trimmed = line.trim();
if (!trimmed || trimmed.startsWith("#")) continue;
const eqIdx = trimmed.indexOf("=");
if (eqIdx === -1) continue;
const key = trimmed.slice(0, eqIdx).trim();
let val = trimmed.slice(eqIdx + 1).trim();
const quoteChar = val[0] === '"' || val[0] === "'" ? val[0] : "";
if (quoteChar) {
const closeIdx = val.indexOf(quoteChar, 1);
if (closeIdx !== -1) val = val.slice(1, closeIdx);
} else {
const hashIdx = val.indexOf(" #");
if (hashIdx !== -1) val = val.slice(0, hashIdx).trim();
}
vars[key] = val;
}
return vars;
}
// Test hook: clears the memoized .env so the next loadEnvFile() re-reads disk
// within the same module instance. vi.resetModules() reloads this module and
// resets the cache on its own; this exists for tests that mutate the file
// without a module reload.
export function __resetEnvFileCache(): void {
envFileCache = undefined;
}
function hasRealValue(v: string | undefined): v is string {
return typeof v === "string" && v.trim().length > 0;
}
// Hydrate ~/.agentmemory/.env into process.env at boot. loadEnvFile() is
// otherwise only consumed via getMergedEnv(), which the many modules that
// read raw process.env["X"] never call — so .env-only values were silently
// ignored by them. Copy the file's vars into process.env, but only when the
// key is currently unset so a real process.env value still wins (this
// preserves the {...fileEnv, ...process.env} precedence getMergedEnv uses).
export function hydrateProcessEnvFromFile(): Record<string, string | undefined> {
const beforeHydration = { ...process.env };
for (const [k, v] of Object.entries(loadEnvFile())) {
if (process.env[k] === undefined) process.env[k] = v;
}
return beforeHydration;
}
// Warn once when a configured model is in the premium tier and likely to burn
// money on background compression. Captured workload data shows ~$5/35h on
// claude-sonnet-4 vs ~$0.46/35h on deepseek-v4-pro for the same compression
// mix. Heuristic match avoids hard-coding a pricing table.
function warnIfPremiumModel(env: Record<string, string>, envName: string, model: string): void {
if (
warnPremiumModelShown ||
!/sonnet|opus|gpt-5\.\d+-sol|gpt-4o(?!.*mini)|gpt-4-turbo/i.test(model) ||
env["AGENTMEMORY_SUPPRESS_COST_WARNING"] === "1" ||
env["AGENTMEMORY_SUPPRESS_COST_WARNING"] === "true"
) {
return;
}
warnPremiumModelShown = true;
process.stderr.write(
`[agentmemory] ${envName}=${model} is in the premium tier. ` +
`Background compression on this model can cost $5+/day under active use. ` +
`Cheaper alternatives with comparable quality for memory compression: ` +
`deepseek/deepseek-v4-flash-0731, deepseek/deepseek-v4-pro, qwen/qwen3-coder. ` +
`See README "Cost-aware model selection" for the full table. ` +
`Set AGENTMEMORY_SUPPRESS_COST_WARNING=1 to silence.\n`,
);
}
function detectProvider(env: Record<string, string>): ProviderConfig {
const maxTokens = parseInt(env["MAX_TOKENS"] || "4096", 10);
// OpenAI-compatible: supports OpenAI, DeepSeek, SiliconFlow, Azure, vLLM, LM Studio
if (hasRealValue(env["OPENAI_API_KEY"]) && env["OPENAI_API_KEY_FOR_LLM"] !== "false") {
const model = env["OPENAI_MODEL"] || "gpt-5.6-luna";
warnIfPremiumModel(env, "OPENAI_MODEL", model);
return {
provider: "openai",
model,
maxTokens,
baseURL: env["OPENAI_BASE_URL"],
};
}
// MiniMax: Anthropic-compatible API, requires raw fetch to avoid SDK stainless headers
if (hasRealValue(env["MINIMAX_API_KEY"])) {
return {
provider: "minimax",
model: env["MINIMAX_MODEL"] || "MiniMax-M3",
maxTokens,
};
}
if (hasRealValue(env["ANTHROPIC_API_KEY"])) {
return {
provider: "anthropic",
model: env["ANTHROPIC_MODEL"] || "claude-sonnet-5",
maxTokens,
baseURL: env["ANTHROPIC_BASE_URL"],
};
}
if (hasRealValue(env["GEMINI_API_KEY"]) || hasRealValue(env["GOOGLE_API_KEY"])) {
if (!hasRealValue(env["GEMINI_API_KEY"]) && hasRealValue(env["GOOGLE_API_KEY"])) {
process.stderr.write(
"[agentmemory] GOOGLE_API_KEY detected — treating as GEMINI_API_KEY. " +
"Set GEMINI_API_KEY in ~/.agentmemory/.env to silence this warning.\n",
);
}
return {
provider: "gemini",
model: env["GEMINI_MODEL"] || "gemini-3.7-flash",
maxTokens,
};
}
if (hasRealValue(env["OPENROUTER_API_KEY"])) {
const model = env["OPENROUTER_MODEL"] || "anthropic/claude-sonnet-5";
warnIfPremiumModel(env, "OPENROUTER_MODEL", model);
return {
provider: "openrouter",
model,
maxTokens,
};
}
const allowAgentSdk = env["AGENTMEMORY_ALLOW_AGENT_SDK"] === "true";
if (!allowAgentSdk) {
writeProviderNoticeOnce(
pc.dim(
"[agentmemory] No LLM provider key set — running zero-LLM: no LLM compression or summaries; search uses BM25 plus any configured embedding provider. " +
"Set EMBEDDING_PROVIDER=local for on-device semantic embeddings if none is configured. " +
"Set ANTHROPIC_API_KEY (or GEMINI/OPENAI/OPENROUTER/MINIMAX) in ~/.agentmemory/.env for LLM compression and summaries. " +
"Agent-SDK fallback stays off by default to avoid a Stop-hook recursion loop; opt in with AGENTMEMORY_AUTO_COMPRESS=true + AGENTMEMORY_ALLOW_AGENT_SDK=true.\n",
),
);
return {
provider: "noop",
model: "noop",
maxTokens,
};
}
writeProviderNoticeOnce(
"[agentmemory] WARNING: agent-sdk fallback enabled via AGENTMEMORY_ALLOW_AGENT_SDK=true. " +
"This spawns @anthropic-ai/claude-agent-sdk child sessions that can trigger the Stop-hook " +
"recursion loop. A SDK-child env marker is set to block re-entry, " +
"but prefer setting a real API key in ~/.agentmemory/.env instead.\n",
);
return {
provider: "agent-sdk",
model: "claude-sonnet-5",
maxTokens,
};
}
export function loadConfig(): AgentMemoryConfig {
const env = getMergedEnv();
const provider = detectProvider(env);
// REST is the anchor; viewer and engine ports derive from it unless individually overridden.
const restPort = parseInt(env["III_REST_PORT"] || "3111", 10) || 3111;
const viewerPort =
parseInt(env["III_VIEWER_PORT"] || "", 10) || restPort + 2;
const engineUrl =
env["III_ENGINE_URL"] ||
env["III_URL"] ||
`ws://localhost:${
parseInt(env["III_ENGINE_PORT"] || "", 10) || restPort + 46023
}`;
const maxObservationsPerSession = safeParseInt(env["MAX_OBS_PER_SESSION"], 500);
if (
!obsCapImportCeilingWarned &&
(maxObservationsPerSession === 0 || maxObservationsPerSession > MAX_IMPORT_OBS_PER_SESSION)
) {
obsCapImportCeilingWarned = true;
const capDesc = maxObservationsPerSession === 0 ? "uncapped (0)" : String(maxObservationsPerSession);
process.stderr.write(
`[agentmemory] WARNING: MAX_OBS_PER_SESSION is ${capDesc}, above the ` +
`${MAX_IMPORT_OBS_PER_SESSION}-per-session import ceiling (MAX_IMPORT_OBS_PER_SESSION). ` +
`Sessions past that ceiling make every mem::export -> mem::import restore fail wholesale. ` +
`Keep MAX_OBS_PER_SESSION at or below ${MAX_IMPORT_OBS_PER_SESSION} if you rely on export/import backups.\n`,
);
}
return {
engineUrl,
restPort,
viewerPort,
provider,
tokenBudget: safeParseInt(env["TOKEN_BUDGET"], 2000),
maxObservationsPerSession,
compressionModel: provider.model,
dataDir: DATA_DIR,
};
}
function getMergedEnv(
overrides?: Record<string, string>,
): Record<string, string> {
const fileEnv = loadEnvFile();
return { ...fileEnv, ...process.env, ...overrides } as Record<string, string>;
}
export function getEnvVar(key: string): string | undefined {
return getMergedEnv()[key];
}
export function isSessionSweepEnabled(): boolean {
return getMergedEnv()["AGENTMEMORY_SESSION_SWEEP_ENABLED"] !== "false";
}
export function getSessionSweepStaleHours(): number {
const raw = getMergedEnv()["AGENTMEMORY_SESSION_SWEEP_STALE_HOURS"];
if (!raw || !/^\d+$/.test(raw.trim())) return 24;
const parsed = parseInt(raw.trim(), 10);
return parsed > 0 ? parsed : 24;
}
export function getFinalizeIdleMs(): number {
const raw = getMergedEnv()["AGENTMEMORY_FINALIZE_IDLE_MS"];
if (!raw || !/^\d+$/.test(raw.trim())) return 120000;
return parseInt(raw.trim(), 10);
}
export function isGraphCompactOnBootEnabled(): boolean {
return getMergedEnv()["AGENTMEMORY_GRAPH_COMPACT_ON_BOOT"] !== "false";
}
export function isDropStaleIndexEnabled(): boolean {
return getMergedEnv()["AGENTMEMORY_DROP_STALE_INDEX"] === "true";
}
const VALID_STATE_BACKENDS = new Set(["file", "redis"]);
export function getStateBackend(): "file" | "redis" {
const raw = (getMergedEnv()["AGENTMEMORY_STATE_BACKEND"] || "")
.trim()
.toLowerCase();
if (!raw) return "file";
if (!VALID_STATE_BACKENDS.has(raw)) {
throw new Error(
`AGENTMEMORY_STATE_BACKEND="${raw}" is not a recognized state backend. Use "file" (the default) or "redis", or unset it to keep the default file store.`,
);
}
return raw as "file" | "redis";
}
export function getRedisUrl(): string | undefined {
const value = getMergedEnv()["AGENTMEMORY_REDIS_URL"];
return hasRealValue(value) ? value.trim() : undefined;
}
export function getAuditRetentionMonths(): number {
return safeParseInt(getMergedEnv()["AGENTMEMORY_AUDIT_RETENTION_MONTHS"], 0);
}
export function getAuditMigrateMaxBytes(): number {
return safeParseInt(
getMergedEnv()["AGENTMEMORY_AUDIT_MIGRATE_MAX_BYTES"],
32 * 1024 * 1024,
);
}
export function detectLlmProviderKind(
env: Record<string, string | undefined> = getMergedEnv(),
): "llm" | "noop" {
if (
hasRealValue(env["ANTHROPIC_API_KEY"]) ||
hasRealValue(env["GEMINI_API_KEY"]) ||
hasRealValue(env["GOOGLE_API_KEY"]) ||
hasRealValue(env["OPENROUTER_API_KEY"]) ||
hasRealValue(env["MINIMAX_API_KEY"]) ||
(hasRealValue(env["OPENAI_API_KEY"]) &&
env["OPENAI_API_KEY_FOR_LLM"] !== "false") ||
env["AGENTMEMORY_ALLOW_AGENT_SDK"] === "true"
) {
return "llm";
}
return "noop";
}
export function describeLlmRoute(provider: ProviderConfig): string | null {
if (provider.provider === "noop") return null;
const parts = [provider.provider, provider.model];
if (provider.baseURL) {
try {
parts.push(new URL(provider.baseURL).host);
} catch {
parts.push("custom base URL");
}
}
return parts.join(" · ");
}
export function loadEmbeddingConfig(): EmbeddingConfig {
const env = getMergedEnv();
let bm25Weight = parseFloat(env["BM25_WEIGHT"] || "0.4");
let vectorWeight = parseFloat(env["VECTOR_WEIGHT"] || "0.6");
bm25Weight =
isNaN(bm25Weight) || bm25Weight < 0 ? 0.4 : Math.min(bm25Weight, 1);
vectorWeight =
isNaN(vectorWeight) || vectorWeight < 0 ? 0.6 : Math.min(vectorWeight, 1);
return {
provider: env["EMBEDDING_PROVIDER"] || undefined,
bm25Weight,
vectorWeight,
};
}
export function detectEmbeddingProvider(
env?: Record<string, string>,
): string | null {
const source = env ?? getMergedEnv();
const forced = source["EMBEDDING_PROVIDER"];
if (forced) return forced;
if (source["GEMINI_API_KEY"]) return "gemini";
if (source["OPENAI_API_KEY"] || source["OPENAI_EMBEDDING_API_KEY"]) return "openai";
if (source["VOYAGE_API_KEY"]) return "voyage";
if (source["COHERE_API_KEY"]) return "cohere";
if (source["OPENROUTER_API_KEY"]) return "openrouter";
return null;
}
export function loadClaudeBridgeConfig(): ClaudeBridgeConfig {
const env = getMergedEnv();
const enabled = env["CLAUDE_MEMORY_BRIDGE"] === "true";
const projectPath = env["CLAUDE_PROJECT_PATH"] || "";
const lineBudget = safeParseInt(env["CLAUDE_MEMORY_LINE_BUDGET"], 200);
let memoryFilePath = "";
if (enabled && projectPath) {
// Claude Code stores project memory at
// ~/.claude/projects/<slug>/memory/MEMORY.md
// where <slug> is the project path with `/` and `\` swapped for `-`.
// The leading `-` from an absolute POSIX path is preserved (Claude
// Code keeps it; stripping it produced a slug Claude never reads).
// The `memory/` subdirectory holds MEMORY.md (the index) plus one
// per-topic `.md` file per memory (verified against Claude Code 2.x).
const safePath = projectPath.replace(/[/\\]/g, "-");
memoryFilePath = join(
homedir(),
".claude",
"projects",
safePath,
"memory",
"MEMORY.md",
);
}
return { enabled, projectPath, memoryFilePath, lineBudget };
}
export function loadTeamConfig(): TeamConfig | null {
const env = getMergedEnv();
const teamId = env["TEAM_ID"];
const userId = env["USER_ID"];
if (!teamId || !userId) return null;
const mode = env["TEAM_MODE"] === "shared" ? "shared" : "private";
return { teamId, userId, mode };
}
// optional AGENT_ID env for multi-agent memory isolation.
// Returns null when unset so memory stays unscoped (legacy behavior).
// Trimmed + length-capped to keep KV writes well-formed.
//
// Filtering is gated by AGENTMEMORY_AGENT_SCOPE:
// "shared" (default) — tag everything, do not filter recall paths
// "isolated" — tag everything AND filter recall paths
export function loadAgentScope(): {
agentId: string;
mode: "shared" | "isolated";
} | null {
const env = getMergedEnv();
const raw = env["AGENT_ID"];
if (!raw) return null;
const agentId = raw.trim().slice(0, 128);
if (!agentId) return null;
const mode = env["AGENTMEMORY_AGENT_SCOPE"] === "isolated"
? "isolated"
: "shared";
return { agentId, mode };
}
export function getAgentId(): string | undefined {
return loadAgentScope()?.agentId;
}
// True only when AGENT_ID is set AND scope=isolated. Recall paths
// consult this to decide whether to filter.
export function isAgentScopeIsolated(): boolean {
return loadAgentScope()?.mode === "isolated";
}
// Floor for the git-snapshot timer. A zero/negative SNAPSHOT_INTERVAL would
// make setInterval fire on roughly every event-loop tick, saturating the
// worker with back-to-back full-state snapshots + git commits. Anything below
// this floor is treated as a misconfiguration and falls back to the default.
const SNAPSHOT_INTERVAL_DEFAULT_SECONDS = 3600;
const MIN_SNAPSHOT_INTERVAL_SECONDS = 1;
export function loadSnapshotConfig(): {
enabled: boolean;
interval: number;
dir: string;
} {
const env = getMergedEnv();
const rawInterval = safeParseInt(
env["SNAPSHOT_INTERVAL"],
SNAPSHOT_INTERVAL_DEFAULT_SECONDS,
);
const interval =
rawInterval >= MIN_SNAPSHOT_INTERVAL_SECONDS
? rawInterval
: SNAPSHOT_INTERVAL_DEFAULT_SECONDS;
return {
enabled: env["SNAPSHOT_ENABLED"] === "true",
interval,
dir: env["SNAPSHOT_DIR"] || join(homedir(), ".agentmemory", "snapshots"),
};
}
export function isGraphExtractionEnabled(): boolean {
return getMergedEnv()["GRAPH_EXTRACTION_ENABLED"] === "true";
}
export function getGraphBatchSize(): number {
return safeParseInt(getMergedEnv()["GRAPH_EXTRACTION_BATCH_SIZE"], 10);
}
// window for the smart-search followup-rate diagnostic. A second
// search arriving within this many seconds (with disjoint results)
// counts as a "follow-up" — a directional signal that the first result
// set didn't satisfy. Long values overcount (legitimate refinement
// looks like a follow-up); short values undercount.
const FOLLOWUP_WINDOW_DEFAULT_SECONDS = 30;
export function getFollowupWindowSeconds(): number {
return safeParseInt(
getMergedEnv()["AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS"],
FOLLOWUP_WINDOW_DEFAULT_SECONDS,
);
}
export function isConsolidationEnabled(): boolean {
const env = getMergedEnv();
const explicit = env["CONSOLIDATION_ENABLED"];
if (explicit === "false" || explicit === "0") return false;
if (explicit === "true" || explicit === "1") return true;
if ((env["AGENTMEMORY_PROVIDER"] || "").toLowerCase() === "noop") return false;
return detectLlmProviderKind(env) === "llm";
}
// Per-observation LLM compression is OFF by default as of 0.8.8.
// When disabled, observations are captured and indexed via a synthetic
// (zero-LLM) compression path so recall/search still works. Users who want
// richer LLM-generated summaries can set AGENTMEMORY_AUTO_COMPRESS=true in
// ~/.agentmemory/.env — but should expect their Claude API token usage to
// climb proportionally with session tool-use frequency.
export function isAutoCompressEnabled(): boolean {
return getMergedEnv()["AGENTMEMORY_AUTO_COMPRESS"] === "true";
}
// Hook-level context injection into Claude Code's conversation is OFF by
// default as of 0.8.10. When disabled, pre-tool-use and
// session-start hooks still POST observations for background capture, but
// never write context to stdout — so Claude Code doesn't inject an extra
// ~4000-char blob into every tool turn. 0.8.8 stopped the agentmemory-side
// Claude calls (via ANTHROPIC_API_KEY); this stops the Claude Code-side
// token burn where every tool call silently grew the model input window.
// Users who want the in-conversation context injection explicitly opt in
// with AGENTMEMORY_INJECT_CONTEXT=true and get a loud startup warning.
export function isContextInjectionEnabled(): boolean {
return getMergedEnv()["AGENTMEMORY_INJECT_CONTEXT"] === "true";
}
export const CONSOLIDATION_INTERVAL_DEFAULT_MS = 7200000;
export function getConsolidationIntervalMs(): number {
const raw = parseInt(process.env.CONSOLIDATION_INTERVAL_MS || String(CONSOLIDATION_INTERVAL_DEFAULT_MS), 10);
return Number.isFinite(raw) && raw > 0 ? raw : CONSOLIDATION_INTERVAL_DEFAULT_MS;
}
export function getConsolidationDecayDays(): number {
return safeParseInt(getMergedEnv()["CONSOLIDATION_DECAY_DAYS"], 30);
}
// Cooldown between corpus consolidations triggered by session stop. The Stop
// hook fires per agent turn and posts /session/end, so without this every turn
// would kick a full LLM semantic-merge + reflect + crystallize. Debounced to at
// most once per window. Set to 0 to disable the debounce (consolidate on every
// stop). Default 5 minutes.
const CONSOLIDATION_COOLDOWN_DEFAULT_MS = 300000;
export function getConsolidationCooldownMs(): number {
const raw = safeParseInt(
getMergedEnv()["AGENTMEMORY_CONSOLIDATION_COOLDOWN_MS"],
CONSOLIDATION_COOLDOWN_DEFAULT_MS,
);
return raw >= 0 ? raw : CONSOLIDATION_COOLDOWN_DEFAULT_MS;
}
export const INDEX_SAVE_INTERVAL_DEFAULT_MS = 600_000;
export function getIndexSaveIntervalMs(): number {
const raw = safeParseInt(
getMergedEnv()["AGENTMEMORY_INDEX_SAVE_INTERVAL_MS"],
INDEX_SAVE_INTERVAL_DEFAULT_MS,
);
return raw > 0 ? raw : INDEX_SAVE_INTERVAL_DEFAULT_MS;
}
export const STATE_SAVE_INTERVAL_DEFAULT_MS = 2000;
export const STATE_SAVE_INTERVAL_MIN_MS = 100;
export const STATE_SAVE_INTERVAL_MAX_MS = 3_600_000;
export function getStateSaveIntervalMs(): number {
const value = getMergedEnv()["AGENTMEMORY_STATE_SAVE_INTERVAL_MS"];
if (value === undefined || value.trim() === "") return STATE_SAVE_INTERVAL_DEFAULT_MS;
if (!/^\d+$/.test(value.trim())) return STATE_SAVE_INTERVAL_DEFAULT_MS;
const raw = Number(value);
return Number.isSafeInteger(raw) && raw >= STATE_SAVE_INTERVAL_MIN_MS && raw <= STATE_SAVE_INTERVAL_MAX_MS
? raw
: STATE_SAVE_INTERVAL_DEFAULT_MS;
}
export const VECTOR_BUCKET_SIZE_DEFAULT = 500;
export function getVectorBucketSize(): number {
const raw = safeParseInt(getMergedEnv()["AGENTMEMORY_VECTOR_BUCKET_SIZE"], VECTOR_BUCKET_SIZE_DEFAULT);
return raw > 0 ? raw : VECTOR_BUCKET_SIZE_DEFAULT;
}
export const VECTOR_BACKFILL_MAX_DEFAULT = 500;
export function getVectorBackfillMax(): number {
const raw = safeParseInt(getMergedEnv()["AGENTMEMORY_VECTOR_BACKFILL_MAX"], VECTOR_BACKFILL_MAX_DEFAULT);
return raw > 0 ? raw : VECTOR_BACKFILL_MAX_DEFAULT;
}
export function isVectorBackfillAllEnabled(): boolean {
return getMergedEnv()["AGENTMEMORY_VECTOR_BACKFILL"] === "all";
}
export function isStandaloneMcp(): boolean {
return getMergedEnv()["STANDALONE_MCP"] === "true";
}
export function getStandalonePersistPath(): string {
const env = getMergedEnv();
return (
env["STANDALONE_PERSIST_PATH"] ||
join(homedir(), ".agentmemory", "standalone.json")
);
}
const VALID_PROVIDERS = new Set([
"anthropic",
"gemini",
"openrouter",
"agent-sdk",
"minimax",
"openai",
]);
export function loadFallbackConfig(): FallbackConfig {
const env = getMergedEnv();
const raw = env["FALLBACK_PROVIDERS"] || "";
const allowAgentSdk = env["AGENTMEMORY_ALLOW_AGENT_SDK"] === "true";
const providers = raw
.split(",")
.map((p) => p.trim())
.filter(
(p): p is FallbackConfig["providers"][number] =>
Boolean(p) && VALID_PROVIDERS.has(p),
)
.filter((p) => {
// Honor the same safety gate as detectProvider: agent-sdk is only
// permitted as a fallback target when the user has explicitly opted
// in. Without this filter, a user could set FALLBACK_PROVIDERS=agent-sdk
// and re-introduce the Stop-hook recursion loop even though
// detectProvider() returned the noop provider.
if (p === "agent-sdk" && !allowAgentSdk) {
process.stderr.write(
"[agentmemory] Ignoring FALLBACK_PROVIDERS entry 'agent-sdk' " +
"(AGENTMEMORY_ALLOW_AGENT_SDK is not 'true'). The agent-sdk " +
"fallback can spawn Claude Agent SDK child sessions that trigger " +
"the Stop-hook recursion loop. Opt in explicitly " +
"with AGENTMEMORY_ALLOW_AGENT_SDK=true if this is intentional.\n",
);
return false;
}
return true;
});
return { providers };
}