@alineo-labs/memory 0.2.2 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -18,7 +18,7 @@ semantic memory are keyed by `resourceId` because their entire point is survivin
18
18
  session they were learned in.
19
19
 
20
20
  `resourceId` (and `parentSandboxId`, for forked sandboxes) ride along in the ledger's existing
21
- `sandbox_created` event payload — the same mechanism `SandboxDetails.runId` already used —
21
+ `sandbox.created` event payload — the same mechanism `SandboxDetails.runId` already used —
22
22
  so there's no ledger schema change. Set it when creating a sandbox:
23
23
 
24
24
  ```ts
@@ -353,7 +353,7 @@ const sb = await client.sandbox({
353
353
  `spawn()` carries it over to the child automatically:
354
354
 
355
355
  ```ts
356
- const agent = await Alineo.load(spec, { adapter, memory });
356
+ const agent = await Alineo.start(spec, { adapter, memory });
357
357
  await agent.memory?.remember(agent.resourceRef, { content: "user prefers concise answers" });
358
358
  ```
359
359
 
package/dist/index.d.mts CHANGED
@@ -55,6 +55,28 @@ interface IWorkingMemoryProvider {
55
55
  list(ref: ResourceRef): Promise<Record<string, unknown>>;
56
56
  delete(ref: ResourceRef, key: string): Promise<void>;
57
57
  }
58
+ /**
59
+ * Optional capability: read one page of a resource's entries, in ascending key order (UTF-8 byte
60
+ * order), without loading the rest. `list()` returns everything and so costs in proportion to how
61
+ * much the resource has stored; a provider with an ordered index can answer a page in proportion
62
+ * to the page.
63
+ *
64
+ * `entries` is an ordered list of pairs, not a record, on purpose: a JavaScript object does not
65
+ * keep the order keys were added in — integer-like keys (`"9"`, `"10"`) come out first, in numeric
66
+ * order — so a record would silently scramble the very order a page cursor depends on.
67
+ */
68
+ interface IPagedWorkingMemoryProvider extends IWorkingMemoryProvider {
69
+ /** Up to `limit` entries whose key sorts after `after` (or from the start when omitted). */
70
+ listPage(ref: ResourceRef, opts: {
71
+ after?: string;
72
+ limit: number;
73
+ }): Promise<{
74
+ entries: Array<[key: string, value: unknown]>;
75
+ more: boolean;
76
+ }>;
77
+ }
78
+ /** True if `provider` implements the optional paging capability. */
79
+ export declare function isPageable(provider: IWorkingMemoryProvider): provider is IPagedWorkingMemoryProvider;
58
80
  /**
59
81
  * Reference implementation — a process-local `Map`. Not durable across restarts, not shared
60
82
  * across processes or hosts. Exists to prove `IWorkingMemoryProvider` composes with `Memory`,
@@ -163,6 +185,19 @@ export declare function isPrunable(provider: ISemanticMemoryProvider): provider
163
185
  interface IBulkSemanticMemoryProvider extends ISemanticMemoryProvider {
164
186
  rememberMany(ref: ResourceRef, facts: MemoryFact[]): Promise<void>;
165
187
  }
188
+ /**
189
+ * Optional capability: read just the newest facts, without enumerating the resource's whole set.
190
+ * `listAll()` is right for compaction and `Memory.fork()`, which need everything; it is wrong for
191
+ * a caller that pages, because it loads and deserializes every fact the resource ever remembered.
192
+ * A provider with an index to walk can answer this directly; one without simply doesn't implement
193
+ * it, and the caller falls back to `listAll()`.
194
+ */
195
+ interface IRecentSemanticMemoryProvider extends ISemanticMemoryProvider {
196
+ /** The `limit` most recently remembered facts, newest first. */
197
+ listRecent(ref: ResourceRef, limit: number): Promise<RememberedFact[]>;
198
+ }
199
+ /** True if `provider` implements the optional newest-first capability. */
200
+ export declare function isRecentListable(provider: ISemanticMemoryProvider): provider is IRecentSemanticMemoryProvider;
166
201
  /** True if `provider` implements the optional bulk-remember capability. */
167
202
  export declare function isBulkRememberable(provider: ISemanticMemoryProvider): provider is IBulkSemanticMemoryProvider;
168
203
  /**
@@ -647,4 +682,4 @@ type TeamGuardedSemanticProvider<T extends ISemanticMemoryProvider> = T extends
647
682
  */
648
683
  export declare function withTeamAccessControlSemantic<T extends ISemanticMemoryProvider>(provider: T, checker: TeamAccessChecker): TeamGuardedSemanticProvider<T>;
649
684
  //#endregion
650
- export type { AutoCompactOptions, CompactionOptions, CompactionResult, ContextSnippetOptions, EmbeddingProvider, EpisodicBranch, EpisodicRecallOptions, EpisodicTreeOptions, ForkMemoryResult, IBulkSemanticMemoryProvider, IPrunableSemanticMemoryProvider, ISemanticMemoryProvider, IWorkingMemoryProvider, LastCheckpointRecord, MemoryCapability, MemoryFact, MemoryLifecycleHooksOptions, MemoryOptions, MemoryTool, RememberedFact, ResourceRef, SandboxSessionRef, SchemaValidator, SemanticFactRow, TeamAccessChecker };
685
+ export type { AutoCompactOptions, CompactionOptions, CompactionResult, ContextSnippetOptions, EmbeddingProvider, EpisodicBranch, EpisodicRecallOptions, EpisodicTreeOptions, ForkMemoryResult, IBulkSemanticMemoryProvider, IPagedWorkingMemoryProvider, IPrunableSemanticMemoryProvider, IRecentSemanticMemoryProvider, ISemanticMemoryProvider, IWorkingMemoryProvider, LastCheckpointRecord, MemoryCapability, MemoryFact, MemoryLifecycleHooksOptions, MemoryOptions, MemoryTool, RememberedFact, ResourceRef, SandboxSessionRef, SchemaValidator, SemanticFactRow, TeamAccessChecker };
package/dist/index.mjs CHANGED
@@ -34,6 +34,10 @@ var MemoryCapabilityError = class extends WorkflowError {
34
34
  };
35
35
  //#endregion
36
36
  //#region src/working.ts
37
+ /** True if `provider` implements the optional paging capability. */
38
+ function isPageable(provider) {
39
+ return typeof provider.listPage === "function";
40
+ }
37
41
  /**
38
42
  * Reference implementation — a process-local `Map`. Not durable across restarts, not shared
39
43
  * across processes or hosts. Exists to prove `IWorkingMemoryProvider` composes with `Memory`,
@@ -73,6 +77,10 @@ var InMemoryWorkingMemoryProvider = class {
73
77
  function isPrunable(provider) {
74
78
  return typeof provider.listAll === "function" && typeof provider.forget === "function";
75
79
  }
80
+ /** True if `provider` implements the optional newest-first capability. */
81
+ function isRecentListable(provider) {
82
+ return typeof provider.listRecent === "function";
83
+ }
76
84
  /** True if `provider` implements the optional bulk-remember capability. */
77
85
  function isBulkRememberable(provider) {
78
86
  return typeof provider.rememberMany === "function";
@@ -768,4 +776,4 @@ var Memory = class {
768
776
  }
769
777
  };
770
778
  //#endregion
771
- export { InMemorySemanticMemoryProvider, InMemoryWorkingMemoryProvider, Memory, MemoryAccessDeniedError, MemoryCapabilityError, SchemaWorkingMemory, buildContextSnippet, compactSemanticMemory, cosineSimilarity, createMemoryLifecycleHooks, createMemoryTools, episodicRecall, episodicTree, factFromRow, isBulkRememberable, isPrunable, scopeKey, withTeamAccessControl, withTeamAccessControlSemantic };
779
+ export { InMemorySemanticMemoryProvider, InMemoryWorkingMemoryProvider, Memory, MemoryAccessDeniedError, MemoryCapabilityError, SchemaWorkingMemory, buildContextSnippet, compactSemanticMemory, cosineSimilarity, createMemoryLifecycleHooks, createMemoryTools, episodicRecall, episodicTree, factFromRow, isBulkRememberable, isPageable, isPrunable, isRecentListable, scopeKey, withTeamAccessControl, withTeamAccessControlSemantic };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alineo-labs/memory",
3
- "version": "0.2.2",
3
+ "version": "0.3.0",
4
4
  "license": "Apache-2.0",
5
5
  "repository": {
6
6
  "type": "git",
@@ -29,7 +29,7 @@
29
29
  "test:watch": "vitest"
30
30
  },
31
31
  "dependencies": {
32
- "@alineo-labs/core": "0.4.1"
32
+ "@alineo-labs/core": "0.5.0"
33
33
  },
34
34
  "devDependencies": {
35
35
  "bun-types": "1.4.2",