qlogicagent 2.0.0 → 2.2.0

package/dist/types/llm/file-upload-service.d.ts

@@ -0,0 +1,68 @@
+/**
+ * FileUploadService — Unified file upload abstraction for all LLM providers.
+ *
+ * Replaces the base64 approach in media-resolve.ts. When a local URL is
+ * encountered, this service uploads the file to the current provider's
+ * File API and returns a public URL or file_id.
+ *
+ * Supported providers:
+ *   - OpenAI-compatible (OpenAI, Kimi, Minimax, Qwen, GLM) — POST /v1/files
+ *   - Volcengine — POST /v3/files
+ *   - Google Gemini — Resumable upload protocol
+ *
+ * Architecture:
+ *   Transport layer calls resolveLocalMedia() before sending messages.
+ *   resolveLocalMedia() fetches local content and uploads to provider,
+ *   returning a public URL the LLM can access.
+ */
+export interface FileUploadResult {
+    /** Public URL accessible by the LLM provider. */
+    url: string;
+    /** Provider-specific file identifier (for reference/deletion). */
+    fileId: string;
+    /** Original filename. */
+    filename: string;
+    /** File size in bytes. */
+    bytes: number;
+    /** MIME type of the uploaded file. */
+    mimeType: string;
+    /** Provider that stored the file. */
+    provider: string;
+}
+/**
+ * Provider-specific upload adapter.
+ * Each transport implements this to upload files to its own File API.
+ */
+export interface FileUploadAdapter {
+    /**
+     * Upload a file buffer and return a publicly accessible URL.
+     * @param buffer - File content
+     * @param filename - Original filename (used for MIME detection)
+     * @param mimeType - MIME type of the file
+     * @param apiKey - Provider API key
+     * @param signal - Abort signal
+     */
+    uploadFile(buffer: Buffer, filename: string, mimeType: string, apiKey: string, signal?: AbortSignal): Promise<FileUploadResult>;
+}
+/** Guess MIME type from filename extension. */
+export declare function guessMimeType(filename: string): string;
+/** Check if a URL points to a local/private address that cloud APIs cannot reach. */
+export declare function isLocalUrl(url: string): boolean;
+/**
+ * Resolve a local URL by uploading its content to the provider's File API.
+ * Public URLs are returned as-is (the LLM API can fetch them directly).
+ *
+ * @param url - The URL to resolve (may be local or public)
+ * @param adapter - Provider-specific upload adapter
+ * @param apiKey - API key for the upload
+ * @param signal - Optional abort signal
+ * @returns Public URL accessible by the LLM
+ */
+export declare function resolveLocalMedia(url: string, adapter: FileUploadAdapter, apiKey: string, signal?: AbortSignal): Promise<string>;
+/**
+ * Batch-resolve multiple URLs concurrently. Returns array in same order.
+ * Local URLs are uploaded; public URLs pass through unchanged.
+ * Supports concurrent uploads (up to `concurrency` limit, default 3).
+ * Failures throw (caller should handle).
+ */
+export declare function resolveLocalMediaBatch(urls: string[], adapter: FileUploadAdapter, apiKey: string, signal?: AbortSignal, concurrency?: number): Promise<string[]>;

package/dist/types/llm/transports/anthropic-messages.d.ts

@@ -13,6 +13,7 @@
  */
 import type { LLMChunk, LLMRequest, LLMTransport } from "../transport.js";
 import type { ProviderQuirks } from "../provider-def.js";
+import type { FileUploadAdapter } from "../file-upload-service.js";
 export interface AnthropicTransportConfig {
     baseUrl: string;
     /** anthropic-version header (default "2023-06-01") */
@@ -29,6 +30,8 @@ export interface AnthropicTransportConfig {
     omitZeroTemperature?: boolean;
     /** Provider-specific quirks for conditional logic (CC/altcode parity) */
     quirks?: ProviderQuirks;
+    /** File upload adapter (Hub OSS relay for Anthropic). */
+    fileUploadAdapter?: FileUploadAdapter;
 }
 export declare class AnthropicMessagesTransport implements LLMTransport {
     private baseUrl;
@@ -39,6 +42,7 @@ export declare class AnthropicMessagesTransport implements LLMTransport {
     private maxRetries;
     private omitZeroTemperature;
     private quirks;
+    private fileUploadAdapter?;
     constructor(config: AnthropicTransportConfig);
     stream(request: LLMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<LLMChunk>;
     /**

package/dist/types/llm/transports/gemini-generatecontent.d.ts

@@ -21,6 +21,7 @@
  */
 import type { LLMChunk, LLMRequest, LLMTransport } from "../transport.js";
 import type { ProviderQuirks } from "../provider-def.js";
+import type { FileUploadAdapter } from "../file-upload-service.js";
 export interface GeminiGenerateContentTransportConfig {
     /** Base URL, e.g. "https://generativelanguage.googleapis.com/v1beta" */
     baseUrl: string;
@@ -28,11 +29,14 @@ export interface GeminiGenerateContentTransportConfig {
     timeoutMs?: number;
     /** Provider-specific quirks */
     quirks?: ProviderQuirks;
+    /** File upload adapter for resolving local media URLs via upload instead of base64. */
+    fileUploadAdapter?: FileUploadAdapter;
 }
 export declare class GeminiGenerateContentTransport implements LLMTransport {
     private baseUrl;
     private timeoutMs;
     private quirks;
+    private fileUploadAdapter?;
     constructor(config: GeminiGenerateContentTransportConfig);
     stream(request: LLMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<LLMChunk>;
     private buildRequestBody;

package/dist/types/llm/transports/media-resolve.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Media URL Resolution — resolves local/private URLs for cloud LLM APIs.
+ *
+ * Cloud LLM APIs (OpenAI, Anthropic, DeepSeek, etc.) cannot fetch content
+ * from localhost or private networks.
+ *
+ * **Primary approach (upload-based):**
+ *   Local URLs are fetched → uploaded to provider's File API or Aliyun OSS → public URL returned.
+ *   This is the ONLY approach for images, video, and documents.
+ *
+ * **Audio exception (base64):**
+ *   OpenAI's input_audio.data API field mandates base64 encoding.
+ *   resolveMediaUrl() is retained ONLY for this case.
+ *
+ * URL-first design: the gateway stores media as HTTP URLs; this layer handles
+ * the last-mile transformation before sending to provider APIs.
+ */
+import type { FileUploadAdapter } from "../file-upload-service.js";
+/** Check if a URL points to a local/private address that cloud APIs cannot reach. */
+export declare function isLocalUrl(url: string): boolean;
+export interface MediaResolveContext {
+    /** Provider-specific upload adapter. */
+    uploadAdapter: FileUploadAdapter;
+    /** API key for the upload. */
+    apiKey: string;
+    /** Abort signal. */
+    signal?: AbortSignal;
+}
+/**
+ * Resolve a local URL by uploading to the provider's File API.
+ * This is the **preferred** method for all media types.
+ *
+ * Public URLs pass through unchanged.
+ * Local URLs are uploaded → public URL or file_id returned.
+ */
+export declare function resolveMediaUrlViaUpload(url: string, ctx: MediaResolveContext): Promise<string>;
+/**
+ * Batch-resolve URLs via upload. Best-effort: failures return original URL.
+ */
+export declare function resolveMediaUrlsViaUpload(urls: string[], ctx: MediaResolveContext): Promise<string[]>;
+/**
+ * Resolve local audio URL to base64 data URL.
+ *
+ * ONLY for audio — OpenAI's input_audio.data API field mandates base64 encoding.
+ * There is no upload alternative for audio in the OpenAI API.
+ *
+ * For images/video/documents: ALWAYS use resolveMediaUrlViaUpload() instead.
+ * base64 is forbidden for non-audio media per project architecture rules.
+ */
+export declare function resolveMediaUrl(url: string, fallbackMime?: string): Promise<string>;

package/dist/types/llm/transports/openai-chat.d.ts

@@ -13,6 +13,7 @@
  */
 import type { LLMChunk, LLMRequest, LLMTransport, FIMRequest, FIMChunk } from "../transport.js";
 import type { ProviderQuirks } from "../provider-def.js";
+import type { FileUploadAdapter } from "../file-upload-service.js";
 export interface OpenAIChatTransportConfig {
     baseUrl: string;
     /** Additional headers (e.g. for specific providers) */
@@ -25,6 +26,8 @@ export interface OpenAIChatTransportConfig {
     omitZeroTemperature?: boolean;
     /** Provider-specific quirks (CC/altcode parity) */
     quirks?: ProviderQuirks;
+    /** File upload adapter for resolving local media URLs via upload instead of base64. */
+    fileUploadAdapter?: FileUploadAdapter;
 }
 export declare class OpenAIChatTransport implements LLMTransport {
     private baseUrl;
@@ -33,6 +36,7 @@ export declare class OpenAIChatTransport implements LLMTransport {
     private supportsStreamOptions;
     private omitZeroTemperature;
     private quirks;
+    private fileUploadAdapter?;
     private cumulativeReasoningLen;
     private cumulativeContentLen;
     constructor(config: OpenAIChatTransportConfig);

package/dist/types/llm/transports/openai-responses.d.ts

@@ -25,17 +25,20 @@
  */
 import type { LLMChunk, LLMRequest, LLMTransport } from "../transport.js";
 import type { ProviderQuirks } from "../provider-def.js";
+import type { FileUploadAdapter } from "../file-upload-service.js";
 export interface OpenAIResponsesTransportConfig {
     baseUrl: string;
     extraHeaders?: Record<string, string>;
     timeoutMs?: number;
     quirks?: ProviderQuirks;
+    fileUploadAdapter?: FileUploadAdapter;
 }
 export declare class OpenAIResponsesTransport implements LLMTransport {
     private baseUrl;
     private extraHeaders;
     private timeoutMs;
     private quirks;
+    private fileUploadAdapter?;
     constructor(config: OpenAIResponsesTransportConfig);
     stream(request: LLMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<LLMChunk>;
     private buildRequestBody;

package/dist/types/llm/transports/volcengine-responses.d.ts

@@ -18,17 +18,21 @@
  */
 import type { LLMChunk, LLMRequest, LLMTransport } from "../transport.js";
 import type { ProviderQuirks } from "../provider-def.js";
+import type { FileUploadAdapter } from "../file-upload-service.js";
 export interface VolcengineResponsesTransportConfig {
     baseUrl: string;
     extraHeaders?: Record<string, string>;
     timeoutMs?: number;
     quirks?: ProviderQuirks;
+    /** File upload adapter for resolving local media URLs via upload instead of base64. */
+    fileUploadAdapter?: FileUploadAdapter;
 }
 export declare class VolcengineResponsesTransport implements LLMTransport {
     private baseUrl;
     private extraHeaders;
     private timeoutMs;
     private quirks;
+    private fileUploadAdapter?;
     constructor(config: VolcengineResponsesTransportConfig);
     stream(request: LLMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<LLMChunk>;
     /**

package/dist/types/orchestration/tool-loop/tool-schema.d.ts

@@ -38,5 +38,6 @@ export declare function buildToolResultMessage(callId: string, result: {
     payload?: unknown;
     error?: string;
     toolReferences?: string[];
+    imageUrls?: string[];
 }): Record<string, unknown>;
 export declare function cleanToolSchemaForGemini(schema: Record<string, unknown>): unknown;

package/dist/types/protocol/methods.d.ts

@@ -302,6 +302,56 @@ export interface TasksCancelResult {
     ok: boolean;
     message: string;
 }
+export type ProjectType = "default" | "personal" | "group";
+export type ProjectStatus = "active" | "archived";
+export interface ProjectInfo {
+    id: string;
+    name: string;
+    workspaceDir: string;
+    type: ProjectType;
+    status: ProjectStatus;
+    groupId?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ProjectCreateParams {
+    name: string;
+    workspaceDir: string;
+    type?: ProjectType;
+    groupId?: string;
+}
+export interface ProjectCreateResult {
+    ok: boolean;
+    project: ProjectInfo;
+}
+export interface ProjectListParams {
+}
+export interface ProjectListResult {
+    projects: ProjectInfo[];
+}
+export interface ProjectDeleteParams {
+    projectId: string;
+}
+export interface ProjectDeleteResult {
+    ok: boolean;
+    switchedTo?: ProjectInfo;
+}
+export interface SessionSwitchProjectParams {
+    projectId?: string;
+    projectName?: string;
+    workspaceDir?: string;
+}
+export interface SessionSwitchProjectResult {
+    ok: boolean;
+    project: ProjectInfo;
+}
+export interface SessionGetStateParams {
+}
+export interface SessionGetStateResult {
+    sessionId: string;
+    activeProject: ProjectInfo | null;
+    projects: ProjectInfo[];
+}
 export interface RpcMethodMap {
     "initialize": {
         params: InitializeParams;
@@ -484,6 +534,26 @@ export interface RpcMethodMap {
         params: undefined;
         result: ProductSummary[];
     };
+    "project.create": {
+        params: ProjectCreateParams;
+        result: ProjectCreateResult;
+    };
+    "project.list": {
+        params: ProjectListParams;
+        result: ProjectListResult;
+    };
+    "project.delete": {
+        params: ProjectDeleteParams;
+        result: ProjectDeleteResult;
+    };
+    "session.switchProject": {
+        params: SessionSwitchProjectParams;
+        result: SessionSwitchProjectResult;
+    };
+    "session.getState": {
+        params: SessionGetStateParams;
+        result: SessionGetStateResult;
+    };
 }
 /** All known RPC method names. */
 export type RpcMethod = keyof RpcMethodMap;

package/dist/types/protocol/notifications.d.ts

@@ -192,6 +192,16 @@ export interface TurnMediaProgressNotification {
     /** Provider id. */
     provider?: string;
 }
+/** Media files auto-downloaded to local storage (~/.qlogicagent/media/). */
+export interface TurnMediaPersistedNotification {
+    turnId: string;
+    files: Array<{
+        remoteUrl: string;
+        localPath: string;
+        bytes: number;
+        mimeType: string;
+    }>;
+}
 /** Full todo list updated — enables DeerFlow-style todo panel sync. */
 export interface TurnTodosUpdatedNotification {
     turnId?: string;
@@ -279,6 +289,15 @@ export interface MemoryUpdatedNotification {
     /** Human-readable summary of what changed. */
     summary?: string;
 }
+/** Emitted when importance decay runs after a Dream consolidation. */
+export interface MemoryDecayCompletedNotification {
+    /** Number of memories whose importance was reduced. */
+    decayed: number;
+    /** Number of memories archived (below threshold). */
+    archived: number;
+    /** Duration in ms. */
+    durationMs: number;
+}
 /** Session metadata changed (title, model, etc.). */
 export interface SessionInfoNotification {
     sessionId: string;
@@ -407,6 +426,24 @@ export interface ProductCompletedNotification {
     productId: string;
     summary: string;
 }
+/** A project was created. */
+export interface ProjectCreatedNotification {
+    id: string;
+    name: string;
+    workspaceDir: string;
+    type: string;
+    groupId?: string;
+}
+/** Active project was switched. */
+export interface ProjectSwitchedNotification {
+    id: string;
+    name: string;
+    workspaceDir: string;
+}
+/** A project was deleted. */
+export interface ProjectDeletedNotification {
+    id: string;
+}
 export interface NotificationMethodMap {
     "turn.start": TurnStartNotification;
     "turn.delta": TurnDeltaNotification;
@@ -425,6 +462,7 @@ export interface NotificationMethodMap {
     "turn.annotations": TurnAnnotationsNotification;
     "turn.media_result": TurnMediaResultNotification;
     "turn.media_progress": TurnMediaProgressNotification;
+    "turn.media_persisted": TurnMediaPersistedNotification;
     "turn.todos_updated": TurnTodosUpdatedNotification;
     "task.updated": TaskUpdatedNotification;
     "turn.exec_progress": TurnExecProgressNotification;
@@ -435,6 +473,7 @@ export interface NotificationMethodMap {
     "turn.skill_instruction": TurnSkillInstructionNotification;
     "turn.ask_user": TurnAskUserNotification;
     "memory.updated": MemoryUpdatedNotification;
+    "memory.decay.completed": MemoryDecayCompletedNotification;
     "session.info": SessionInfoNotification;
     "permission.rule_updated": PermissionRuleUpdatedNotification;
     "team.updated": TeamUpdatedNotification;
@@ -453,6 +492,9 @@ export interface NotificationMethodMap {
     "product.checkpointed": ProductCheckpointedNotification;
     "product.budgetWarning": ProductBudgetWarningNotification;
     "product.completed": ProductCompletedNotification;
+    "project.created": ProjectCreatedNotification;
+    "project.switched": ProjectSwitchedNotification;
+    "project.deleted": ProjectDeletedNotification;
 }
 /** All known notification method names. */
 export type NotificationMethod = keyof NotificationMethodMap;

package/dist/types/runtime/execution/dream-agent.d.ts

@@ -72,9 +72,11 @@ export declare function canUseDreamTool(memoryRoot: string, restriction: DreamTo
  * Build the 4-phase memory consolidation prompt.
  *
  * Adapted from CC's consolidationPrompt.ts with our project context.
+ * P5: Enhanced with category-aware merge rules from write gate taxonomy.
  */
 export declare function buildConsolidationPrompt(memoryRoot: string, transcriptDir: string, sessionIds: string[], opts?: {
     hasQMemory?: boolean;
+    categoryContext?: string;
 }): string;
 /**
  * Check whether dream consolidation should run.

package/dist/types/runtime/execution/dream-category-context.d.ts

@@ -0,0 +1,47 @@
+import type { QMemoryCategory } from "../../skills/memory/categories.js";
+/** A memory file with its inferred category and metadata. */
+export interface CategorizedMemoryFile {
+    filename: string;
+    category: QMemoryCategory | "uncategorized";
+    /** First line description. */
+    description: string;
+    /** File size bytes. */
+    sizeBytes: number;
+    /** Count of entries/bullets in the file. */
+    entryCount: number;
+}
+/** Category statistics for the dream prompt. */
+export interface CategoryManifest {
+    /** Per-category file groups. */
+    categories: Record<string, CategorizedMemoryFile[]>;
+    /** Total files scanned. */
+    totalFiles: number;
+    /** Files that couldn't be classified. */
+    uncategorizedCount: number;
+}
+/**
+ * Scan MEMDIR and classify all topic files by category.
+ *
+ * @param memoryRoot - The MEMDIR root directory
+ * @returns Category manifest with grouped files
+ */
+export declare function scanCategoryManifest(memoryRoot: string): Promise<CategoryManifest>;
+/**
+ * Category-specific merge/conflict rules for the dream prompt.
+ *
+ * These rules tell the dream agent how to handle each category:
+ * - facts: supersede (newer replaces older when same topic)
+ * - lessons: accumulate (append new insights, don't delete old)
+ * - preferences: overwrite (latest preference wins)
+ * - patterns: merge (consolidate duplicates into one authoritative entry)
+ * - decisions: update (add "update" section if decision changed)
+ */
+export declare const CATEGORY_MERGE_RULES: Record<QMemoryCategory | "uncategorized", string>;
+/**
+ * Format the category manifest and merge rules as an injection block
+ * for the dream consolidation prompt.
+ *
+ * This replaces the blind "grep transcripts" approach with structured
+ * guidance about what exists and how to handle each category.
+ */
+export declare function formatCategoryContextBlock(manifest: CategoryManifest): string;

package/dist/types/runtime/execution/dream-category-context.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/runtime/execution/index.d.ts

@@ -3,4 +3,5 @@ export { createContentReplacementState, enforceToolResultBudget, maybePersistLar
 export { resolveToolEligibility, type ToolEligibilityContext, type ToolEligibilityResult } from "./tool-eligibility.js";
 export { runForkedAgent, type ForkedAgentParams, type CanUseToolFn } from "./forked-agent.js";
 export { runDream, type DreamRunDeps } from "./dream-agent.js";
+export { runDecayCycle, shouldTriggerDecay, markDecayComplete, type DecayCycleDeps, type DecayCycleResult, type DecayConfig } from "./memory-decay.js";
 export { createProgressTracker, updateProgressFromUsage, recordToolUse, getProgressUpdate, type AgentProgress, } from "./progress-tracker.js";

package/dist/types/runtime/execution/memory-decay.d.ts

@@ -0,0 +1,57 @@
+import type { DecayOptions, DecayResult } from "../../skills/memory/qmemory-adapter.js";
+export interface DecayConfig {
+    /** Minimum hours between decay cycles. Default: 24. */
+    minIntervalHours: number;
+    /** Enable temporal expiry (event/plan memories past grace period). Default: true. */
+    temporalExpiry: boolean;
+    /** Enable staleness decay (reduce importance of unaccessed memories). Default: true. */
+    stalenessDecay: boolean;
+    /** Enable noise archival (archive memories below threshold). Default: true. */
+    noiseArchival: boolean;
+}
+export declare const DEFAULT_DECAY_CONFIG: DecayConfig;
+/**
+ * Check whether enough time has elapsed since last decay.
+ * Returns true if decay should run.
+ */
+export declare function shouldTriggerDecay(memoryRoot: string, config?: Partial<DecayConfig>): Promise<boolean>;
+/**
+ * Mark decay as having just run (persist timestamp).
+ */
+export declare function markDecayComplete(memoryRoot: string): Promise<void>;
+export interface DecayCycleDeps {
+    /** QMemory adapter with triggerDecay method. */
+    adapter: {
+        triggerDecay(userId: string, options?: DecayOptions): Promise<DecayResult>;
+    };
+    /** User ID for QMemory operations. */
+    userId: string;
+    /** Memory root directory (for gate marker). */
+    memoryRoot: string;
+    /** Decay configuration overrides. */
+    config?: Partial<DecayConfig>;
+    /** Logger. */
+    log?: {
+        info(msg: string): void;
+        debug?(msg: string): void;
+    };
+}
+export interface DecayCycleResult {
+    /** Whether decay actually ran (false = skipped by gate). */
+    ran: boolean;
+    /** Number of memories whose importance was reduced. */
+    decayed: number;
+    /** Number of memories archived (below threshold). */
+    archived: number;
+    /** Duration in ms. */
+    durationMs: number;
+}
+/**
+ * Run a full decay cycle with gate check.
+ *
+ * Lifecycle:
+ *   1. Check time gate (24h default)
+ *   2. Call QMemory /v1/admin/decay
+ *   3. Mark completion timestamp
+ */
+export declare function runDecayCycle(deps: DecayCycleDeps): Promise<DecayCycleResult>;

package/dist/types/runtime/execution/memory-decay.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/runtime/hooks/index.d.ts

@@ -1,3 +1,4 @@
 export { createHookRegistry, type RuntimeLogger } from "./hook-registry.js";
 export { registerMemoryHooks, createMemoryPrefetchState, type MemoryHooksDeps, type MemoryPrefetchState, MEMORY_PREFETCH_CONFIG, } from "./memory-hooks.js";
 export { registerContextCompressionHook, compressMessages } from "./context-compression.js";
+export { registerSkillRecallHooks, detectRetrospectiveTrigger, invalidateSkillRecallCache, type SkillRecallHooksDeps, SKILL_RECALL_CONFIG, } from "./skill-recall-hooks.js";

package/dist/types/runtime/hooks/memory-hooks.d.ts

@@ -1,5 +1,6 @@
 import type { HookRegistry } from "../../contracts/hooks.js";
 import type { MemoryProvider } from "qlogicagent-runtime-contracts";
+import type { Memdir } from "../../skills/memory/memdir.js";
 export declare const MEMORY_PREFETCH_CONFIG: {
     /** Max bytes of memory content to inject per session (CC: 60KB) */
     readonly MAX_SESSION_BYTES: number;
@@ -47,3 +48,22 @@ export declare function createMemoryPrefetchState(): MemoryPrefetchState;
 export declare function registerMemoryHooks(hooks: HookRegistry, deps: MemoryHooksDeps, 
 /** Shared state — pass the same object across hook re-registrations in a session. */
 prefetchState?: MemoryPrefetchState): () => void;
+export interface MemdirRecallHookDeps {
+    /** MEMDIR instance (lazy: may be null at registration time). */
+    getMemdir: () => Memdir | null;
+    /** Logger. */
+    log: {
+        debug(msg: string): void;
+        warn(msg: string): void;
+    };
+}
+/**
+ * Register the MEMDIR cross-file recall hook on `memory.before_recall`.
+ *
+ * - Priority 40 (before QMemory at 50)
+ * - Scans topic files, selects top-5 relevant
+ * - Injects content into recalledMemories (merged with QMemory results)
+ * - Respects session byte budget from shared MemoryPrefetchState
+ * - Dedup via surfacedPaths (shared with QMemory hook)
+ */
+export declare function registerMemdirRecallHook(hooks: HookRegistry, deps: MemdirRecallHookDeps, prefetchState?: MemoryPrefetchState): () => void;

package/dist/types/runtime/hooks/skill-recall-hooks.d.ts

@@ -0,0 +1,36 @@
+import type { HookRegistry } from "../../contracts/hooks.js";
+export declare const SKILL_RECALL_CONFIG: {
+    /** Max number of cross-project skills to inject per turn. */
+    readonly MAX_RECALLED_SKILLS: 3;
+    /** Max chars of skill content to include in recall context. */
+    readonly MAX_SKILL_CONTENT_CHARS: 800;
+    /** Cache TTL for known project skill index (ms). */
+    readonly CACHE_TTL_MS: number;
+};
+/**
+ * Detect whether user message contains retrospective/cross-reference semantics.
+ * Returns extracted keywords for skill matching if triggered, or null.
+ */
+export declare function detectRetrospectiveTrigger(message: string): string[] | null;
+export interface SkillRecallHooksDeps {
+    /** Current project cwd (to exclude from cross-project search). */
+    currentCwd?: string;
+    /** Logger. */
+    log: {
+        debug(msg: string): void;
+        warn(msg: string): void;
+    };
+}
+/**
+ * Register the cross-project skill recall hook on `memory.before_recall`.
+ * Runs at lower priority (60) than QMemory prefetch (50) so it supplements,
+ * not replaces, the standard memory recall.
+ *
+ * When triggered, injects cross-project skill metadata into recalledMemories.
+ */
+export declare function registerSkillRecallHooks(hooks: HookRegistry, deps: SkillRecallHooksDeps): () => void;
+/**
+ * Invalidate the cross-project skill index cache.
+ * Call when skills are created/deleted/promoted to refresh.
+ */
+export declare function invalidateSkillRecallCache(): void;

package/dist/types/runtime/infra/agent-paths.d.ts

@@ -39,6 +39,8 @@ export declare function getUserWorkflowsDir(): string;
 export declare function getUserInstructionsPath(): string;
 /** `~/.qlogicagent/rules/` */
 export declare function getUserRulesDir(): string;
+/** `~/.qlogicagent/media/` — auto-downloaded media files (images, videos, audio). */
+export declare function getUserMediaDir(): string;
 /** `<cwd>/.qlogicagent/` */
 export declare function getProjectAgentDir(cwd?: string): string;
 /** `<cwd>/.qlogicagent/workflows/` */
@@ -51,6 +53,10 @@ export declare function getProjectSkillsDir(cwd?: string): string;
 export declare function getProjectSettingsPath(cwd?: string): string;
 /** `<cwd>/.qlogicagent/INSTRUCTIONS.md` */
 export declare function getProjectInstructionsPath(cwd?: string): string;
+/** `<cwd>/.qlogicagent/instructions/` — project-scoped instruction files (CRUD via RPC) */
+export declare function getProjectInstructionsDir(cwd?: string): string;
+/** `<cwd>/.qlogicagent/plans/` — project-scoped plan files */
+export declare function getProjectPlansDir(cwd?: string): string;
 /** `<cwd>/.qlogicagent/rules/` */
 export declare function getProjectRulesDir(cwd?: string): string;
 /** `<cwd>/.qlogicagent/sessions/` */
@@ -59,7 +65,19 @@ export declare function getProjectSessionsRoot(cwd: string): string;
 export declare function getProjectSessionDir(cwd: string, sessionId: string): string;
 /** `<cwd>/.qlogicagent/checkpoints/` or `<cwd>/.qlogicagent/checkpoints/{sessionId}` */
 export declare function getProjectCheckpointsDir(cwd: string, sessionId?: string): string;
-/** `<cwd>/.qlogicagent/memory.json` */
-export declare function getProjectMemoryPath(cwd: string): string;
 /** `<gitRoot>/.qlogicagent/hooks/` */
 export declare function getGitRootHooksDir(gitRoot: string): string;
+/**
+ * Discover all known project directories from session history.
+ * Scans `~/.qlogicagent/sessions/` metadata to extract unique `cwd` paths.
+ * Used for cross-project skill recall (read-only, never writes to foreign projects).
+ *
+ * @param excludeCwd - Current project cwd to exclude from results
+ * @returns Array of absolute paths to project roots that have been worked on
+ */
+export declare function getKnownProjectDirs(excludeCwd?: string): string[];
+/**
+ * Get skill directories from all known projects (excluding current).
+ * Returns paths to `<project>/.qlogicagent/skills/` for recall-only access.
+ */
+export declare function getAllProjectSkillDirs(excludeCwd?: string): string[];