memory Power

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

Memory scopes

There are exactly two subjects: the current Agent and the whole City. Workspace is not a separate memory scope; a current_workspace write shares storage with city.

Storage

Agent private memory and shared memory are physically separated:

<platform-root>/agents/<agent_id>/memory/  Agent private
<platform-root>/powers/memory/             Shared across Agents

Both roots use the same structure: wiki/ holds long-term memories, evidence/ holds raw evidence, and capture-jobs/ holds pending automatic captures.

memory_id is always a logical reference such as agent/<agent_id>/wiki/<topic> or city/wiki/<topic>, never a physical path. Pass it unchanged to read, revise, and forget.

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 Power exposes status, list, search, read, remember, digest, revise, and forget.

list enumerates readable memories for the current access context without a query; the optional subject_kinds, memory_types, include_evidence, limit, and offset inputs filter and page the result. search requires a query and ranks by relevance.

Explicit memory writes require a bounded semantic target:

{
  "content": "This project always uses pnpm.",
  "target": "current_workspace",
  "topic": "project-overview",
  "memory_type": "decision"
}

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

Desktop workspace

Memory contributes a first-class entry to the Desktop navigation rail with a Sidebar and Mainview:

• Sidebar does one thing: it lists the memory scopes flat, Shared first and then one row per Agent, each showing only its memory count. Selecting a scope decides both what the Mainview lists and where new memories are written.
• Mainview has three in-place views. The list shows the memories of the selected scope; opening one shows a Markdown detail page with memory_id, type, subject, observed time, citation, and evidence count; the Settings button switches to a read-only view of the Provider, its capabilities, and the storage counts. New, revise, and delete are available in place.

Settings stay inside the workspace. Opening them never leaves the Memory workspace for the global Powers catalog.

A scope and the Agent that executes it are separate. Selecting Shared still runs through a real Agent, because every memory action is bound to an Agent; the workspace falls back to the first registered Agent.

Every read and write goes through the host action on the selected Agent and Workspace, so the workspace shows exactly what the Agent can read.

Assembly

Construct the instance directly. MemoryPower.initialize() takes the shared root from City's PowerLifecycleContext.storage. Agent private roots are derived from the platform data root, so pass it explicitly:

const memory_power = new MemoryPower({ platform_root_path: "~/.downcity" });
const city = new City({ powers: [memory_power] });

Desktop and CLI builtin registrations already pass the platform root, so manual wiring is rarely needed.

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

Related docs

• Power System
• Power Actions
• Built-ins Overview