@kybernesis/arcana weekly downloads statistics

@kybernesis/arcana

Kybernesis Arcana long-term memory for eve agents.

Mounting this extension gives an agent a durable workspace brain — timeline, entity graph, fact store, semantic search, and a brain/ notes directory — plus the skills and always-on instructions that make the agent actually use it: recall-first lookups, proactive fact storage, and two-step brain notes.

What ships in the package

• @kybernesis/arcana/memory — arcanaMemory(), an eve 0.49 memory provider (see below).

Contribution	What it does
connections/memory	MCP connection to https://mcp.arcana.kybernesis.ai/mcp (static-key auth + the required X-Kyberagent-Agent workspace header)
skills/recall	Entity/timeline/semantic retrieval playbook
skills/remember	Proactive fact storage, tagging, correction detection
skills/brain-note	Long-form notes: brain_write and brain_add, always both
instructions.md	Always-on memory rules: recall-first, never claim ignorance without searching, proactive remember, no secrets in memory

Tools surfaced to the model (remote names): arcana_recall, arcana_search, arcana_timeline, arcana_remember, arcana_brain_list/read/write/add/query, and more. See Tool naming for how names are qualified.

Prerequisites

1. An Arcana workspace and a kb_ API key for it (from arcana.kybernesis.ai). Keys are workspace-scoped: a key for one workspace gets 403 on any other. One brain per mount → one workspace + one key per mount.
2. eve >= 0.29 in the consuming agent.
3. Validate the key before wiring anything (read-only):

curl -s -o /dev/null -w "HTTP %{http_code}\n" \
  -H "Authorization: Bearer kb_..." \
  -H "X-Kyberagent-Agent: <workspace-slug>" \
  "https://api.arcana.kybernesis.ai/brain/<workspace-slug>/timeline?limit=1"
# expect HTTP 200

Install

From npm (once published):

npm install @kybernesis/arcana

From a monorepo workspace (this repo checked out under packages/arcana):

// consuming agent package.json
{
  "workspaces": ["packages/*"],
  "dependencies": { "@kybernesis/arcana": "*" }
}

Then npm install. Under eve dev, workspace-mounted extensions rebuild automatically when their source changes.

Mount it

Create one file in the consuming agent. The filename is the mount namespace (here: arcana):

// agent/extensions/arcana.ts
import arcana from "@kybernesis/arcana";

export default arcana({
  apiKey: process.env.ARCANA_API_KEY!,
  workspace: "my-company",
});

That's the whole integration: connection, skills, and memory instructions are now part of the agent.

Config reference

Option	Type	Required	Purpose
apiKey	string	yes	The workspace's kb_ key. Read it from an env var — never hardcode.
workspace	string	yes	Arcana workspace slug this brain reads/writes.
resolveWorkspace	(ctx) => string | undefined	no	Per-session workspace override, resolved at runtime. Return undefined to fall back to workspace.

resolveWorkspace example — route DM sessions to a different brain than public-channel sessions (pair it with a verified session attribute your channel stamps; never key it off model output):

export default arcana({
  apiKey: process.env.ARCANA_API_KEY!,
  workspace: "my-company",
  resolveWorkspace: (ctx) =>
    ctx.session.auth.current?.attributes.surface === "dm"
      ? "my-company-dm"
      : undefined,
});

Scoped-key caveat: resolveWorkspace may only select workspaces the configured apiKey can reach — with workspace-scoped keys, keep one mount per workspace instead. And it must derive only from verified session context (ctx.session.auth attributes stamped by route/channel auth), never from model output or message text.

Environment variables

Local dev reads .env.local; deployed agents read Vercel envs. Set both:

echo 'ARCANA_API_KEY="kb_..."' >> .env.local

vercel env add ARCANA_API_KEY production   # mark Sensitive
vercel env add ARCANA_API_KEY preview      # mark Sensitive
vercel env add ARCANA_API_KEY development  # (Sensitive not supported on dev)

Note: eve deploy runs vercel env pull, which overwrites .env.local from the development environment — so the Vercel env is the source of truth; put real values there.

Deploy

npm run typecheck && npx eve info   # expect 0 errors / 0 warnings
npx eve deploy

Two rules that save hours:

1. Deployed surfaces (e.g. Slack) run the deployed build — redeploy after every change, or you'll debug stale code.
2. Memory failures are graceful: a missing/invalid key surfaces as a tool error the model reports, never a crash. If memory "doesn't work" after deploy, check the env vars in the target environment first.

eve memory slot (eve ≥ 0.49)

eve 0.49 added first-class memory: a slot file names a provider, eve resolves who the memory belongs to from trusted session context, calls the provider to recall before the model sees a turn and to capture after it answers, and mounts the provider's tools as <slot>__<tool>. Arcana ships as such a provider, so an agent gets recall-before-every-turn without a skill telling the model to go and look:

import { defineMemory } from "eve/memory";
import { byPrincipal } from "eve/memory/scope";
import { arcanaMemory } from "@kybernesis/arcana/memory";

export default defineMemory({
  description: "Durable company memory in Arcana.",
  provider: arcanaMemory({
    apiKey: process.env.ARCANA_API_KEY!,
    workspace: process.env.ARCANA_COMPANY_WORKSPACE!,
  }),
  scope: byPrincipal,
});

What the provider does, and the two defaults that differ from the hosted providers eve documents:…