peon-mem 1.0.0

package/dist/global-promotion.d.ts

@@ -0,0 +1,25 @@
+import type { MemoryRecord, MemoryType } from "./types.js";
+/**
+ * Auto-promotion policy: which project beliefs should also live in GLOBAL memory
+ * so any project can recall them, not just the one that learned them.
+ *
+ * The bar is deliberately high to keep project isolation the default (a locked
+ * product decision). Only two things cross the line:
+ *   1. Records the processor (or a human) explicitly scoped "global" — the
+ *      AI's own judgment that knowledge is cross-cutting (infra, environment,
+ *      external services, reusable references like cluster docs).
+ *   2. `fact` records — facts about the user/environment/tooling are
+ *      cross-cutting by nature.
+ *
+ * Project-internal noise (decisions about THIS repo, file artifacts, timeline
+ * events, project-specific preferences) intentionally stays project-scoped.
+ */
+export declare const DEFAULT_PROMOTABLE_TYPES: readonly MemoryType[];
+export interface PromotionPolicy {
+    /** Types always promoted regardless of explicit scope. */
+    promotableTypes?: readonly MemoryType[];
+}
+/** A pure predicate — true if this record should be copied into global memory. */
+export declare function isGloballyPromotable(record: MemoryRecord, policy?: PromotionPolicy): boolean;
+/** Select the subset of project records that should be promoted to global memory. */
+export declare function selectGloballyPromotable(records: readonly MemoryRecord[], policy?: PromotionPolicy): MemoryRecord[];

package/dist/global-promotion.js

@@ -0,0 +1,29 @@
+/**
+ * Auto-promotion policy: which project beliefs should also live in GLOBAL memory
+ * so any project can recall them, not just the one that learned them.
+ *
+ * The bar is deliberately high to keep project isolation the default (a locked
+ * product decision). Only two things cross the line:
+ *   1. Records the processor (or a human) explicitly scoped "global" — the
+ *      AI's own judgment that knowledge is cross-cutting (infra, environment,
+ *      external services, reusable references like cluster docs).
+ *   2. `fact` records — facts about the user/environment/tooling are
+ *      cross-cutting by nature.
+ *
+ * Project-internal noise (decisions about THIS repo, file artifacts, timeline
+ * events, project-specific preferences) intentionally stays project-scoped.
+ */
+export const DEFAULT_PROMOTABLE_TYPES = ["fact"];
+/** A pure predicate — true if this record should be copied into global memory. */
+export function isGloballyPromotable(record, policy = {}) {
+    if (record.status !== "active")
+        return false;
+    if (record.scope === "global")
+        return true;
+    const types = policy.promotableTypes ?? DEFAULT_PROMOTABLE_TYPES;
+    return types.includes(record.type);
+}
+/** Select the subset of project records that should be promoted to global memory. */
+export function selectGloballyPromotable(records, policy = {}) {
+    return records.filter((record) => isGloballyPromotable(record, policy));
+}

package/dist/hyde.d.ts

@@ -0,0 +1,31 @@
+import type { PeonConfig } from "./config.js";
+import type { FetchLike } from "./reranker.js";
+/**
+ * HyDE — Hypothetical Document Embeddings (Gao et al., 2022).
+ *
+ * A short, vague query ("how do we handle retries?") often shares few tokens — and little
+ * embedding mass — with the belief that actually answers it ("Route webhook retries through
+ * the durable queue with exponential backoff"). HyDE closes that gap: a small LLM writes a
+ * HYPOTHETICAL answer to the query, and we retrieve against THAT richer text instead of the
+ * bare query. The hypothetical may be factually wrong — it doesn't matter; its job is to land
+ * in the right neighborhood of the embedding/lexical space so the real, stored answer ranks up.
+ *
+ * We return an EXPANDED query = original query + hypothetical. Keeping the original terms means
+ * lexical matching stays anchored on what the user literally asked, while the hypothetical adds
+ * the vocabulary and semantic signal that pure query embedding lacks. Opt-in and fail-safe:
+ * with no API key, AI disabled, or any error, it returns the original query untouched.
+ */
+export interface HydeOptions {
+    config: PeonConfig;
+    model?: string;
+    fetchImpl?: FetchLike;
+    /** Cap on the generated hypothetical (keeps prompt cost and noise down). Default 320. */
+    maxChars?: number;
+}
+export interface HydeResult {
+    /** original + hypothetical, for use as the retrieval query. Equals original on any failure. */
+    expanded: string;
+    /** the generated hypothetical answer alone (empty if generation was skipped/failed). */
+    hypothetical: string;
+}
+export declare function expandQuery(query: string | undefined, options: HydeOptions): Promise<HydeResult>;

package/dist/hyde.js

@@ -0,0 +1,46 @@
+const DEFAULT_MAX_CHARS = 320;
+export async function expandQuery(query, options) {
+    const q = (query ?? "").trim();
+    if (!q)
+        return { expanded: "", hypothetical: "" };
+    const { config } = options;
+    if (config.aiMode === "off" || !config.openRouterApiKey)
+        return { expanded: q, hypothetical: "" };
+    const doFetch = options.fetchImpl ?? globalThis.fetch;
+    if (!doFetch)
+        return { expanded: q, hypothetical: "" };
+    const maxChars = Math.max(80, Math.trunc(options.maxChars ?? DEFAULT_MAX_CHARS));
+    const system = "You write a brief HYPOTHETICAL answer used only to improve memory retrieval. " +
+        "Given a question, write 1-3 plausible sentences that such an answer might contain, " +
+        "using concrete, specific vocabulary (entities, file names, decisions, values). " +
+        "Do not hedge, do not say you lack context, do not ask questions. Output the sentences only.";
+    const user = `Question: ${q}\n\nHypothetical answer:`;
+    try {
+        const response = await doFetch("https://openrouter.ai/api/v1/chat/completions", {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${config.openRouterApiKey}`,
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+                model: options.model ?? config.processingModel,
+                messages: [
+                    { role: "system", content: system },
+                    { role: "user", content: user }
+                ],
+                temperature: 0.3
+            })
+        });
+        if (!response.ok)
+            return { expanded: q, hypothetical: "" };
+        const json = (await response.json());
+        const raw = (json.choices?.[0]?.message?.content ?? "").replace(/\s+/g, " ").trim();
+        if (!raw)
+            return { expanded: q, hypothetical: "" };
+        const hypothetical = raw.length > maxChars ? `${raw.slice(0, maxChars - 1)}…` : raw;
+        return { expanded: `${q}\n${hypothetical}`, hypothetical };
+    }
+    catch {
+        return { expanded: q, hypothetical: "" };
+    }
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { createPeonTools } from "./tools.js";
+const tools = createPeonTools({ daemonUrl: process.env.PEON_DAEMON_URL });
+const server = new McpServer({
+    name: "peon-mcp",
+    version: "0.1.0"
+});
+const projectName = (path) => path.split("/").filter(Boolean).pop() ?? "project";
+/**
+ * Compact text for the model. The internal tool results carry redundant fields
+ * (normalized index text, duplicated record arrays, per-reason breakdowns) that
+ * would otherwise flood the calling model's context — a single recall could cost
+ * thousands of tokens. These formatters return only what an AI needs to read.
+ */
+function compactContext(ctx) {
+    const sections = [
+        ["Summary", ctx.summary],
+        ["Memory", ctx.memories],
+        ["Decisions", ctx.decisions],
+        ["Preferences", ctx.preferences],
+        ["Open questions", ctx.openQuestions],
+        ["Artifacts", ctx.artifacts],
+        ["Timeline", ctx.timeline]
+    ];
+    const body = sections
+        .filter(([, value]) => value && value.trim())
+        .map(([label, value]) => `## ${label}\n${value.trim()}`)
+        .join("\n\n");
+    return body || "No memory recorded for this project yet.";
+}
+function compactSearch(result) {
+    return result.injectionPreview?.trim() || `No memory matched "${result.query}".`;
+}
+function compactBrain(result) {
+    const counts = {};
+    for (const record of result.records)
+        counts[record.status] = (counts[record.status] ?? 0) + 1;
+    const status = Object.entries(counts).map(([k, v]) => `${v} ${k}`).join(", ") || "no records";
+    const head = `Peon brain — ${projectName(result.projectPath)} (${status}; ${result.graph.nodes.length} graph nodes)`;
+    return `${head}\n\n${result.injectionPreview?.trim() || compactContext(result.context)}`;
+}
+function compactCrossProject(result) {
+    if (result.results.length === 0) {
+        return `No relevant beliefs found in other projects for "${result.query}" (searched ${result.projectsSearched.length}).`;
+    }
+    const lines = result.results.map((hit) => `- [${hit.projectName} · ${hit.record.type}] ${hit.record.content}`);
+    return `Recall across projects for "${result.query}" (searched ${result.projectsSearched.length}):\n${lines.join("\n")}`;
+}
+server.registerTool("start_session", {
+    title: "Start Peon Session",
+    description: "Start a Peon memory session for a project.",
+    inputSchema: {
+        projectPath: z.string(),
+        client: z.string(),
+        cwd: z.string().optional()
+    }
+}, async (input) => ({
+    content: [{ type: "text", text: JSON.stringify(await tools.startSession(input), null, 2) }]
+}));
+server.registerTool("record_message", {
+    title: "Record Message",
+    description: "Record a user, assistant, or system message into Peon memory.",
+    inputSchema: {
+        sessionId: z.string(),
+        role: z.enum(["user", "assistant", "system"]),
+        content: z.string()
+    }
+}, async (input) => ({
+    content: [{ type: "text", text: JSON.stringify(await tools.recordMessage(input), null, 2) }]
+}));
+server.registerTool("record_event", {
+    title: "Record Event",
+    description: "Record a structured Peon memory event such as a decision or preference.",
+    inputSchema: {
+        sessionId: z.string(),
+        type: z.string(),
+        content: z.string()
+    }
+}, async (input) => ({
+    content: [{ type: "text", text: JSON.stringify(await tools.recordEvent(input), null, 2) }]
+}));
+server.registerTool("end_session", {
+    title: "End Peon Session",
+    description: "End a Peon session and update brain files.",
+    inputSchema: { sessionId: z.string() }
+}, async (input) => ({
+    content: [{ type: "text", text: JSON.stringify(await tools.endSession(input), null, 2) }]
+}));
+server.registerTool("get_context", {
+    title: "Get Peon Context",
+    description: "Return project brain context from Peon memory.",
+    inputSchema: {
+        projectPath: z.string(),
+        query: z.string().optional(),
+        maxChars: z.number().optional()
+    }
+}, async (input) => ({
+    content: [{ type: "text", text: compactContext(await tools.getContext(input)) }]
+}));
+server.registerTool("inspect_brain", {
+    title: "Inspect Peon Brain",
+    description: "Return a compact summary of a project's brain: record counts by status and the prompt injection preview.",
+    inputSchema: {
+        projectPath: z.string(),
+        query: z.string().optional(),
+        maxChars: z.number().optional()
+    }
+}, async (input) => ({
+    content: [{ type: "text", text: compactBrain(await tools.inspectBrain(input)) }]
+}));
+server.registerTool("search_memory", {
+    title: "Search Peon Memory",
+    description: "Search structured Peon memory; returns a compact ranked list with one-line reasons.",
+    inputSchema: {
+        projectPath: z.string(),
+        query: z.string(),
+        limit: z.number().optional(),
+        maxChars: z.number().optional()
+    }
+}, async (input) => ({
+    content: [{ type: "text", text: compactSearch(await tools.searchMemory(input)) }]
+}));
+server.registerTool("quality_report", {
+    title: "Peon Quality Report",
+    description: "Inspect Peon memory quality signals: duplicates, conflicts, stale records, and promotions.",
+    inputSchema: {
+        projectPath: z.string(),
+        staleAfterDays: z.number().optional()
+    }
+}, async (input) => ({
+    content: [{ type: "text", text: JSON.stringify(await tools.qualityReport(input), null, 2) }]
+}));
+server.registerTool("build_injection", {
+    title: "Build Peon Context Injection",
+    description: "Build a redacted context injection from project and global memory with selection explanations.",
+    inputSchema: {
+        projectPath: z.string(),
+        query: z.string().optional(),
+        maxChars: z.number().optional(),
+        includeInactive: z.boolean().optional()
+    }
+}, async (input) => ({
+    content: [{ type: "text", text: JSON.stringify(await tools.buildInjection(input), null, 2) }]
+}));
+server.registerTool("query_projects", {
+    title: "Recall Across Projects",
+    description: "Recall relevant beliefs from OTHER Peon projects on demand. Peon memory is isolated per project by default; call this when the user explicitly asks about another project (e.g. 'what did we decide in project Y about auth?'). Omit projectPath to search every known project; pass it to target one. Set excludeProjectPath to the current project so you only get other projects' beliefs.",
+    inputSchema: {
+        query: z.string(),
+        projectPath: z.string().optional(),
+        excludeProjectPath: z.string().optional(),
+        limit: z.number().optional()
+    }
+}, async (input) => ({
+    content: [
+        {
+            type: "text",
+            text: compactCrossProject(await tools.crossProjectSearch({
+                query: input.query,
+                projectPaths: input.projectPath ? [input.projectPath] : undefined,
+                excludeProjectPath: input.excludeProjectPath,
+                limit: input.limit
+            }))
+        }
+    ]
+}));
+server.registerTool("remember_global", {
+    title: "Remember Global Memory",
+    description: "Upsert a global Peon memory record for cross-project reuse.",
+    inputSchema: {
+        memory: z.object({
+            type: z.enum(["summary", "decision", "preference", "open_question", "artifact", "timeline", "fact"]),
+            content: z.string(),
+            scope: z.enum(["project", "global", "session"]).optional(),
+            importance: z.number().optional(),
+            confidence: z.number().optional(),
+            entities: z.array(z.string()).optional(),
+            status: z.enum(["active", "stale", "conflicted"]).optional()
+        }),
+        source: z
+            .object({
+            kind: z.enum(["ai_processing", "manual", "hook"]).optional(),
+            reason: z.string().optional()
+        })
+            .optional()
+    }
+}, async (input) => ({
+    content: [{ type: "text", text: JSON.stringify(await tools.rememberGlobal(input), null, 2) }]
+}));
+server.registerTool("search_global_memory", {
+    title: "Search Global Peon Memory",
+    description: "Search cross-project global Peon memory.",
+    inputSchema: {
+        query: z.string().optional(),
+        type: z.enum(["summary", "decision", "preference", "open_question", "artifact", "timeline", "fact"]).optional(),
+        status: z.enum(["active", "stale", "conflicted"]).optional()
+    }
+}, async (input) => ({
+    content: [{ type: "text", text: JSON.stringify(await tools.searchGlobalMemory(input), null, 2) }]
+}));
+server.registerTool("import_global_memory", {
+    title: "Import Global Peon Memory",
+    description: "Import global-scoped memory records from a project brain into the global memory store.",
+    inputSchema: {
+        projectPath: z.string()
+    }
+}, async (input) => ({
+    content: [{ type: "text", text: JSON.stringify(await tools.importGlobalMemory(input), null, 2) }]
+}));
+server.registerTool("evaluate_project", {
+    title: "Evaluate Peon Project Memory",
+    description: "Evaluate recall, coverage, noise, and cost for a Peon project memory folder.",
+    inputSchema: {
+        projectPath: z.string(),
+        expectedMemories: z
+            .array(z.union([z.string(), z.object({ id: z.string().optional(), content: z.string() })]))
+            .optional()
+    }
+}, async (input) => ({
+    content: [{ type: "text", text: JSON.stringify(await tools.evaluateProject(input), null, 2) }]
+}));
+server.registerTool("process_memory", {
+    title: "Process Peon Memory",
+    description: "Run gated Peon AI processing for a project and update structured brain files.",
+    inputSchema: {
+        projectPath: z.string(),
+        reason: z.string().optional()
+    }
+}, async (input) => ({
+    content: [{ type: "text", text: JSON.stringify(await tools.processMemory(input), null, 2) }]
+}));
+server.registerTool("maybe_process_memory", {
+    title: "Maybe Process Peon Memory",
+    description: "Apply Peon's automatic cost-aware processing policy and process only when the gate says to run.",
+    inputSchema: {
+        projectPath: z.string(),
+        trigger: z.string(),
+        force: z.boolean().optional()
+    }
+}, async (input) => ({
+    content: [{ type: "text", text: JSON.stringify(await tools.maybeProcessMemory(input), null, 2) }]
+}));
+await server.connect(new StdioServerTransport());

package/dist/injection.d.ts

@@ -0,0 +1,38 @@
+import { type RankedMemoryRecord } from "./retrieval.js";
+import type { MemoryRecord, MemoryScope, MemoryStatus, MemoryType } from "./types.js";
+export interface BuildContextInjectionOptions {
+    projectResults: RankedMemoryRecord[];
+    globalRecords: MemoryRecord[];
+    query?: string;
+    maxChars: number;
+    includeInactive?: boolean;
+    now?: Date | string | number;
+}
+export interface SelectedInjectionMetadata {
+    id: string;
+    scope: MemoryScope;
+    type: MemoryType;
+    status: MemoryStatus;
+    score: number;
+    whySelected: string;
+    source: MemoryRecord["source"];
+    chars: number;
+}
+export type OmittedInjectionReason = "suppressed_status" | "max_chars";
+export interface OmittedInjectionMetadata {
+    id: string;
+    scope: MemoryScope;
+    type: MemoryType;
+    status: MemoryStatus;
+    reason: OmittedInjectionReason;
+    score: number;
+}
+export interface ContextInjection {
+    preview: string;
+    selected: SelectedInjectionMetadata[];
+    omitted: OmittedInjectionMetadata[];
+    totalChars: number;
+    maxChars: number;
+}
+export declare function buildContextInjection(options: BuildContextInjectionOptions): ContextInjection;
+export declare function redactSecrets(value: string): string;

package/dist/injection.js

@@ -0,0 +1,133 @@
+import { diversifyByMMR, rankMemoryRecords } from "./retrieval.js";
+const title = "Peon Context Injection v2";
+const emptyPreview = `${title}\nNo memory selected.`;
+export function buildContextInjection(options) {
+    const maxChars = Math.max(0, Math.trunc(options.maxChars));
+    const includeInactive = options.includeInactive === true;
+    const projectResults = options.projectResults.map((item, originIndex) => ({ item, originIndex }));
+    const globalResults = rankMemoryRecords(options.globalRecords, options.query, { now: options.now }).map((item, originIndex) => ({
+        item,
+        originIndex: projectResults.length + originIndex
+    }));
+    const omitted = [];
+    const relevant = [...projectResults, ...globalResults]
+        .filter((candidate) => {
+        if (includeInactive || candidate.item.record.status === "active")
+            return true;
+        omitted.push(omittedMetadata(candidate.item, "suppressed_status"));
+        return false;
+    })
+        .sort(compareCandidates);
+    // Diversify (MMR) so the block has coverage, not N paraphrases of the top hit.
+    // We reorder the relevance-sorted candidates by the diversified order of their records.
+    const diversified = diversifyByMMR(relevant.map((c) => c.item));
+    const orderOf = new Map(diversified.map((item, i) => [item, i]));
+    const candidates = relevant.slice().sort((a, b) => (orderOf.get(a.item) ?? 0) - (orderOf.get(b.item) ?? 0));
+    const selected = [];
+    const lines = [title];
+    let preview = lines.join("\n");
+    for (const candidate of candidates) {
+        const block = formatCandidate(candidate.item);
+        const nextPreview = `${preview}\n${block}`;
+        if (nextPreview.length > maxChars) {
+            omitted.push(omittedMetadata(candidate.item, "max_chars"));
+            continue;
+        }
+        preview = nextPreview;
+        selected.push(selectedMetadata(candidate.item, block.length));
+    }
+    if (selected.length === 0 && emptyPreview.length <= maxChars) {
+        preview = emptyPreview;
+    }
+    if (preview.length > maxChars) {
+        preview = preview.slice(0, maxChars);
+    }
+    return {
+        preview,
+        selected,
+        omitted,
+        totalChars: preview.length,
+        maxChars
+    };
+}
+function compareCandidates(left, right) {
+    const scoreDelta = injectionScore(right.item) - injectionScore(left.item);
+    if (scoreDelta !== 0)
+        return scoreDelta;
+    const updatedDelta = timestamp(right.item.record.updatedAt) - timestamp(left.item.record.updatedAt);
+    if (updatedDelta !== 0)
+        return updatedDelta;
+    return left.originIndex - right.originIndex;
+}
+function injectionScore(item) {
+    if (item.record.status === "stale")
+        return item.score - 4;
+    if (item.record.status === "conflicted")
+        return item.score - 1;
+    return item.score;
+}
+function formatCandidate(item) {
+    const record = item.record;
+    const statusSuffix = record.status === "active" ? "" : ` status: ${record.status}`;
+    return [
+        `- [${record.scope}:${record.type}] ${redactSecrets(record.content)}${statusSuffix}`,
+        `  why: ${redactSecrets(whySelected(item))}`
+    ].join("\n");
+}
+function selectedMetadata(item, chars) {
+    return {
+        id: item.record.id,
+        scope: item.record.scope,
+        type: item.record.type,
+        status: item.record.status,
+        score: item.score,
+        whySelected: redactSecrets(whySelected(item)),
+        source: item.record.source,
+        chars
+    };
+}
+function omittedMetadata(item, reason) {
+    return {
+        id: item.record.id,
+        scope: item.record.scope,
+        type: item.record.type,
+        status: item.record.status,
+        reason,
+        score: item.score
+    };
+}
+function whySelected(item) {
+    if (item.explanation.trim().length > 0)
+        return item.explanation.trim();
+    const positiveReasons = item.reasons.filter((reason) => reason.score > 0);
+    if (positiveReasons.length > 0)
+        return positiveReasons.map(formatReason).join("; ");
+    return `score ${item.score.toFixed(3)}`;
+}
+function formatReason(reason) {
+    return reason.label;
+}
+export function redactSecrets(value) {
+    return value
+        // Anthropic (must run before the generic sk- rule)
+        .replace(/\bsk-ant-[A-Za-z0-9_-]{16,}/g, "sk-ant-[REDACTED]")
+        // OpenAI (sk-, sk-proj-, sk-live-, …)
+        .replace(/\bsk-(?:proj-|live-|test-)?[A-Za-z0-9_-]{16,}/g, "sk-[REDACTED]")
+        // GitHub tokens
+        .replace(/\b(gh[pousr]_[A-Za-z0-9_]{8,})\b/g, "[REDACTED]")
+        // AWS access key id
+        .replace(/\bAKIA[0-9A-Z]{16}\b/g, "AKIA[REDACTED]")
+        // Google API key
+        .replace(/\bAIza[0-9A-Za-z_-]{20,}\b/g, "AIza[REDACTED]")
+        // JWTs (header.payload.signature)
+        .replace(/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]+/g, "[REDACTED_JWT]")
+        // Bearer tokens
+        .replace(/\b(Bearer\s+)[A-Za-z0-9._-]{12,}/gi, "$1[REDACTED]")
+        // Generic NAME=secret / NAME: secret for *_KEY/*_TOKEN/*_SECRET/PASSWORD/API_KEY (the \b before
+        // the name is dropped so FOO_API_KEY=… with a leading underscore still matches)
+        .replace(/((?:[A-Za-z0-9_]*(?:api[_-]?key|token|secret|password))\s*[:=]\s*)[^\n]+/gi, "$1[REDACTED]");
+}
+function timestamp(value) {
+    const time = new Date(value).getTime();
+    return Number.isFinite(time) ? time : 0;
+}

package/dist/logger.d.ts

@@ -0,0 +1,17 @@
+export interface PeonLoggerOptions {
+    logDir?: string;
+}
+export interface PeonLogEntry {
+    id: string;
+    type: string;
+    createdAt: string;
+    [key: string]: unknown;
+}
+export declare class PeonLogger {
+    private readonly logFile;
+    private writeQueue;
+    constructor(options?: PeonLoggerOptions);
+    log(type: string, fields?: Record<string, unknown>): Promise<PeonLogEntry>;
+    recent(limit?: number): Promise<PeonLogEntry[]>;
+    private enqueueWrite;
+}

package/dist/logger.js

@@ -0,0 +1,63 @@
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const DEFAULT_LOG_DIR = join(homedir(), "Library", "Logs", "Peon");
+export class PeonLogger {
+    logFile;
+    writeQueue = Promise.resolve();
+    constructor(options = {}) {
+        this.logFile = join(options.logDir ?? DEFAULT_LOG_DIR, "daemon.jsonl");
+    }
+    async log(type, fields = {}) {
+        const entry = {
+            id: crypto.randomUUID(),
+            type,
+            createdAt: new Date().toISOString(),
+            ...sanitize(fields)
+        };
+        await this.enqueueWrite(`${JSON.stringify(entry)}\n`);
+        return entry;
+    }
+    async recent(limit = 100) {
+        const raw = await readFile(this.logFile, "utf8").catch(() => "");
+        return raw
+            .trim()
+            .split("\n")
+            .filter(Boolean)
+            .slice(-limit)
+            .reverse()
+            .flatMap((line) => {
+            try {
+                return [JSON.parse(line)];
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+    async enqueueWrite(line) {
+        const write = async () => {
+            try {
+                await mkdir(this.logFile.slice(0, this.logFile.lastIndexOf("/")), { recursive: true });
+                await appendFile(this.logFile, line, "utf8");
+            }
+            catch {
+                // Best-effort logging: a log write failure must never crash the daemon
+                // or reject a request handler.
+            }
+        };
+        this.writeQueue = this.writeQueue.then(write);
+        return this.writeQueue;
+    }
+}
+function sanitize(fields) {
+    return Object.fromEntries(Object.entries(fields).map(([key, value]) => {
+        if (key.toLowerCase().includes("key") || key.toLowerCase().includes("authorization")) {
+            return [key, "[redacted]"];
+        }
+        if (typeof value === "string" && value.length > 1200) {
+            return [key, `${value.slice(0, 1200)}...`];
+        }
+        return [key, value];
+    }));
+}

package/dist/memory-mutations.d.ts

@@ -0,0 +1,24 @@
+import type { MemoryRecord, MemoryStatus } from "./types.js";
+/**
+ * Pure, in-memory transforms over a belief set. The store wraps these with
+ * read + replaceMemoryRecords so the curation logic stays testable in isolation.
+ */
+export interface MemoryPatch {
+    content?: string;
+    importance?: number;
+    confidence?: number;
+    status?: MemoryStatus;
+    pinned?: boolean;
+}
+/** Edit a belief's content/scores/status/pin. Unknown id → unchanged array. */
+export declare function applyUpdate(records: readonly MemoryRecord[], id: string, patch: MemoryPatch, now: string): MemoryRecord[];
+/** Remove a belief outright. */
+export declare function applyDelete(records: readonly MemoryRecord[], id: string): MemoryRecord[];
+/** Pin/unpin a belief — pinned beliefs are protected and rank first. */
+export declare function applyPin(records: readonly MemoryRecord[], id: string, pinned: boolean, now: string): MemoryRecord[];
+/**
+ * Fold `dropId` into `keepId`: union the entities, take the higher importance and
+ * confidence, OR the pin flag, then remove the dropped record. Either id missing
+ * → unchanged array (no partial merge).
+ */
+export declare function applyMerge(records: readonly MemoryRecord[], keepId: string, dropId: string, now: string): MemoryRecord[];