agenr 2.1.0 → 3.1.0

package/dist/{ports-Nj5nd2Ri.d.ts → ports-CpzWESmZ.d.ts}

@@ -34,7 +34,7 @@ type ClaimKeySource = (typeof CLAIM_KEY_SOURCES)[number];
  */
 type ClaimSupportMode = (typeof CLAIM_SUPPORT_MODES)[number];
 /** Ordered list of supported episode sources. */
-declare const EPISODE_SOURCES: readonly ["openclaw", "codex", "cli", "synthesis"];
+declare const EPISODE_SOURCES: readonly ["openclaw", "skeln", "codex", "cli", "synthesis"];
 /** Ordered list of supported episode activity levels. */
 declare const EPISODE_ACTIVITY_LEVELS: readonly ["substantial", "minimal", "none"];
 /** Ordered list of supported procedure step kinds. */
@@ -106,6 +106,30 @@ interface Entry extends ClaimKeyLifecycleMetadata {
     created_at: string;
     updated_at: string;
 }
+/**
+ * Mutable entry fields supported by direct update paths.
+ *
+ * Claim-key lifecycle updates are replacement-style, not merge-style. When any
+ * lifecycle field is mutated, callers must provide one complete validated
+ * lifecycle payload for the target claim key. Partial lifecycle patches are
+ * rejected at the persistence boundary.
+ */
+interface EntryUpdateInput {
+    importance?: Entry["importance"];
+    expiry?: Entry["expiry"];
+    claim_key?: Entry["claim_key"];
+    claim_key_raw?: Entry["claim_key_raw"];
+    claim_key_status?: Entry["claim_key_status"];
+    claim_key_source?: Entry["claim_key_source"];
+    claim_key_confidence?: Entry["claim_key_confidence"];
+    claim_key_rationale?: Entry["claim_key_rationale"];
+    claim_support_source_kind?: Entry["claim_support_source_kind"];
+    claim_support_locator?: Entry["claim_support_locator"];
+    claim_support_observed_at?: Entry["claim_support_observed_at"];
+    claim_support_mode?: Entry["claim_support_mode"];
+    valid_from?: Entry["valid_from"];
+    valid_to?: Entry["valid_to"];
+}
 /**
  * Canonical stored episodic-memory record.
  */
@@ -359,6 +383,65 @@ interface ParsedTranscript {
     warnings: string[];
 }
 
+/**
+ * Aggregate active corpus counts for one entity prefix.
+ */
+interface ClaimKeyEntityPrefixStats {
+    entityPrefix: string;
+    activeEntryCount: number;
+    trustedEntryCount: number;
+    tentativeEntryCount: number;
+    unresolvedEntryCount: number;
+    legacyEntryCount: number;
+    deterministicRepairEntryCount: number;
+    manualEntryCount: number;
+    modelEntryCount: number;
+    jsonRetryEntryCount: number;
+    surgeonFamilyReuseEntryCount: number;
+}
+
+/**
+ * Write-time episode payload before adapter-managed identity and lifecycle fields are applied.
+ */
+interface EpisodeInput {
+    source: EpisodeSource;
+    sourceId?: string;
+    sourceRef?: string;
+    transcriptHash?: string;
+    summaryHash?: string;
+    agentId?: string;
+    surface?: string;
+    startedAt: string;
+    endedAt?: string;
+    summary: string;
+    tags?: string[];
+    activityLevel?: EpisodeActivityLevel;
+    userId?: string;
+    project?: string;
+    genModel?: string;
+    genVersion?: string;
+    messageCount?: number;
+    embedding?: number[];
+}
+/**
+ * Calendar-aware temporal constraint used by future episode retrieval.
+ */
+interface TemporalWindow {
+    kind: "interval" | "anchor" | "open_start" | "open_end";
+    start?: Date;
+    end?: Date;
+    anchor?: Date;
+    radiusDays?: number;
+    source: "explicit" | "inferred";
+}
+/**
+ * Upsert outcome returned by episode persistence adapters.
+ */
+interface EpisodeUpsertResult {
+    episode: Episode;
+    action: "inserted" | "updated" | "unchanged";
+}
+
 /**
  * Internal ranking profiles that adjust recall scoring for specific query intents.
  */
@@ -538,6 +621,7 @@ declare const DEFAULT_STRONG_SEED_SCORE_GAP = 0.05;
  * trust suppression.
  */
 declare const DEFAULT_SEEDED_RERANK_WEIGHT = 0.03;
+
 /** Shared shape used by all seededRerank callers. */
 interface SeededRerankCandidate {
     /** Stable identifier used to detect the seed itself and skip rerank. */
@@ -624,6 +708,119 @@ declare function sharesEpisodeLineage(candidate: Episode, seed: Episode): boolea
  */
 declare function sharesProcedureLineage(candidate: Procedure, seed: Procedure): boolean;
 
+/**
+ * Storage contract for persisting, updating, and querying knowledge entries.
+ */
+interface DatabasePort {
+    /** Insert a new entry with its embedding. */
+    insertEntry(entry: Entry, embedding: number[], contentHash: string): Promise<string>;
+    /** Drop expensive indexes and triggers before a bulk write phase begins. */
+    prepareForBulkWrites(): Promise<void>;
+    /** Rebuild expensive indexes and triggers after a bulk write phase ends. */
+    finalizeBulkWrites(): Promise<void>;
+    /** Get entries by IDs. */
+    getEntries(ids: string[]): Promise<Entry[]>;
+    /** Get a single entry by ID. */
+    getEntry(id: string): Promise<Entry | null>;
+    /** Check if content hashes already exist. Returns the set of existing hashes. */
+    findExistingHashes(hashes: string[]): Promise<Set<string>>;
+    /** Check if normalized content hashes already exist. Returns the set of existing hashes. */
+    findExistingNormHashes(hashes: string[]): Promise<Set<string>>;
+    /** Mark an entry as retired. */
+    retireEntry(id: string, reason?: string): Promise<boolean>;
+    /** Supersede an active entry, linking it to the new entry that replaces it. */
+    supersedeEntry(oldId: string, newId: string, kind?: string, reason?: string): Promise<boolean>;
+    /** Find active entries with the given claim key. */
+    findActiveEntriesByClaimKey(claimKey: string): Promise<Entry[]>;
+    /** Get distinct entity prefixes from existing claim keys. */
+    getDistinctClaimKeyPrefixes(): Promise<string[]>;
+    /** Get bounded full claim-key examples ordered for extraction hinting. */
+    getClaimKeyExamples?(limit?: number): Promise<string[]>;
+    /** Get active per-prefix claim-key counts for conservative alias-family handling. */
+    getClaimKeyEntityPrefixStats?(): Promise<ClaimKeyEntityPrefixStats[]>;
+    /** Update entry fields (importance, expiry, and temporal metadata). */
+    updateEntry(id: string, fields: EntryUpdateInput): Promise<boolean>;
+    /** Check if a file has been ingested (by path + hash). */
+    getIngestLogEntry(filePath: string): Promise<{
+        fileHash: string;
+        ingestedAt: string;
+    } | null>;
+    /** Record that a file was ingested. */
+    insertIngestLogEntry(filePath: string, fileHash: string, entryCount: number): Promise<void>;
+    /** Initialize the database schema. */
+    init(): Promise<void>;
+    /** Close the database connection. */
+    close(): Promise<void>;
+}
+/**
+ * Storage contract for persisting and querying episodic memory records.
+ */
+interface EpisodeDatabasePort {
+    /** Get one episode by its stable `(source, sourceId)` identity. */
+    getEpisodeBySourceId(source: EpisodeSource, sourceId: string): Promise<Episode | null>;
+    /** Get one episode by fallback `(source, transcriptHash)` identity. */
+    getEpisodeByTranscriptHash(source: EpisodeSource, transcriptHash: string): Promise<Episode | null>;
+    /** Insert or update an episode using `summaryHash` change detection. */
+    upsertEpisode(input: EpisodeInput): Promise<EpisodeUpsertResult>;
+    /** List non-retired episodes whose time range overlaps the requested window. */
+    listEpisodesByTimeWindow(window: TemporalWindow, limit?: number): Promise<Episode[]>;
+    /** Find episodes by vector similarity to a query embedding. */
+    episodeVectorSearch(params: {
+        embedding: number[];
+        limit: number;
+    }): Promise<Array<{
+        episode: Episode;
+        vectorSim: number;
+    }>>;
+    /** List non-retired episodes that still need embeddings. */
+    listEpisodesWithoutEmbeddings(limit?: number): Promise<Episode[]>;
+    /** Update only the embedding payload for an existing episode row. */
+    updateEpisodeEmbedding(id: string, embedding: number[]): Promise<void>;
+}
+/**
+ * Storage contract for persisting and querying procedural-memory revisions.
+ */
+interface ProcedureDatabasePort {
+    /** Insert or update one procedure revision row. */
+    upsertProcedure(procedure: Procedure): Promise<Procedure>;
+    /** Get one active procedure by primary key. */
+    getProcedure(id: string): Promise<Procedure | null>;
+    /** Hydrate active procedures by ID while preserving caller order. */
+    hydrateProcedures(ids: string[]): Promise<Procedure[]>;
+    /** Get the currently active procedure revision for one stable key. */
+    findActiveProcedureByKey(procedureKey: string): Promise<Procedure | null>;
+    /** Find procedures by vector similarity to a query embedding. */
+    procedureVectorSearch(params: {
+        embedding: number[];
+        limit: number;
+    }): Promise<Array<{
+        procedure: Procedure;
+        vectorSim: number;
+    }>>;
+    /** Find procedures by lexical search over the procedure FTS index. */
+    procedureFtsSearch(params: {
+        text: string;
+        limit: number;
+    }): Promise<Array<{
+        procedure: Procedure;
+        rank: number;
+    }>>;
+    /** List active procedures that still need embeddings. */
+    listProceduresWithoutEmbeddings(limit?: number): Promise<Procedure[]>;
+    /** Update only the embedding payload for an existing procedure row. */
+    updateProcedureEmbedding(id: string, embedding: number[]): Promise<void>;
+    /** Mark one active procedure revision as retired. */
+    retireProcedure(id: string, reason?: string): Promise<boolean>;
+    /** Supersede one active procedure revision with a new revision. */
+    supersedeProcedure(oldId: string, newId: string, reason?: string): Promise<boolean>;
+}
+/**
+ * Embedding provider contract used by core ranking and storage flows.
+ */
+interface EmbeddingPort {
+    /** Compute embeddings for one or more texts. */
+    embed(texts: string[]): Promise<number[][]>;
+}
 /**
  * Query-time retrieval contract used by the v1 recall pipeline.
  */
@@ -669,6 +866,15 @@ interface RecallPorts {
      */
     crossEncoder?: CrossEncoderPort;
 }
+/**
+ * LLM provider contract for free-form and structured completions.
+ */
+interface LlmPort {
+    /** Generate a completion from a system prompt and user message. */
+    complete(systemPrompt: string, userMessage: string): Promise<string>;
+    /** Generate a structured completion (JSON output). */
+    completeJson<T>(systemPrompt: string, userMessage: string): Promise<T>;
+}
 /**
  * One passage handed to the cross-encoder for relevance scoring.
  */
@@ -716,4 +922,4 @@ interface TranscriptPort {
     }): Promise<ParsedTranscript>;
 }
 
-export { type CrossEncoderPort as C, DEFAULT_NEIGHBORHOOD_BUDGET as D, type EntryType as E, type FtsCandidate as F, type NeighborhoodFamily as N, type ParsedTranscript as P, type RecallInput as R, type SeededRerankCandidate as S, type TranscriptPort as T, type VectorCandidate as V, type Expiry as a, type RecallPorts as b, type RecallOutput as c, DEFAULT_SEEDED_RERANK_WEIGHT as d, DEFAULT_STRONG_SEED_SCORE_GAP as e, DEFAULT_STRONG_SEED_TOP_N as f, type EntityAttributeKind as g, type EntityAttributeQueryShape as h, type EntryFilters as i, type EntryNeighborhoodRequest as j, type RecallCandidateEntry as k, type RecallRankingProfile as l, type SeededRerankOptions as m, selectStrongSeeds as n, sharesEntryLineage as o, sharesEpisodeLineage as p, sharesProcedureLineage as q, seededRerank as s };
+export { type CrossEncoderPort as C, DEFAULT_NEIGHBORHOOD_BUDGET as D, type EntryType as E, type FtsCandidate as F, type LlmPort as L, type NeighborhoodFamily as N, type ParsedTranscript as P, type RecallInput as R, type SeededRerankCandidate as S, type TranscriptPort as T, type VectorCandidate as V, type Expiry as a, type RecallPorts as b, type RecallOutput as c, DEFAULT_SEEDED_RERANK_WEIGHT as d, DEFAULT_STRONG_SEED_SCORE_GAP as e, DEFAULT_STRONG_SEED_TOP_N as f, type EntityAttributeKind as g, type EntityAttributeQueryShape as h, type EntryFilters as i, type EntryNeighborhoodRequest as j, type RecallCandidateEntry as k, type RecallRankingProfile as l, type SeededRerankOptions as m, selectStrongSeeds as n, sharesEntryLineage as o, sharesEpisodeLineage as p, sharesProcedureLineage as q, type ProcedureDatabasePort as r, seededRerank as s, type Entry as t, type DatabasePort as u, type EpisodeDatabasePort as v, type EmbeddingPort as w };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agenr",
-  "version": "2.1.0",
+  "version": "3.1.0",
   "description": "Agent memory - local-first knowledge infrastructure for AI agents",
   "type": "module",
   "bin": {
@@ -15,8 +15,8 @@
   "dependencies": {
     "@clack/prompts": "^1.1.0",
     "@libsql/client": "^0.17.2",
-    "@mariozechner/pi-agent-core": "^0.63.1",
-    "@mariozechner/pi-ai": "^0.63.2",
+    "@earendil-works/pi-agent-core": "^0.78.0",
+    "@earendil-works/pi-ai": "^0.78.0",
     "@sinclair/typebox": "^0.34.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
@@ -26,6 +26,8 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/node": "^25.5.0",
+    "skeln": "file:../skeln",
+    "typebox": "^1.1.38",
     "eslint": "^10.1.0",
     "eslint-plugin-jsdoc": "^62.8.1",
     "globals": "^17.4.0",
@@ -38,14 +40,14 @@
   "engines": {
     "node": ">=24"
   },
-  "license": "AGPL-3.0",
+  "license": "MIT",
   "scripts": {
     "build": "pnpm run build:root && pnpm run build:plugin",
     "build:root": "tsup",
-    "build:plugin": "pnpm --filter @agenr/agenr-plugin build",
+    "build:plugin": "pnpm --filter @agenr/agenr-plugin build && pnpm --filter @agenr/skeln-plugin build",
     "build:debug": "pnpm run build:root:debug && pnpm run build:plugin:debug",
     "build:root:debug": "tsup --sourcemap",
-    "build:plugin:debug": "pnpm --filter @agenr/agenr-plugin build:debug",
+    "build:plugin:debug": "pnpm --filter @agenr/agenr-plugin build:debug && pnpm --filter @agenr/skeln-plugin build:debug",
     "dev": "tsup --watch",
     "internal:eval-server": "pnpm run build:root && node dist/internal-eval-server.js",
     "internal:recall-eval-server": "pnpm run internal:eval-server",