peon-mem 1.0.0

package/dist/brain.d.ts

@@ -0,0 +1,72 @@
+import type { MemoryRecord } from "./types.js";
+/**
+ * The autonomous brain — a "sleep cycle" of curation the daemon runs on its own.
+ * Pure and testable: every step takes a belief set and returns a new one plus a
+ * log of what it did. Nothing is destroyed — losers/merged/compressed beliefs are
+ * demoted to the `archived` tier (recoverable, searchable, never injected).
+ *
+ * The LLM-dependent step (topic compression) takes an injected `summarize`
+ * callback so the orchestration stays unit-testable without a model.
+ */
+export type BrainActionType = "reinforce" | "resolve_conflict" | "merge_duplicate" | "compress_cluster";
+export interface BrainAction {
+    type: BrainActionType;
+    detail: string;
+    affectedIds: string[];
+}
+export interface SleepCycleResult {
+    records: MemoryRecord[];
+    actions: BrainAction[];
+}
+/**
+ * Reinforcement: beliefs recalled since the last pass get stronger and a fresh
+ * lastRecalledAt; everything else relaxes slightly toward its importance anchor.
+ * This is the "use it or lose it" signal — except nothing is lost, it only
+ * decides what stays detailed in working memory vs. eligible for compression.
+ */
+export declare function reinforce(records: readonly MemoryRecord[], recalledIds: readonly string[], now: string, protectGlobalScope?: boolean): SleepCycleResult;
+/**
+ * Resolve detected conflicts autonomously: the higher-confidence belief wins,
+ * ties break to the newer one; the loser is archived (recoverable), not deleted.
+ */
+export declare function resolveConflicts(records: readonly MemoryRecord[], now: string, protectGlobalScope?: boolean): SleepCycleResult;
+/**
+ * Auto-merge near-duplicate beliefs: fold the weaker into the stronger (union
+ * entities, keep the higher scores), archiving the raw copy via the merge helper's
+ * delete — here we instead ARCHIVE the dropped record so nothing is lost.
+ */
+export declare function autoMergeDuplicates(records: readonly MemoryRecord[], now: string, threshold?: number, protectGlobalScope?: boolean): SleepCycleResult;
+export interface TopicCluster {
+    entity: string;
+    members: MemoryRecord[];
+}
+/** Group ACTIVE, non-protected beliefs by their dominant entity. */
+export declare function findTopicClusters(records: readonly MemoryRecord[], minSize: number, protectGlobalScope?: boolean): TopicCluster[];
+export type Summarizer = (cluster: TopicCluster) => Promise<string>;
+/**
+ * Compress topic clusters: when many beliefs share an entity, roll them into one
+ * summary belief (via the injected LLM `summarize`) and archive the raw detail,
+ * linked by summaryOf/summarizedBy. Working memory shrinks; nothing is lost.
+ */
+export declare function compressTopicClusters(records: readonly MemoryRecord[], summarize: Summarizer, now: string, options?: {
+    minClusterSize?: number;
+    maxClusters?: number;
+    protectGlobalScope?: boolean;
+    makeId: (entity: string) => string;
+}): Promise<SleepCycleResult>;
+export interface SleepCycleOptions {
+    recalledIds?: string[];
+    now: string;
+    summarize?: Summarizer;
+    minClusterSize?: number;
+    maxClusters?: number;
+    /** Set false when curating the GLOBAL brain — there, global beliefs are the working set. */
+    protectGlobalScope?: boolean;
+    makeSummaryId: (entity: string) => string;
+}
+/**
+ * One full autonomous pass: reinforce → resolve conflicts → merge duplicates →
+ * compress topic clusters. Returns the curated belief set and an action log.
+ * The caller snapshots a backup BEFORE applying this — every step is recoverable.
+ */
+export declare function runSleepCycle(records: readonly MemoryRecord[], options: SleepCycleOptions): Promise<SleepCycleResult>;

package/dist/brain.js

@@ -0,0 +1,224 @@
+import { detectMemoryConflicts } from "./quality.js";
+import { detectDuplicates } from "./overview.js";
+import { applyMerge } from "./memory-mutations.js";
+function isProtected(record, protectGlobalScope = true) {
+    // Pinned beliefs are always protected. Global-scoped beliefs are protected when
+    // curating a PROJECT brain (don't touch shared memory), but NOT when curating the
+    // GLOBAL brain itself — there, global beliefs are the working set.
+    if (record.pinned)
+        return true;
+    return protectGlobalScope && record.scope === "global";
+}
+function clamp01(value) {
+    return Math.max(0, Math.min(1, value));
+}
+/** Strength a belief starts at if it has never been scored — anchored to importance. */
+function baseStrength(record) {
+    return typeof record.strength === "number" ? record.strength : record.score.importance;
+}
+/**
+ * Reinforcement: beliefs recalled since the last pass get stronger and a fresh
+ * lastRecalledAt; everything else relaxes slightly toward its importance anchor.
+ * This is the "use it or lose it" signal — except nothing is lost, it only
+ * decides what stays detailed in working memory vs. eligible for compression.
+ */
+export function reinforce(records, recalledIds, now, protectGlobalScope = true) {
+    const recalled = new Set(recalledIds);
+    const actions = [];
+    const out = records.map((record) => {
+        const current = baseStrength(record);
+        if (recalled.has(record.id)) {
+            actions.push({ type: "reinforce", detail: `recalled: ${record.content.slice(0, 60)}`, affectedIds: [record.id] });
+            return {
+                ...record,
+                strength: clamp01(current + 0.15 * (1 - current)),
+                recallCount: (record.recallCount ?? 0) + 1,
+                lastRecalledAt: now
+            };
+        }
+        // Gentle relaxation toward the importance anchor (never below it for protected beliefs).
+        const anchor = record.score.importance;
+        const relaxed = isProtected(record, protectGlobalScope) ? Math.max(current, anchor) : current - 0.02 * (current - anchor * 0.5);
+        return { ...record, strength: clamp01(relaxed) };
+    });
+    return { records: out, actions };
+}
+/**
+ * Resolve detected conflicts autonomously: the higher-confidence belief wins,
+ * ties break to the newer one; the loser is archived (recoverable), not deleted.
+ */
+export function resolveConflicts(records, now, protectGlobalScope = true) {
+    // Consolidation flags BOTH sides of a conflict as "conflicted" and waits for a
+    // human. The brain re-detects among active+conflicted and decides: winner back
+    // to active, loser archived (recoverable).
+    const candidates = records.filter((r) => r.status === "active" || r.status === "conflicted");
+    const conflicts = detectMemoryConflicts(candidates);
+    if (conflicts.length === 0)
+        return { records: [...records], actions: [] };
+    const byId = new Map(records.map((r) => [r.id, r]));
+    const archived = new Set();
+    const reactivated = new Set();
+    const actions = [];
+    for (const conflict of conflicts) {
+        const left = byId.get(conflict.leftId);
+        const right = byId.get(conflict.rightId);
+        if (!left || !right)
+            continue;
+        if (archived.has(left.id) || archived.has(right.id))
+            continue;
+        // Protected beliefs always win; otherwise confidence, then recency.
+        let loser;
+        if (isProtected(left, protectGlobalScope) && !isProtected(right, protectGlobalScope))
+            loser = right;
+        else if (isProtected(right, protectGlobalScope) && !isProtected(left, protectGlobalScope))
+            loser = left;
+        else if (left.score.confidence !== right.score.confidence)
+            loser = left.score.confidence < right.score.confidence ? left : right;
+        else
+            loser = left.updatedAt <= right.updatedAt ? left : right;
+        const winner = loser.id === left.id ? right : left;
+        if (isProtected(loser, protectGlobalScope))
+            continue; // never archive a protected belief
+        archived.add(loser.id);
+        reactivated.add(winner.id);
+        actions.push({
+            type: "resolve_conflict",
+            detail: `kept "${winner.content.slice(0, 40)}" over "${loser.content.slice(0, 40)}"`,
+            affectedIds: [winner.id, loser.id]
+        });
+    }
+    const out = records.map((r) => {
+        if (archived.has(r.id))
+            return { ...r, status: "archived", updatedAt: now };
+        if (reactivated.has(r.id))
+            return { ...r, status: "active", updatedAt: now };
+        return r;
+    });
+    return { records: out, actions };
+}
+/**
+ * Auto-merge near-duplicate beliefs: fold the weaker into the stronger (union
+ * entities, keep the higher scores), archiving the raw copy via the merge helper's
+ * delete — here we instead ARCHIVE the dropped record so nothing is lost.
+ */
+export function autoMergeDuplicates(records, now, threshold = 0.6, protectGlobalScope = true) {
+    const pairs = detectDuplicates(records, { threshold, limit: 50 });
+    if (pairs.length === 0)
+        return { records: [...records], actions: [] };
+    const byId = new Map(records.map((r) => [r.id, r]));
+    let working = [...records];
+    const archived = new Set();
+    const actions = [];
+    for (const pair of pairs) {
+        const a = byId.get(pair.aId);
+        const b = byId.get(pair.bId);
+        if (!a || !b || archived.has(a.id) || archived.has(b.id))
+            continue;
+        if (isProtected(a, protectGlobalScope) && isProtected(b, protectGlobalScope))
+            continue;
+        // Keep the stronger (or protected) belief; archive the other.
+        const keep = isProtected(a, protectGlobalScope) ? a : isProtected(b, protectGlobalScope) ? b : baseStrength(a) >= baseStrength(b) ? a : b;
+        const drop = keep.id === a.id ? b : a;
+        // Fold drop's entities/score into keep (applyMerge removes drop), then re-add
+        // drop as an archived record so the raw copy is recoverable, not erased.
+        working = applyMerge(working, keep.id, drop.id, now);
+        working.push({ ...drop, status: "archived", summarizedBy: keep.id, updatedAt: now });
+        archived.add(drop.id);
+        actions.push({ type: "merge_duplicate", detail: `merged duplicate of "${keep.content.slice(0, 50)}"`, affectedIds: [keep.id, drop.id] });
+    }
+    return { records: working, actions };
+}
+/** Group ACTIVE, non-protected beliefs by their dominant entity. */
+export function findTopicClusters(records, minSize, protectGlobalScope = true) {
+    const byEntity = new Map();
+    for (const record of records) {
+        if (record.status !== "active" || isProtected(record, protectGlobalScope))
+            continue;
+        if (record.summaryOf)
+            continue; // don't re-compress existing summaries
+        const entity = (record.entities[0] ?? "").toLowerCase();
+        if (!entity)
+            continue;
+        const list = byEntity.get(entity) ?? [];
+        list.push(record);
+        byEntity.set(entity, list);
+    }
+    return Array.from(byEntity.entries())
+        .filter(([, members]) => members.length >= minSize)
+        .map(([entity, members]) => ({ entity, members }));
+}
+/**
+ * Compress topic clusters: when many beliefs share an entity, roll them into one
+ * summary belief (via the injected LLM `summarize`) and archive the raw detail,
+ * linked by summaryOf/summarizedBy. Working memory shrinks; nothing is lost.
+ */
+export async function compressTopicClusters(records, summarize, now, options = { makeId: (e) => `summary_${e}` }) {
+    const minClusterSize = options.minClusterSize ?? 5;
+    const maxClusters = options.maxClusters ?? 3; // bound LLM cost per pass
+    const clusters = findTopicClusters(records, minClusterSize, options.protectGlobalScope ?? true)
+        .sort((a, b) => b.members.length - a.members.length)
+        .slice(0, maxClusters);
+    if (clusters.length === 0)
+        return { records: [...records], actions: [] };
+    let working = [...records];
+    const actions = [];
+    for (const cluster of clusters) {
+        const content = (await summarize(cluster)).trim();
+        if (!content)
+            continue;
+        const memberIds = cluster.members.map((m) => m.id);
+        const summaryId = options.makeId(cluster.entity);
+        const importance = Math.max(...cluster.members.map((m) => m.score.importance));
+        const entities = Array.from(new Set(cluster.members.flatMap((m) => m.entities)));
+        const summary = {
+            id: summaryId,
+            type: "summary",
+            content,
+            normalized: content.toLowerCase(),
+            scope: cluster.members[0].scope,
+            status: "active",
+            score: { importance, confidence: 0.82 },
+            source: { kind: "ai_processing", reason: `compressed ${memberIds.length} beliefs about ${cluster.entity}` },
+            entities,
+            createdAt: now,
+            updatedAt: now,
+            strength: importance,
+            summaryOf: memberIds
+        };
+        const memberSet = new Set(memberIds);
+        working = working.map((r) => (memberSet.has(r.id) ? { ...r, status: "archived", summarizedBy: summaryId, updatedAt: now } : r));
+        working.push(summary);
+        actions.push({ type: "compress_cluster", detail: `compressed ${memberIds.length} beliefs about "${cluster.entity}" into one summary`, affectedIds: [summaryId, ...memberIds] });
+    }
+    return { records: working, actions };
+}
+/**
+ * One full autonomous pass: reinforce → resolve conflicts → merge duplicates →
+ * compress topic clusters. Returns the curated belief set and an action log.
+ * The caller snapshots a backup BEFORE applying this — every step is recoverable.
+ */
+export async function runSleepCycle(records, options) {
+    const actions = [];
+    let working = [...records];
+    const protectGlobalScope = options.protectGlobalScope ?? true;
+    const r = reinforce(working, options.recalledIds ?? [], options.now, protectGlobalScope);
+    working = r.records;
+    actions.push(...r.actions);
+    const c = resolveConflicts(working, options.now, protectGlobalScope);
+    working = c.records;
+    actions.push(...c.actions);
+    const m = autoMergeDuplicates(working, options.now, 0.6, protectGlobalScope);
+    working = m.records;
+    actions.push(...m.actions);
+    if (options.summarize) {
+        const z = await compressTopicClusters(working, options.summarize, options.now, {
+            minClusterSize: options.minClusterSize,
+            maxClusters: options.maxClusters,
+            protectGlobalScope,
+            makeId: options.makeSummaryId
+        });
+        working = z.records;
+        actions.push(...z.actions);
+    }
+    return { records: working, actions };
+}

package/dist/compression.d.ts

@@ -0,0 +1,9 @@
+import type { PeonConfig } from "./config.js";
+import type { Summarizer } from "./brain.js";
+/**
+ * Builds the LLM summarizer the brain uses to compress a topic cluster into one
+ * gist belief. Kept separate from brain.ts so the curation logic stays pure and
+ * testable; this is the only network-touching piece. Returns null when AI is off
+ * or no key is configured (the brain then runs cost-free, skipping compression).
+ */
+export declare function createClusterSummarizer(config: PeonConfig): Summarizer | null;

package/dist/compression.js

@@ -0,0 +1,37 @@
+/**
+ * Builds the LLM summarizer the brain uses to compress a topic cluster into one
+ * gist belief. Kept separate from brain.ts so the curation logic stays pure and
+ * testable; this is the only network-touching piece. Returns null when AI is off
+ * or no key is configured (the brain then runs cost-free, skipping compression).
+ */
+export function createClusterSummarizer(config) {
+    if (config.aiMode === "off" || !config.openRouterApiKey)
+        return null;
+    return async (cluster) => {
+        const beliefs = cluster.members.map((m, i) => `${i + 1}. ${m.content}`).join("\n");
+        const system = "You compress several related memory beliefs into ONE durable summary belief. " +
+            "PRESERVE every concrete fact verbatim — names, numbers, metrics, file paths, hostnames, decisions. " +
+            "Losing a specific fact is a failure; merge wording, never drop information. Drop only redundancy and filler. " +
+            "Output ONLY the summary sentence(s) — no preamble, no markdown, no quotes around it. Max 240 characters.";
+        const user = `Topic: ${cluster.entity}\n\nBeliefs to compress:\n${beliefs}\n\nOne compact summary:`;
+        const response = await fetch("https://openrouter.ai/api/v1/chat/completions", {
+            method: "POST",
+            headers: { Authorization: `Bearer ${config.openRouterApiKey}`, "Content-Type": "application/json" },
+            body: JSON.stringify({
+                model: config.processingModel,
+                messages: [
+                    { role: "system", content: system },
+                    { role: "user", content: user }
+                ],
+                temperature: 0.1
+            })
+        });
+        if (!response.ok)
+            throw new Error(`compression failed with ${response.status}`);
+        const json = (await response.json());
+        const content = json.choices?.[0]?.message?.content?.trim();
+        if (!content)
+            throw new Error("compression returned no content");
+        return content.slice(0, 280);
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,22 @@
+export type PeonProvider = "openrouter" | "openai" | "anthropic" | "ollama";
+export interface PeonConfig {
+    /** LLM provider for consolidation (+ embeddings where supported). */
+    provider: PeonProvider;
+    /** Generic API key (falls back to provider-specific env vars). */
+    llmApiKey?: string;
+    /** OpenAI-compatible chat/embeddings base URL for the provider. */
+    llmBaseUrl: string;
+    openRouterApiKey?: string;
+    processingModel: string;
+    embeddingModel?: string;
+    embeddingMode: "off" | "local" | "api" | "ollama";
+    /** Ollama server for local semantic embeddings (embeddingMode "ollama"). */
+    ollamaBaseUrl?: string;
+    memoryDirName: string;
+    flushMinChars: number;
+    aiMode: "off" | "gated";
+}
+type Env = Record<string, string | undefined>;
+export declare function loadPeonConfig(env?: Env): PeonConfig;
+export declare function readEnvFile(startDir?: string): Env;
+export {};

package/dist/config.js

@@ -0,0 +1,99 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, parse } from "node:path";
+function optional(value) {
+    return value && value.trim() ? value.trim() : undefined;
+}
+function numberFromEnv(value, fallback) {
+    if (!value)
+        return fallback;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+function resolveEmbeddingMode(explicit, caps) {
+    const normalized = explicit?.trim().toLowerCase();
+    if (normalized === "off" || normalized === "api" || normalized === "local" || normalized === "ollama")
+        return normalized;
+    // No explicit mode: prefer REAL semantic embeddings when an API key + embedding
+    // model are configured; otherwise fall back to the deterministic local lexical
+    // (character-trigram) embeddings so retrieval still works fully offline.
+    return caps.hasKey && caps.hasModel ? "api" : "local";
+}
+const PROVIDER_BASE_URLS = {
+    openrouter: "https://openrouter.ai/api/v1",
+    openai: "https://api.openai.com/v1",
+    anthropic: "https://api.anthropic.com",
+    ollama: "http://127.0.0.1:11434/v1" // Ollama's OpenAI-compatible endpoint
+};
+const PROVIDER_DEFAULT_MODELS = {
+    openrouter: "google/gemini-2.5-flash-lite",
+    openai: "gpt-4o-mini",
+    anthropic: "claude-haiku-4-5-20251001",
+    ollama: "llama3.2"
+};
+function resolveProvider(mergedEnv) {
+    const explicit = mergedEnv.PEON_PROVIDER?.trim().toLowerCase();
+    if (explicit === "openrouter" || explicit === "openai" || explicit === "anthropic" || explicit === "ollama")
+        return explicit;
+    if (mergedEnv.OPENROUTER_API_KEY)
+        return "openrouter";
+    if (mergedEnv.OPENAI_API_KEY)
+        return "openai";
+    if (mergedEnv.ANTHROPIC_API_KEY)
+        return "anthropic";
+    return "openrouter"; // default; without a key the cost gate simply never opens
+}
+export function loadPeonConfig(env = process.env) {
+    const mergedEnv = env === process.env ? { ...readEnvFile(), ...env } : env;
+    const provider = resolveProvider(mergedEnv);
+    const llmApiKey = optional(mergedEnv.PEON_API_KEY) ??
+        optional(mergedEnv.OPENROUTER_API_KEY) ?? optional(mergedEnv.OPENAI_API_KEY) ?? optional(mergedEnv.ANTHROPIC_API_KEY);
+    const openRouterApiKey = provider === "openrouter" ? (optional(mergedEnv.OPENROUTER_API_KEY) ?? llmApiKey) : optional(mergedEnv.OPENROUTER_API_KEY);
+    const embeddingModel = optional(mergedEnv.PEON_EMBEDDING_MODEL);
+    return {
+        provider,
+        llmApiKey,
+        llmBaseUrl: optional(mergedEnv.PEON_LLM_BASE_URL) ?? PROVIDER_BASE_URLS[provider],
+        openRouterApiKey,
+        processingModel: mergedEnv.PEON_PROCESSING_MODEL ?? mergedEnv.PEON_SUMMARY_MODEL ?? PROVIDER_DEFAULT_MODELS[provider],
+        embeddingModel,
+        embeddingMode: resolveEmbeddingMode(mergedEnv.PEON_EMBEDDING_MODE, {
+            hasKey: Boolean(openRouterApiKey),
+            hasModel: Boolean(embeddingModel)
+        }),
+        ollamaBaseUrl: optional(mergedEnv.PEON_OLLAMA_URL),
+        memoryDirName: mergedEnv.PEON_MEMORY_DIR ?? ".peon",
+        flushMinChars: numberFromEnv(mergedEnv.PEON_FLUSH_MIN_CHARS, 6000),
+        aiMode: mergedEnv.PEON_AI_MODE === "off" ? "off" : "gated"
+    };
+}
+export function readEnvFile(startDir = process.cwd()) {
+    const envPath = findEnvFile(startDir);
+    if (!envPath)
+        return {};
+    return Object.fromEntries(readFileSync(envPath, "utf8")
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line && !line.startsWith("#"))
+        .map((line) => {
+        const equalsIndex = line.indexOf("=");
+        if (equalsIndex < 0)
+            return undefined;
+        const key = line.slice(0, equalsIndex).trim();
+        const rawValue = line.slice(equalsIndex + 1).trim();
+        const value = rawValue.replace(/^['"]|['"]$/g, "");
+        return key ? [key, value] : undefined;
+    })
+        .filter((entry) => Boolean(entry)));
+}
+function findEnvFile(startDir) {
+    let current = startDir;
+    const root = parse(current).root;
+    while (true) {
+        const candidate = join(current, ".env");
+        if (existsSync(candidate))
+            return candidate;
+        if (current === root)
+            return undefined;
+        current = dirname(current);
+    }
+}

package/dist/daemon-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/daemon-cli.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { startPeonDaemon } from "./daemon.js";
+const host = process.env.PEON_DAEMON_HOST ?? "127.0.0.1";
+const parsedPort = Number.parseInt(process.env.PEON_DAEMON_PORT ?? "3737", 10);
+const port = Number.isFinite(parsedPort) ? parsedPort : 3737;
+/** True if a healthy Peon daemon already answers on this host:port. */
+async function daemonAlreadyHealthy() {
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 1000);
+        const response = await fetch(`http://${host}:${port}/health`, { signal: controller.signal });
+        clearTimeout(timer);
+        if (!response.ok)
+            return false;
+        const body = (await response.json());
+        return body?.service === "peon-daemon";
+    }
+    catch {
+        return false;
+    }
+}
+// Single-owner: if a healthy daemon is already running (e.g. spawned by the MCP
+// client), attach to it instead of fighting over the port and crashing.
+if (await daemonAlreadyHealthy()) {
+    process.stderr.write(`Peon daemon already running on http://${host}:${port} — attaching.\n`);
+    process.exit(0);
+}
+let daemon;
+try {
+    daemon = await startPeonDaemon({ host, port });
+}
+catch (error) {
+    // Lost a start race (another daemon bound the port between our health check and
+    // listen). If it's now healthy, that's fine — attach. Otherwise surface the error.
+    if (isAddrInUse(error) && (await daemonAlreadyHealthy())) {
+        process.stderr.write(`Peon daemon already running on http://${host}:${port} — attaching.\n`);
+        process.exit(0);
+    }
+    throw error;
+}
+process.stderr.write(`Peon daemon listening on ${daemon.url}\n`);
+function isAddrInUse(error) {
+    return Boolean(error && typeof error === "object" && error.code === "EADDRINUSE");
+}
+async function shutdown() {
+    await daemon.close();
+    process.exit(0);
+}
+process.on("SIGINT", () => {
+    void shutdown();
+});
+process.on("SIGTERM", () => {
+    void shutdown();
+});

package/dist/daemon.d.ts

@@ -0,0 +1,23 @@
+export interface StartPeonDaemonOptions {
+    host?: string;
+    port?: number;
+    logDir?: string;
+    globalMemoryDir?: string;
+}
+export interface PeonDaemonHandle {
+    host: string;
+    port: number;
+    url: string;
+    close(): Promise<void>;
+}
+/**
+ * Resolve any path to its ONE project brain: collapse git-worktree paths to the repo root, then
+ * climb ancestors (bounded by home). A `.peon/root` marker declares a brain BOUNDARY — the nearest
+ * one wins and the climb stops there, so a big sub-project (e.g. a thesis folder) keeps its OWN
+ * brain instead of being swallowed by the parent. With no marker anywhere the behaviour is
+ * unchanged: climb to the TOPMOST `.peon` (unify stray subfolders onto the root brain). Applied at
+ * the daemon boundary so EVERY caller (Claude hook, direct MCP, Codex) resolves a path identically
+ * — not just the hook. Mirrors resolveProjectPath() in scripts/claude-peon-hook.mjs.
+ */
+export declare function canonicalProjectPath(projectPath: string, home?: string): string;
+export declare function startPeonDaemon(options?: StartPeonDaemonOptions): Promise<PeonDaemonHandle>;