pi-honcho-memory 0.1.0

package/extensions/config.ts

@@ -0,0 +1,307 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir, userInfo } from "node:os";
+import { dirname, join } from "node:path";
+
+export type SessionStrategy = "per-directory" | "git-branch" | "pi-session" | "per-repo" | "global";
+export type RecallMode = "hybrid" | "context" | "tools";
+export type ReasoningLevel = "minimal" | "low" | "medium" | "high" | "max";
+export type WriteFrequency = "async" | "turn" | "session";
+export type InjectionFrequency = "every-turn" | "first-turn";
+export type ObservationMode = "directional" | "unified";
+
+export interface PiHostConfig {
+  workspace: string;
+  aiPeer: string;
+  linkedHosts?: string[];
+  endpoint?: string;
+  sessionStrategy?: SessionStrategy;
+  recallMode?: RecallMode;
+  contextTokens?: number;
+  contextRefreshTtlSeconds?: number;
+  maxMessageLength?: number;
+  searchLimit?: number;
+  toolPreviewLength?: number;
+  observeMe?: boolean;
+  observeOthers?: boolean;
+  aiObserveMe?: boolean;
+  aiObserveOthers?: boolean;
+  reasoningLevel?: ReasoningLevel;
+  contextInjectionInterval?: number;
+  // Phase 1 additions
+  saveMessages?: boolean;
+  writeFrequency?: WriteFrequency | number;
+  dialecticDynamic?: boolean;
+  dialecticMaxChars?: number;
+  dialecticMaxInputChars?: number;
+  sessionPeerPrefix?: boolean;
+  observationMode?: ObservationMode;
+  injectionFrequency?: InjectionFrequency;
+  contextCadence?: number;
+  dialecticCadence?: number;
+  reasoningLevelCap?: ReasoningLevel;
+  environment?: "local" | "production";
+  logging?: boolean;
+}
+
+export interface HonchoConfigFile {
+  apiKey?: string;
+  peerName?: string;
+  baseUrl?: string;
+  sessions?: Record<string, string>;
+  globalOverride?: boolean;
+  contextRefresh?: { messageThreshold?: number };
+  logging?: boolean;
+  hosts?: {
+    pi?: Partial<PiHostConfig>;
+  };
+}
+
+export interface HonchoConfig {
+  enabled: boolean;
+  apiKey?: string;
+  peerName: string;
+  baseURL?: string;
+  workspace: string;
+  aiPeer: string;
+  linkedHosts: string[];
+  sessionStrategy: SessionStrategy;
+  recallMode: RecallMode;
+  contextTokens: number;
+  contextRefreshTtlSeconds: number;
+  maxMessageLength: number;
+  searchLimit: number;
+  toolPreviewLength: number;
+  observeMe: boolean;
+  observeOthers: boolean;
+  aiObserveMe: boolean;
+  aiObserveOthers: boolean;
+  reasoningLevel: ReasoningLevel;
+  contextInjectionInterval: number;
+  // Phase 1 additions
+  saveMessages: boolean;
+  writeFrequency: WriteFrequency | number;
+  dialecticDynamic: boolean;
+  dialecticMaxChars: number;
+  dialecticMaxInputChars: number;
+  sessionPeerPrefix: boolean;
+  observationMode: ObservationMode;
+  injectionFrequency: InjectionFrequency;
+  contextCadence: number;
+  dialecticCadence: number;
+  reasoningLevelCap: ReasoningLevel | null;
+  environment: "local" | "production";
+  logging: boolean;
+  sessions: Record<string, string>;
+  contextRefreshMessageThreshold: number | null;
+}
+
+export const CONFIG_PATH = join(homedir(), ".honcho", "config.json");
+const DEFAULT_CONTEXT_TOKENS = 1200;
+const DEFAULT_CONTEXT_REFRESH_TTL_SECONDS = 300;
+const DEFAULT_MAX_MESSAGE_LENGTH = 25000;
+const DEFAULT_SEARCH_LIMIT = 8;
+const DEFAULT_TOOL_PREVIEW_LENGTH = 500;
+const DEFAULT_DIALECTIC_MAX_CHARS = 600;
+const DEFAULT_DIALECTIC_MAX_INPUT_CHARS = 10000;
+
+const toPositiveInt = (value: string | number | undefined, fallback: number): number => {
+  if (typeof value === "number" && Number.isInteger(value) && value > 0) return value;
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    if (Number.isInteger(parsed) && parsed > 0) return parsed;
+  }
+  return fallback;
+};
+
+const toBool = (value: string | boolean | undefined, fallback: boolean): boolean => {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") return value === "true";
+  return fallback;
+};
+
+export const normalizeSessionStrategy = (value: string | undefined): SessionStrategy => {
+  if (value === "per-directory" || value === "git-branch" || value === "pi-session" || value === "per-repo" || value === "global") return value;
+  return "per-directory";
+};
+
+export const normalizeRecallMode = (value: string | undefined): RecallMode => {
+  if (value === "hybrid" || value === "context" || value === "tools") return value;
+  if (value === "auto") return "hybrid";
+  return "hybrid";
+};
+
+export const normalizeReasoningLevel = (value: string | undefined): ReasoningLevel => {
+  if (value === "minimal" || value === "low" || value === "medium" || value === "high" || value === "max") return value;
+  if (value === "mid") return "medium";
+  return "low";
+};
+
+const normalizeWriteFrequency = (value: string | number | undefined): WriteFrequency | number => {
+  if (typeof value === "number" && Number.isInteger(value) && value > 0) return value;
+  if (typeof value === "string") {
+    const n = Number(value);
+    if (Number.isInteger(n) && n > 0) return n;
+    if (value === "async" || value === "turn" || value === "session") return value;
+  }
+  return "async";
+};
+
+const normalizeInjectionFrequency = (value: string | undefined): InjectionFrequency => {
+  if (value === "every-turn" || value === "first-turn") return value;
+  return "every-turn";
+};
+
+const normalizeObservationMode = (value: string | undefined): ObservationMode => {
+  if (value === "directional" || value === "unified") return value;
+  if (value === "shared") return "unified";
+  if (value === "separate" || value === "cross") return "directional";
+  return "directional";
+};
+
+export const resolveObservation = (
+  mode: ObservationMode,
+  explicit: { observeMe?: boolean; observeOthers?: boolean; aiObserveMe?: boolean; aiObserveOthers?: boolean },
+): { observeMe: boolean; observeOthers: boolean; aiObserveMe: boolean; aiObserveOthers: boolean } => {
+  const presets: Record<ObservationMode, { observeMe: boolean; observeOthers: boolean; aiObserveMe: boolean; aiObserveOthers: boolean }> = {
+    directional: { observeMe: true, observeOthers: true, aiObserveMe: true, aiObserveOthers: true },
+    unified: { observeMe: true, observeOthers: false, aiObserveMe: false, aiObserveOthers: true },
+  };
+  const base = presets[mode];
+  return {
+    observeMe: explicit.observeMe ?? base.observeMe,
+    observeOthers: explicit.observeOthers ?? base.observeOthers,
+    aiObserveMe: explicit.aiObserveMe ?? base.aiObserveMe,
+    aiObserveOthers: explicit.aiObserveOthers ?? base.aiObserveOthers,
+  };
+};
+
+let activeRecallMode: RecallMode = "hybrid";
+export const getRecallMode = (): RecallMode => activeRecallMode;
+export const setRecallMode = (mode: RecallMode): void => { activeRecallMode = mode; };
+
+export const readConfigFile = async (): Promise<HonchoConfigFile | null> => {
+  try {
+    const raw = await readFile(CONFIG_PATH, "utf8");
+    const parsed = JSON.parse(raw) as unknown;
+    return typeof parsed === "object" && parsed !== null ? (parsed as HonchoConfigFile) : null;
+  } catch {
+    return null;
+  }
+};
+
+export const resolveConfig = async (): Promise<HonchoConfig> => {
+  const file = await readConfigFile();
+  const host = file?.hosts?.pi ?? {};
+  const apiKey = process.env.HONCHO_API_KEY ?? file?.apiKey;
+  const peerName = process.env.HONCHO_PEER_NAME ?? file?.peerName ?? userInfo().username ?? "user";
+  const baseURL = process.env.HONCHO_URL ?? host.endpoint ?? file?.baseUrl;
+  const workspace = process.env.HONCHO_WORKSPACE_ID ?? host.workspace ?? "pi";
+  const aiPeer = process.env.HONCHO_AI_PEER ?? host.aiPeer ?? "pi";
+  const linkedHosts = host.linkedHosts ?? [];
+  const sessionStrategy = normalizeSessionStrategy(process.env.HONCHO_SESSION_STRATEGY ?? host.sessionStrategy);
+  const recallMode = normalizeRecallMode(process.env.HONCHO_RECALL_MODE ?? host.recallMode);
+  const contextTokens = toPositiveInt(process.env.HONCHO_CONTEXT_TOKENS ?? host.contextTokens, DEFAULT_CONTEXT_TOKENS);
+  const contextRefreshTtlSeconds = toPositiveInt(
+    process.env.HONCHO_CONTEXT_REFRESH_TTL_SECONDS ?? host.contextRefreshTtlSeconds,
+    DEFAULT_CONTEXT_REFRESH_TTL_SECONDS,
+  );
+  const maxMessageLength = toPositiveInt(
+    process.env.HONCHO_MAX_MESSAGE_LENGTH ?? host.maxMessageLength,
+    DEFAULT_MAX_MESSAGE_LENGTH,
+  );
+  const searchLimit = toPositiveInt(process.env.HONCHO_SEARCH_LIMIT ?? host.searchLimit, DEFAULT_SEARCH_LIMIT);
+  const toolPreviewLength = toPositiveInt(process.env.HONCHO_TOOL_PREVIEW_LENGTH ?? host.toolPreviewLength, DEFAULT_TOOL_PREVIEW_LENGTH);
+  const reasoningLevel = normalizeReasoningLevel(process.env.HONCHO_REASONING_LEVEL ?? host.reasoningLevel);
+  const contextInjectionInterval = toPositiveInt(process.env.HONCHO_CONTEXT_INJECTION_INTERVAL ?? host.contextInjectionInterval, 1);
+
+  // Observation: preset first, then explicit overrides
+  const obsMode = normalizeObservationMode(process.env.HONCHO_OBSERVATION_MODE ?? host.observationMode);
+  const explicitObs = {
+    observeMe: host.observeMe !== undefined ? toBool(process.env.HONCHO_OBSERVE_ME ?? host.observeMe, true) : undefined,
+    observeOthers: host.observeOthers !== undefined ? toBool(process.env.HONCHO_OBSERVE_OTHERS ?? host.observeOthers, true) : undefined,
+    aiObserveMe: host.aiObserveMe !== undefined ? toBool(process.env.HONCHO_AI_OBSERVE_ME ?? host.aiObserveMe, true) : undefined,
+    aiObserveOthers: host.aiObserveOthers !== undefined ? toBool(process.env.HONCHO_AI_OBSERVE_OTHERS ?? host.aiObserveOthers, true) : undefined,
+  };
+  const obs = resolveObservation(obsMode, explicitObs);
+
+  // Phase 1 additions
+  const saveMessages = toBool(process.env.HONCHO_SAVE_MESSAGES ?? host.saveMessages, true);
+  const writeFrequency = normalizeWriteFrequency(process.env.HONCHO_WRITE_FREQUENCY ?? host.writeFrequency);
+  const dialecticDynamic = toBool(process.env.HONCHO_DIALECTIC_DYNAMIC ?? host.dialecticDynamic, true);
+  const dialecticMaxChars = toPositiveInt(process.env.HONCHO_DIALECTIC_MAX_CHARS ?? host.dialecticMaxChars, DEFAULT_DIALECTIC_MAX_CHARS);
+  const dialecticMaxInputChars = toPositiveInt(process.env.HONCHO_DIALECTIC_MAX_INPUT_CHARS ?? host.dialecticMaxInputChars, DEFAULT_DIALECTIC_MAX_INPUT_CHARS);
+  const sessionPeerPrefix = toBool(process.env.HONCHO_SESSION_PEER_PREFIX ?? host.sessionPeerPrefix, false);
+  const injectionFrequency = normalizeInjectionFrequency(process.env.HONCHO_INJECTION_FREQUENCY ?? host.injectionFrequency);
+  const contextCadence = toPositiveInt(process.env.HONCHO_CONTEXT_CADENCE ?? host.contextCadence, 1);
+  const dialecticCadence = toPositiveInt(process.env.HONCHO_DIALECTIC_CADENCE ?? host.dialecticCadence, 1);
+  const reasoningLevelCapRaw = process.env.HONCHO_REASONING_LEVEL_CAP ?? host.reasoningLevelCap;
+  const reasoningLevelCap = reasoningLevelCapRaw ? normalizeReasoningLevel(reasoningLevelCapRaw) : null;
+  const envRaw = process.env.HONCHO_ENVIRONMENT ?? host.environment ?? "production";
+  const environment: "local" | "production" = envRaw === "local" ? "local" : "production";
+  const logging = toBool(process.env.HONCHO_LOGGING ?? file?.logging, true);
+  const sessions = file?.sessions ?? {};
+  const contextRefreshMessageThreshold = file?.contextRefresh?.messageThreshold ?? null;
+
+  const enabled = (process.env.HONCHO_ENABLED ? process.env.HONCHO_ENABLED === "true" : Boolean(apiKey || baseURL));
+
+  return {
+    enabled,
+    apiKey,
+    peerName,
+    baseURL,
+    workspace,
+    aiPeer,
+    linkedHosts,
+    sessionStrategy,
+    recallMode,
+    contextTokens,
+    contextRefreshTtlSeconds,
+    maxMessageLength,
+    searchLimit,
+    toolPreviewLength,
+    ...obs,
+    observationMode: obsMode,
+    reasoningLevel,
+    contextInjectionInterval,
+    saveMessages,
+    writeFrequency,
+    dialecticDynamic,
+    dialecticMaxChars,
+    dialecticMaxInputChars,
+    sessionPeerPrefix,
+    injectionFrequency,
+    contextCadence,
+    dialecticCadence,
+    reasoningLevelCap,
+    environment,
+    logging,
+    sessions,
+    contextRefreshMessageThreshold,
+  };
+};
+
+export const saveConfig = async (input: {
+  apiKey?: string;
+  peerName?: string;
+  workspace?: string;
+  aiPeer?: string;
+  endpoint?: string;
+  linkedHosts?: string[];
+  sessionStrategy?: SessionStrategy;
+}): Promise<void> => {
+  const current = (await readConfigFile()) ?? {};
+  const next: HonchoConfigFile = { ...current };
+  if (input.apiKey) next.apiKey = input.apiKey;
+  if (input.peerName) next.peerName = input.peerName;
+
+  const pi: Partial<PiHostConfig> = { ...(current.hosts?.pi ?? {}) };
+  if (input.workspace) pi.workspace = input.workspace;
+  if (input.aiPeer) pi.aiPeer = input.aiPeer;
+  if (input.endpoint) pi.endpoint = input.endpoint;
+  if (input.linkedHosts) pi.linkedHosts = input.linkedHosts;
+  if (input.sessionStrategy) pi.sessionStrategy = input.sessionStrategy;
+  next.hosts = { ...(current.hosts ?? {}), pi };
+
+  await mkdir(dirname(CONFIG_PATH), { recursive: true, mode: 0o700 });
+  await writeFile(CONFIG_PATH, `${JSON.stringify(next, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+};

package/extensions/context.ts

@@ -0,0 +1,107 @@
+import type { HonchoHandles } from "./client.js";
+
+interface CachedContext {
+  profile: string | null;
+  aiProfile: string | null;
+  peerCard: string[] | null;
+  aiCard: string[] | null;
+  summary: string | null;
+  refreshedAt: number | null;
+  pinned: boolean;
+}
+
+const EMPTY: CachedContext = { profile: null, aiProfile: null, peerCard: null, aiCard: null, summary: null, refreshedAt: null, pinned: false };
+let cachedContext: CachedContext = EMPTY;
+let messagesSinceRefresh = 0;
+
+const normalize = (value?: string | null): string | null => {
+  if (!value) return null;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+};
+
+const normalizeCard = (card: unknown): string[] | null => {
+  if (!Array.isArray(card)) return null;
+  const items = card.filter((c): c is string => typeof c === "string" && c.trim().length > 0);
+  return items.length > 0 ? items : null;
+};
+
+export const clearCachedContext = (): void => {
+  cachedContext = EMPTY;
+  messagesSinceRefresh = 0;
+};
+
+export const incrementMessageCount = (count: number): void => {
+  messagesSinceRefresh += count;
+};
+
+export const refreshCachedContext = async (handles: HonchoHandles): Promise<void> => {
+  if (!handles.session) return;
+  try {
+    const [userCtx, aiCtx] = await Promise.all([
+      handles.session.context({
+        summary: true,
+        peerPerspective: handles.aiPeer,
+        peerTarget: handles.userPeer,
+        tokens: handles.config.contextTokens,
+      }),
+      handles.session.context({
+        summary: false,
+        peerPerspective: handles.userPeer,
+        peerTarget: handles.aiPeer,
+        tokens: Math.floor(handles.config.contextTokens / 3),
+      }),
+    ]);
+    cachedContext = {
+      profile: normalize(userCtx.peerRepresentation),
+      aiProfile: normalize(aiCtx.peerRepresentation),
+      peerCard: normalizeCard(userCtx.peerCard),
+      aiCard: normalizeCard(aiCtx.peerCard),
+      summary: normalize(userCtx.summary?.content),
+      refreshedAt: Date.now(),
+      pinned: false,
+    };
+    messagesSinceRefresh = 0;
+  } catch (error) {
+    console.error("[honcho-memory] context refresh failed:", error instanceof Error ? error.message : error);
+  }
+};
+
+export const pinCachedContext = (): void => {
+  if (cachedContext.refreshedAt !== null) cachedContext.pinned = true;
+};
+
+export let pendingRefresh: Promise<void> | null = null;
+
+export const backgroundRefresh = (handles: HonchoHandles): void => {
+  pendingRefresh = refreshCachedContext(handles).finally(() => { pendingRefresh = null; });
+};
+
+export const shouldRefreshCachedContext = (handles: HonchoHandles): boolean => {
+  if (cachedContext.pinned) return false;
+  if (cachedContext.refreshedAt === null) return true;
+  const ttlExpired = (Date.now() - cachedContext.refreshedAt) / 1000 >= handles.config.contextRefreshTtlSeconds;
+  const thresholdExceeded = handles.config.contextRefreshMessageThreshold !== null
+    && messagesSinceRefresh >= handles.config.contextRefreshMessageThreshold;
+  return ttlExpired || thresholdExceeded;
+};
+
+const truncateToBudget = (text: string, tokens: number): string => {
+  const budgetChars = tokens * 4;
+  return text.length > budgetChars ? text.slice(0, budgetChars) : text;
+};
+
+export const renderCachedContext = (contextTokens: number): string | null => {
+  const sections = [
+    cachedContext.profile ? `User profile:\n${cachedContext.profile}` : null,
+    cachedContext.peerCard?.length ? `User peer card:\n${cachedContext.peerCard.join("\n")}` : null,
+    cachedContext.aiProfile ? `AI peer profile:\n${cachedContext.aiProfile}` : null,
+    cachedContext.aiCard?.length ? `AI peer card:\n${cachedContext.aiCard.join("\n")}` : null,
+    cachedContext.summary ? `Project summary:\n${cachedContext.summary}` : null,
+    cachedContext.refreshedAt ? `Context refreshed: ${new Date(cachedContext.refreshedAt).toISOString()}` : null,
+  ].filter((value): value is string => Boolean(value));
+
+  if (!sections.length) return null;
+  const raw = `[Persistent memory]\n${sections.join("\n\n")}`;
+  return truncateToBudget(raw, contextTokens);
+};

package/extensions/git.ts

@@ -0,0 +1,28 @@
+import { execFile } from "node:child_process";
+
+export interface GitExecResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+export const execGit = async (cwd: string, args: string[]): Promise<GitExecResult | null> => {
+  try {
+    return await new Promise<GitExecResult>((resolve) => {
+      execFile("git", args, { cwd, encoding: "utf8" }, (error, stdout, stderr) => {
+        if (error) {
+          const err = error as { code?: number };
+          resolve({
+            code: typeof err.code === "number" ? err.code : 1,
+            stdout: stdout ?? "",
+            stderr: stderr ?? "",
+          });
+          return;
+        }
+        resolve({ code: 0, stdout, stderr });
+      });
+    });
+  } catch {
+    return null;
+  }
+};

package/extensions/index.ts

@@ -0,0 +1,190 @@
+import { createHash } from "node:crypto";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { bootstrap, clearHandles, ensureSession, getHandles, type HonchoHandles } from "./client.js";
+import { registerCommands } from "./commands.js";
+import { getRecallMode, resolveConfig, setRecallMode } from "./config.js";
+import {
+  backgroundRefresh,
+  clearCachedContext,
+  incrementMessageCount,
+  pendingRefresh,
+  pinCachedContext,
+  refreshCachedContext,
+  renderCachedContext,
+  shouldRefreshCachedContext,
+} from "./context.js";
+import { registerTools } from "./tools.js";
+import { WriteScheduler } from "./upload.js";
+
+const setStatus = (ctx: { ui: { setStatus(id: string, text: string): void } }, state: "off" | "connected" | "syncing" | "offline") => {
+  const labels: Record<typeof state, string> = {
+    off: "🧠 Honcho off",
+    connected: "🧠 Honcho connected",
+    syncing: "🧠 Honcho syncing",
+    offline: "🧠 Honcho offline",
+  };
+  ctx.ui.setStatus("honcho", labels[state]);
+};
+
+const MIGRATION_DIR = join(homedir(), ".honcho", "migrations");
+const MAX_MIGRATE_CHARS = 4000;
+
+const migrateMemoryFiles = async (handles: HonchoHandles, cwd: string): Promise<void> => {
+  if (!handles.session) return;
+  const markerPath = join(MIGRATION_DIR, createHash("sha256").update(handles.sessionKey).digest("hex").slice(0, 16));
+  try {
+    await access(markerPath);
+    return;
+  } catch { /* marker doesn't exist, proceed */ }
+
+  const filesToMigrate = ["MEMORY.md", "USER.md", "SOUL.md"];
+  const conclusions: Array<{ content: string; sessionId: typeof handles.session }> = [];
+
+  for (const filename of filesToMigrate) {
+    try {
+      const content = await readFile(join(cwd, filename), "utf8");
+      const trimmed = content.trim();
+      if (trimmed) {
+        conclusions.push({
+          content: `[Migrated from ${filename}]\n${trimmed.slice(0, MAX_MIGRATE_CHARS)}`,
+          sessionId: handles.session,
+        });
+      }
+    } catch { /* file doesn't exist, skip */ }
+  }
+
+  if (conclusions.length > 0) {
+    await handles.aiPeer.conclusionsOf(handles.userPeer).create(conclusions);
+    await mkdir(MIGRATION_DIR, { recursive: true });
+    await writeFile(markerPath, `migrated=${new Date().toISOString()}\n`, "utf8");
+    if (handles.config.logging) {
+      console.log(`[honcho-memory] Migrated ${conclusions.length} memory file(s) to Honcho.`);
+    }
+  }
+};
+
+export default function honchoMemory(pi: ExtensionAPI): void {
+  let initializing: Promise<void> | null = null;
+  let turnCount = 0;
+  let lastContextTurn = 0;
+  let scheduler: WriteScheduler | null = null;
+
+  registerTools(pi);
+  registerCommands(pi);
+
+  const initialize = (ctx: { cwd: string; ui: { setStatus(id: string, text: string): void } }) => {
+    initializing = (async () => {
+      try {
+        clearHandles();
+        clearCachedContext();
+        turnCount = 0;
+        lastContextTurn = 0;
+        scheduler?.reset();
+        scheduler = null;
+
+        const config = await resolveConfig();
+        if (!config.enabled || !config.apiKey) {
+          setStatus(ctx, "off");
+          return;
+        }
+        setRecallMode(config.recallMode);
+        scheduler = new WriteScheduler(config.writeFrequency);
+
+        const handles = await bootstrap(config, ctx.cwd);
+        pi.setSessionName(handles.sessionKey);
+
+        if (handles.session) {
+          await refreshCachedContext(handles);
+          if (config.injectionFrequency === "first-turn") {
+            pinCachedContext();
+          }
+          migrateMemoryFiles(handles, ctx.cwd).catch((error) => {
+            if (config.logging) {
+              console.error("[honcho-memory] migration failed:", error instanceof Error ? error.message : error);
+            }
+          });
+        }
+
+        setStatus(ctx, "connected");
+      } catch (error) {
+        console.error("[honcho-memory] initialization failed:", error instanceof Error ? error.message : error);
+        setStatus(ctx, "offline");
+      } finally {
+        initializing = null;
+      }
+    })();
+  };
+
+  pi.on("session_start", async (_event, ctx) => {
+    initialize(ctx);
+  });
+
+  pi.on("before_agent_start", async (event) => {
+    if (initializing) await initializing;
+    const recallMode = getRecallMode();
+    if (recallMode === "tools") return;
+    const handles = getHandles();
+    if (!handles || !handles.session) return;
+
+    turnCount++;
+
+    // Injection frequency: "first-turn" only injects on turn 1
+    if (handles.config.injectionFrequency === "first-turn" && turnCount > 1) return;
+
+    // Context cadence: respect minimum turns between context API calls
+    const contextCadence = handles.config.contextCadence;
+    const shouldRefresh = (turnCount - lastContextTurn) >= contextCadence
+      && shouldRefreshCachedContext(handles);
+
+    if (pendingRefresh) await pendingRefresh;
+
+    if (shouldRefresh) {
+      backgroundRefresh(handles);
+      lastContextTurn = turnCount;
+    }
+
+    const memory = renderCachedContext(handles.config.contextTokens);
+    if (!memory) return;
+    const toolHint = recallMode === "hybrid"
+      ? "\n\nUse honcho_search / honcho_context when durable context may matter. Use honcho_conclude for stable preferences, decisions, and long-lived project facts."
+      : "";
+    return {
+      systemPrompt: `${event.systemPrompt}\n\n${memory}${toolHint}`,
+    };
+  });
+
+  pi.on("agent_end", async (event, ctx) => {
+    const handles = getHandles();
+    if (!handles) return;
+    if (!handles.config.saveMessages) return;
+
+    // Ensure session exists for upload (lazy init case)
+    try {
+      await ensureSession(handles);
+    } catch {
+      return;
+    }
+
+    incrementMessageCount(event.messages.length);
+    setStatus(ctx, "syncing");
+    try {
+      await scheduler?.onTurnEnd(handles, event.messages);
+      setStatus(ctx, "connected");
+    } catch (error) {
+      if (handles.config.logging) {
+        console.error("[honcho-memory] upload failed:", error instanceof Error ? error.message : error);
+      }
+      setStatus(ctx, "offline");
+    }
+  });
+
+  const flush = async () => { await scheduler?.flush(); };
+
+  pi.on("session_shutdown", flush);
+  pi.on("session_before_switch", flush);
+  pi.on("session_before_fork", flush);
+  pi.on("session_before_compact", flush);
+}

package/extensions/session.ts

@@ -0,0 +1,53 @@
+import { createHash } from "node:crypto";
+import type { HonchoConfig, SessionStrategy } from "./config.js";
+import { execGit } from "./git.js";
+
+const hash = (value: string): string => createHash("sha256").update(value).digest("hex").slice(0, 8);
+const sanitize = (value: string): string => value.replace(/[^a-zA-Z0-9_-]/g, "_");
+
+const repoBase = async (cwd: string): Promise<string | null> => {
+  const remote = await execGit(cwd, ["remote", "get-url", "origin"]);
+  if (remote?.code === 0 && remote.stdout.trim()) {
+    const url = remote.stdout.trim().replace(/\.git$/, "").replace(/^(https?:\/\/)[^@]+@/, "$1");
+    return sanitize(url);
+  }
+  const root = await execGit(cwd, ["rev-parse", "--show-toplevel"]);
+  if (root?.code === 0 && root.stdout.trim()) {
+    const normalized = root.stdout.trim();
+    return sanitize(`${normalized.split("/").pop() ?? "repo"}_${hash(normalized)}`);
+  }
+  return null;
+};
+
+const branchName = async (cwd: string): Promise<string | null> => {
+  const result = await execGit(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  const name = result?.code === 0 ? result.stdout.trim() : null;
+  if (name && name !== "HEAD") return sanitize(name);
+  return null;
+};
+
+const directoryKey = (cwd: string): string =>
+  sanitize(`dir_${cwd.split("/").pop() ?? "project"}_${hash(cwd)}`);
+
+export const deriveSessionKey = async (cwd: string, strategy: SessionStrategy, config: HonchoConfig): Promise<string> => {
+  // Priority 1: explicit mapping from config.sessions
+  const manual = config.sessions[cwd];
+  if (manual) {
+    const key = sanitize(manual);
+    return config.sessionPeerPrefix ? sanitize(`${config.peerName}_${key}`) : key;
+  }
+
+  // Priority 2: algorithmic derivation
+  let key: string;
+  if (strategy === "global") key = "global";
+  else if (strategy === "pi-session") key = sanitize(`pi_${hash(cwd)}_${Date.now().toString(36)}`);
+  else if (strategy === "per-directory") key = directoryKey(cwd);
+  else if (strategy === "per-repo") key = (await repoBase(cwd)) ?? directoryKey(cwd);
+  else {
+    const repo = (await repoBase(cwd)) ?? directoryKey(cwd);
+    const branch = await branchName(cwd);
+    key = branch ? `${repo}__branch_${branch}` : repo;
+  }
+
+  return config.sessionPeerPrefix ? sanitize(`${config.peerName}_${key}`) : key;
+};