The Open Framework for Building Agents
docs: add Arcana memory provider (#2904)
Colton Padden68ccefb94168
diff --git a/apps/docs/lib/geistdocs/redirects.test.ts b/apps/docs/lib/geistdocs/redirects.test.tsindex 59623c6a4..3b2040373 100644--- a/apps/docs/lib/geistdocs/redirects.test.ts+++ b/apps/docs/lib/geistdocs/redirects.test.ts@@ -159,6 +159,14 @@ describe("compatibilityRedirects", () => {permanent: true,});});++ it("redirects the Arcana extension registry item to its memory provider", () => {+ expect(compatibilityRedirects).toContainEqual({+ source: "/r/extension/arcana.json",+ destination: "/r/memory/arcana.json",+ permanent: true,+ });+ });});describe("defaultLanguageRedirects", () => {diff --git a/apps/docs/lib/geistdocs/redirects.ts b/apps/docs/lib/geistdocs/redirects.tsindex 1a63a5307..8df102ef0 100644--- a/apps/docs/lib/geistdocs/redirects.ts+++ b/apps/docs/lib/geistdocs/redirects.ts@@ -97,6 +97,11 @@ export const rootMarkdownRedirects: DocsRedirect[] = [export const compatibilityRedirects: DocsRedirect[] = [...createIntegrationRedirects("chat-sdk-photon", "photon"),+ {+ source: "/r/extension/arcana.json",+ destination: "/r/memory/arcana.json",+ permanent: true,+ },{ source: "/evals", destination: "/benchmarks", permanent: true },{ source: "/feed", destination: "/rss.xml", permanent: true },{ source: "/feed.xml", destination: "/rss.xml", permanent: true },diff --git a/apps/docs/lib/integrations/data.ts b/apps/docs/lib/integrations/data.tsindex b2d4d5d6c..7e5de1521 100644--- a/apps/docs/lib/integrations/data.ts+++ b/apps/docs/lib/integrations/data.ts@@ -1560,64 +1560,6 @@ export default githubExtension({\`\`\`For local or non-Vercel deployments, omit \`connector\` and set \`GITHUB_TOKEN\`; the extension also accepts an explicit \`token\`. Prefer fine-grained credentials, expose only the presets the agent needs, and keep approval enabled for writes. See the [GitHub Tools eve documentation](https://github-tools.com/frameworks/eve#eve-extension) for token authentication, per-tool overrides, commit attribution, and the complete tool catalog.`,- },- arcana: {- logo: "arcana",- docsHref: "https://github.com/KybernesisAI/platform/tree/master/packages/arcana#readme",- keywords: [- "memory",- "long-term memory",- "mcp",- "semantic search",- "entity graph",- "timeline",- "brain notes",- "Kybernesis",- ],- install: `Install Kybernesis Arcana for eve:--\`\`\`bash-eve add extension/arcana-\`\`\`--This installs \`@kybernesis/arcana\` and writes an extension mount. The package requires Node.js 24 or later.`,- quickStart: `Create an Arcana workspace and workspace-scoped API key, then add both values to the agent's environment:--\`\`\`bash title=".env.local"-ARCANA_API_KEY=kb_your_api_key_here-ARCANA_WORKSPACE=your-workspace-\`\`\`--The registry creates this mount:--\`\`\`ts title="agent/extensions/arcana.ts"-import arcana from "@kybernesis/arcana";--export default arcana({- apiKey: process.env.ARCANA_API_KEY!,- workspace: process.env.ARCANA_WORKSPACE!,-});-\`\`\`--The filename supplies the \`arcana\` namespace. The extension adds an MCP memory connection, recall, remember, and brain-note skills, and instructions that tell the model to search the workspace before it claims not to know something.`,- configure: `An Arcana key is scoped to a workspace. Keep the key in a sensitive environment variable and use a separate workspace and key when people or tenants must not share memory. The model can choose what to store and retrieve, but it cannot choose the configured key or default workspace.--You can select a workspace per session with \`resolveWorkspace\`. Derive it only from verified session context, and only return workspaces that the configured key can access:--\`\`\`ts title="agent/extensions/arcana.ts"-import arcana from "@kybernesis/arcana";--export default arcana({- apiKey: process.env.ARCANA_API_KEY!,- workspace: process.env.ARCANA_WORKSPACE!,- resolveWorkspace: (ctx) =>- ctx.session.auth.current?.attributes.surface === "dm"- ? process.env.ARCANA_DM_WORKSPACE- : undefined,-});-\`\`\`--Arcana stores memories, embeddings, timeline entries, and brain notes in the selected workspace. The shipped instructions tell the model not to store passwords, access tokens, payment data, private keys, or one-time codes; add approval rules to memory-write tools when you need an enforced control. See the [Arcana package documentation](https://github.com/KybernesisAI/platform/tree/master/packages/arcana#readme) for the full configuration and tool reference.`,},hindsight: {logo: "hindsight",@@ -1718,6 +1660,46 @@ During \`eve dev\`, file memory stays in the local process. On Vercel, the defauconfigure: `Run \`eve integration setup file-memory\` to repair or re-run provisioning without reinstalling the registry item. Setup uses the first configured function region, preserves an existing eve-owned store if the project region later changes, and never adopts or changes an application store connected with \`BLOB_*\`.Provisioned bindings use the \`EVE_MEMORY_BLOB_*\` namespace. \`fileMemory()\` prefers \`EVE_MEMORY_BLOB_READ_WRITE_TOKEN\`, then \`EVE_MEMORY_BLOB_STORE_ID\` with Vercel OIDC from the environment or request context. Generic \`BLOB_*\` credentials remain a fallback for manually connected stores. See [File memory](/docs/memory/file) for backend behavior and manual configuration.`,+ },+ arcana: {+ logo: "arcana",+ docsHref: "https://github.com/KybernesisAI/platform/tree/master/packages/arcana#readme",+ keywords: ["memory", "long-term memory", "semantic search", "brain notes", "Kybernesis"],+ install: `Install the Kybernesis Arcana provider for eve:++\`\`\`bash+eve add memory/arcana+\`\`\`++This installs \`@kybernesis/arcana\` and writes a memory slot. The provider requires Node.js 24 or later and eve 0.49 or later.`,+ quickStart: `Create an Arcana workspace and workspace-scoped API key, then add both values to the agent's environment:++\`\`\`bash title=".env.local"+ARCANA_API_KEY=kb_your_api_key_here+ARCANA_WORKSPACE=your-workspace+\`\`\`++The registry creates this memory slot:++\`\`\`ts title="agent/memory/arcana.ts"+import { arcanaMemory } from "@kybernesis/arcana/memory";+import { defineMemory } from "eve/memory";+import { byPrincipal } from "eve/memory/scope";++export default defineMemory({+ description: "Recall and manage durable context for the current user.",+ provider: arcanaMemory({+ apiKey: process.env.ARCANA_API_KEY!,+ workspace: process.env.ARCANA_WORKSPACE!,+ }),+ scope: byPrincipal,+});+\`\`\`++The filename creates the \`arcana\` memory slot. Before each turn with at least four words, Arcana searches memories and queries brain notes, then injects the result as one context message. The provider also gives the model \`arcana__remember\`, \`arcana__recall\`, and \`arcana__search\` tools.`,+ configure: `Arcana does not capture turns automatically by default. The model stores memories deliberately with \`arcana__remember\`; set \`capture: { enabled: true }\` when you want it to capture completed turns automatically.++An Arcana key is scoped to a workspace. Keep the key in a sensitive environment variable and use a separate workspace and key when people or tenants must not share memory. The provider records eve's scope as a tag, but Arcana isolates data by workspace rather than by eve scope. See the [Arcana package documentation](https://github.com/KybernesisAI/platform/tree/master/packages/arcana#readme) for the full configuration and tool reference.`,},supermemory: {logo: "supermemory",diff --git a/apps/docs/lib/integrations/discovery.test.ts b/apps/docs/lib/integrations/discovery.test.tsindex f572c027a..aa00b744a 100644--- a/apps/docs/lib/integrations/discovery.test.ts+++ b/apps/docs/lib/integrations/discovery.test.ts@@ -124,16 +124,17 @@ describe("integration discovery", () => {expect(integrationSearchText(agentkit!)).toContain("long-term memory");});- it("renders the Kybernesis Arcana memory extension setup", () => {+ it("renders the Kybernesis Arcana memory provider setup", () => {const arcana = getIntegration("arcana");expect(arcana).toBeDefined();const markdown = integrationMarkdown(arcana!);- expect(markdown).toContain("eve add extension/arcana");- expect(markdown).toContain('import arcana from "@kybernesis/arcana"');+ expect(markdown).toContain("eve add memory/arcana");+ expect(markdown).toContain('import { arcanaMemory } from "@kybernesis/arcana/memory"');expect(markdown).toContain("ARCANA_API_KEY");expect(markdown).toContain("ARCANA_WORKSPACE");- expect(integrationSearchText(arcana!)).toContain("long-term memory");+ expect(markdown).toContain("capture: { enabled: true }");+ expect(integrationSearchText(arcana!)).toContain("Memory provider");});it("renders the Supermemory provider setup", () => {diff --git a/apps/docs/package.json b/apps/docs/package.jsonindex 739578a2a..c46d3558e 100644--- a/apps/docs/package.json+++ b/apps/docs/package.json@@ -64,7 +64,7 @@"@github-tools/eve-extension": "^0.1.0","@jetty/eve": "^0.3.0","@kapso/chat-adapter": "0.1.1",- "@kybernesis/arcana": "0.2.0",+ "@kybernesis/arcana": "0.4.1","@larksuite/vercel-chat-adapter": "0.1.2","@liveblocks/chat-sdk-adapter": "3.23.0","@novu/chat-sdk-adapter": "0.1.0",diff --git a/apps/docs/registry.json b/apps/docs/registry.jsonindex bb9ec9afa..0bb9bf7c0 100644--- a/apps/docs/registry.json+++ b/apps/docs/registry.json@@ -233,20 +233,25 @@]},{- "name": "extension/arcana",+ "name": "memory/arcana","type": "registry:item","title": "Kybernesis Arcana",- "description": "Give an eve agent a workspace-scoped long-term memory with recall, storage, and brain notes.",+ "description": "Give your agents workspace-scoped long-term memory with automatic recall and deliberate storage.","dependencies": ["@kybernesis/arcana"],"envVars": {"ARCANA_API_KEY": "","ARCANA_WORKSPACE": ""},+ "meta": {+ "eve": {+ "requires": ">=0.49.0"+ }+ },"files": [{- "path": "registry/extensions/arcana.ts",+ "path": "registry/memory/arcana.ts","type": "registry:file",- "target": "agent/extensions/arcana.ts"+ "target": "agent/memory/arcana.ts"}]},diff --git a/apps/docs/registry/extensions/arcana.ts b/apps/docs/registry/extensions/arcana.tsdeleted file mode 100644index d899380c9..000000000--- a/apps/docs/registry/extensions/arcana.ts+++ /dev/null@@ -1,6 +0,0 @@-import arcana from "@kybernesis/arcana";--export default arcana({- apiKey: process.env.ARCANA_API_KEY!,- workspace: process.env.ARCANA_WORKSPACE!,-});diff --git a/apps/docs/registry/memory/arcana.ts b/apps/docs/registry/memory/arcana.tsnew file mode 100644index 000000000..f6844b929--- /dev/null+++ b/apps/docs/registry/memory/arcana.ts@@ -0,0 +1,12 @@+import { arcanaMemory } from "@kybernesis/arcana/memory";+import { defineMemory } from "eve/memory";+import { byPrincipal } from "eve/memory/scope";++export default defineMemory({+ description: "Recall and manage durable context for the current user.",+ provider: arcanaMemory({+ apiKey: process.env.ARCANA_API_KEY!,+ workspace: process.env.ARCANA_WORKSPACE!,+ }),+ scope: byPrincipal,+});diff --git a/apps/docs/scripts/validate-memory-registry.ts b/apps/docs/scripts/validate-memory-registry.tsindex 50f3521b7..1d310b4a3 100644--- a/apps/docs/scripts/validate-memory-registry.ts+++ b/apps/docs/scripts/validate-memory-registry.ts@@ -62,6 +62,18 @@ for (const item of items) {'Registry item "memory/file" must declare the trusted file-memory setup flow.',);}+ } else if (slug === "arcana") {+ if (!item.dependencies?.includes("@kybernesis/arcana")) {+ throw new Error('Registry item "memory/arcana" must depend on @kybernesis/arcana.');+ }+ if (+ !("ARCANA_API_KEY" in (item.envVars ?? {})) ||+ !("ARCANA_WORKSPACE" in (item.envVars ?? {}))+ ) {+ throw new Error(+ 'Registry item "memory/arcana" must declare ARCANA_API_KEY and ARCANA_WORKSPACE as environment variables.',+ );+ }} else if (slug === "supermemory") {if (!item.dependencies?.includes("@supermemory/eve")) {throw new Error('Registry item "memory/supermemory" must depend on @supermemory/eve.');diff --git a/packages/eve-catalog/src/index.test.ts b/packages/eve-catalog/src/index.test.tsindex f21c200ac..3f574d349 100644--- a/packages/eve-catalog/src/index.test.ts+++ b/packages/eve-catalog/src/index.test.ts@@ -127,8 +127,8 @@ describe("integration catalog", () => {expect(getIntegrationEntry("upstash-agentkit")?.connection).toBeUndefined();});- it("exposes Kybernesis Arcana as an extension", () => {- expect(getIntegrationEntry("arcana")?.kind).toBe("extension");+ it("exposes Kybernesis Arcana as a memory provider", () => {+ expect(getIntegrationEntry("arcana")?.kind).toBe("memory");expect(getIntegrationEntry("arcana")?.connection).toBeUndefined();});diff --git a/packages/eve-catalog/src/index.ts b/packages/eve-catalog/src/index.tsindex e72105ad2..7416a4176 100644--- a/packages/eve-catalog/src/index.ts+++ b/packages/eve-catalog/src/index.ts@@ -352,9 +352,9 @@ export const INTEGRATIONS: readonly IntegrationEntry[] = [{slug: "arcana",name: "Kybernesis Arcana",- kind: "extension",+ kind: "memory",tagline:- "Give your agent workspace-scoped long-term memory with recall, storage, and brain notes.",+ "Give your agents workspace-scoped long-term memory with automatic recall and deliberate storage.",surfaces: { scaffoldable: false, registry: true, gallery: true },},{diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 3e9cd3716..20d791695 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -282,8 +282,8 @@ importers:specifier: 0.1.1version: 0.1.1([email protected]([email protected]))([email protected]([email protected]([email protected]))([email protected])([email protected]))([email protected])([email protected])'@kybernesis/arcana':- specifier: 0.2.0- version: 0.2.0(eve@packages+eve)+ specifier: 0.4.1+ version: 0.4.1(eve@packages+eve)'@larksuite/vercel-chat-adapter':specifier: 0.1.2version: 0.1.2([email protected]([email protected]))([email protected])([email protected]([email protected]([email protected]))([email protected])([email protected]))([email protected]([email protected]))([email protected])([email protected])@@ -3449,11 +3449,11 @@ packages:'@kwsites/[email protected]':resolution: {integrity: sha512-GaHYm+c0O9MjZRu0ongGBRbinu8gVAMd2UZjji6jVmqKtZluZnptXGWhz1E8j8D2HJ3f/yMxKAUC0b+57wncIw==}- '@kybernesis/[email protected]':- resolution: {integrity: sha512-9F0zw/SDgutjOFXqnpgyJhBuePVbGKJRS+p0V37ejbcNe+GH/LTWLowEz8t/o9d98JgnJfxK0cuJcEPqjI2qrQ==}+ '@kybernesis/[email protected]':+ resolution: {integrity: sha512-UrHefmb7ZWSiKwb42wbDJsu+HS63FEHR8QQGbELdKi2cUpbcbJStqfoyO6BoKrZhubuZTOAWMRQA3lgdFSWxFw==}engines: {node: 24.x}peerDependencies:- eve: '>=0.30.0 <0.31.0'+ eve: '>=0.49.0 <0.50.0''@langchain/[email protected]':resolution: {integrity: sha512-GIrJktdsFPx8gM0C3VyikkeYGZAV7iRIzUJuS5tFatiKLExybou0LI0MuxH9kksN38quyfWdQDl20lIEAEVkVA==}@@ -17876,7 +17876,7 @@ snapshots:'@kwsites/[email protected]': {}- '@kybernesis/[email protected](eve@packages+eve)':+ '@kybernesis/[email protected](eve@packages+eve)':dependencies:eve: link:packages/evezod: 4.4.3diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yamlindex cb2cc3a0b..6be61ef55 100644--- a/pnpm-workspace.yaml+++ b/pnpm-workspace.yaml@@ -66,6 +66,7 @@ catalogs:minimumReleaseAge: 2880 # 2 daysminimumReleaseAgeExclude:+ - "@kybernesis/arcana"- "@linqapp/chat-sdk-adapter"- "@linqapp/sdk"- "@supermemory/eve"