clawvault 3.1.0 → 3.2.1

package/dist/lib/webdav.d.ts

@@ -0,0 +1,109 @@
+import * as fs from 'fs';
+import { IncomingMessage, ServerResponse } from 'http';
+
+/**
+ * WebDAV Handler for ClawVault
+ *
+ * Implements WebDAV protocol support for Obsidian mobile sync via Remotely Save plugin.
+ * Uses only Node built-in modules (http, fs, path) - zero external dependencies.
+ *
+ * Supported methods:
+ * - GET: Serve file contents
+ * - PUT: Write/create file (creates parent dirs if needed)
+ * - DELETE: Delete file or directory
+ * - MKCOL: Create directory
+ * - PROPFIND: List directory contents or file properties (XML response)
+ * - OPTIONS: Return allowed methods + DAV header
+ * - HEAD: File metadata without body
+ * - MOVE: Rename/move file (uses Destination header)
+ * - COPY: Copy file
+ */
+
+interface WebDAVConfig {
+    /** Root path for WebDAV files (vault path) */
+    rootPath: string;
+    /** URL prefix for WebDAV routes (default: /webdav) */
+    prefix?: string;
+    /** Optional Basic Auth credentials */
+    auth?: {
+        username: string;
+        password: string;
+    };
+}
+interface WebDAVRequest {
+    method: string;
+    path: string;
+    headers: Record<string, string | string[] | undefined>;
+    body?: string;
+}
+interface WebDAVResponse {
+    status: number;
+    headers: Record<string, string>;
+    body?: string;
+}
+declare const WEBDAV_PREFIX = "/webdav";
+/**
+ * Check if a path is safe (no traversal attacks, not blocked)
+ */
+declare function isPathSafe(requestPath: string, rootPath: string): boolean;
+/**
+ * Resolve a WebDAV path to filesystem path
+ */
+declare function resolveWebDAVPath(requestPath: string, rootPath: string): string | null;
+/**
+ * Check Basic Auth credentials
+ */
+declare function checkAuth(req: IncomingMessage, auth?: {
+    username: string;
+    password: string;
+}): boolean;
+/**
+ * Generate full PROPFIND response XML
+ */
+declare function generatePropfindResponse(entries: Array<{
+    href: string;
+    stats: fs.Stats | null;
+    isCollection: boolean;
+}>): string;
+/**
+ * Handle OPTIONS request
+ */
+declare function handleOptions(res: ServerResponse, prefix: string): void;
+/**
+ * Handle HEAD request
+ */
+declare function handleHead(res: ServerResponse, filePath: string): void;
+/**
+ * Handle GET request
+ */
+declare function handleGet(res: ServerResponse, filePath: string): void;
+/**
+ * Handle PUT request
+ */
+declare function handlePut(res: ServerResponse, filePath: string, body: Buffer): void;
+/**
+ * Handle DELETE request
+ */
+declare function handleDelete(res: ServerResponse, filePath: string): void;
+/**
+ * Handle MKCOL request (create directory)
+ */
+declare function handleMkcol(res: ServerResponse, filePath: string): void;
+/**
+ * Handle PROPFIND request
+ */
+declare function handlePropfind(res: ServerResponse, filePath: string, webdavPath: string, prefix: string, depth: string): void;
+/**
+ * Handle MOVE request
+ */
+declare function handleMove(res: ServerResponse, sourcePath: string, destinationPath: string | null, overwrite: boolean): void;
+/**
+ * Handle COPY request
+ */
+declare function handleCopy(res: ServerResponse, sourcePath: string, destinationPath: string | null, overwrite: boolean): void;
+/**
+ * Create WebDAV request handler
+ */
+declare function createWebDAVHandler(config: WebDAVConfig): (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
+
+export { WEBDAV_PREFIX, type WebDAVConfig, type WebDAVRequest, type WebDAVResponse, checkAuth, createWebDAVHandler, generatePropfindResponse, handleCopy, handleDelete, handleGet, handleHead, handleMkcol, handleMove, handleOptions, handlePropfind, handlePut, isPathSafe, resolveWebDAVPath };

package/dist/lib/webdav.js

@@ -0,0 +1,35 @@
+import {
+  WEBDAV_PREFIX,
+  checkAuth,
+  createWebDAVHandler,
+  generatePropfindResponse,
+  handleCopy,
+  handleDelete,
+  handleGet,
+  handleHead,
+  handleMkcol,
+  handleMove,
+  handleOptions,
+  handlePropfind,
+  handlePut,
+  isPathSafe,
+  resolveWebDAVPath
+} from "../chunk-IVRIKYFE.js";
+import "../chunk-U67V476Y.js";
+export {
+  WEBDAV_PREFIX,
+  checkAuth,
+  createWebDAVHandler,
+  generatePropfindResponse,
+  handleCopy,
+  handleDelete,
+  handleGet,
+  handleHead,
+  handleMkcol,
+  handleMove,
+  handleOptions,
+  handlePropfind,
+  handlePut,
+  isPathSafe,
+  resolveWebDAVPath
+};

package/dist/plugin/index.d.ts

@@ -1,36 +1,352 @@
-import { TemplateRegistry } from './templates.js';
-export { classifyText, getAllSchemas, getSchema, getSchemaNames, initializeTemplateRegistry } from './templates.js';
-export { detectCategory, extractObservations, extractSearchTerms, isObservable, processMessageForObservations } from './observe.js';
-export { buildFullContext, buildPreferenceContext, buildSessionRecap, formatMemoriesForContext, formatSearchResults, scanVaultFiles } from './inject.js';
-export { appendToLedger, batchWriteObservations, ensureVaultStructure, writeObservation, writeVaultFile } from './vault.js';
+/**
+ * ClawVault Plugin v2 — Type definitions
+ */
+interface FieldDef {
+    type: 'string' | 'number' | 'boolean' | 'datetime' | 'date';
+    required?: boolean;
+    default?: string | number | boolean;
+    enum?: string[];
+    description?: string;
+}
+interface TemplateSchema {
+    primitive: string;
+    description?: string;
+    fields: Record<string, FieldDef>;
+    bodyTemplate?: string;
+    keywords?: string[];
+}
+interface TemplateRegistry {
+    schemas: Map<string, TemplateSchema>;
+    keywordIndex: Map<string, string[]>;
+    initialized: boolean;
+}
+interface ClassificationResult {
+    primitiveType: string;
+    confidence: number;
+    matchedKeywords: string[];
+}
+interface Observation {
+    text: string;
+    primitiveType: string;
+    confidence: number;
+    matchedKeywords: string[];
+    category: string;
+    tags: string[];
+    extractedAt: Date;
+}
+interface ObservationResult {
+    observations: Observation[];
+    skipped: number;
+    reason?: string;
+}
+interface VaultFile {
+    path: string;
+    relativePath: string;
+    primitiveType: string;
+    frontmatter: Record<string, unknown>;
+    content: string;
+    modifiedAt: Date;
+    createdAt: Date;
+}
+interface WriteResult {
+    success: boolean;
+    path: string;
+    primitiveType: string;
+    errors: string[];
+    created: boolean;
+    updated: boolean;
+}
+interface WriteOptions {
+    primitiveType?: string;
+    title?: string;
+    content?: string;
+    extraFields?: Record<string, unknown>;
+    source?: string;
+    sessionId?: string;
+    directory?: string;
+    filename?: string;
+    overwrite?: boolean;
+}
+interface LedgerEntry {
+    timestamp: Date;
+    category?: string;
+    actor?: string;
+    content: string;
+    primitiveType?: string;
+    tags?: string[];
+}
+interface BatchWriteOptions {
+    source?: string;
+    sessionId?: string;
+    actor?: string;
+    writeLedger?: boolean;
+    writeFiles?: boolean;
+}
+interface BatchWriteResult {
+    total: number;
+    successful: number;
+    failed: number;
+    results: WriteResult[];
+}
+interface ScanOptions {
+    maxAge?: number;
+    limit?: number;
+    primitiveTypes?: string[];
+}
+interface SessionRecapResult {
+    xml: string;
+    fileCount: number;
+    primitiveGroups: Record<string, number>;
+    timeRange: {
+        oldest: Date;
+        newest: Date;
+    } | null;
+}
+interface PreferenceContextResult {
+    xml: string;
+    preferenceCount: number;
+    categories: string[];
+}
+interface QmdResult {
+    file?: string;
+    title?: string;
+    snippet?: string;
+    score?: number;
+}
+type MemoryScope = 'global' | `agent:${string}` | `project:${string}` | `user:${string}`;
+interface RetrievalConfig {
+    /** BM25 weight in RRF fusion (default: 0.5) */
+    bm25Weight: number;
+    /** Semantic weight in RRF fusion (default: 0.5) */
+    semanticWeight: number;
+    /** RRF k parameter (default: 60) */
+    rrfK: number;
+    /** Max results to return (default: 10) */
+    topK: number;
+    /** Minimum score threshold (default: 0.01) */
+    minScore: number;
+    /** Recency boost half-life in days (default: 14, 0 = disabled) */
+    recencyHalfLifeDays: number;
+    /** Recency boost weight (default: 0.10) */
+    recencyWeight: number;
+    /** Time decay half-life in days (default: 60, 0 = disabled) */
+    decayHalfLifeDays: number;
+    /** Length normalization anchor in chars (default: 500, 0 = disabled) */
+    lengthNormAnchor: number;
+    /** MMR lambda for diversity (default: 0.7, 1.0 = no diversity) */
+    mmrLambda: number;
+    /** Reranker provider (default: none) */
+    rerankProvider?: 'jina' | 'voyage' | 'siliconflow' | 'pinecone';
+    /** Reranker API key */
+    rerankApiKey?: string;
+    /** Reranker model name */
+    rerankModel?: string;
+    /** Reranker endpoint URL */
+    rerankEndpoint?: string;
+    /** Reranker weight vs fused score (default: 0.6) */
+    rerankWeight: number;
+}
+interface PluginConfig {
+    vaultPath?: string;
+    agentVaults?: Record<string, string>;
+    collection?: string;
+    autoRecall?: boolean;
+    autoCapture?: boolean;
+    recallLimit?: number;
+    templatesDir?: string;
+    autoCheckpoint?: boolean;
+    contextProfile?: 'default' | 'planning' | 'incident' | 'handoff' | 'auto';
+    maxContextResults?: number;
+    observeOnHeartbeat?: boolean;
+    weeklyReflection?: boolean;
+    /** Retrieval pipeline config */
+    retrieval?: Partial<RetrievalConfig>;
+    /** Noise filter config */
+    noise?: {
+        enabled?: boolean;
+        minLength?: number;
+        maxLength?: number;
+    };
+    /** Adaptive retrieval config */
+    adaptive?: {
+        enabled?: boolean;
+        skipPatterns?: string[];
+    };
+    /** Default memory scope */
+    defaultScope?: MemoryScope;
+}
+interface PluginLogger {
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+    debug(msg: string): void;
+}
+interface ToolDefinition {
+    name: string;
+    label: string;
+    description: string;
+    parameters: unknown;
+    execute(id: string, params: Record<string, unknown>): Promise<ToolResult>;
+}
+interface ToolResult {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    details?: Record<string, unknown>;
+    isError?: boolean;
+}
+interface ServiceDefinition {
+    id: string;
+    start: () => void;
+    stop: () => void;
+}
+interface CommandDefinition {
+    name: string;
+    description: string;
+    acceptsArgs?: boolean;
+    requireAuth?: boolean;
+    handler: (ctx: {
+        args?: string;
+    }) => {
+        text: string;
+    };
+}
+type EventHandler = (event: Record<string, unknown>) => Promise<unknown>;
+interface PluginApi {
+    pluginConfig: PluginConfig;
+    logger: PluginLogger;
+    registerTool(tool: ToolDefinition): void;
+    registerService(service: ServiceDefinition): void;
+    registerCommand(command: CommandDefinition): void;
+    registerCli(fn: (ctx: {
+        program: unknown;
+    }) => void, opts?: {
+        commands: string[];
+    }): void;
+    on(event: string, handler: EventHandler, opts?: {
+        priority?: number;
+    }): void;
+}
+interface Plugin {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    kind: string;
+    register(api: PluginApi): void;
+}
 
 /**
- * ClawVault OpenClaw Plugin v2.2.0
+ * ClawVault Plugin v2 — Template engine
  *
- * Memory slot provider for OpenClaw. Template-driven observational memory architecture:
- * memories are captured automatically from conversations, classified against template
- * schemas, and stored with proper frontmatter validation.
+ * Manages typed primitive schemas (memory_event, person, decision, task, etc.)
+ * with keyword-based classification, frontmatter generation, and validation.
+ */
+
+declare function getTemplateRegistry(): TemplateRegistry;
+declare function initializeTemplateRegistry(templatesDir?: string): TemplateRegistry;
+declare function classifyText(text: string): ClassificationResult;
+declare function getSchema(primitiveType: string): TemplateSchema | undefined;
+declare function getAllSchemas(): TemplateSchema[];
+declare function getSchemaNames(): string[];
+
+/**
+ * ClawVault Plugin v2 — Noise Filter
  *
- * Architecture:
- *   ClawVault (engine) ←→ Plugin (integration) ←→ OpenClaw (agent platform)
- *   - ClawVault = vault, observations, search index, knowledge graph
- *   - Plugin = auto-recall, auto-capture, search tools, lifecycle hooks
- *   - OpenClaw = agent runtime, sessions, tools, channels
- *   - Templates = schema definitions for primitive types
+ * Filters low-quality content on both write and read paths:
+ * - Refusals ("I can't help with that")
+ * - Meta-questions ("How does it feel to be an AI?")
+ * - Greetings ("Hello!", "Hi there")
+ * - Low-information content (too short, too repetitive)
+ * - System noise (heartbeats, tool calls, JSON blobs)
+ */
+interface NoiseFilterConfig {
+    enabled: boolean;
+    minLength: number;
+    maxLength: number;
+}
+
+/**
+ * ClawVault Plugin v2 — Observer / Session Parser
  *
- * The plugin does NOT give the agent a "store memory" tool. Memory is
- * observational: the system watches conversations and captures automatically.
- * The agent searches memory; it doesn't manage it.
+ * Extracts observations from conversation messages:
+ * - Detects preferences, decisions, facts, tasks, lessons
+ * - Classifies against template schemas
+ * - Generates tags and categories
  */
 
-declare function getTemplateRegistry(): TemplateRegistry | null;
-declare const clawvaultPlugin: {
-    id: string;
-    name: string;
-    description: string;
-    version: string;
-    kind: "memory";
-    register(api: any): void;
-};
+/**
+ * Check if text is worth observing (not system noise, not too short/long).
+ */
+declare function isObservable(text: string, noiseConfig?: NoiseFilterConfig): boolean;
+declare function extractObservations(text: string): Observation[];
+declare function processMessageForObservations(content: string, _options?: Record<string, unknown>): ObservationResult;
+declare function detectCategory(text: string): string;
+declare function extractSearchTerms(input: string): string;
+
+/**
+ * ClawVault Plugin v2 — Context Injection
+ *
+ * Scans vault files and builds context for session injection:
+ * - Session recaps (recent activity)
+ * - Preference context
+ * - Memory formatting for LLM consumption
+ */
+
+declare function scanVaultFiles(vaultPath: string, options?: ScanOptions): VaultFile[];
+declare function buildSessionRecap(vaultPath: string, options?: {
+    maxAge?: number;
+    limit?: number;
+    includeContent?: boolean;
+}): SessionRecapResult;
+declare function buildPreferenceContext(vaultPath: string, options?: {
+    maxAge?: number;
+    limit?: number;
+}): PreferenceContextResult;
+declare function formatMemoriesForContext(results: QmdResult[], collection: string): string;
+declare function formatSearchResults(results: QmdResult[], collection: string): string;
+declare function buildFullContext(vaultPath: string, options?: {
+    includeRecap?: boolean;
+    includePreferences?: boolean;
+    recapMaxAge?: number;
+    preferenceMaxAge?: number;
+}): string;
+
+/**
+ * ClawVault Plugin v2 — Vault file operations
+ *
+ * Handles writing, updating, and managing vault markdown files:
+ * - Template-based file creation
+ * - Frontmatter merge on update
+ * - Observation writing to individual files and ledger
+ * - Scope tagging for multi-scope support
+ */
+
+declare function writeVaultFile(vaultPath: string, options: WriteOptions): WriteResult;
+declare function writeObservation(vaultPath: string, observation: Observation, options?: {
+    source?: string;
+    sessionId?: string;
+    scope?: MemoryScope;
+}): WriteResult;
+declare function appendToLedger(vaultPath: string, entry: LedgerEntry): void;
+declare function batchWriteObservations(vaultPath: string, observations: Observation[], options?: BatchWriteOptions): BatchWriteResult;
+declare function ensureVaultStructure(vaultPath: string): void;
+
+/**
+ * ClawVault Plugin v2 — Main Entry Point
+ *
+ * OpenClaw memory plugin with:
+ * - Template-driven typed primitives
+ * - In-process hybrid retrieval (BM25 + Semantic + RRF)
+ * - Cross-encoder rerank (optional, API-based)
+ * - Recency boost + time decay
+ * - Length normalization + MMR diversity
+ * - Noise filtering + adaptive retrieval
+ * - Multi-scope support (global, agent, project, user)
+ * - Management CLI (stats, export, import, reembed)
+ */
+
+declare const clawvaultPlugin: Plugin;
 
-export { clawvaultPlugin as default, getTemplateRegistry };
+export { appendToLedger, batchWriteObservations, buildFullContext, buildPreferenceContext, buildSessionRecap, classifyText, clawvaultPlugin as default, detectCategory, ensureVaultStructure, extractObservations, extractSearchTerms, formatMemoriesForContext, formatSearchResults, getAllSchemas, getSchema, getSchemaNames, getTemplateRegistry, initializeTemplateRegistry, isObservable, processMessageForObservations, scanVaultFiles, writeObservation, writeVaultFile };