@plur-ai/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,600 @@
+import { z } from 'zod';
+
+declare const KnowledgeAnchorSchema: z.ZodObject<{
+    path: z.ZodString;
+    relevance: z.ZodDefault<z.ZodEnum<["primary", "supporting", "example"]>>;
+    snippet: z.ZodOptional<z.ZodString>;
+    snippet_extracted_at: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    relevance: "primary" | "supporting" | "example";
+    snippet?: string | undefined;
+    snippet_extracted_at?: string | undefined;
+}, {
+    path: string;
+    relevance?: "primary" | "supporting" | "example" | undefined;
+    snippet?: string | undefined;
+    snippet_extracted_at?: string | undefined;
+}>;
+declare const AssociationSchema: z.ZodObject<{
+    target_type: z.ZodEnum<["engram", "document"]>;
+    target: z.ZodString;
+    strength: z.ZodNumber;
+    type: z.ZodEnum<["semantic", "temporal", "causal", "co_accessed"]>;
+    updated_at: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "semantic" | "temporal" | "causal" | "co_accessed";
+    target_type: "engram" | "document";
+    target: string;
+    strength: number;
+    updated_at?: string | undefined;
+}, {
+    type: "semantic" | "temporal" | "causal" | "co_accessed";
+    target_type: "engram" | "document";
+    target: string;
+    strength: number;
+    updated_at?: string | undefined;
+}>;
+declare const EngramSchema: z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodDefault<z.ZodNumber>;
+    status: z.ZodEnum<["active", "dormant", "retired", "candidate"]>;
+    consolidated: z.ZodDefault<z.ZodBoolean>;
+    type: z.ZodEnum<["behavioral", "terminological", "procedural", "architectural"]>;
+    scope: z.ZodString;
+    visibility: z.ZodDefault<z.ZodEnum<["private", "public", "template"]>>;
+    statement: z.ZodString;
+    rationale: z.ZodOptional<z.ZodString>;
+    contraindications: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    source_patterns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    derivation_count: z.ZodDefault<z.ZodNumber>;
+    knowledge_type: z.ZodOptional<z.ZodObject<{
+        memory_class: z.ZodEnum<["semantic", "episodic", "procedural", "metacognitive"]>;
+        cognitive_level: z.ZodEnum<["remember", "understand", "apply", "analyze", "evaluate", "create"]>;
+    }, "strip", z.ZodTypeAny, {
+        memory_class: "procedural" | "semantic" | "episodic" | "metacognitive";
+        cognitive_level: "remember" | "understand" | "apply" | "analyze" | "evaluate" | "create";
+    }, {
+        memory_class: "procedural" | "semantic" | "episodic" | "metacognitive";
+        cognitive_level: "remember" | "understand" | "apply" | "analyze" | "evaluate" | "create";
+    }>>;
+    domain: z.ZodOptional<z.ZodString>;
+    relations: z.ZodOptional<z.ZodObject<{
+        broader: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        narrower: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        related: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        conflicts: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        broader: string[];
+        narrower: string[];
+        related: string[];
+        conflicts: string[];
+    }, {
+        broader?: string[] | undefined;
+        narrower?: string[] | undefined;
+        related?: string[] | undefined;
+        conflicts?: string[] | undefined;
+    }>>;
+    activation: z.ZodDefault<z.ZodObject<{
+        retrieval_strength: z.ZodNumber;
+        storage_strength: z.ZodNumber;
+        frequency: z.ZodNumber;
+        last_accessed: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        retrieval_strength: number;
+        storage_strength: number;
+        frequency: number;
+        last_accessed: string;
+    }, {
+        retrieval_strength: number;
+        storage_strength: number;
+        frequency: number;
+        last_accessed: string;
+    }>>;
+    provenance: z.ZodOptional<z.ZodObject<{
+        origin: z.ZodString;
+        chain: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        signature: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        license: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        origin: string;
+        chain: string[];
+        signature: string | null;
+        license: string;
+    }, {
+        origin: string;
+        chain?: string[] | undefined;
+        signature?: string | null | undefined;
+        license?: string | undefined;
+    }>>;
+    feedback_signals: z.ZodDefault<z.ZodObject<{
+        positive: z.ZodDefault<z.ZodNumber>;
+        negative: z.ZodDefault<z.ZodNumber>;
+        neutral: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        positive: number;
+        negative: number;
+        neutral: number;
+    }, {
+        positive?: number | undefined;
+        negative?: number | undefined;
+        neutral?: number | undefined;
+    }>>;
+    knowledge_anchors: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        relevance: z.ZodDefault<z.ZodEnum<["primary", "supporting", "example"]>>;
+        snippet: z.ZodOptional<z.ZodString>;
+        snippet_extracted_at: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        relevance: "primary" | "supporting" | "example";
+        snippet?: string | undefined;
+        snippet_extracted_at?: string | undefined;
+    }, {
+        path: string;
+        relevance?: "primary" | "supporting" | "example" | undefined;
+        snippet?: string | undefined;
+        snippet_extracted_at?: string | undefined;
+    }>, "many">>;
+    associations: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        target_type: z.ZodEnum<["engram", "document"]>;
+        target: z.ZodString;
+        strength: z.ZodNumber;
+        type: z.ZodEnum<["semantic", "temporal", "causal", "co_accessed"]>;
+        updated_at: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "semantic" | "temporal" | "causal" | "co_accessed";
+        target_type: "engram" | "document";
+        target: string;
+        strength: number;
+        updated_at?: string | undefined;
+    }, {
+        type: "semantic" | "temporal" | "causal" | "co_accessed";
+        target_type: "engram" | "document";
+        target: string;
+        strength: number;
+        updated_at?: string | undefined;
+    }>, "many">>;
+    dual_coding: z.ZodOptional<z.ZodEffects<z.ZodObject<{
+        example: z.ZodOptional<z.ZodString>;
+        analogy: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        example?: string | undefined;
+        analogy?: string | undefined;
+    }, {
+        example?: string | undefined;
+        analogy?: string | undefined;
+    }>, {
+        example?: string | undefined;
+        analogy?: string | undefined;
+    }, {
+        example?: string | undefined;
+        analogy?: string | undefined;
+    }>>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    pack: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    abstract: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    derived_from: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    type: "behavioral" | "architectural" | "procedural" | "terminological";
+    status: "active" | "dormant" | "retired" | "candidate";
+    id: string;
+    version: number;
+    consolidated: boolean;
+    scope: string;
+    visibility: "private" | "public" | "template";
+    statement: string;
+    derivation_count: number;
+    activation: {
+        retrieval_strength: number;
+        storage_strength: number;
+        frequency: number;
+        last_accessed: string;
+    };
+    feedback_signals: {
+        positive: number;
+        negative: number;
+        neutral: number;
+    };
+    knowledge_anchors: {
+        path: string;
+        relevance: "primary" | "supporting" | "example";
+        snippet?: string | undefined;
+        snippet_extracted_at?: string | undefined;
+    }[];
+    associations: {
+        type: "semantic" | "temporal" | "causal" | "co_accessed";
+        target_type: "engram" | "document";
+        target: string;
+        strength: number;
+        updated_at?: string | undefined;
+    }[];
+    tags: string[];
+    pack: string | null;
+    abstract: string | null;
+    derived_from: string | null;
+    rationale?: string | undefined;
+    contraindications?: string[] | undefined;
+    source_patterns?: string[] | undefined;
+    knowledge_type?: {
+        memory_class: "procedural" | "semantic" | "episodic" | "metacognitive";
+        cognitive_level: "remember" | "understand" | "apply" | "analyze" | "evaluate" | "create";
+    } | undefined;
+    domain?: string | undefined;
+    relations?: {
+        broader: string[];
+        narrower: string[];
+        related: string[];
+        conflicts: string[];
+    } | undefined;
+    provenance?: {
+        origin: string;
+        chain: string[];
+        signature: string | null;
+        license: string;
+    } | undefined;
+    dual_coding?: {
+        example?: string | undefined;
+        analogy?: string | undefined;
+    } | undefined;
+}, {
+    type: "behavioral" | "architectural" | "procedural" | "terminological";
+    status: "active" | "dormant" | "retired" | "candidate";
+    id: string;
+    scope: string;
+    statement: string;
+    version?: number | undefined;
+    consolidated?: boolean | undefined;
+    visibility?: "private" | "public" | "template" | undefined;
+    rationale?: string | undefined;
+    contraindications?: string[] | undefined;
+    source_patterns?: string[] | undefined;
+    derivation_count?: number | undefined;
+    knowledge_type?: {
+        memory_class: "procedural" | "semantic" | "episodic" | "metacognitive";
+        cognitive_level: "remember" | "understand" | "apply" | "analyze" | "evaluate" | "create";
+    } | undefined;
+    domain?: string | undefined;
+    relations?: {
+        broader?: string[] | undefined;
+        narrower?: string[] | undefined;
+        related?: string[] | undefined;
+        conflicts?: string[] | undefined;
+    } | undefined;
+    activation?: {
+        retrieval_strength: number;
+        storage_strength: number;
+        frequency: number;
+        last_accessed: string;
+    } | undefined;
+    provenance?: {
+        origin: string;
+        chain?: string[] | undefined;
+        signature?: string | null | undefined;
+        license?: string | undefined;
+    } | undefined;
+    feedback_signals?: {
+        positive?: number | undefined;
+        negative?: number | undefined;
+        neutral?: number | undefined;
+    } | undefined;
+    knowledge_anchors?: {
+        path: string;
+        relevance?: "primary" | "supporting" | "example" | undefined;
+        snippet?: string | undefined;
+        snippet_extracted_at?: string | undefined;
+    }[] | undefined;
+    associations?: {
+        type: "semantic" | "temporal" | "causal" | "co_accessed";
+        target_type: "engram" | "document";
+        target: string;
+        strength: number;
+        updated_at?: string | undefined;
+    }[] | undefined;
+    dual_coding?: {
+        example?: string | undefined;
+        analogy?: string | undefined;
+    } | undefined;
+    tags?: string[] | undefined;
+    pack?: string | null | undefined;
+    abstract?: string | null | undefined;
+    derived_from?: string | null | undefined;
+}>;
+type Engram = z.infer<typeof EngramSchema>;
+type KnowledgeAnchor = z.infer<typeof KnowledgeAnchorSchema>;
+type Association = z.infer<typeof AssociationSchema>;
+
+declare const PackManifestSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    creator: z.ZodOptional<z.ZodString>;
+    license: z.ZodDefault<z.ZodString>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        injection_policy: z.ZodDefault<z.ZodEnum<["on_match", "on_request", "always"]>>;
+        match_terms: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        domain: z.ZodOptional<z.ZodString>;
+        engram_count: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        injection_policy: "on_match" | "on_request" | "always";
+        match_terms: string[];
+        id?: string | undefined;
+        domain?: string | undefined;
+        engram_count?: number | undefined;
+    }, {
+        id?: string | undefined;
+        domain?: string | undefined;
+        injection_policy?: "on_match" | "on_request" | "always" | undefined;
+        match_terms?: string[] | undefined;
+        engram_count?: number | undefined;
+    }>>;
+    'x-datacore': z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        injection_policy: z.ZodEnum<["on_match", "on_request"]>;
+        match_terms: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        domain: z.ZodOptional<z.ZodString>;
+        engram_count: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        injection_policy: "on_match" | "on_request";
+        match_terms: string[];
+        engram_count: number;
+        domain?: string | undefined;
+    }, {
+        id: string;
+        injection_policy: "on_match" | "on_request";
+        engram_count: number;
+        domain?: string | undefined;
+        match_terms?: string[] | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    license: string;
+    tags: string[];
+    name: string;
+    description?: string | undefined;
+    creator?: string | undefined;
+    metadata?: {
+        injection_policy: "on_match" | "on_request" | "always";
+        match_terms: string[];
+        id?: string | undefined;
+        domain?: string | undefined;
+        engram_count?: number | undefined;
+    } | undefined;
+    'x-datacore'?: {
+        id: string;
+        injection_policy: "on_match" | "on_request";
+        match_terms: string[];
+        engram_count: number;
+        domain?: string | undefined;
+    } | undefined;
+}, {
+    version: string;
+    name: string;
+    license?: string | undefined;
+    tags?: string[] | undefined;
+    description?: string | undefined;
+    creator?: string | undefined;
+    metadata?: {
+        id?: string | undefined;
+        domain?: string | undefined;
+        injection_policy?: "on_match" | "on_request" | "always" | undefined;
+        match_terms?: string[] | undefined;
+        engram_count?: number | undefined;
+    } | undefined;
+    'x-datacore'?: {
+        id: string;
+        injection_policy: "on_match" | "on_request";
+        engram_count: number;
+        domain?: string | undefined;
+        match_terms?: string[] | undefined;
+    } | undefined;
+}>;
+type PackManifest = z.infer<typeof PackManifestSchema>;
+
+interface PackInfo {
+    name: string;
+    path: string;
+    engram_count: number;
+    manifest?: PackManifest;
+}
+declare function listPacks(packsDir: string): PackInfo[];
+
+declare const EpisodeSchema: z.ZodObject<{
+    id: z.ZodString;
+    summary: z.ZodString;
+    agent: z.ZodOptional<z.ZodString>;
+    channel: z.ZodOptional<z.ZodString>;
+    session_id: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    timestamp: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    summary: string;
+    timestamp: string;
+    tags?: string[] | undefined;
+    agent?: string | undefined;
+    channel?: string | undefined;
+    session_id?: string | undefined;
+}, {
+    id: string;
+    summary: string;
+    timestamp: string;
+    tags?: string[] | undefined;
+    agent?: string | undefined;
+    channel?: string | undefined;
+    session_id?: string | undefined;
+}>;
+type Episode = z.infer<typeof EpisodeSchema>;
+
+declare const PlurConfigSchema: z.ZodObject<{
+    auto_learn: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    auto_capture: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    injection_budget: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    decay_enabled: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    decay_threshold: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    packs: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString, "many">>>;
+    injection: z.ZodOptional<z.ZodDefault<z.ZodObject<{
+        spread_cap: z.ZodDefault<z.ZodNumber>;
+        spread_budget: z.ZodDefault<z.ZodNumber>;
+        co_access: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        spread_cap: number;
+        spread_budget: number;
+        co_access: boolean;
+    }, {
+        spread_cap?: number | undefined;
+        spread_budget?: number | undefined;
+        co_access?: boolean | undefined;
+    }>>>;
+}, "strip", z.ZodTypeAny, {
+    auto_learn?: boolean | undefined;
+    auto_capture?: boolean | undefined;
+    injection_budget?: number | undefined;
+    decay_enabled?: boolean | undefined;
+    decay_threshold?: number | undefined;
+    packs?: string[] | undefined;
+    injection?: {
+        spread_cap: number;
+        spread_budget: number;
+        co_access: boolean;
+    } | undefined;
+}, {
+    auto_learn?: boolean | undefined;
+    auto_capture?: boolean | undefined;
+    injection_budget?: number | undefined;
+    decay_enabled?: boolean | undefined;
+    decay_threshold?: number | undefined;
+    packs?: string[] | undefined;
+    injection?: {
+        spread_cap?: number | undefined;
+        spread_budget?: number | undefined;
+        co_access?: boolean | undefined;
+    } | undefined;
+}>;
+type PlurConfig = z.infer<typeof PlurConfigSchema>;
+
+interface LearnContext {
+    type?: 'behavioral' | 'terminological' | 'procedural' | 'architectural';
+    scope?: string;
+    domain?: string;
+    source?: string;
+}
+/**
+ * Function that calls an LLM. Model-agnostic — consumer provides this.
+ * Takes a prompt, returns the LLM's text response.
+ */
+type LlmFunction = (prompt: string) => Promise<string>;
+interface RecallOptions {
+    scope?: string;
+    domain?: string;
+    limit?: number;
+    min_strength?: number;
+    /** Search mode: 'fast' (BM25, default) or 'agentic' (LLM-assisted semantic search) */
+    mode?: 'fast' | 'agentic';
+    /** LLM function for agentic mode. Required when mode='agentic'. */
+    llm?: LlmFunction;
+}
+interface InjectOptions {
+    budget?: number;
+    scope?: string;
+    boost_recent?: boolean;
+}
+interface InjectionResult {
+    directives: string;
+    consider: string;
+    count: number;
+    tokens_used: number;
+}
+interface CaptureContext {
+    agent?: string;
+    channel?: string;
+    session_id?: string;
+    tags?: string[];
+}
+interface TimelineQuery {
+    since?: Date;
+    until?: Date;
+    agent?: string;
+    channel?: string;
+    search?: string;
+}
+
+interface IngestOptions {
+    source?: string;
+    extract_only?: boolean;
+    scope?: string;
+    domain?: string;
+}
+interface IngestCandidate {
+    statement: string;
+    type: 'behavioral' | 'architectural' | 'procedural';
+    source?: string;
+}
+interface StatusResult {
+    engram_count: number;
+    episode_count: number;
+    pack_count: number;
+    storage_root: string;
+    config: PlurConfig;
+}
+declare class Plur {
+    private paths;
+    private config;
+    constructor(options?: {
+        path?: string;
+    });
+    /** Create engram, detect conflicts, save. Returns the created engram. */
+    learn(statement: string, context?: LearnContext): Engram;
+    /**
+     * Search engrams, filter by scope/domain/strength, reactivate accessed.
+     * Supports two modes:
+     *   - 'fast' (default): BM25 keyword search, instant, no API calls
+     *   - 'agentic': LLM-assisted semantic search, higher accuracy, requires llm function
+     */
+    /** Search engrams using fast BM25 keyword matching. Sync, no API calls. */
+    recall(query: string, options?: Omit<RecallOptions, 'mode' | 'llm'>): Engram[];
+    /** Search engrams using LLM-assisted semantic filtering. Async, requires llm function. */
+    recallAsync(query: string, options: RecallOptions & {
+        llm: LlmFunction;
+    }): Promise<Engram[]>;
+    /** Filter engrams by scope/domain/strength (shared by both modes) */
+    private _filterEngrams;
+    /** Reactivate accessed engrams (bump retrieval strength, frequency, last_accessed) */
+    private _reactivateResults;
+    /** Scored injection within token budget. Returns formatted strings. */
+    inject(task: string, options?: InjectOptions): InjectionResult;
+    /** Update feedback_signals and adjust retrieval_strength. */
+    feedback(id: string, signal: 'positive' | 'negative' | 'neutral'): void;
+    /** Set engram status to 'retired'. */
+    forget(id: string, reason?: string): void;
+    /** Capture an episodic memory. */
+    capture(summary: string, context?: CaptureContext): Episode;
+    /** Query the episode timeline. */
+    timeline(query?: TimelineQuery): Episode[];
+    /** Rule-based extraction of engram candidates from content. */
+    ingest(content: string, options?: IngestOptions): IngestCandidate[];
+    /** Install a pack from a source path. */
+    installPack(source: string): {
+        installed: number;
+        name: string;
+    };
+    /** Export engrams as a shareable pack. */
+    exportPack(engrams: Engram[], outputDir: string, manifest: {
+        name: string;
+        version: string;
+        description?: string;
+        creator?: string;
+    }): {
+        path: string;
+        engram_count: number;
+    };
+    /** List all installed packs. */
+    listPacks(): ReturnType<typeof listPacks>;
+    /** Return system health info. */
+    status(): StatusResult;
+}
+
+export { type Association, type CaptureContext, type Engram, type Episode, type IngestCandidate, type IngestOptions, type InjectOptions, type InjectionResult, type KnowledgeAnchor, type LearnContext, type LlmFunction, type PackManifest, Plur, type PlurConfig, type RecallOptions, type StatusResult, type TimelineQuery };