qlogicagent 2.0.0 → 2.1.0

package/dist/types/skills/memory/memory-write-gate.d.ts

@@ -0,0 +1,46 @@
+import type { MemorySearchResult } from "qlogicagent-runtime-contracts";
+/**
+ * Memory categories for QMemory writes.
+ * Each has different value thresholds and retention policies.
+ */
+export type QMemoryCategory = "lesson" | "preference" | "pattern" | "fact" | "decision" | "skill-learning";
+/**
+ * A candidate memory extracted from a turn.
+ */
+export interface MemoryCandidate {
+    text: string;
+    category: QMemoryCategory;
+    importance: number;
+    tags: string[];
+}
+/**
+ * Extract memory candidates from a completed turn.
+ *
+ * Strategy: scan assistant response for category signal patterns.
+ * This is a fast pattern-based approach (no LLM call needed).
+ * Only extracts segments that match high-value patterns.
+ */
+export declare function extractCandidates(userPrompt: string, assistantResponse: string): MemoryCandidate[];
+/**
+ * Quality gate: filter candidates by minimum importance threshold.
+ */
+export declare function applyQualityGate(candidates: MemoryCandidate[], minImportance?: number): MemoryCandidate[];
+/**
+ * Result of supersedes check for a single candidate.
+ */
+export interface SupersedesCheckResult {
+    candidate: MemoryCandidate;
+    supersedes: string[];
+}
+/**
+ * Check if candidates supersede existing memories.
+ *
+ * Strategy: for each candidate, search QMemory for semantically similar
+ * existing entries. If similarity is high (>0.80) and the candidate is
+ * newer/more specific, mark the old one for supersede.
+ *
+ * @param candidates - Memory candidates to check
+ * @param existingSearch - Function to search existing memories
+ * @returns Candidates with supersedes info
+ */
+export declare function checkSupersedes(candidates: MemoryCandidate[], existingSearch: (query: string) => Promise<MemorySearchResult[]>): Promise<SupersedesCheckResult[]>;

package/dist/types/skills/memory/memory-write-hook.d.ts

@@ -0,0 +1,44 @@
+import type { MemorySearchResult } from "qlogicagent-runtime-contracts";
+import type { ExtractedMemoryItem } from "./qmemory-adapter.js";
+export declare const WRITE_HOOK_CONFIG: {
+    /** Minimum importance to pass the quality gate. */
+    readonly MIN_IMPORTANCE: 0.4;
+    /** Max candidates to write per turn (prevent flood). */
+    readonly MAX_PER_TURN: 3;
+    /** Cooldown between writes (ms) — prevents rapid duplicate writes. */
+    readonly COOLDOWN_MS: 5000;
+};
+export interface MemoryWriteHookDeps {
+    /** Write extracted items to QMemory. */
+    ingestExtracted: (items: ExtractedMemoryItem[], userId: string) => Promise<{
+        memoriesAdded: number;
+    }>;
+    /** Search existing memories (for supersedes check). */
+    searchMemories: (query: string, userId: string) => Promise<MemorySearchResult[]>;
+    /** Remove a superseded memory by ID. */
+    removeMemory?: (memoryId: string) => Promise<boolean>;
+    /** User ID for QMemory writes. */
+    userId: string;
+    /** Logger. */
+    log: {
+        debug(msg: string): void;
+        warn(msg: string): void;
+    };
+}
+/** Per-session state for the write hook. */
+export interface MemoryWriteState {
+    /** Timestamp of last write (for cooldown). */
+    lastWriteAt: number;
+    /** Total memories written this session (for budget). */
+    sessionWrites: number;
+    /** Recent write texts (for intra-session dedup). */
+    recentTexts: Set<string>;
+}
+export declare function createMemoryWriteState(): MemoryWriteState;
+/**
+ * Process a completed turn for memory-worthy content.
+ * Called directly from stdio-server after turn.end (fire-and-forget).
+ *
+ * Pipeline: extract → gate → dedup → supersedes check → write.
+ */
+export declare function processMemoryWriteGate(userPrompt: string, assistantResponse: string, deps: MemoryWriteHookDeps, state: MemoryWriteState): Promise<void>;

package/dist/types/skills/memory/qmemory-adapter.d.ts

@@ -19,6 +19,17 @@ export interface QMemoryAdapterConfig {
     /** Prefix prepended to userId for multi-tenant isolation. */
     userIdPrefix?: string;
 }
+/** Options for triggering a decay cycle. */
+export interface DecayOptions {
+    temporalExpiry?: boolean;
+    stalenessDecay?: boolean;
+    noiseArchival?: boolean;
+}
+/** Result of a decay cycle. */
+export interface DecayResult {
+    decayed: number;
+    archived: number;
+}
 /** Health status returned by qmemory `/v1/health/`. */
 export interface QMemoryHealthStatus {
     status: string;
@@ -40,4 +51,5 @@ export declare function createQMemoryAdapter(config: QMemoryAdapterConfig): Memo
         memoriesAdded: number;
     }>;
     feedback(memoryIds: string[], signal: string, sessionId?: string): Promise<void>;
+    triggerDecay(userId: string, options?: DecayOptions): Promise<DecayResult>;
 };

package/dist/types/skills/memory/recall-category-filter.d.ts

@@ -0,0 +1,54 @@
+import type { QMemoryCategory } from "../../skills/memory/memory-write-gate.js";
+/** Detected query scenario with preferred categories. */
+export interface RecallCategoryHint {
+    /** Detected scenario label. */
+    scenario: QueryScenario;
+    /** Preferred categories for this scenario (ordered by priority). */
+    preferred: QMemoryCategory[];
+    /** Categories to deprioritize (still recalled but scored lower). */
+    deprioritized: QMemoryCategory[];
+    /** Confidence of scenario detection (0.0-1.0). */
+    confidence: number;
+}
+/** Known query scenarios. */
+export type QueryScenario = "coding" | "config" | "conversation" | "learning" | "decision" | "general";
+/**
+ * Detect the query scenario and return category preferences.
+ *
+ * Uses pattern matching on the user query to infer intent.
+ * Returns "general" (no filtering) when confidence is below threshold.
+ *
+ * @param query - User query text
+ * @returns Category hint with preferred/deprioritized categories
+ */
+export declare function detectRecallCategories(query: string): RecallCategoryHint;
+/**
+ * Apply category boost/penalty to a recall score.
+ *
+ * Used by recall hooks to adjust memory scores based on category alignment.
+ *
+ * @param baseScore - Original relevance score (0.0-1.0)
+ * @param memoryCategory - Category of the memory entry (if known)
+ * @param hint - Category hint from detectRecallCategories()
+ * @returns Adjusted score
+ */
+export declare function applyCategoryBoost(baseScore: number, memoryCategory: string | undefined | null, hint: RecallCategoryHint): number;
+/**
+ * Filter and re-rank a list of recalled memories based on category preferences.
+ *
+ * @param memories - Raw recalled memories with optional category
+ * @param hint - Category hint from detectRecallCategories()
+ * @param minScore - Minimum adjusted score to keep (default: 0)
+ * @returns Re-ranked memories (highest adjusted score first)
+ */
+export declare function filterByCategory<T extends {
+    score?: number;
+    category?: string | null;
+}>(memories: T[], hint: RecallCategoryHint, minScore?: number): T[];
+/**
+ * Infer memory category from filename prefix convention.
+ * E.g. "lesson-docker.md" → "lesson", "fact-ports.md" → "fact"
+ *
+ * Exported for use by recall hooks.
+ */
+export declare function inferCategoryFromFilename(filename: string): QMemoryCategory | null;

package/dist/types/skills/tools/skill-tool.d.ts

@@ -1,7 +1,7 @@
 import type { PortableTool } from "../portable-tool.js";
 import type { WorkspaceSkill } from "../skill-system/skill-types.js";
 export declare const SKILL_TOOL_NAME: "skill";
-export type SkillAction = "invoke" | "list" | "view" | "create" | "edit" | "patch" | "delete";
+export type SkillAction = "invoke" | "list" | "view" | "create" | "edit" | "patch" | "delete" | "promote" | "install";
 export interface SkillToolParams {
     action: SkillAction;
     name?: string;
@@ -12,18 +12,20 @@ export interface SkillToolParams {
     fileContent?: string;
     oldString?: string;
     newString?: string;
+    /** URL to download skill from (for 'install' action). */
+    url?: string;
 }
 export declare const SKILL_TOOL_SCHEMA: {
     readonly type: "object";
     readonly properties: {
         readonly action: {
             readonly type: "string";
-            readonly enum: readonly ["invoke", "list", "view", "create", "edit", "patch", "delete"];
+            readonly enum: readonly ["invoke", "list", "view", "create", "edit", "patch", "delete", "promote", "install"];
             readonly description: string;
         };
         readonly name: {
             readonly type: "string";
-            readonly description: "Skill name (required for invoke/view/create/edit/patch/delete).";
+            readonly description: "Skill name (required for invoke/view/create/edit/patch/delete/promote).";
         };
         readonly args: {
             readonly type: "string";
@@ -53,6 +55,10 @@ export declare const SKILL_TOOL_SCHEMA: {
             readonly type: "string";
             readonly description: "Replacement text for patch action.";
         };
+        readonly url: {
+            readonly type: "string";
+            readonly description: "URL to download a skill from (for 'install' action). Supports skill stores (skillhub.cn, skill.io, GitHub raw links, etc.) and any direct .md URL.";
+        };
     };
     readonly required: readonly ["action"];
 };
@@ -61,6 +67,8 @@ export interface SkillListItem {
     description: string;
     version?: string;
     category?: string;
+    /** Where the skill lives: "global" (user-level) or "project" (cwd-level). */
+    scope?: "global" | "project" | "plugin" | "config";
 }
 export interface SkillListOutput {
     skills: SkillListItem[];
@@ -91,11 +99,16 @@ export interface SkillToolDeps {
     manageSkill(params: {
         action: string;
         name: string;
+        category?: string;
         content?: string;
         filePath?: string;
         fileContent?: string;
         oldString?: string;
         newString?: string;
     }): Promise<SkillManageResult>;
+    /** Promote a project-level skill to user/global level. Returns success message. */
+    promoteSkill?(name: string): Promise<SkillManageResult>;
+    /** Install a skill from a URL. Downloads .md content and saves it. */
+    installSkill?(url: string, name?: string): Promise<SkillManageResult>;
 }
 export declare function createSkillMetaTool(deps: SkillToolDeps): PortableTool<SkillToolParams>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qlogicagent",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "XiaozhiClaw Agent CLI — subprocess architecture (JSON-RPC over stdio)",
   "type": "module",
   "main": "dist/index.js",

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

@@ -1,86 +0,0 @@
-export declare const MEMORY_ENTRY_DELIMITER = "\n\u00A7\n";
-export declare const DEFAULT_MEMORY_CHAR_LIMIT = 2200;
-export declare const DEFAULT_USER_CHAR_LIMIT = 1375;
-export type MemoryStoreTarget = "memory" | "user";
-export interface MemoryStoreResult {
-    ok: boolean;
-    message: string;
-    target: MemoryStoreTarget;
-    entries: readonly string[];
-    entryCount: number;
-    usage: string;
-    errorCode?: string;
-}
-export interface MemoryStoreOptions {
-    memoryCharLimit?: number;
-    userCharLimit?: number;
-    /** When true, mutations automatically persist to ~/.qlogicagent/memory.json */
-    persistToDisk?: boolean;
-}
-export interface MemoryStoreSerialized {
-    memory: string;
-    user: string;
-}
-export declare class MemoryStore {
-    private memoryEntries;
-    private userEntries;
-    private frozenSnapshot;
-    private snapshotFrozen;
-    private saveTimer;
-    private readonly memoryCharLimit;
-    private readonly userCharLimit;
-    private readonly persistToDisk;
-    constructor(options?: MemoryStoreOptions);
-    /**
-     * Load from serialized form (e.g. from PG or filesystem).
-     * Deduplicates entries on load.
-     */
-    loadFromSerialized(data: Partial<MemoryStoreSerialized>): void;
-    /**
-     * Serialize current live state for persistence.
-     */
-    serialize(): MemoryStoreSerialized;
-    /**
-     * Load from disk (~/.qlogicagent/memory.json). No-op if file doesn't exist.
-     * Call this at startup when persistToDisk is enabled.
-     */
-    loadFromDisk(): Promise<void>;
-    /**
-     * Synchronous variant for use in sync constructors / init paths.
-     */
-    loadFromDiskSync(): void;
-    /**
-     * Schedule a debounced save to disk (500ms). Multiple rapid mutations
-     * coalesce into a single disk write.
-     */
-    private scheduleSave;
-    /** Flush any pending save immediately. Call before shutdown. */
-    flush(): Promise<void>;
-    /**
-     * Freeze current entries for system prompt injection.
-     * Call once at session start. After freezing, mutations update
-     * live state but NOT the system prompt block.
-     */
-    freezeSnapshot(): void;
-    /**
-     * Get frozen system prompt block for the given target.
-     * Returns empty string if no entries or not yet frozen.
-     */
-    getSystemPromptBlock(target: MemoryStoreTarget): string;
-    add(target: MemoryStoreTarget, content: string): MemoryStoreResult;
-    replace(target: MemoryStoreTarget, oldText: string, newContent: string): MemoryStoreResult;
-    remove(target: MemoryStoreTarget, oldText: string): MemoryStoreResult;
-    getEntries(target: MemoryStoreTarget): readonly string[];
-    getUsage(target: MemoryStoreTarget): {
-        used: number;
-        limit: number;
-        percent: number;
-    };
-    isEmpty(): boolean;
-    private entriesFor;
-    private charLimitFor;
-    private formatUsage;
-    private renderBlock;
-    private successResult;
-    private errorResult;
-}

package/dist/types/skills/tools/skill-invoke-tool.d.ts

@@ -1,46 +0,0 @@
-import type { PortableTool } from "../portable-tool.js";
-import type { WorkspaceSkill } from "../skill-system/skill-types.js";
-export declare const SKILL_TOOL_NAME: "skill_invoke";
-export interface SkillInvokeParams {
-    skill: string;
-    args?: string;
-}
-export declare const SKILL_INVOKE_SCHEMA: {
-    readonly type: "object";
-    readonly properties: {
-        readonly skill: {
-            readonly type: "string";
-            readonly description: "Name of the skill to invoke. Use skill_list to see available skills.";
-        };
-        readonly args: {
-            readonly type: "string";
-            readonly description: string;
-        };
-    };
-    readonly required: readonly ["skill"];
-};
-export interface SkillToolDeps {
-    /**
-     * Get all available skills (Layer 0 metadata).
-     * Returns name + description pairs for tool manifest enrichment.
-     */
-    listSkills(): WorkspaceSkill[];
-    /**
-     * Read skill content (Layer 1 instructions).
-     * Returns the full SKILL.md content for the named skill.
-     * Returns null if skill not found.
-     */
-    readSkillContent(name: string): Promise<string | null>;
-    /**
-     * Execute the skill instructions as a sub-turn.
-     * The implementation should:
-     *   1. Build system prompt from SKILL.md content
-     *   2. Run a sub-turn (fork) with skill instructions
-     *   3. Return the sub-turn's final response
-     *
-     * If not provided, the skill content is returned directly
-     * (the LLM can then follow the instructions in context).
-     */
-    executeSkillSubturn?(skillName: string, skillContent: string, userArgs: string | undefined, signal?: AbortSignal): Promise<string>;
-}
-export declare function createSkillTool(deps: SkillToolDeps): PortableTool<SkillInvokeParams>;

package/dist/types/skills/tools/skill-list-tool.d.ts

@@ -1,33 +0,0 @@
-import type { PortableTool } from "../portable-tool.js";
-export declare const SKILL_LIST_TOOL_NAME: "skill_list";
-export interface SkillListToolParams {
-    category?: string;
-}
-export declare const SKILL_LIST_TOOL_SCHEMA: {
-    readonly type: "object";
-    readonly properties: {
-        readonly category: {
-            readonly type: "string";
-            readonly description: "Filter skills by category (e.g. 'devops', 'mlops'). Omit to list all.";
-        };
-    };
-    readonly required: readonly [];
-};
-export interface SkillListItem {
-    name: string;
-    description: string;
-    version?: string;
-    category?: string;
-}
-export interface SkillListOutput {
-    skills: SkillListItem[];
-    categories: string[];
-}
-/**
- * Host-provided skill registry for listing.
- */
-export interface SkillListToolDeps {
-    /** List all available skills, optionally filtered by category. */
-    listSkills(category?: string): Promise<SkillListOutput>;
-}
-export declare function createSkillListTool(deps: SkillListToolDeps): PortableTool<SkillListToolParams>;

package/dist/types/skills/tools/skill-manage-tool.d.ts

@@ -1,73 +0,0 @@
-import type { PortableTool } from "../portable-tool.js";
-export declare const SKILL_MANAGE_TOOL_NAME: "skill_manage";
-export type SkillManageAction = "create" | "edit" | "patch" | "delete" | "write_file" | "remove_file";
-export interface SkillManageToolParams {
-    action: SkillManageAction;
-    name: string;
-    content?: string;
-    category?: string;
-    filePath?: string;
-    fileContent?: string;
-    oldString?: string;
-    newString?: string;
-}
-export declare const SKILL_MANAGE_TOOL_SCHEMA: {
-    readonly type: "object";
-    readonly properties: {
-        readonly action: {
-            readonly type: "string";
-            readonly enum: readonly ["create", "edit", "patch", "delete", "write_file", "remove_file"];
-            readonly description: string;
-        };
-        readonly name: {
-            readonly type: "string";
-            readonly description: "Skill name (lowercase, max 64 chars, kebab-case: letters, digits, hyphens).";
-        };
-        readonly content: {
-            readonly type: "string";
-            readonly description: string;
-        };
-        readonly category: {
-            readonly type: "string";
-            readonly description: "Category/domain (e.g. 'devops', 'mlops'). Used by create to organize skills.";
-        };
-        readonly filePath: {
-            readonly type: "string";
-            readonly description: string;
-        };
-        readonly fileContent: {
-            readonly type: "string";
-            readonly description: "Content for write_file action. Max 1 MiB.";
-        };
-        readonly oldString: {
-            readonly type: "string";
-            readonly description: "Text to find for patch action (must match uniquely in SKILL.md).";
-        };
-        readonly newString: {
-            readonly type: "string";
-            readonly description: "Replacement text for patch action (can be empty to delete).";
-        };
-    };
-    readonly required: readonly ["action", "name"];
-};
-export interface SkillManageResult {
-    success: boolean;
-    message: string;
-    path?: string;
-}
-/**
- * Host-provided skill management backend.
- */
-export interface SkillManageToolDeps {
-    /**
-     * Execute a skill management action.
-     * The host handles file system operations, validation, and security scanning.
-     */
-    manageSkill(params: SkillManageToolParams): Promise<SkillManageResult>;
-    /**
-     * Validate skill name format.
-     * If not provided, tool uses built-in validation.
-     */
-    validateName?(name: string): string | null;
-}
-export declare function createSkillManageTool(deps: SkillManageToolDeps): PortableTool<SkillManageToolParams>;

package/dist/types/skills/tools/skill-view-tool.d.ts

@@ -1,37 +0,0 @@
-import type { PortableTool } from "../portable-tool.js";
-export declare const SKILL_VIEW_TOOL_NAME: "skill_view";
-export interface SkillViewToolParams {
-    name: string;
-    filePath?: string;
-}
-export declare const SKILL_VIEW_TOOL_SCHEMA: {
-    readonly type: "object";
-    readonly properties: {
-        readonly name: {
-            readonly type: "string";
-            readonly description: "Skill name to view (e.g. 'code-review', 'deploy-ecs').";
-        };
-        readonly filePath: {
-            readonly type: "string";
-            readonly description: string;
-        };
-    };
-    readonly required: readonly ["name"];
-};
-export interface SkillViewOutput {
-    name: string;
-    content: string;
-    referenceFiles?: string[];
-    tags?: string[];
-}
-/**
- * Host-provided skill viewer.
- */
-export interface SkillViewToolDeps {
-    /**
-     * Read skill content. Returns the main SKILL.md or a specific file.
-     * Returns null if skill not found.
-     */
-    viewSkill(name: string, filePath?: string): Promise<SkillViewOutput | null>;
-}
-export declare function createSkillViewTool(deps: SkillViewToolDeps): PortableTool<SkillViewToolParams>;