@fgv/ts-agent-memory 5.1.0-41 → 5.1.0-43

package/temp/ts-agent-memory.api.md

@@ -121,6 +121,22 @@ export class FileTreeMemoryStore implements IMemoryStore {
     list(filter?: IMemoryStoreListFilter): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
     listScoped(): Promise<Result<ReadonlyArray<IScopedMemoryRecord>>>;
     put(record: IMemoryRecord<unknown>): Promise<Result<IMemoryRecord<unknown>>>;
+    get skippedRecords(): ReadonlyArray<ISkippedRecord>;
+}
+
+// @public
+export const FRAGMENT_SEMANTIC_UNWIRED_MESSAGE: string;
+
+// @public
+export type FragmentEmbedder = (record: IMemoryRecord<unknown>) => Promise<Result<ReadonlyArray<IEmbeddedFragment>>>;
+
+// @public
+export class FragmentSemanticRetriever {
+    get capabilities(): IFragmentRetrieverCapabilities;
+    static create(params: {
+        readonly backend?: IFragmentSemanticBackend;
+    }): Result<FragmentSemanticRetriever>;
+    retrieve(query: IFragmentQuery): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
 }
 
 // @public
@@ -203,6 +219,12 @@ export interface IEdgeTarget {
     readonly scope: MemoryScopeKey;
 }
 
+// @public
+export interface IEmbeddedFragment {
+    readonly locator: IFragmentLocator;
+    readonly vector: Float32Array;
+}
+
 // @public
 export interface IEntityResolutionCandidate {
     readonly record: IMemoryRecord<unknown>;
@@ -226,8 +248,11 @@ export interface IFileTreeMemoryStoreCreateParams {
     readonly codecs?: ReadonlyMap<Kind, IIdentityCodec>;
     readonly defaultCodec?: IIdentityCodec;
     readonly embed?: MemoryEmbedder;
+    readonly fragmentEmbedder?: FragmentEmbedder;
+    readonly fragmentIndex?: IFragmentVectorIndex;
     readonly logger?: Logging.ILogger;
     readonly observers?: ReadonlyArray<IMemoryObserver>;
+    readonly onRecordError?: MemoryRecordErrorMode;
     readonly rankProjectors?: ReadonlyMap<Kind, RankProjector>;
     readonly registry: IBodyConverterRegistry;
     readonly root: FileTree.IMutableFileTreeDirectoryItem;
@@ -236,6 +261,37 @@ export interface IFileTreeMemoryStoreCreateParams {
     readonly writePolicies?: ReadonlyMap<Kind, IWritePolicy>;
 }
 
+// @public
+export interface IFragmentLocator {
+    readonly end: number;
+    readonly start: number;
+}
+
+// @public
+export interface IFragmentQuery {
+    readonly maxPerRecord?: number;
+    readonly semantic: string;
+    readonly topK?: number;
+}
+
+// @public
+export interface IFragmentRetrieverCapabilities {
+    readonly supportsFragmentRecall: boolean;
+}
+
+// @public
+export interface IFragmentSemanticBackend {
+    readonly embedQuery: QueryEmbedder;
+    readonly fragmentIndex: IFragmentVectorIndex;
+}
+
+// @public
+export interface IFragmentVectorIndex {
+    addFragments(target: IEdgeTarget, fragments: ReadonlyArray<IEmbeddedFragment>): Promise<Result<number>>;
+    query(vector: Float32Array, topK: number, maxPerRecord?: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>>;
+}
+
 // @public
 export interface IIdentityCodec {
     decode(scope: MemoryScopeKey, encodedStem: string): Result<EntityId>;
@@ -495,6 +551,17 @@ export class InMemoryCosineIndex implements IVectorIndex {
     get size(): number;
 }
 
+// @public
+export class InMemoryFragmentCosineIndex implements IFragmentVectorIndex {
+    addFragments(target: IEdgeTarget, fragments: ReadonlyArray<IEmbeddedFragment>): Promise<Result<number>>;
+    static create(): Result<InMemoryFragmentCosineIndex>;
+    get fragmentCount(): number;
+    query(vector: Float32Array, topK: number, maxPerRecord?: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    rebuild(source: IMemoryRecordSource, embed: FragmentEmbedder): Promise<Result<number>>;
+    get recordCount(): number;
+    remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>>;
+}
+
 // @public
 export interface IProvenance {
     readonly [key: string]: unknown;
@@ -540,6 +607,13 @@ export interface ISemanticRetrieverCreateParams {
     readonly index: IMemoryIndex;
 }
 
+// @public
+export interface ISkippedRecord {
+    readonly error: string;
+    readonly path: string;
+    readonly scope: MemoryScopeKey;
+}
+
 // @public
 export function isTemporalIdentityCodec(codec: IIdentityCodec): codec is ITemporalIdentityCodec;
 
@@ -579,6 +653,7 @@ export interface IVectorIndex {
 
 // @public
 export interface IVectorQueryHit {
+    readonly locator?: IFragmentLocator;
     readonly score: number;
     readonly target: IEdgeTarget;
 }
@@ -698,6 +773,9 @@ export class MemoryObservationStore implements IMemoryObserver {
     get size(): number;
 }
 
+// @public
+export type MemoryRecordErrorMode = 'skip' | 'fail';
+
 // @public
 export type MemoryScopeKey = Brand<string, 'MemoryScopeKey'>;