@dbx-tools/appkit-memory 0.9.131 → 0.9.136
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 +47 -9
- package/index.ts +1 -1
- package/lib/index.d.ts +1 -1
- package/lib/index.js +2 -2
- package/package.json +9 -9
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @dbx-tools/appkit-memory
|
|
2
2
|
|
|
3
3
|
Add durable, actor-scoped memory tools to an AppKit application. The plugin
|
|
4
4
|
checks Databricks Agent Memory first and starts its Graphiti sidecar only when
|
|
@@ -21,27 +21,32 @@ await createApp({
|
|
|
21
21
|
});
|
|
22
22
|
```
|
|
23
23
|
|
|
24
|
-
|
|
24
|
+
The plugin is beta. It publishes two tools:
|
|
25
25
|
|
|
26
|
-
- `remember` saves content at a stable absolute path
|
|
27
|
-
|
|
26
|
+
- `remember` saves non-empty content at a stable absolute path, such as
|
|
27
|
+
`/preferences/response.md`.
|
|
28
|
+
- `recall_memory` searches memory for the current actor and returns up to 100
|
|
29
|
+
results.
|
|
28
30
|
|
|
29
31
|
A 403 or 404 from the Databricks store selects Graphiti. Other Databricks
|
|
30
|
-
errors
|
|
31
|
-
between backends.
|
|
32
|
+
errors remain errors, which prevents a transient outage from splitting one
|
|
33
|
+
actor's memory between backends.
|
|
32
34
|
|
|
33
35
|
`databricks` defaults to `"auto"`. Set it to `true` to require managed-memory
|
|
34
36
|
access for every caller or `false` to disable the managed backend. The object
|
|
35
37
|
form accepts `memoryStore` and `mode: "auto" | "required"`.
|
|
36
38
|
|
|
37
|
-
##
|
|
39
|
+
## Add the tools to a Mastra agent
|
|
38
40
|
|
|
39
41
|
Request the toolkit from an agent:
|
|
40
42
|
|
|
41
43
|
```ts
|
|
44
|
+
import { createApp, server } from "@databricks/appkit";
|
|
42
45
|
import { agents, mastra } from "@dbx-tools/appkit-mastra";
|
|
46
|
+
import { memory } from "@dbx-tools/appkit-memory";
|
|
43
47
|
|
|
44
48
|
const support = agents.createAgent({
|
|
49
|
+
name: "Support",
|
|
45
50
|
instructions: "Help the user.",
|
|
46
51
|
async tools(plugins) {
|
|
47
52
|
return (await plugins.memory?.toolkit()) ?? {};
|
|
@@ -61,7 +66,23 @@ or `false` to disable it. Completed turns are mirrored to Graphiti only when
|
|
|
61
66
|
Databricks managed memory is unavailable. Managed-memory session extraction is
|
|
62
67
|
not used.
|
|
63
68
|
|
|
64
|
-
##
|
|
69
|
+
## Configure the backends
|
|
70
|
+
|
|
71
|
+
`memory()` accepts the following backend and turn-saving settings:
|
|
72
|
+
|
|
73
|
+
| Option | Default | Behavior |
|
|
74
|
+
| ------------------------ | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
75
|
+
| `databricks` | `"auto"` | Uses Databricks managed memory when the actor can access the store. A 403 or 404 selects Graphiti. |
|
|
76
|
+
| `databricks.memoryStore` | Project-derived store name | Selects an existing memory store by ID or resource name. |
|
|
77
|
+
| `databricks.mode` | `"auto"` | Set to `"required"` to fail instead of selecting Graphiti. |
|
|
78
|
+
| `graphiti` | `true` | Enables the lazy Graphiti fallback. Pass a Graphiti options object to override its model, database, listener, or authentication settings. |
|
|
79
|
+
| `saveTurns` | `"auto"` | Attaches a Mastra output processor when Mastra and Graphiti are registered. |
|
|
80
|
+
|
|
81
|
+
At least one backend must remain enabled. `saveTurns: true` requires both a
|
|
82
|
+
registered Mastra plugin and the Graphiti backend. `databricks: true` requires
|
|
83
|
+
managed-memory access for every caller.
|
|
84
|
+
|
|
85
|
+
## Run Graphiti directly
|
|
65
86
|
|
|
66
87
|
The Graphiti fallback is imported and started on the first operation that needs
|
|
67
88
|
it. Concurrent first operations share one startup. Configure `PYTHON` to use an
|
|
@@ -76,4 +97,21 @@ import { runtime as graphiti } from "@dbx-tools/appkit-memory/graphiti";
|
|
|
76
97
|
await graphiti.runGraphiti({ profile: "MY-PROFILE" });
|
|
77
98
|
```
|
|
78
99
|
|
|
79
|
-
|
|
100
|
+
`runGraphiti()` blocks until the process exits. Use it for a standalone
|
|
101
|
+
Graphiti server or CLI integration. AppKit applications don't need to call it
|
|
102
|
+
because the plugin supervises the fallback process.
|
|
103
|
+
|
|
104
|
+
## Understand memory limits
|
|
105
|
+
|
|
106
|
+
- Memory is partitioned by the trusted AppKit request identity. An `actor_id`
|
|
107
|
+
is a storage key, not an authorization mechanism.
|
|
108
|
+
- Graphiti starts only after an operation cannot use Databricks managed memory.
|
|
109
|
+
Registering the plugin doesn't start Python or PostgreSQL.
|
|
110
|
+
- The plugin stops a Graphiti process that it started when AppKit shuts down.
|
|
111
|
+
- Mastra thread storage and PgVector semantic recall remain separate from these
|
|
112
|
+
durable memory tools.
|
|
113
|
+
- Graphiti needs either a PostgreSQL or Lakebase database URL, or the optional
|
|
114
|
+
embedded PostgreSQL runtime.
|
|
115
|
+
|
|
116
|
+
For Graphiti server, database, and queue behavior, see
|
|
117
|
+
[dbx-tools-graphiti](../../../py/graphiti/README.md).
|
package/index.ts
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
// Hand edits are overwritten on the next watch; this file is read-only.
|
|
4
4
|
|
|
5
5
|
export const PACKAGE_IDENTIFIER = "@dbx-tools/appkit-memory";
|
|
6
|
-
export const PACKAGE_VERSION = "0.9.
|
|
6
|
+
export const PACKAGE_VERSION = "0.9.136";
|
|
7
7
|
export * as config from "./src/config.ts";
|
|
8
8
|
export * as databricksClient from "./src/databricks/client.ts";
|
|
9
9
|
export * as graphitiOptions from "./src/graphiti/options.ts";
|
package/lib/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
export declare const PACKAGE_IDENTIFIER = "@dbx-tools/appkit-memory";
|
|
2
|
-
export declare const PACKAGE_VERSION = "0.9.
|
|
2
|
+
export declare const PACKAGE_VERSION = "0.9.136";
|
|
3
3
|
export * as config from "./src/config.ts";
|
|
4
4
|
export * as databricksClient from "./src/databricks/client.ts";
|
|
5
5
|
export * as graphitiOptions from "./src/graphiti/options.ts";
|
package/lib/index.js
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
// Regenerated from the exporting modules in ./src.
|
|
3
3
|
// Hand edits are overwritten on the next watch; this file is read-only.
|
|
4
4
|
export const PACKAGE_IDENTIFIER = "@dbx-tools/appkit-memory";
|
|
5
|
-
export const PACKAGE_VERSION = "0.9.
|
|
5
|
+
export const PACKAGE_VERSION = "0.9.136";
|
|
6
6
|
export * as config from "./src/config.js";
|
|
7
7
|
export * as databricksClient from "./src/databricks/client.js";
|
|
8
8
|
export * as graphitiOptions from "./src/graphiti/options.js";
|
|
@@ -11,4 +11,4 @@ export * as plugin from "./src/plugin.js";
|
|
|
11
11
|
export { DatabricksMemoryOptionsSchema, MemoryPluginOptionsSchema, MEMORY_CONFIG_SCHEMA } from "./src/config.js";
|
|
12
12
|
export { ManagedMemoryEntrySchema, ManagedAgentMemoryClient } from "./src/databricks/client.js";
|
|
13
13
|
export { MemoryPlugin, memory } from "./src/plugin.js";
|
|
14
|
-
//# sourceMappingURL=data:application/json;base64,
|
|
14
|
+
//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxNQUFNLENBQUMsTUFBTSxrQkFBa0IsR0FBRywwQkFBMEIsQ0FBQztBQUM3RCxNQUFNLENBQUMsTUFBTSxlQUFlLEdBQUcsU0FBUyxDQUFDO0FBQ3pDLE9BQU8sS0FBSyxNQUFNLE1BQU0saUJBQWlCLENBQUM7QUFDMUMsT0FBTyxLQUFLLGdCQUFnQixNQUFNLDRCQUE0QixDQUFDO0FBQy9ELE9BQU8sS0FBSyxlQUFlLE1BQU0sMkJBQTJCLENBQUM7QUFDN0QsT0FBTyxLQUFLLGVBQWUsTUFBTSwyQkFBMkIsQ0FBQztBQUM3RCxPQUFPLEtBQUssTUFBTSxNQUFNLGlCQUFpQixDQUFDO0FBQzFDLE9BQU8sRUFBRSw2QkFBNkIsRUFBRSx5QkFBeUIsRUFBRSxvQkFBb0IsRUFBRSxNQUFNLGlCQUFpQixDQUFDO0FBRWpILE9BQU8sRUFBRSx3QkFBd0IsRUFBRSx3QkFBd0IsRUFBRSxNQUFNLDRCQUE0QixDQUFDO0FBR2hHLE9BQU8sRUFBRSxZQUFZLEVBQUUsTUFBTSxFQUFFLE1BQU0saUJBQWlCLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBHRU5FUkFURUQgYnkgcHJvamVuIHdhdGNoIC0gRE8gTk9UIEVESVQuXG4vLyBSZWdlbmVyYXRlZCBmcm9tIHRoZSBleHBvcnRpbmcgbW9kdWxlcyBpbiAuL3NyYy5cbi8vIEhhbmQgZWRpdHMgYXJlIG92ZXJ3cml0dGVuIG9uIHRoZSBuZXh0IHdhdGNoOyB0aGlzIGZpbGUgaXMgcmVhZC1vbmx5LlxuXG5leHBvcnQgY29uc3QgUEFDS0FHRV9JREVOVElGSUVSID0gXCJAZGJ4LXRvb2xzL2FwcGtpdC1tZW1vcnlcIjtcbmV4cG9ydCBjb25zdCBQQUNLQUdFX1ZFUlNJT04gPSBcIjAuOS4xMzZcIjtcbmV4cG9ydCAqIGFzIGNvbmZpZyBmcm9tIFwiLi9zcmMvY29uZmlnLnRzXCI7XG5leHBvcnQgKiBhcyBkYXRhYnJpY2tzQ2xpZW50IGZyb20gXCIuL3NyYy9kYXRhYnJpY2tzL2NsaWVudC50c1wiO1xuZXhwb3J0ICogYXMgZ3JhcGhpdGlPcHRpb25zIGZyb20gXCIuL3NyYy9ncmFwaGl0aS9vcHRpb25zLnRzXCI7XG5leHBvcnQgKiBhcyBncmFwaGl0aVJ1bnRpbWUgZnJvbSBcIi4vc3JjL2dyYXBoaXRpL3J1bnRpbWUudHNcIjtcbmV4cG9ydCAqIGFzIHBsdWdpbiBmcm9tIFwiLi9zcmMvcGx1Z2luLnRzXCI7XG5leHBvcnQgeyBEYXRhYnJpY2tzTWVtb3J5T3B0aW9uc1NjaGVtYSwgTWVtb3J5UGx1Z2luT3B0aW9uc1NjaGVtYSwgTUVNT1JZX0NPTkZJR19TQ0hFTUEgfSBmcm9tIFwiLi9zcmMvY29uZmlnLnRzXCI7XG5leHBvcnQgdHlwZSB7IERhdGFicmlja3NNZW1vcnlPcHRpb25zLCBNZW1vcnlQbHVnaW5PcHRpb25zLCBNZW1vcnlQbHVnaW5Db25maWcsIFJlc29sdmVkRGF0YWJyaWNrc01lbW9yeU9wdGlvbnMsIFJlc29sdmVkTWVtb3J5UGx1Z2luQ29uZmlnIH0gZnJvbSBcIi4vc3JjL2NvbmZpZy50c1wiO1xuZXhwb3J0IHsgTWFuYWdlZE1lbW9yeUVudHJ5U2NoZW1hLCBNYW5hZ2VkQWdlbnRNZW1vcnlDbGllbnQgfSBmcm9tIFwiLi9zcmMvZGF0YWJyaWNrcy9jbGllbnQudHNcIjtcbmV4cG9ydCB0eXBlIHsgTWFuYWdlZE1lbW9yeUVudHJ5LCBNYW5hZ2VkTWVtb3J5U2VhcmNoUmVzdWx0IH0gZnJvbSBcIi4vc3JjL2RhdGFicmlja3MvY2xpZW50LnRzXCI7XG5leHBvcnQgdHlwZSB7IEdyYXBoaXRpSGVhbHRoQ2hlY2tDb250ZXh0LCBHcmFwaGl0aUhlYWx0aENoZWNrLCBHcmFwaGl0aUNoaWxkUHJvY2VzcywgR3JhcGhpdGlSdW50aW1lT3B0aW9ucywgR3JhcGhpdGlQeXRob25Db21tYW5kIH0gZnJvbSBcIi4vc3JjL2dyYXBoaXRpL3J1bnRpbWUudHNcIjtcbmV4cG9ydCB7IE1lbW9yeVBsdWdpbiwgbWVtb3J5IH0gZnJvbSBcIi4vc3JjL3BsdWdpbi50c1wiO1xuIl19
|
package/package.json
CHANGED
|
@@ -19,23 +19,23 @@
|
|
|
19
19
|
"projen": "projen"
|
|
20
20
|
},
|
|
21
21
|
"devDependencies": {
|
|
22
|
-
"@dbx-tools/appkit-mastra": "^0.9.
|
|
22
|
+
"@dbx-tools/appkit-mastra": "^0.9.136",
|
|
23
23
|
"@types/json-schema": "^7",
|
|
24
24
|
"@types/node": "^24.6.0",
|
|
25
25
|
"typescript": "^5.9.3",
|
|
26
26
|
"vitest": "3.2.4"
|
|
27
27
|
},
|
|
28
28
|
"peerDependencies": {
|
|
29
|
-
"@dbx-tools/appkit-mastra": "^0.9.
|
|
29
|
+
"@dbx-tools/appkit-mastra": "^0.9.136"
|
|
30
30
|
},
|
|
31
31
|
"dependencies": {
|
|
32
32
|
"@databricks/appkit": "0.81.0",
|
|
33
|
-
"@dbx-tools/appkit": "^0.9.
|
|
34
|
-
"@dbx-tools/auth": "^0.9.
|
|
35
|
-
"@dbx-tools/cache": "^0.9.
|
|
36
|
-
"@dbx-tools/core": "^0.9.
|
|
37
|
-
"@dbx-tools/shared-core": "^0.9.
|
|
38
|
-
"@dbx-tools/shared-graphiti": "^0.9.
|
|
33
|
+
"@dbx-tools/appkit": "^0.9.136",
|
|
34
|
+
"@dbx-tools/auth": "^0.9.136",
|
|
35
|
+
"@dbx-tools/cache": "^0.9.136",
|
|
36
|
+
"@dbx-tools/core": "^0.9.136",
|
|
37
|
+
"@dbx-tools/shared-core": "^0.9.136",
|
|
38
|
+
"@dbx-tools/shared-graphiti": "^0.9.136",
|
|
39
39
|
"semver": "^7.7.3",
|
|
40
40
|
"zod": "4.3.6"
|
|
41
41
|
},
|
|
@@ -65,7 +65,7 @@
|
|
|
65
65
|
"./package.json": "./package.json"
|
|
66
66
|
}
|
|
67
67
|
},
|
|
68
|
-
"version": "0.9.
|
|
68
|
+
"version": "0.9.136",
|
|
69
69
|
"types": "./lib/index.d.ts",
|
|
70
70
|
"dbxToolsConfig": {
|
|
71
71
|
"tags": [
|