qlogicagent 2.0.0 → 2.1.0

package/dist/types/cli/stdio-server.d.ts

@@ -46,8 +46,10 @@ export declare class StdioServer {
     /** QMemory adapter (when QMEMORY_BASE_URL env is set). Used by Dream hippocampus bridge. */
     private qmemoryAdapter;
     private qmemoryUserId;
-    /** Local memory store for system prompt injection (CC memory parity). */
-    private memoryStore;
+    /** MEMDIR file-based memory (CC memdir parity). */
+    private memdir;
+    /** Memory write gate state (P2+P3: category gate + supersedes). */
+    private memoryWriteState;
     private fileWatcher;
     /** Pending ask_user requests waiting for host response */
     private pendingAskUser;
@@ -123,15 +125,15 @@ export declare class StdioServer {
      */
     private handleSessionGetInfo;
     /**
-     * `memory.list` — Enumerate available memory sources (local store + qmemory).
+     * `memory.list` — Enumerate available memory sources (memdir + qmemory).
      */
     private handleMemoryList;
     /**
-     * `memory.read` — Read memory content from local store or QMemory.
+     * `memory.read` — Read memory content from memdir (INDEX.md or topic file).
      */
     private handleMemoryRead;
     /**
-     * `memory.write` — Write memory content to local store (agent notes / user profile).
+     * `memory.write` — Write memory content to memdir (INDEX.md or topic file).
      */
     private handleMemoryWrite;
     /**
@@ -176,12 +178,11 @@ export declare class StdioServer {
      */
     private handleTodosList;
     /**
-     * `memory.search` — Vector search via QMemory adapter.
-     * Powers the memory page's search feature.
+     * `memory.search` — Search memory via QMemory (vector) or memdir (local keyword).
      */
     private handleMemorySearch;
     /**
-     * `memory.delete` — Remove a memory entry by substring match (local) or ID (qmemory).
+     * `memory.delete` — Remove memory entry from memdir (INDEX.md line) or QMemory (by ID).
      */
     private handleMemoryDelete;
     /**

package/dist/types/contracts/hooks.d.ts

@@ -114,7 +114,10 @@ export interface HookContextMap {
         recalledMemories?: Array<{
             text: string;
             score?: number;
+            category?: string | null;
         }>;
+        preferredCategories?: string[];
+        deprioritizedCategories?: string[];
     };
     "memory.after_recall": HookTurnContext & {
         blockCount?: number;

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

@@ -0,0 +1,25 @@
+/**
+ * Media URL Resolution — converts local/private URLs to inline base64 data URLs.
+ *
+ * Cloud LLM APIs (OpenAI, Anthropic, DeepSeek) cannot fetch content from
+ * localhost or private networks. This utility detects such URLs and resolves
+ * them to base64 data URLs that can be sent inline.
+ *
+ * URL-first design: the gateway stores media as HTTP URLs; this layer handles
+ * the last-mile transformation before sending to provider APIs.
+ */
+/** Check if a URL points to a local/private address that cloud APIs cannot reach. */
+export declare function isLocalUrl(url: string): boolean;
+/**
+ * Resolve a URL to a base64 data URL if it's a local address.
+ * Public URLs are returned as-is (the LLM API can fetch them directly).
+ *
+ * Returns the original URL for non-local addresses.
+ * Returns a `data:<mime>;base64,...` string for local addresses.
+ */
+export declare function resolveMediaUrl(url: string, fallbackMime?: string): Promise<string>;
+/**
+ * Batch-resolve multiple URLs. Returns array in same order.
+ * Failures are logged and the original URL is kept (best-effort).
+ */
+export declare function resolveMediaUrls(urls: string[], fallbackMime?: string): Promise<string[]>;

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/memory-write-gate.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

@@ -59,7 +59,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[];

package/dist/types/runtime/infra/disk-storage.d.ts

@@ -4,7 +4,6 @@
  * Provides:
  * - Atomic write (tmp + rename) with dir auto-creation
  * - JSON read/write helpers
- * - MemoryStore disk persistence (auto-save on mutation)
  */
 /**
  * Write data atomically: write to a temp file in the same directory,
@@ -19,18 +18,3 @@ export declare function readJsonFile<T = unknown>(filePath: string): Promise<T |
  * Write a JSON file atomically.
  */
 export declare function writeJsonFile(filePath: string, data: unknown): Promise<void>;
-/** Path to user-level memory file: `~/.qlogicagent/memory.json` */
-export declare function getMemoryFilePath(): string;
-export interface PersistedMemory {
-    memory: string;
-    user: string;
-    /** ISO 8601 timestamp of last save. */
-    savedAt: string;
-}
-/** Load persisted memory from disk. Returns undefined if no file exists. */
-export declare function loadPersistedMemory(): Promise<PersistedMemory | undefined>;
-/** Save memory to disk atomically. */
-export declare function savePersistedMemory(data: {
-    memory: string;
-    user: string;
-}): Promise<void>;

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

@@ -1,11 +1,11 @@
-export { AGENT_DOT_DIR, getUserAgentHome, getUserSessionDir, getUserCredentialsPath, getUserPluginsDir, getUserSkillsDir, getUserSettingsPath, getUserCacheDir, getUserDebugLogsDir, getUserCheckpointsDir, getUserPluginCacheDir, getUserMcpConfigPath, getUserMarketplaceConfigPath, getUserWorkflowsDir, getUserInstructionsPath, getProjectAgentDir, getProjectWorkflowsDir, getProjectPluginsDir, getProjectSkillsDir, getProjectSettingsPath, getProjectInstructionsPath, getProjectRulesDir, getGitRootHooksDir, } from "./agent-paths.js";
+export { AGENT_DOT_DIR, getUserAgentHome, getUserSessionDir, getUserCredentialsPath, getUserPluginsDir, getUserSkillsDir, getUserSettingsPath, getUserCacheDir, getUserDebugLogsDir, getUserCheckpointsDir, getUserPluginCacheDir, getUserMcpConfigPath, getUserMarketplaceConfigPath, getUserWorkflowsDir, getUserInstructionsPath, getProjectAgentDir, getProjectWorkflowsDir, getProjectPluginsDir, getProjectSkillsDir, getProjectSettingsPath, getProjectInstructionsPath, getProjectRulesDir, getGitRootHooksDir, getKnownProjectDirs, getAllProjectSkillDirs, } from "./agent-paths.js";
 export { getBudgetContinuationMessage } from "./token-budget.js";
 export { type SecureStorage, saveApiKey, loadApiKey } from "./secure-storage.js";
 export { createFileWatcher, FileWatcher } from "./file-watcher.js";
 export { TaskStore } from "./task-runtime.js";
 export { createWorktreeBackend } from "./worktree-backend.js";
 export { registerCleanup, runCleanupFunctions } from "./cleanup-registry.js";
-export { atomicWriteFile, readJsonFile, writeJsonFile, loadPersistedMemory, savePersistedMemory, getMemoryFilePath, type PersistedMemory, } from "./disk-storage.js";
+export { atomicWriteFile, readJsonFile, writeJsonFile, } from "./disk-storage.js";
 export { AcpDetector, ACP_BACKENDS } from "./acp-detector.js";
 export { AcpProtocolAdapter, type TranslatedNotification, type AcpHostRequestHandler } from "./acp-protocol-adapter.js";
 export { AcpUsageTracker, type AccumulatedUsage } from "./acp-usage-tracker.js";

package/dist/types/runtime/session/session-persistence.d.ts

@@ -52,8 +52,10 @@ export interface SessionListEntry {
 /**
  * Append a message to the session transcript.
  * Creates the session directory if it doesn't exist.
+ * When turnId is provided, it acts as a per-turn boundary marker enabling
+ * reconciliation with Gateway's token_usage records.
  */
-export declare function appendMessage(sessionId: string, message: ChatMessage, projectRoot?: string): Promise<void>;
+export declare function appendMessage(sessionId: string, message: ChatMessage, projectRoot?: string, turnId?: string): Promise<void>;
 /**
  * Save session state (cost + metadata) atomically.
  */

package/dist/types/skills/index.d.ts

@@ -1,11 +1,11 @@
 export type { PortableTool, PortableToolResult, ToolContentBlock, } from "./portable-tool.js";
 export { setToolPool, addTool, addTools, removeTool, findTool, hasTool, getToolNames, getToolCount, executeTool, getToolManifest, getTools, activateTool, isToolActivated, clearActivatedTools, AGENT_DISALLOWED_TOOLS, CUSTOM_AGENT_DISALLOWED_TOOLS, filterToolsForAgent, } from "./tools.js";
-export { MEMORY_TOOL_NAME, MEMORY_TOOL_MAX_CONTENT_LENGTH, MEMORY_TOOL_ACTIONS, MEMORY_TOOL_SCHEMA, MEMORY_TOOL_DESCRIPTION, MEMORY_TOOL_LABEL, isMemoryContentSafe, executeMemoryTool, } from "./memory/memory-tool.js";
-export type { MemoryToolAction, MemoryToolParams, MemoryToolResult, MemoryToolExecutorDeps, MediaPreferencesSummary, } from "./memory/memory-tool.js";
-export { MemoryStore, MEMORY_ENTRY_DELIMITER, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_USER_CHAR_LIMIT, } from "./memory/memory-store.js";
-export type { MemoryStoreTarget, MemoryStoreResult, MemoryStoreOptions, MemoryStoreSerialized, } from "./memory/memory-store.js";
+export { MEMORY_TOOL_NAME, MEMORY_TOOL_ACTIONS, MEMORY_TOOL_SCHEMA, MEMORY_TOOL_DESCRIPTION, MEMORY_TOOL_LABEL, isMemoryContentSafe, executeMemoryTool, } from "./memory/memory-tool.js";
+export type { MemoryToolAction, MemoryToolParams, MemoryToolResult, MemoryToolExecutorDeps, } from "./memory/memory-tool.js";
+export { Memdir, getMemdirPath, getIndexPath } from "./memory/memdir.js";
+export type { MemdirFileInfo, MemdirResult } from "./memory/memdir.js";
 export { createQMemoryAdapter } from "./memory/qmemory-adapter.js";
-export type { QMemoryAdapterConfig, QMemoryHealthStatus, ExtractedMemoryItem } from "./memory/qmemory-adapter.js";
+export type { QMemoryAdapterConfig, QMemoryHealthStatus, ExtractedMemoryItem, DecayOptions, DecayResult } from "./memory/qmemory-adapter.js";
 export { THINK_TOOL_NAME, THINK_TOOL_SCHEMA, createThinkTool } from "./think-tool.js";
 export type { ThinkToolParams } from "./think-tool.js";
 export { TODO_TOOL_NAME, TODO_TOOL_SCHEMA, TODO_ACTIONS, createTodoTool } from "./todo-tool.js";

package/dist/types/skills/memory/find-relevant-memories.d.ts

@@ -0,0 +1,70 @@
+export declare const RELEVANT_MEMORIES_CONFIG: {
+    /** Max topic files to consider during scan. */
+    readonly MAX_SCAN_FILES: 100;
+    /** Max files to surface per turn. */
+    readonly MAX_SELECTED: 5;
+    /** Max bytes per surfaced file (CC: 4096). */
+    readonly MAX_FILE_BYTES: 4096;
+    /** Max total bytes for all surfaced files combined. */
+    readonly MAX_TOTAL_BYTES: number;
+    /** Minimum score to be selected (0.0-1.0). */
+    readonly MIN_SCORE: 0.2;
+    /** Lines to read for header/description extraction. */
+    readonly HEADER_LINES: 10;
+    /** Recency boost: files modified within this many days get a bonus. */
+    readonly RECENCY_DAYS: 7;
+    /** Recency boost amount. */
+    readonly RECENCY_BOOST: 0.15;
+};
+/** Scanned memory file header (CC MemoryHeader parity). */
+export interface MemoryFileHeader {
+    /** Filename (e.g. "lesson-docker.md") */
+    filename: string;
+    /** Absolute path */
+    filePath: string;
+    /** Last modified timestamp (ms since epoch) */
+    mtimeMs: number;
+    /** File size in bytes */
+    sizeBytes: number;
+    /** Description extracted from first non-heading line */
+    description: string | null;
+    /** Category inferred from filename prefix */
+    category: string | null;
+}
+/** A selected relevant memory with content loaded. */
+export interface RelevantMemory {
+    /** Filename */
+    filename: string;
+    /** Full file path */
+    filePath: string;
+    /** Last modified timestamp */
+    mtimeMs: number;
+    /** Relevance score (0.0 - 1.0) */
+    score: number;
+    /** Content (possibly truncated) */
+    content: string;
+    /** Whether content was truncated */
+    truncated: boolean;
+}
+/**
+ * Find memory files relevant to a user query.
+ *
+ * CC parity: scans topic files, scores by keyword + filename + recency,
+ * selects top-N, loads content. No LLM needed (unlike CC's Sonnet call).
+ *
+ * @param query - User query text
+ * @param memoryDir - Root of the MEMDIR directory (~/.qlogicagent/memory/)
+ * @param alreadySurfaced - Paths already shown in prior turns (for dedup)
+ * @returns Relevant memories with content, sorted by score
+ */
+export declare function findRelevantMemories(query: string, memoryDir: string, alreadySurfaced?: ReadonlySet<string>): Promise<RelevantMemory[]>;
+/**
+ * Scan memory directory for topic files (excludes INDEX.md).
+ * Returns headers sorted by modification time (newest first).
+ */
+export declare function scanMemoryHeaders(memoryDir: string): Promise<MemoryFileHeader[]>;
+/**
+ * Format relevant memories as a single block for system prompt injection.
+ * CC parity: includes freshness header per file.
+ */
+export declare function formatRelevantMemoriesBlock(memories: RelevantMemory[]): string;

package/dist/types/skills/memory/memdir.d.ts

@@ -0,0 +1,80 @@
+/** Max chars for INDEX.md to inject into system prompt (CC uses 25KB, we use 12KB). */
+export declare const INDEX_MAX_CHARS = 12288;
+/** Max lines for INDEX.md injection. */
+export declare const INDEX_MAX_LINES = 200;
+/** Max chars for a single topic file. */
+export declare const TOPIC_FILE_MAX_CHARS = 8192;
+/** Root directory: ~/.qlogicagent/memory/ */
+export declare function getMemdirPath(): string;
+/** Full path to INDEX.md */
+export declare function getIndexPath(): string;
+export interface MemdirFileInfo {
+    name: string;
+    /** Size in bytes */
+    size: number;
+    /** Last modified ISO timestamp */
+    modifiedAt: string;
+    /** First non-empty line (preview) */
+    preview?: string;
+}
+export interface MemdirResult {
+    ok: boolean;
+    message: string;
+    /** File path relative to memdir */
+    file?: string;
+    /** Current INDEX.md char usage */
+    indexUsage?: string;
+}
+export declare function isMemoryContentSafe(text: string): boolean;
+export declare class Memdir {
+    private readonly root;
+    private indexCache;
+    constructor(root?: string);
+    /** Get the root directory path of this MEMDIR. */
+    getRootPath(): string;
+    /** Ensure memdir exists with a default INDEX.md if missing. */
+    ensureInitialized(): void;
+    /**
+     * Get INDEX.md content for system prompt injection.
+     * Truncated to INDEX_MAX_CHARS / INDEX_MAX_LINES.
+     */
+    getIndexForPrompt(): string;
+    /** Get raw INDEX.md content (untruncated). */
+    getIndexRaw(): string;
+    /** Get INDEX.md usage stats. */
+    getIndexUsage(): {
+        chars: number;
+        lines: number;
+        percent: number;
+    };
+    /** Append a line/entry to INDEX.md. */
+    addToIndex(content: string): Promise<MemdirResult>;
+    /** Replace text in INDEX.md (str_replace semantics). */
+    replaceInIndex(oldText: string, newText: string): Promise<MemdirResult>;
+    /** Remove text from INDEX.md. */
+    removeFromIndex(oldText: string): Promise<MemdirResult>;
+    /** List all memory files (excluding INDEX.md). */
+    listFiles(): Promise<MemdirFileInfo[]>;
+    /** Create a new topic file. Fails if it already exists. */
+    createFile(name: string, content: string): Promise<MemdirResult>;
+    /** Write/overwrite a topic file. */
+    writeFile(name: string, content: string): Promise<MemdirResult>;
+    /** Read a topic file. */
+    readFile(name: string): Promise<{
+        ok: boolean;
+        content?: string;
+        message: string;
+    }>;
+    /** Delete a topic file. INDEX.md cannot be deleted. */
+    deleteFile(name: string): Promise<MemdirResult>;
+    /** Search all memory files for keyword matches. Returns matching snippets. */
+    searchLocal(query: string): Promise<Array<{
+        file: string;
+        snippet: string;
+        score: number;
+    }>>;
+    private writeIndex;
+    private ensureDir;
+    /** Append an entry to the file listing section of INDEX.md (idempotent). */
+    private appendIndexEntry;
+}

package/dist/types/skills/memory/memory-tool.d.ts

@@ -1,16 +1,8 @@
 import type { MemoryProvider, MemorySearchResult } from "qlogicagent-runtime-contracts";
-import type { MemoryStore, MemoryStoreTarget } from "./memory-store.js";
-export interface MediaPreferencesSummary {
-    imageStyle?: string;
-    videoStyle?: string;
-    musicGenre?: string;
-    musicMood?: string;
-    primaryPurpose?: string;
-    colorPreference?: string;
-}
+import type { Memdir } from "./memdir.js";
 export declare const MEMORY_TOOL_NAME: "memory";
-export declare const MEMORY_TOOL_MAX_CONTENT_LENGTH = 2000;
-export declare const MEMORY_TOOL_ACTIONS: readonly ["add", "replace", "remove", "search"];
+export declare const MEMORY_TOOL_LABEL = "Memory";
+export declare const MEMORY_TOOL_ACTIONS: readonly ["add", "replace", "remove", "create_file", "write_file", "read_file", "delete_file", "list_files", "search"];
 export type MemoryToolAction = (typeof MEMORY_TOOL_ACTIONS)[number];
 export declare const MEMORY_TOOL_SCHEMA: {
     readonly type: "object";
@@ -20,68 +12,48 @@ export declare const MEMORY_TOOL_SCHEMA: {
             readonly enum: string[];
             readonly description: string;
         };
-        readonly target: {
-            readonly type: "string";
-            readonly enum: readonly ["memory", "user"];
-            readonly description: string;
-        };
         readonly content: {
             readonly type: "string";
             readonly description: string;
         };
         readonly old_text: {
             readonly type: "string";
-            readonly description: "Required for 'replace' and 'remove'. A substring that uniquely identifies the note entry to modify.";
+            readonly description: "For 'replace'/'remove': the exact text to find in INDEX.md.";
         };
-        readonly query: {
+        readonly new_text: {
             readonly type: "string";
-            readonly description: "Required for 'search'. Natural language query to find relevant memories.";
+            readonly description: "For 'replace': the replacement text.";
         };
-        readonly category: {
+        readonly file: {
             readonly type: "string";
-            readonly enum: readonly ["profile", "facts", "media", "projects"];
-            readonly description: string;
+            readonly description: "Filename for file operations (e.g. 'project-notes.md', 'lesson-esbuild.md'). Must be kebab-case .md.";
+        };
+        readonly query: {
+            readonly type: "string";
+            readonly description: "For 'search': natural language query to find relevant memories.";
         };
     };
     readonly required: readonly ["action"];
 };
 export declare const MEMORY_TOOL_DESCRIPTION: string;
-export declare const MEMORY_TOOL_LABEL = "Memory";
 export declare function isMemoryContentSafe(text: string): boolean;
 export interface MemoryToolParams {
     action: MemoryToolAction;
-    target?: MemoryStoreTarget;
     content?: string;
     old_text?: string;
+    new_text?: string;
+    file?: string;
     query?: string;
-    category?: "profile" | "facts" | "media" | "projects";
 }
 export interface MemoryToolResult {
     ok: boolean;
     message: string;
     action: string;
-    /** For MD store operations: live entry count */
-    entryCount?: number;
-    /** For MD store operations: usage string */
-    usage?: string;
-    /** For search: qmemory results */
     results?: MemorySearchResult[];
-    /** Indicates MD store was mutated (consumer should persist) */
-    storeModified?: boolean;
-    errorCode?: string;
 }
 export interface MemoryToolExecutorDeps {
-    /** QMemory provider for semantic search. */
-    provider: MemoryProvider;
-    /** Local MD memory store for notes. */
-    store?: MemoryStore;
+    memdir: Memdir;
+    provider?: MemoryProvider;
     userId: string;
-    sessionId?: string;
-    /** Query recalled facts/memories by natural language. */
-    queryGraph?: (query: string, userId: string) => string[];
-    /** Retrieve user profile summary. */
-    getProfileSummary?: (userId: string) => string | null;
-    /** Retrieve media preferences. */
-    getMediaPreferences?: (userId: string) => MediaPreferencesSummary | null;
 }
 export declare function executeMemoryTool(params: MemoryToolParams, deps: MemoryToolExecutorDeps): Promise<MemoryToolResult>;