memory Plugin

memory gives multiple Agents long-term memory. City owns the shared Plugin instance and allocates its private storage root; access control, recall, and context assembly remain inside MemoryPlugin.

Memory scopes

User Memory only accepts an authenticated identity returned by Embassy. Without one, a current_user write fails instead of falling back to a default user or Agent Memory.

Context behavior

• Core Memory is injected as separate named system blocks and frozen with the Session system snapshot.
• Dynamic Recall runs at most once per Turn and is attached to the current User Message model-input copy.
• Tool loops and context-limit retries reuse the same Recall result.
• Recall never changes canonical Session Messages or gains system-instruction authority.
• Canonical User/Assistant text from completed Turns creates an idempotent Capture Job; failed, stopped, trivial, and obviously sensitive Turns are skipped.

Actions

The Plugin exposes status, search, read, remember, digest, revise, and forget.

Explicit memory writes require a bounded semantic target:

{
  "content": "The user prefers concise answers.",
  "target": "current_user",
  "topic": "user-preferences",
  "memory_type": "preference"
}

remember returns a complete logical memory_id. Pass that ID unchanged to read, revise, or forget; do not interpret it as a physical path.

Storage

City allocates one lifecycle root for the unique MemoryPlugin instance. The Provider separates City, Agent, User, and Workspace logical scopes inside it:

<city-storage>/plugins/memory/

Raw user_id, workspace_id, and agent_id values are encoded as safe path segments. Multiple Agents can use the same City root while User and Workspace subjects remain isolated.

Construct the instance directly. MemoryPlugin.initialize() initializes its Provider from City's PluginLifecycleContext.storage:

const memory_plugin = new MemoryPlugin();
const city = new City({ plugins: [memory_plugin] });

Do not derive Memory paths from Agent Session directories; physical layout belongs to City and the Provider.

Related docs

• Plugin System
• Plugin Actions
• Built-ins Overview