@memco/eve 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Memco Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,267 @@
-# Temporary Holding Version
+# memco for eve
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p>
+  <a href="https://github.com/memcoai/eve-memco/actions/workflows/ci.yaml"><img alt="CI" src="https://github.com/memcoai/eve-memco/actions/workflows/ci.yaml/badge.svg?branch=main"></a>
+  <img alt="Node version" src="https://img.shields.io/node/v/@memco/eve">
+  <a href="LICENSE"><img alt="Licence" src="https://img.shields.io/npm/l/@memco/eve"></a>
+</p>
+
+Shared memory for [eve](https://github.com/vercel/eve) agents. Make useful knowledge from one task
+available to later conversations and other users sharing that memory.
+
+`@memco/eve` connects your agent to [memco](https://memco.ai). Agents can search existing knowledge,
+save findings, enrich memories and report whether they helped. For example, an agent can save a
+support workaround that another agent serving the same customer can reuse.
+
+Use one API token for a shared memco identity, or an API client to give each tenant its own memory
+network. The provider supplies memory guidance and tools; it does not automatically capture
+conversation transcripts.
+
+## Requirements and installation
+
+You need Node.js 24 or later, an existing eve app using `eve >=0.84.1 <0.91.0`, and a memco account. If
+you are starting a new app, follow [eve's first-agent tutorial](https://eve.dev/docs/tutorial/first-agent).
+
+Install the provider in your eve app:
+
+```sh
+npm i @memco/eve
+```
+
+Create an API token in the [memco dashboard](https://spark.memco.ai/) for the shared-identity
+quickstart below. For a multi-tenant app, use an API client with network and user management
+permissions and the admin grant to act for your users; see the
+[credential guide](https://docs.memco.ai/sdk/embedding-memory/#managing-networks-and-users).
+
+Keep credentials on the server. Choose one credential set: API client credentials take precedence
+when both they and an API token are set in the environment.
+
+## Quickstart: shared identity
+
+Every caller of this deployment uses the token's memco identity and shares the memory it can
+access. Use this mode for a personal agent or one trusted audience, not for separate customers.
+
+Set the token in your deployment's environment, or in an uncommitted `.env.local` for `eve dev`:
+
+```dotenv
+MEMCO_API_TOKEN=replace-with-your-memco-api-token
+```
+
+Add the memory slot at `agent/memory/memco.ts`:
+
+```ts
+import { memco } from '@memco/eve'
+import { defineMemory } from 'eve/memory'
+import { byPrincipal } from 'eve/memory/scope'
+
+export default defineMemory({
+  description:
+    "The team's shared memory: search it before working something out.",
+  provider: memco({ domain: 'knowledge' }),
+  namespace: 'acme-support-agent',
+  scope: byPrincipal
+})
+```
+
+`byPrincipal` scopes eve's use of the slot; it does not create separate memco identities or isolate
+callers' stored memories when they use one token. For tenant isolation, use the
+[multi-tenant setup](#multi-tenant-setup) below.
+
+### Verify your setup
+
+Use a test account or network for this check so the example does not enter production memory.
+Start your agent with tool inputs and results visible:
+
+```sh
+npx eve dev --tools full
+```
+
+1. Ask: "Save this test fact in memco: the sandbox support demo uses the escalation code
+   cobalt-orchid. This is test data, not a real support policy." Confirm that
+   `memco__create_memory` runs and its result reports success.
+2. Enter `/reset` in eve's terminal UI to start a fresh session, then ask: "Search memco for the
+   sandbox support demo's escalation code." Confirm that `memco__search` returns the saved fact.
+   An answer from the model alone is not evidence that memory worked.
+3. After using a real memory on a task, tell the agent whether it worked, and ask it to report
+   that through `memco__share_feedback`. That feedback is part of the learning loop, alongside
+   creating and enriching memories.
+
+The fresh session checks persistence beyond conversation history. See
+[eve's terminal UI guide](https://eve.dev/docs/guides/dev-tui) for tool display and logs. If tools
+are missing, check the active credential, its role and access to the `knowledge` domain, and the
+provider's `[@memco/eve]` logs.
+
+## Multi-tenant setup
+
+Each tenant gets its own memco network, and each of its users an external user placed in it. Users
+within a tenant share that tenant's memory. The provider derives tenant and user identities from
+verified sign-in, never from the model.
+
+Set your API client's credentials in the server environment:
+
+```dotenv
+MEMCO_CLIENT_ID=replace-with-your-api-client-id
+MEMCO_CLIENT_SECRET=replace-with-your-api-client-secret
+```
+
+Use this definition in `agent/memory/memco.ts` instead of the shared-identity example:
+
+```ts
+import { byTenant, memco } from '@memco/eve'
+import { defineMemory } from 'eve/memory'
+
+export default defineMemory({
+  description:
+    "Your organization's shared memory: search it before working something out.",
+  provider: memco({ domain: 'knowledge' }),
+  namespace: 'acme-support-agent',
+  scope: byTenant(principal => {
+    const tenant = principal.attributes['tenantId']
+    return typeof tenant === 'string' ? tenant : null
+  })
+})
+```
+
+To show readable names in memco, add `userName: principal => ...` to `memco()`. See
+[Options](#options).
+
+Your authentication integration must supply the verified `tenantId` attribute; adapt the resolver
+to your sign-in system. `byTenant` turns memory off, and eve calls no provider, for a caller that is
+not a signed-in user or whose tenant the resolver cannot name. That includes eve's local development
+principal: test this mode through a channel with authenticated users, not the unauthenticated local
+terminal session.
+
+A `byTenant` slot needs the API client. With a token instead, every tenant would share one memco
+identity, so the provider fails the turn rather than run.
+
+To check sharing and isolation, save a test fact as one user, then search for it in a new session
+as another user in the same tenant. It should be available there. A user in a different tenant must
+not be able to retrieve that tenant's memory, including by its ID with `memco__get_memory`. Inspect
+tool results, not just the agent's answer; a search miss alone does not establish access isolation.
+
+Both setups are runnable agents in [`examples/`](examples).
+
+## Memory behaviour
+
+The provider adds guidance and tools to the agent's normal turn lifecycle:
+
+- On the first turn of a memco session, a briefing supplies the domain's guidance (when to search,
+  what to save, which tags to use) and the session's instructions. It is recalled once, under the id
+  `memco-briefing`, and stays in context.
+- When a session starts and every `nudgeEvery` turns after, a nudge beside the turn's input asks the
+  agent to search memory before working and to save lessons the team will need again. Each copy
+  stays in context for the rest of the session.
+- The slot exposes `memco__search`, `memco__get_memory`, `memco__create_memory`,
+  `memco__enrich_memory`, `memco__share_feedback` and `memco__revert_memory`, as the credential's
+  role allows. The `memco__` prefix comes from the slot's file name; tool descriptions and results
+  use the same names.
+
+The agent decides when to call the tools. Searching is encouraged, not enforced, and writes happen
+only through tool calls, so nothing is saved after a turn or when a session ends; eve gives a
+provider no way to act at either point. Tool inputs, including search queries and memory content, are sent to
+memco; the provider does not automatically upload the conversation transcript. Set your agent's
+instructions to exclude secrets and other content that should not become shared memory.
+
+## Options
+
+`memco(options)` takes the memco client's own options (`host`, `timeout`, `token`, `clientId`,
+`clientSecret`, ...), each falling back to the environment as the client does, and:
+
+| Option          | Default     | Meaning                                                                       |
+| --------------- | ----------- | ----------------------------------------------------------------------------- |
+| `domain`        | `knowledge` | The memco memory domain the slot reads and writes                             |
+| `keyTtlMinutes` | `10`        | Lifetime, in whole minutes, of the key a multi-tenant turn uses for its user  |
+| `userName`      | none        | Names a multi-tenant user when memco first creates them, from their principal |
+| `nudgeEvery`    | `5`         | Turns between nudges, after the one a session starts with                     |
+
+`userName` is a label: identity stays the external ID, which holds no personal data, so a name may
+be the first thing that does. An existing user keeps their name. Take it from your verified sign-in,
+never from the model.
+
+See the [SDK configuration reference](https://docs.memco.ai/sdk/#configuration) for client
+settings and environment variables.
+
+## Production considerations
+
+### Namespaces and preview deployments
+
+In multi-tenant mode, each tenant's network and users are named from eve's namespace. Set an
+explicit, stable `namespace` before launch:
+
+- Make it unique per app within your memco organisation. Apps using the same namespace, tenant ID
+  and domain address the same tenant network.
+- Changing it starts tenants in newly named networks without their existing memory. eve's default
+  namespace includes the slot's file name, so without an explicit one, renaming the slot does the
+  same. This does not delete the old networks.
+- With eve's default namespace, Preview deployments get separate networks and users per branch
+  with traffic. Nothing removes those automatically. An explicit namespace is used as-is, with no
+  environment suffix: do not reuse the production namespace and organisation for Preview. Use a
+  separate memco organisation, or a namespace resolver that returns a distinct preview namespace
+  or `null` there. See [eve's namespace rules](https://eve.dev/docs/memory#namespace).
+
+A namespace does not partition the token's stored memory in shared-identity mode.
+
+### Failure behaviour
+
+During recall and tool setup, a memco outage or timeout leaves the turn without memory and the
+provider logs why. Authentication, permission and configuration errors are not treated as outages:
+those errors propagate rather than silently disabling memory. Errors from executing a memory tool
+or closing its session also propagate; the setup fallback does not cover every call in a turn.
+
+### API calls and rate limits
+
+A multi-tenant turn acts as the tenant's user with a key minted for the turn and ended when it
+completes. eve does not report a failed or cancelled turn to the provider, so that key ends with the
+next turn in the same process, or expires. eve keeps the provider's state per conversation, so a user's first turn in each
+conversation provisions again: creating a user or network that already exists costs a second call
+to find it, and adding a member already in the network changes nothing.
+
+| Turn                                     | Calls                                                                                                                                              |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| First of a conversation, multi-tenant    | Create (or find) the external user and the tenant network, add the user to it; mint a key; `ListDomains`, `StartSession`, `ListTools`; end the key |
+| Every later one, multi-tenant            | Mint a key; `ListDomains`, `GetSession`, `ListTools`; end the key                                                                                  |
+| First of a conversation, shared identity | `ListDomains`, `StartSession`, `ListTools`                                                                                                         |
+| Every later one, shared identity         | `ListDomains`, `GetSession`, `ListTools`                                                                                                           |
+
+Each tool the model calls is one more. In multi-tenant mode the API client also exchanges its
+credentials for a token, once and then as it expires. All of a deployment's tenants share the API
+client's rate limits.
+
+Deleting a tenant's memory is a call you make yourself, `client.networks.delete(networkId)` with
+the [memco SDK](https://www.npmjs.com/package/@memco/memcoai).
+
+## Development
+
+From a checkout of this repository, using Node.js 24 or later:
+
+```sh
+make install   # npm ci
+make check     # lint, typecheck, test
+```
+
+### Validation
+
+`examples/` holds a shared-identity and a multi-tenant agent, and `examples/validate.ts` drives them
+with real turns against a real model and memco. It checks that memories land, are used and stay
+within their tenant, and that a turn's key is ended. It needs Docker and a dedicated memco test
+organisation: each run writes synthetic facts. A multi-tenant run makes its own tenants and removes
+them at the end; a shared-identity run reverts what it wrote.
+
+```sh
+export ANTHROPIC_API_KEY=... MEMCO_API_TOKEN=... MEMCO_CLIENT_ID=... MEMCO_CLIENT_SECRET=...
+make examples                  # after any change to src/
+make validate MODE=single
+make validate MODE=multi
+```
+
+`VALIDATE_TURN_SECONDS` sets how long a turn may take, `VALIDATE_SAMPLES=0` skips the scenarios that
+only report rates, and `VALIDATE_KEEP=1` keeps a run's tenants or memories, to look at them in the
+dashboard.
+
+`.github/workflows/system.yaml` runs this on every pull request from this repository, and the
+release pipeline requires it before publishing. It reads the same four variables as secrets of a
+GitHub environment named `system-test`.
+
+## Licence
+
+[MIT](LICENSE)

package/dist/src/derive.d.ts

@@ -0,0 +1,35 @@
+import type { SessionAuthContext } from 'eve/context';
+/**
+ * The Memco external id of one principal of one tenant.
+ *
+ * It names the parts eve's `byPrincipal` scope uses, with a missing issuer
+ * as `null`, as eve encodes it. The tenant is part of it because an external
+ * user sits in one network per domain: without it, a principal under two
+ * tenants would be moved between their networks. The namespace is part of it
+ * so two apps in one Memco organization never share a user.
+ *
+ * Changing this derivation is a data migration: every existing user is
+ * orphaned.
+ *
+ * @param namespace The slot's resolved namespace, `ctx.memory.scope.namespace`.
+ * @param tenantId The tenant the principal acts under.
+ * @param principal The authenticated caller of the turn.
+ * @returns `eve-` and 64 hex digits; no personal data.
+ */
+export declare function externalId(namespace: string, tenantId: string, principal: SessionAuthContext): string;
+/**
+ * The name of one tenant's Memco network in one domain.
+ *
+ * Network names are unique across an organization's domains, so the domain
+ * is part of the name. The hash keeps long or sensitive tenant ids out of the
+ * service and fixes the length within a domain.
+ *
+ * Changing this derivation is a data migration: every tenant's existing
+ * network, and the memory in it, is orphaned.
+ *
+ * @param namespace The slot's resolved namespace, `ctx.memory.scope.namespace`.
+ * @param tenantId The tenant the network serves.
+ * @param domain The Memco memory domain.
+ * @returns `eve-<domain>-` and 64 hex digits.
+ */
+export declare function networkName(namespace: string, tenantId: string, domain: string): string;

package/dist/src/derive.js

@@ -0,0 +1,54 @@
+import { createHash } from 'node:crypto';
+/**
+ * Hash the parts as one JSON array. The array encodes each part with its
+ * boundaries, so (`acme1`, `23`) and (`acme`, `123`) never hash alike, as a
+ * plain concatenation would.
+ */
+function digest(parts) {
+    return createHash('sha256').update(JSON.stringify(parts)).digest('hex');
+}
+/**
+ * The Memco external id of one principal of one tenant.
+ *
+ * It names the parts eve's `byPrincipal` scope uses, with a missing issuer
+ * as `null`, as eve encodes it. The tenant is part of it because an external
+ * user sits in one network per domain: without it, a principal under two
+ * tenants would be moved between their networks. The namespace is part of it
+ * so two apps in one Memco organization never share a user.
+ *
+ * Changing this derivation is a data migration: every existing user is
+ * orphaned.
+ *
+ * @param namespace The slot's resolved namespace, `ctx.memory.scope.namespace`.
+ * @param tenantId The tenant the principal acts under.
+ * @param principal The authenticated caller of the turn.
+ * @returns `eve-` and 64 hex digits; no personal data.
+ */
+export function externalId(namespace, tenantId, principal) {
+    return `eve-${digest([
+        namespace,
+        tenantId,
+        principal.principalType,
+        principal.authenticator,
+        principal.issuer ?? null,
+        principal.principalId
+    ])}`;
+}
+/**
+ * The name of one tenant's Memco network in one domain.
+ *
+ * Network names are unique across an organization's domains, so the domain
+ * is part of the name. The hash keeps long or sensitive tenant ids out of the
+ * service and fixes the length within a domain.
+ *
+ * Changing this derivation is a data migration: every tenant's existing
+ * network, and the memory in it, is orphaned.
+ *
+ * @param namespace The slot's resolved namespace, `ctx.memory.scope.namespace`.
+ * @param tenantId The tenant the network serves.
+ * @param domain The Memco memory domain.
+ * @returns `eve-<domain>-` and 64 hex digits.
+ */
+export function networkName(namespace, tenantId, domain) {
+    return `eve-${domain}-${digest([namespace, tenantId])}`;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+export { memco, type MemcoProviderOptions, type UserNameResolver } from './provider.js';
+export { byTenant, type TenantResolver } from './scope.js';

package/dist/src/index.js

@@ -0,0 +1,2 @@
+export { memco } from './provider.js';
+export { byTenant } from './scope.js';

package/dist/src/provider.d.ts

@@ -0,0 +1,120 @@
+import { type AddMemberOptions, type CreateNetworkOptions, type CreateUserOptions, type MemcoOptions, type Session, type SessionOptions } from '@memco/memcoai';
+import type { SessionAuthContext } from 'eve/context';
+import { type MemoryProvider, type MemoryRecallResult, type MemoryToolSet } from 'eve/memory';
+/** Names a user for people reading Memco, or `null` for none. */
+export type UserNameResolver = (principal: SessionAuthContext) => string | null | undefined | Promise<string | null | undefined>;
+/** What the provider sets beyond the Memco client's own options. */
+export interface MemcoProviderOptions extends MemcoOptions {
+    /** The Memco memory domain the slot reads and writes. Defaults to `knowledge`. */
+    domain?: string;
+    /**
+     * How many minutes a key acting as a tenant's user lives, in multi-tenant
+     * mode. Each turn mints one and ends it when the turn completes, or when the
+     * next turn starts after one that failed. A session unused for this long is
+     * closed by whichever turn next asks for memory in the process; a session in
+     * use outlives it, as its key renews. A process that ends mid-turn leaves its
+     * key to expire. Defaults to 10.
+     */
+    keyTtlMinutes?: number;
+    /**
+     * The readable name of a tenant's user, in multi-tenant mode, set when Memco
+     * first creates them; an existing user keeps theirs. It is a label: identity
+     * stays the external id, which holds no personal data, so a name may be the
+     * first thing here that does. Without one, or when it returns none, a user is
+     * named by the external id.
+     */
+    userName?: UserNameResolver;
+    /**
+     * How many turns apart the nudge is recalled, after the one a session starts
+     * with. Each copy stays in context for the rest of the eve session, so a
+     * higher number costs fewer tokens and keeps the instruction further from
+     * the latest turn. Defaults to 5.
+     */
+    nudgeEvery?: number;
+}
+/** The part of a Memco session the provider uses. */
+export type MemcoSession = Pick<Session, 'id' | 'instructions' | 'domain' | 'close' | 'tools'>;
+/** The part of the Memco client the provider uses. */
+export interface MemcoClient {
+    readonly credentialKind: 'token' | 'apiClient';
+    readonly memory: {
+        startSession(domain: string, options?: SessionOptions): Promise<MemcoSession>;
+        resumeSession(sessionId: string, options?: SessionOptions): Promise<MemcoSession>;
+    };
+    readonly users: {
+        createOrGet(externalId: string, options: CreateUserOptions): Promise<{
+            readonly id: string;
+        }>;
+    };
+    readonly networks: {
+        createOrGet(options: CreateNetworkOptions): Promise<{
+            readonly id: string;
+        }>;
+        addMember(networkId: string, options: AddMemberOptions): Promise<unknown>;
+    };
+}
+/** What eve keeps for one user's Memco session, across turns. JSON only. */
+export interface StoredSession {
+    /** The Memco session the next turn resumes. */
+    readonly sessionId?: string;
+    /** Whether the user and the tenant network are known to exist. */
+    readonly provisioned?: boolean;
+}
+/** Every stored session of one eve session, by {@link Identity.stateKey}. */
+export type StoredSessions = Readonly<Record<string, StoredSession>>;
+/** Where the stored sessions live: eve's `defineState` in production. */
+export interface SessionState {
+    get(): StoredSessions;
+    update(fn: (current: StoredSessions) => StoredSessions): void;
+}
+/** What {@link createProvider} is built from. */
+export interface ProviderDependencies {
+    /** The Memco client, created on first use. */
+    client: () => MemcoClient;
+    state: SessionState;
+    domain: string;
+    keyTtlMinutes: number;
+    nudgeEvery: number;
+    userName?: UserNameResolver;
+    /** The current time, in milliseconds. */
+    now: () => number;
+    log: (message: string) => void;
+}
+/** The stable id of the briefing, so a later recall replaces it in place. */
+export declare const BRIEFING_ID = "memco-briefing";
+/**
+ * Memco Shared Memory as an eve memory provider.
+ *
+ * The credential decides the mode. A token is single-user: every caller shares
+ * the token's Memco identity. An API client's id and secret are multi-tenant:
+ * scope the slot with {@link byTenant}, and each tenant gets its own Memco
+ * network, each of its users an external user placed in it.
+ *
+ * @param options The domain, the key lifetime, and the Memco client's own
+ *   options, each falling back to the environment as the client does.
+ * @returns The provider, for `defineMemory({ provider })`.
+ *
+ * @example
+ * ```ts
+ * export default defineMemory({
+ *   description: "The team's shared memory.",
+ *   provider: memco(),
+ *   scope: byTenant(principal => principal.attributes.tenantId as string)
+ * })
+ * ```
+ */
+export declare function memco(options?: MemcoProviderOptions): MemoryProvider;
+/**
+ * Build the provider from its dependencies.
+ *
+ * @internal Exported for the tests, which supply a fake client and state.
+ */
+export declare function createProvider(dependencies: ProviderDependencies): {
+    recall: {
+        'turn.started': (context: import("eve/memory").MemoryTurnStartedContext) => Promise<MemoryRecallResult>;
+    };
+    tools: (context: import("eve/memory").MemoryToolsContext) => Promise<MemoryToolSet | null>;
+    capture: {
+        'turn.completed': (context: import("eve/memory").MemoryTurnCompletedContext) => Promise<void>;
+    };
+};

package/dist/src/provider.js

@@ -0,0 +1,314 @@
+import { Memco, MemcoConfigError, MemcoNotFoundError, MemcoPermissionError, MemcoTimeoutError, MemcoUnavailableError, briefing } from '@memco/memcoai';
+import { defineState } from 'eve/context';
+import { defineMemoryProvider } from 'eve/memory';
+import { defineTool } from 'eve/tools';
+import { externalId, networkName } from './derive.js';
+import { TENANT_SCOPE } from './scope.js';
+/** The stable id of the briefing, so a later recall replaces it in place. */
+export const BRIEFING_ID = 'memco-briefing';
+const sessions = defineState('memco.sessions', () => ({}));
+/**
+ * Memco Shared Memory as an eve memory provider.
+ *
+ * The credential decides the mode. A token is single-user: every caller shares
+ * the token's Memco identity. An API client's id and secret are multi-tenant:
+ * scope the slot with {@link byTenant}, and each tenant gets its own Memco
+ * network, each of its users an external user placed in it.
+ *
+ * @param options The domain, the key lifetime, and the Memco client's own
+ *   options, each falling back to the environment as the client does.
+ * @returns The provider, for `defineMemory({ provider })`.
+ *
+ * @example
+ * ```ts
+ * export default defineMemory({
+ *   description: "The team's shared memory.",
+ *   provider: memco(),
+ *   scope: byTenant(principal => principal.attributes.tenantId as string)
+ * })
+ * ```
+ */
+export function memco(options = {}) {
+    const { domain = 'knowledge', keyTtlMinutes = 10, nudgeEvery = 5, userName, ...clientOptions } = options;
+    // Checked here so a misconfiguration fails when the slot loads, not on
+    // every turn.
+    if (!Number.isInteger(keyTtlMinutes) || keyTtlMinutes < 1) {
+        throw new MemcoConfigError(`keyTtlMinutes must be a whole number of minutes from 1 up, got ${keyTtlMinutes}`);
+    }
+    if (!Number.isInteger(nudgeEvery) || nudgeEvery < 1) {
+        throw new MemcoConfigError(`nudgeEvery must be a whole number of turns from 1 up, got ${nudgeEvery}`);
+    }
+    let client;
+    return defineMemoryProvider(createProvider({
+        // Created on first use, so the environment is read when the agent runs
+        // rather than when the slot's module loads.
+        client: () => (client ??= new Memco(clientOptions)),
+        state: sessions,
+        domain,
+        keyTtlMinutes,
+        nudgeEvery,
+        ...(userName === undefined ? {} : { userName }),
+        now: Date.now,
+        log: message => console.warn(`[@memco/eve] ${message}`)
+    }));
+}
+/**
+ * Build the provider from its dependencies.
+ *
+ * @internal Exported for the tests, which supply a fake client and state.
+ */
+export function createProvider(dependencies) {
+    const { state, domain, keyTtlMinutes, nudgeEvery, now, log } = dependencies;
+    // The session each turn opened, by eve session and identity, held until the
+    // turn completes or its key's lifetime passes. A promise, so a rerun or an
+    // overlapping call shares the one open rather than minting a second key.
+    const open = new Map();
+    function identify(scope, auth) {
+        const value = typeof scope.value === 'string' ? [scope.value] : scope.value;
+        const byTenant = value[0] === TENANT_SCOPE;
+        // The domain is in every key, so two slots on one agent never share one.
+        if (dependencies.client().credentialKind !== 'apiClient') {
+            if (byTenant) {
+                throw new Error('byTenant memory needs MEMCO_CLIENT_ID and MEMCO_CLIENT_SECRET: with ' +
+                    'a token, every tenant would share one Memco identity');
+            }
+            return { stateKey: `${scope.key}:${domain}` };
+        }
+        const tenant = value[1];
+        const principal = auth.current;
+        if (!byTenant ||
+            value.length !== 2 ||
+            tenant === undefined ||
+            principal === null) {
+            throw new Error('multi-tenant Memco memory needs a user principal and a scope of one ' +
+                'tenant: scope the slot with byTenant');
+        }
+        const id = externalId(scope.namespace, tenant, principal);
+        return {
+            stateKey: `${scope.key}:${domain}:${id}`,
+            externalId: id,
+            networkName: networkName(scope.namespace, tenant, domain),
+            principal
+        };
+    }
+    function store(key, entry) {
+        state.update(current => ({ ...current, [key]: entry }));
+    }
+    async function provision(identity, namespace) {
+        const client = dependencies.client();
+        const id = identity.externalId;
+        const name = identity.networkName;
+        const given = await dependencies.userName?.(identity.principal);
+        const user = await client.users.createOrGet(id, {
+            roles: ['reader', 'creator'],
+            name: given?.trim() || id
+        });
+        const network = await client.networks.createOrGet({
+            name,
+            domain,
+            scope: 'customer',
+            owner: name,
+            description: `Eve memory · namespace: ${namespace} · domain: ${domain}`
+        });
+        await client.networks.addMember(network.id, { userId: user.id });
+        store(identity.stateKey, {
+            ...state.get()[identity.stateKey],
+            provisioned: true
+        });
+    }
+    async function startOrResume(identity, sessionId) {
+        const client = dependencies.client();
+        const options = identity.externalId === undefined
+            ? {}
+            : { externalId: identity.externalId, keyTtlMinutes };
+        if (sessionId !== undefined) {
+            try {
+                const session = await client.memory.resumeSession(sessionId, options);
+                return { session, fresh: false };
+            }
+            catch (error) {
+                // The stored session is gone: start another in its place.
+                if (!(error instanceof MemcoNotFoundError)) {
+                    throw error;
+                }
+            }
+        }
+        const session = await client.memory.startSession(domain, options);
+        store(identity.stateKey, {
+            ...state.get()[identity.stateKey],
+            sessionId: session.id
+        });
+        return { session, fresh: true };
+    }
+    async function openFor(identity, namespace) {
+        const stored = state.get()[identity.stateKey];
+        if (identity.externalId === undefined) {
+            return startOrResume(identity, stored?.sessionId);
+        }
+        const provisioned = stored?.provisioned === true;
+        if (!provisioned) {
+            await provision(identity, namespace);
+        }
+        try {
+            return await startOrResume(identity, stored?.sessionId);
+        }
+        catch (error) {
+            // Only a stored `provisioned` can be stale; one just made is not.
+            if (!provisioned ||
+                (!(error instanceof MemcoNotFoundError) &&
+                    !(error instanceof MemcoPermissionError))) {
+                throw error;
+            }
+            // The user or the network was deleted: provision again, once.
+            store(identity.stateKey, {});
+            await provision(identity, namespace);
+            return startOrResume(identity, undefined);
+        }
+    }
+    /** Close and forget the session `key` holds, if any. */
+    async function release(key) {
+        const entry = open.get(key);
+        if (entry === undefined)
+            return;
+        open.delete(key);
+        // A turn whose open failed has no session to close.
+        const turn = await entry.opened.catch(() => null);
+        await turn?.session.close();
+    }
+    /**
+     * Close and forget every session unused for its key's lifetime, in any eve
+     * session: a failed turn's is otherwise held until its eve session has
+     * another turn. A turn asks for its session before every model call, so this
+     * spares a running turn, unless one step outlasts the lifetime. A failure to
+     * close is logged, as the turn asking has no part in it.
+     */
+    async function evict() {
+        const oldest = now() - keyTtlMinutes * 60_000;
+        const stale = [...open].filter(([, entry]) => entry.usedAt < oldest);
+        await Promise.all(stale.map(([key]) => release(key).catch(error => {
+            log(`could not close an expired session: ${error}`);
+        })));
+    }
+    /**
+     * The session for `identity` in this eve session: the one already open, or a
+     * new one.
+     *
+     * @param turnId The turn asking, when known. A session another turn opened
+     *   is closed first: eve completes only a turn that succeeds, so a failed
+     *   turn's session is still held, and no session serves two turns. One opened
+     *   with no turn id, by `tools()`, is adopted: eve can ask for tools before
+     *   recall, and the session and its `fresh` are this turn's.
+     */
+    async function opened(eveSession, identity, namespace, turnId) {
+        await evict();
+        const key = `${eveSession}\0${identity.stateKey}`;
+        const held = open.get(key);
+        if (held !== undefined && turnId !== undefined) {
+            if (held.turnId === undefined) {
+                held.turnId = turnId;
+            }
+            else if (held.turnId !== turnId) {
+                await release(key);
+            }
+        }
+        let entry = open.get(key);
+        if (entry === undefined) {
+            const created = {
+                turnId,
+                opened: openFor(identity, namespace),
+                usedAt: now()
+            };
+            entry = created;
+            open.set(key, created);
+            // A failed open is forgotten, so the next call tries again.
+            created.opened.catch(() => {
+                if (open.get(key) === created)
+                    open.delete(key);
+            });
+        }
+        entry.usedAt = now();
+        return entry.opened;
+    }
+    /** Whether a failure is an outage, which leaves the turn without memory. */
+    function outage(error, during) {
+        if (error instanceof MemcoUnavailableError ||
+            error instanceof MemcoTimeoutError) {
+            log(`${during} without memory: ${error.message}`);
+            return true;
+        }
+        return false;
+    }
+    return {
+        recall: {
+            'turn.started': async (context) => {
+                const { scope, slot } = context.memory;
+                const prefix = `${slot}__`;
+                try {
+                    const identity = identify(scope, context.session.auth);
+                    const { session, fresh } = await opened(context.session.id, identity, scope.namespace, context.turn.id);
+                    const messages = [];
+                    if (fresh) {
+                        if (session.domain === null) {
+                            log(`no briefing: the listing does not describe '${domain}'`);
+                        }
+                        else {
+                            messages.push({
+                                id: BRIEFING_ID,
+                                content: briefing(session.domain, session.instructions, prefix)
+                            });
+                        }
+                    }
+                    if (fresh || context.turn.sequence % nudgeEvery === 0) {
+                        messages.push({ content: nudge(prefix) });
+                    }
+                    return { messages };
+                }
+                catch (error) {
+                    if (outage(error, 'recall'))
+                        return null;
+                    throw error;
+                }
+            }
+        },
+        tools: async (context) => {
+            const { scope, slot } = context.memory;
+            const prefix = `${slot}__`;
+            try {
+                const identity = identify(scope, context.session.auth);
+                const { session } = await opened(context.session.id, identity, scope.namespace);
+                const offered = session.tools({ prefix }).tools;
+                return Object.fromEntries(offered.map(tool => [
+                    tool.name.slice(prefix.length),
+                    defineTool({
+                        description: tool.description,
+                        // Plain JSON Schema, which the SDK's narrower type does not prove.
+                        inputSchema: tool.parameters,
+                        execute: input => tool.call(input)
+                    })
+                ]));
+            }
+            catch (error) {
+                if (outage(error, 'tools'))
+                    return null;
+                throw error;
+            }
+        },
+        capture: {
+            'turn.completed': async (context) => {
+                const identity = identify(context.memory.scope, context.session.auth);
+                await release(`${context.session.id}\0${identity.stateKey}`);
+            }
+        }
+    };
+}
+/**
+ * The instruction recalled when a session starts and every `nudgeEvery` turns.
+ *
+ * @param prefix What the slot's tools start with.
+ */
+function nudge(prefix) {
+    return (`Before working on this, search the team's shared memory with ` +
+        `${prefix}search for what is already known. When you learn a lesson the ` +
+        `team will need again, not general knowledge, save it with ` +
+        `${prefix}create_memory or ${prefix}enrich_memory before you finish.`);
+}

package/dist/src/scope.d.ts

@@ -0,0 +1,32 @@
+import type { SessionAuthContext } from 'eve/context';
+import type { MemoryScopeContext } from 'eve/memory';
+/**
+ * The first component of every {@link byTenant} scope. It marks the scope as
+ * multi-tenant, so a provider holding a token, which would run every tenant as
+ * one shared identity, refuses it rather than share memory across tenants.
+ */
+export declare const TENANT_SCOPE = "@memco/eve:tenant";
+/** Names the tenant a user principal acts under, or `null` for none. */
+export type TenantResolver = (principal: SessionAuthContext) => string | null | undefined | Promise<string | null | undefined>;
+/**
+ * A multi-tenant scope: every user of one tenant shares that tenant's memory.
+ *
+ * The scope is the tenant, marked as one with {@link TENANT_SCOPE}, and needs
+ * an API client's credentials. Memory is off, and eve calls no provider, for a
+ * turn with no principal, a principal that is not a user, or a user whose
+ * tenant the resolver cannot name. Never resolve the tenant from anything the
+ * model supplies.
+ *
+ * @param resolveTenant Names the tenant of an authenticated user principal,
+ *   e.g. from a verified token attribute.
+ * @returns A scope resolver for `defineMemory({ scope })`.
+ *
+ * @example
+ * ```ts
+ * scope: byTenant(principal => {
+ *   const tenant = principal.attributes.tenantId
+ *   return typeof tenant === 'string' ? tenant : null
+ * })
+ * ```
+ */
+export declare function byTenant(resolveTenant: TenantResolver): (context: MemoryScopeContext) => Promise<readonly [typeof TENANT_SCOPE, string] | null>;

package/dist/src/scope.js

@@ -0,0 +1,39 @@
+/**
+ * The first component of every {@link byTenant} scope. It marks the scope as
+ * multi-tenant, so a provider holding a token, which would run every tenant as
+ * one shared identity, refuses it rather than share memory across tenants.
+ */
+export const TENANT_SCOPE = '@memco/eve:tenant';
+/**
+ * A multi-tenant scope: every user of one tenant shares that tenant's memory.
+ *
+ * The scope is the tenant, marked as one with {@link TENANT_SCOPE}, and needs
+ * an API client's credentials. Memory is off, and eve calls no provider, for a
+ * turn with no principal, a principal that is not a user, or a user whose
+ * tenant the resolver cannot name. Never resolve the tenant from anything the
+ * model supplies.
+ *
+ * @param resolveTenant Names the tenant of an authenticated user principal,
+ *   e.g. from a verified token attribute.
+ * @returns A scope resolver for `defineMemory({ scope })`.
+ *
+ * @example
+ * ```ts
+ * scope: byTenant(principal => {
+ *   const tenant = principal.attributes.tenantId
+ *   return typeof tenant === 'string' ? tenant : null
+ * })
+ * ```
+ */
+export function byTenant(resolveTenant) {
+    return async (context) => {
+        const principal = context.session.auth.current;
+        if (principal?.principalType !== 'user') {
+            return null;
+        }
+        const tenant = await resolveTenant(principal);
+        return typeof tenant === 'string' && tenant !== ''
+            ? [TENANT_SCOPE, tenant]
+            : null;
+    };
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@memco/eve",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Memco Shared Memory as a memory provider for eve agents",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "workspaces": [
+    "examples/single-user",
+    "examples/multi-tenant"
+  ],
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "prettier --check . && node-actionlint '.github/workflows/*.yaml'",
+    "format": "prettier --write .",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "build:test": "rm -rf build && tsc -p tsconfig.json",
+    "test": "npm run build:test && node --test --enable-source-maps 'build/tests/**/*.test.js'"
+  },
+  "peerDependencies": {
+    "eve": ">=0.84.1 <0.91.0"
+  },
+  "devDependencies": {
+    "@tktco/node-actionlint": "1.6.0",
+    "@types/node": "24.19.2",
+    "eve": "0.90.0",
+    "prettier": "3.9.6",
+    "typescript": "5.9.3"
+  },
+  "dependencies": {
+    "@memco/memcoai": "^0.3.1"
+  }
+}