Memory

alpha 0.3.0-rc.3

Published preview for @wf/agent-memory@0.3.0-rc.3. Follow the registry guide and review compatibility before installing.

Join the alpha Sign in with Google, then add your name. We review alpha access requests.

Memory stores notes, preferences, events and knowledge graphs for an application. This guide covers @wf/agent-memory 0.3.0-rc.3, published as a release candidate on 2026-09-09 through the store. Its live licensed installation and downloaded archive hashes are verified.

Install and configure

Use Node.js 22.19 or newer. Configure @wf:registry using the registry guide, then install @wf/agent-memory@0.3.0-rc.3. Credentials belong in host secret storage, never dependency URLs or YAML. All configurable public engines take one YAML configuration path; raw engine options are internal.

Where user data lives

An installed application chooses a private directory on the customer's device. A hosted application chooses a durable local volume on its server and exposes its own authenticated API to devices. The SDK does not provision a hosted database or synchronize machines. Set storage.root explicitly in YAML; relative paths resolve beside that file. Use storage.isolation: user for a hosted application.

The host supplies tenantId, userId and projectId from authenticated identity. Each user receives a separate hashed namespace and each project a subdirectory. Global preferences cross that user's projects; project preferences override them. Hashes are safe directory names, not encryption. Never take identity from a model or client-supplied tool argument without authenticating it.

Reliability and recovery

Successful writes flush to storage before acknowledgement. Reusing the same event identity with identical content is safe; conflicting retries are rejected. Note edits use the content digest returned by get. OS locks reject competing owners and release after a crash. Close clients before transferring ownership. Cancellation suppresses late responses and drains admitted disk writes before releasing their writer lock.

Malformed records and uncertain writes fail explicitly and preserve evidence. The host must inspect returned errors and retry with the same identity. Projection progress and state commit together; inspect dead letters for failed reductions. Memory can preserve recorded evidence, but cannot guarantee perfect model recall.

The host owns access checks, encryption, backups and retention. Namespace backup and restore cover notes, preferences, events and knowledge graphs after all clients close; restore requires an absent target. Test restores onto a separate private volume. Backups retain historical values until the host's retention process removes them. Network shares, synchronized folders and temporary container disks are outside the storage contract.

Preferences are bounded to 2 MB and 10,000 retry receipts per document; backups are bounded to 64 MiB and 10,000 files. Limit failures never silently discard records.

Optional local Tencent provider

Tencent is optional and off by default. The installed agent-memory-tencent command prepares stable Tencent 2.0.1 with WF's erasure repair from a verified archive and locked dependencies. It binds authenticated loopback port 8422 and stores each user's derived database and files separately beneath the YAML dataRoot.

Use Node 22.19 or newer, npm, tar and an existing local OpenAI-compatible model. The default model is qwen3.5:9b at http://127.0.0.1:11434/v1. Extraction disables model reasoning so the output budget remains available for memory content. Copy the provider YAML, set separate runtimeRoot and dataRoot directories, and reference a host-owned secret.

agent-memory-tencent prepare --config ./tencent-provider.yaml
agent-memory-tencent start --config ./tencent-provider.yaml

The second command runs in the foreground; the host owns supervision. Its ready record reports 2.0.1 and wf-tencent-erasure-v1. Add this to the application's memory YAML and continue supplying authenticated identity to its SDK client:

preferences:
  tencent:
    enabled: true
    endpoint: http://127.0.0.1:8422
    apiKeyEnv: WF_TENCENT_API_KEY

Forgetting drains in-flight extraction, removes that user's entire provider tree, and rebuilds only their retained preferences. Other users keep separate stores. A recovery journal finishes interrupted deletion before admission; retries use content-free completion receipts. Stock Tencent endpoints cannot accept these writes. Local records and pending work survive a provider outage.

Completion covers active provider records, vectors, mirrors, profiles and derived files. The host separately owns backups, disk snapshots and local model logs. Do not restore a provider backup without reconciling current deletion tombstones. Limits are 1,000 original rows, a 4 MB recovery journal and 10,000 erasure receipts per user. Failures retain pending work instead of reporting erasure as complete.

Existing Tencent installations are preserved. Legacy copies and changed provider destinations remain cleanup-required until the operator verifies their cleanup. Self-hosted Tencent does not imply Tencent Cloud uploads. The package's TENCENT-MIGRATION.md contains the storage and migration procedure.

Session preferences

Read local session preferences with preferences.sessionContext(). App-specific corrections retain global/project precedence and history. The installed agent-memory-mcp --config memory-server.yaml --preferences command reads the same local store if an MCP connection is closed. Optional provider synchronization remains explicit.

Upgrade

Stop old writers and back up data before upgrading. Schema-1 preferences are read and change to schema 2 on their next edit. Rebuild old split projection checkpoints from their retained event log. Rollback uses a pre-upgrade backup and reconciliation; never downgrade a modified store in place. MCP supports only 2026-07-28.

See compatibility for tested platforms and support commitments, and release notes for changes. The canonical BrightOps preview has Windows x64 proof. Recorded macOS and Linux proof belongs to the earlier BrightOps rc.1 artifact; it does not establish this new package on those platforms.

License

The included commercial license covers embedded applications, automated coding agents and CI within the purchased developer or company entitlement. Acquired paid versions and their pinned dependencies remain licensed for reinstall and rebuild after ordinary cancellation. The local SDK requires no licensing-server call. Third-party rights remain in the included notices. Read the terms with the purchase order.