claude-cognitive 0.1.0

package/dist/mind.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Mind class - the orchestrator for claude-cognitive.
+ * @module mind
+ */
+import { type AgentTemplate, type GetAgentContextOptions } from "./agents/index.js";
+import { TypedEventEmitter } from "./events.js";
+import { PromotionManager } from "./promotion.js";
+import { SemanticMemory } from "./semantic.js";
+import type { Bank, LearnOptions, LearnResult, Memory, MindOptions, RecallOptions, ReflectResult } from "./types.js";
+/**
+ * Mind is the orchestrator layer that wraps HindsightClient and provides
+ * session lifecycle management, graceful degradation, and event emission.
+ *
+ * Claude operates as a **project manager** through Mind:
+ * - Manages session workflow and delegates to specialized agents
+ * - Owns all memory operations (agents don't access memory)
+ * - Synthesizes findings from multiple agents
+ *
+ * @example
+ * ```typescript
+ * const mind = new Mind({
+ *   projectPath: '/path/to/project',
+ *   disposition: { skepticism: 4, literalism: 4, empathy: 2 },
+ *   background: 'Developer assistant for a React app',
+ * });
+ *
+ * await mind.init();
+ *
+ * // Session start - get context to inject
+ * const context = await mind.onSessionStart();
+ *
+ * // During work - recall when helpful
+ * const memories = await mind.recall('authentication');
+ *
+ * // Session end - reflect and store observations
+ * await mind.onSessionEnd(transcript);
+ * ```
+ */
+export declare class Mind extends TypedEventEmitter {
+    private readonly projectPath;
+    private readonly pendingOptions;
+    private bankId;
+    private disposition;
+    private background?;
+    /** Path to semantic memory file. Used in Phase 3. */
+    private semanticPath;
+    private client;
+    private initialized;
+    private degraded;
+    private sessionActive;
+    /** Session start time. Used for duration tracking. */
+    private sessionStartTime;
+    private customAgents;
+    private semantic;
+    private promotionManager;
+    /**
+     * Create a new Mind instance.
+     *
+     * @param options - Mind configuration options
+     */
+    constructor(options?: MindOptions);
+    /**
+     * Initialize the Mind instance.
+     *
+     * This method:
+     * 1. Loads configuration from multiple sources
+     * 2. Creates HindsightClient
+     * 3. Performs health check
+     * 4. Creates bank if it doesn't exist
+     * 5. Loads custom agent templates
+     *
+     * @throws {Error} If init() is called twice
+     */
+    init(): Promise<void>;
+    /**
+     * Derive bank ID from project name if not specified.
+     * @internal
+     */
+    private deriveBankId;
+    /**
+     * Sanitize a string to be a valid bank ID.
+     * @internal
+     */
+    private sanitizeBankId;
+    /**
+     * Ensure the bank exists, creating it if necessary.
+     * @internal
+     */
+    private ensureBank;
+    /**
+     * Called at session start. Returns context to inject.
+     *
+     * This method:
+     * 1. Loads semantic memory (Phase 3)
+     * 2. Recalls recent experiences
+     * 3. Formats as context string
+     *
+     * @returns Formatted context string for injection
+     */
+    onSessionStart(): Promise<string>;
+    /**
+     * Called at session end. Reflects on session and stores observations.
+     *
+     * This method:
+     * 1. Retains transcript if provided
+     * 2. Reflects on the session
+     * 3. Emits opinion events
+     *
+     * @param transcript - Optional session transcript to store
+     * @returns Reflection result, or null in degraded mode
+     */
+    onSessionEnd(transcript?: string): Promise<ReflectResult | null>;
+    /**
+     * Search memories for relevant context.
+     *
+     * In degraded mode, returns an empty array.
+     *
+     * @param query - What to search for
+     * @param options - Search options (budget, factType, etc.)
+     * @returns Matching memories
+     */
+    recall(query: string, options?: RecallOptions): Promise<Memory[]>;
+    /**
+     * Reason about accumulated knowledge and form opinions.
+     *
+     * @param query - What to think about or reason through
+     * @returns Reflection result with opinions
+     * @throws {HindsightError} If in degraded mode (reflect requires Hindsight)
+     */
+    reflect(query: string): Promise<ReflectResult>;
+    /**
+     * Store content in memory.
+     *
+     * In degraded mode, skips silently and emits an error event.
+     *
+     * @param content - Content to store
+     * @param context - Optional additional context
+     */
+    retain(content: string, context?: string): Promise<void>;
+    /**
+     * Bootstrap memory from an existing codebase.
+     *
+     * This solves the **cold start problem** when adopting claude-cognitive
+     * on a mature project.
+     *
+     * @param options - Learn options (depth, git history, etc.)
+     * @returns Learn result with summary and stats
+     * @throws {HindsightError} If in degraded mode (learn requires Hindsight)
+     */
+    learn(options?: LearnOptions): Promise<LearnResult>;
+    /**
+     * Get all available agent templates (built-in + custom).
+     *
+     * @returns Array of agent templates
+     */
+    getAgentTemplates(): AgentTemplate[];
+    /**
+     * Get a specific agent template by name.
+     *
+     * @param name - Agent template name
+     * @returns Agent template, or undefined if not found
+     */
+    getAgentTemplate(name: string): AgentTemplate | undefined;
+    /**
+     * Prepare context for delegating to an agent.
+     *
+     * This should be called by the orchestrator before delegation.
+     * It retrieves relevant memories and formats them for the agent.
+     *
+     * @param agentType - Name of the agent (built-in or custom)
+     * @param task - The task description to delegate
+     * @param options - Optional configuration
+     * @returns Formatted prompt string for the agent
+     */
+    getAgentContext(agentType: string, task: string, options?: GetAgentContextOptions): Promise<string>;
+    /**
+     * Whether the Mind is in degraded mode (Hindsight unavailable).
+     */
+    get isDegraded(): boolean;
+    /**
+     * Attempt to recover from degraded mode.
+     *
+     * @returns True if recovery was successful
+     */
+    attemptRecovery(): Promise<boolean>;
+    /**
+     * Enter degraded mode.
+     * @internal
+     */
+    private enterDegradedMode;
+    /**
+     * Exit degraded mode.
+     * @internal
+     */
+    private exitDegradedMode;
+    /**
+     * Handle an error, potentially entering degraded mode.
+     * @internal
+     */
+    private handleError;
+    /**
+     * Get bank information.
+     *
+     * @returns Bank info, or null if in degraded mode
+     */
+    getBank(): Promise<Bank | null>;
+    /**
+     * Get the current bank ID.
+     */
+    getBankId(): string;
+    /**
+     * Get the project path.
+     */
+    getProjectPath(): string;
+    /**
+     * Check if a session is currently active.
+     */
+    isSessionActive(): boolean;
+    /**
+     * Get the path to semantic memory file.
+     */
+    getSemanticPath(): string;
+    /**
+     * Get the SemanticMemory instance.
+     *
+     * @returns SemanticMemory or null if not initialized
+     */
+    getSemanticMemory(): SemanticMemory | null;
+    /**
+     * Get the PromotionManager instance.
+     *
+     * @returns PromotionManager or null if not initialized
+     */
+    getPromotionManager(): PromotionManager | null;
+    /**
+     * Get the session start time, or null if no session is active.
+     */
+    getSessionStartTime(): Date | null;
+    /**
+     * Assert that init() has been called.
+     * @internal
+     */
+    private assertInitialized;
+    /**
+     * Format recent memories as context string.
+     * @internal
+     */
+    private formatRecentMemories;
+}
+//# sourceMappingURL=mind.d.ts.map

package/dist/mind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mind.d.ts","sourceRoot":"","sources":["../src/mind.ts"],"names":[],"mappings":"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"}