neo4j-agent-memory 0.3.17

package/dist/index.d.ts

@@ -0,0 +1,320 @@
+import { Session } from 'neo4j-driver';
+
+type MemoryKind = "semantic" | "procedural" | "episodic";
+type MemoryPolarity = "positive" | "negative";
+interface EnvironmentFingerprint {
+    hash?: string;
+    os?: "macos" | "linux" | "windows";
+    distro?: string;
+    ci?: string;
+    container?: boolean;
+    filesystem?: string;
+    workspaceMount?: "local" | "network" | "bind" | "readonly";
+    nodeVersion?: string;
+    packageManager?: "npm" | "pnpm" | "yarn";
+    pmVersion?: string;
+}
+interface DistilledInvariant {
+    invariant: string;
+    justification?: string;
+    verification?: string[];
+    applicability?: string[];
+    risks?: string[];
+}
+interface MemoryRecord {
+    id: string;
+    kind: MemoryKind;
+    polarity: MemoryPolarity;
+    title: string;
+    content: string;
+    tags: string[];
+    confidence: number;
+    utility: number;
+    createdAt?: string;
+    updatedAt?: string;
+    signals?: {
+        symptoms?: string[];
+        environment?: string[];
+    };
+    distilled?: {
+        invariants?: DistilledInvariant[];
+        steps?: string[];
+        verificationSteps?: string[];
+        gotchas?: string[];
+    };
+    antiPattern?: {
+        action: string;
+        whyBad: string;
+        saferAlternative?: string;
+    };
+    env?: EnvironmentFingerprint;
+}
+interface MemorySummary {
+    id: string;
+    kind: MemoryKind;
+    polarity: MemoryPolarity;
+    title: string;
+    tags: string[];
+    confidence: number;
+    utility: number;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+}
+interface CaseRecord {
+    id: string;
+    title: string;
+    summary: string;
+    outcome: "resolved" | "unresolved" | "workaround";
+    symptoms: string[];
+    env: EnvironmentFingerprint;
+    resolvedByMemoryIds: string[];
+    negativeMemoryIds: string[];
+    resolvedAtIso?: string | null;
+}
+interface RetrieveContextArgs {
+    agentId: string;
+    prompt: string;
+    symptoms?: string[];
+    tags?: string[];
+    kinds?: MemoryKind[];
+    env?: EnvironmentFingerprint;
+    baseline?: Record<string, {
+        a: number;
+        b: number;
+    }>;
+    caseLimit?: number;
+    fixLimit?: number;
+    dontLimit?: number;
+    nowIso?: string;
+}
+interface ListMemoriesArgs {
+    kind?: MemoryKind;
+    limit?: number;
+    agentId?: string;
+}
+interface BetaEdge {
+    a: number;
+    b: number;
+    /** Posterior mean a/(a+b), cached for query speed */
+    strength: number;
+    /** Evidence mass a+b, cached for query speed */
+    evidence: number;
+    updatedAt: string | null;
+}
+type ContextMemoryBase = Pick<MemoryRecord, "id" | "kind" | "polarity" | "title" | "content" | "tags" | "confidence" | "utility" | "updatedAt">;
+type ContextMemorySummary = ContextMemoryBase & {
+    /** Posterior snapshot before the current run (baseline) */
+    edgeBefore?: BetaEdge;
+    /** Posterior snapshot after the current run (undefined until feedback arrives) */
+    edgeAfter?: BetaEdge;
+};
+interface ContextBundle {
+    sessionId: string;
+    sections: {
+        fix: ContextMemorySummary[];
+        doNotDo: ContextMemorySummary[];
+    };
+    injection: {
+        fixBlock: string;
+        doNotDoBlock: string;
+    };
+}
+interface FeedbackMetrics {
+    durationMs?: number;
+    quality?: number;
+    hallucinationRisk?: number;
+    toolCalls?: number;
+    verificationPassed?: boolean;
+}
+interface MemoryFeedback {
+    agentId: string;
+    sessionId: string;
+    usedIds: string[];
+    usefulIds: string[];
+    notUsefulIds: string[];
+    preventedErrorIds?: string[];
+    metrics?: FeedbackMetrics;
+    notes?: string;
+}
+interface CaptureEpisodeArgs {
+    agentId: string;
+    runId: string;
+    workflowName: string;
+    prompt: string;
+    response: string;
+    outcome?: "success" | "failure" | "partial" | "unknown";
+    tags?: string[];
+}
+interface CaptureStepEpisodeArgs extends CaptureEpisodeArgs {
+    stepName: string;
+}
+interface MemoryEvent {
+    type: "read" | "write";
+    action: string;
+    at: string;
+    meta?: Record<string, unknown>;
+}
+interface LearningCandidate {
+    kind: MemoryKind;
+    polarity?: MemoryPolarity;
+    title: string;
+    content: string;
+    tags: string[];
+    confidence: number;
+    signals?: MemoryRecord["signals"];
+    env?: EnvironmentFingerprint;
+    triage?: {
+        symptoms: string[];
+        likelyCauses: string[];
+        verificationSteps?: string[];
+        fixSteps?: string[];
+        gotchas?: string[];
+    };
+    antiPattern?: MemoryRecord["antiPattern"];
+}
+interface SaveLearningRequest {
+    agentId: string;
+    sessionId?: string;
+    taskId?: string;
+    learnings: LearningCandidate[];
+    policy?: {
+        minConfidence?: number;
+        requireVerificationSteps?: boolean;
+        maxItems?: number;
+    };
+}
+interface SaveLearningResult {
+    saved: Array<{
+        id: string;
+        kind: MemoryKind;
+        title: string;
+        deduped: boolean;
+    }>;
+    rejected: Array<{
+        title: string;
+        reason: string;
+    }>;
+}
+interface MemoryServiceConfig {
+    neo4j: {
+        uri: string;
+        username: string;
+        password: string;
+        database?: string;
+    };
+    vectorIndex?: string;
+    fulltextIndex?: string;
+    halfLifeSeconds?: number;
+    onMemoryEvent?: (event: MemoryEvent) => void;
+}
+type MemoryToolName = "store_skill" | "store_pattern" | "store_concept" | "relate_concepts" | "recall_skills" | "recall_concepts" | "recall_patterns";
+interface MemoryToolDefinition<TInput, TResult> {
+    name: MemoryToolName;
+    description: string;
+    inputSchema?: unknown;
+    execute: (input: TInput) => Promise<TResult>;
+}
+type MemoryToolSet = Record<MemoryToolName, MemoryToolDefinition<any, any>>;
+
+declare class MemoryService {
+    private client;
+    private vectorIndex;
+    private fulltextIndex;
+    private halfLifeSeconds;
+    private onMemoryEvent?;
+    private cyUpsertMemory;
+    private cyUpsertCase;
+    private cyRetrieveBundle;
+    private cyFeedbackBatch;
+    private cyFeedbackCoUsed;
+    private cyListMemories;
+    private cyRelateConcepts;
+    private cyGetRecallEdges;
+    constructor(cfg: MemoryServiceConfig);
+    init(): Promise<void>;
+    close(): Promise<void>;
+    private ensureEnvHash;
+    private emit;
+    /**
+     * Save a distilled memory (semantic/procedural/episodic) with exact dedupe by contentHash.
+     * NOTE: This package intentionally does not store "full answers" as semantic/procedural.
+     */
+    upsertMemory(l: LearningCandidate & {
+        id?: string;
+    }): Promise<{
+        id: string;
+        deduped: boolean;
+    }>;
+    /**
+     * Upsert an episodic Case (case-based reasoning) that links symptoms + env + resolved_by + negative memories.
+     */
+    upsertCase(c: CaseRecord): Promise<string>;
+    /**
+     * Retrieve a ContextBundle with separate Fix and Do-not-do sections, using case-based reasoning.
+     * The key idea: match cases by symptoms + env similarity, then pull linked memories.
+     */
+    retrieveContextBundle(args: RetrieveContextArgs): Promise<ContextBundle>;
+    listMemories(args?: ListMemoriesArgs): Promise<MemorySummary[]>;
+    listEpisodes(args?: Omit<ListMemoriesArgs, "kind">): Promise<MemorySummary[]>;
+    listSkills(args?: Omit<ListMemoriesArgs, "kind">): Promise<MemorySummary[]>;
+    listConcepts(args?: Omit<ListMemoriesArgs, "kind">): Promise<MemorySummary[]>;
+    relateConcepts(args: {
+        sourceId: string;
+        targetId: string;
+        weight?: number;
+    }): Promise<void>;
+    captureEpisode(args: CaptureEpisodeArgs): Promise<SaveLearningResult>;
+    captureStepEpisode(args: CaptureStepEpisodeArgs): Promise<SaveLearningResult>;
+    /**
+     * Reinforce/degrade agent->memory association weights using a single batched Cypher query.
+     * This supports mid-run retrieval by making feedback cheap and frequent.
+     */
+    feedback(fb: MemoryFeedback): Promise<void>;
+    /**
+     * Save distilled learnings discovered during a task.
+     * Enforces quality gates and stores negative memories explicitly.
+     * Automatically creates a Case if learnings have triage.symptoms.
+     */
+    saveLearnings(req: SaveLearningRequest): Promise<SaveLearningResult>;
+}
+declare function createMemoryService(cfg: MemoryServiceConfig): Promise<MemoryService>;
+
+interface Neo4jClientConfig {
+    uri: string;
+    username: string;
+    password: string;
+    database?: string;
+}
+declare class Neo4jClient {
+    private driver;
+    private database?;
+    constructor(cfg: Neo4jClientConfig);
+    session(mode?: "READ" | "WRITE"): Session;
+    close(): Promise<void>;
+}
+
+declare const schemaVersion = 1;
+declare function ensureSchema(client: Neo4jClient): Promise<void>;
+declare function migrate(client: Neo4jClient, targetVersion?: number): Promise<void>;
+
+declare function loadCypher(rel: string): string;
+declare const cypher: {
+    schema: string;
+    upsertMemory: string;
+    upsertCase: string;
+    retrieveContextBundle: string;
+    feedbackBatch: string;
+    feedbackCoUsed: string;
+    listMemories: string;
+    relateConcepts: string;
+};
+
+declare function createMemoryTools(service: MemoryService): MemoryToolSet;
+
+declare function sha256Hex(s: string): string;
+declare function canonicaliseForHash(title: string, content: string, tags: string[]): string;
+declare function newId(prefix: string): string;
+declare function normaliseSymptom(s: string): string;
+declare function envHash(env: EnvironmentFingerprint): string;
+
+export { type BetaEdge, type CaptureEpisodeArgs, type CaptureStepEpisodeArgs, type CaseRecord, type ContextBundle, type ContextMemoryBase, type ContextMemorySummary, type DistilledInvariant, type EnvironmentFingerprint, type FeedbackMetrics, type LearningCandidate, type ListMemoriesArgs, type MemoryEvent, type MemoryFeedback, type MemoryKind, type MemoryPolarity, type MemoryRecord, MemoryService, type MemoryServiceConfig, type MemorySummary, type MemoryToolDefinition, type MemoryToolName, type MemoryToolSet, Neo4jClient, type Neo4jClientConfig, type RetrieveContextArgs, type SaveLearningRequest, type SaveLearningResult, canonicaliseForHash, createMemoryService, createMemoryTools, cypher, ensureSchema, envHash, loadCypher, migrate, newId, normaliseSymptom, schemaVersion, sha256Hex };