memory Power

One local user, User/Agent Profiles and searchable knowledge

City owns the single local user's base information. MemoryPower owns persistent agreements and knowledge. Local Agents share User local; switching Federation accounts does not switch identity or memories. Dedicated Memory Sessions perform extraction, consolidation and complex corrections. The Memory Coordinator manages requests, retries and commits. There is no per-turn chat copying or automatic per-turn capture. Background consolidation is an internal Memory Power process, explicitly enabled per scope and disabled by default.

User memory, processing records and settings

Memory Power opens on User memory. Its sidebar has three entries, with Settings fixed in a separate bottom section:

EntryPurpose
User memoryUser agreements and knowledge; default page
Processing recordsInspect target=user Jobs, changes, sources and retry results in descending time order
SettingsKnowledge backend, memory processing and maintenance configuration information

The main navigation has no Agent list or project dimension. User memory is fixed to target=user and contains Agreements and Knowledge tabs. Agreements displays source blocks and supports viewing and appending. Editing or deleting a source block requires an exact unique match and the version returned by the read; re-read after conflicts. Knowledge supports search, viewing, creation, editing and deletion. User knowledge details open in the current main area, with a return to the list.

The Agent Profile's Memory section contains Agreements, Knowledge and Processing records tabs, fixed to the current Agent's private scope. Agreements displays that Agent's Core Profile as read-only content by default, with refresh and retry after read failures. Knowledge supports browsing, creation, revision and deletion. Processing records contains only Jobs with target=agent owned by that Agent, with no project filter. Access Workspace knowledge through scoped memory tools with target=current_workspace.

Click a memory in the Agent Profile's knowledge list to open its detail in a separate host tab, with revision, deletion, sources and the update time. After deletion, the tab displays “Memory deleted”; close it through the host tab controls. The list retains its scroll position, and details bind to the selected memory and its ownership. If reading fails, use Retry in the same detail tab.

Settings opens without an Agent or Workspace. The knowledge backend section displays the current Provider's actual status, storage and knowledge capabilities. Builtin is the available implementation; its file Adapter is internal to that backend. Processing shows the dedicated Memory Session model, or follows the execution Agent's default model; this configuration belongs to the Power. Maintenance policies also belong to the Power. Main Settings has no Agent or Workspace consolidation-scope selector. Automatic background consolidation currently does not support writing User memory. By default, only explicit memories are saved; ordinary chat does not trigger automatic inference. Downcity persists User/Agent Profiles and injects them into context independently of the knowledge backend.

Basic Provider reads and retrieval are separate from strong transaction capabilities. Builtin supplies scope versions, atomic commits and durable receipts. Knowledge writes and processing that require transactions fail explicitly when the backend lacks this capability. Processing authorizes structured record ownership rather than ID paths. The host manages the knowledge backend.

Main Processing records contains only user-targeted Jobs, including target=user requests initiated by different Agents. Jobs for an Agent's own memories appear in that Agent's Profile. Select a record to inspect processing details, changes and sources or retry a failed request.

Scope and mode

targetprofileknowledge
userCross-Agent user agreementsUser goals, facts and historical knowledge
agentCurrent Agent agreementsPrivate Agent experience
current_workspaceUnsupportedProject facts, decisions and procedures

Initial assembly or syncshot loads both Profiles and freezes them with Instruction, then the Agent decides whether to query knowledge. Identity and Instruction share one Agent system message, immediately followed by a separate Agent Profile system message. User Profile is another independent system message before Session information. Both Profiles belong to the frozen system snapshot, never enter user content, and do not define the current task. Canonical messages remain unchanged. Current requests and permissions take precedence.

remember

{"target":"user","mode":"profile","content":"Before the main answer, remind me to speak English and briefly correct my expressions."}
ParameterBehavior
contentRequired non-empty text
targetuser, agent, current_workspace
modeprofile or knowledge; default knowledge
topicKnowledge topic; default inbox
memory_typefact, preference, decision, episode, procedure, document; default fact
sourceOptional knowledge evidence label

Explicit new information is saved through a deterministic commit. Profile returns profile_id; knowledge returns memory_id. User writes require no login or resolve_user callback. Requests needing semantic consolidation or judgment go to a Memory Session. Saving is confirmed only after commit; accepted or running requests still require a processing result.

Results and activation

Persistent behavior changes should explicitly choose mode=profile; omitting mode defaults to searchable knowledge. The returned status describes saving or processing; mode describes how the memory is used. Asynchronous processing results are associated with the returned Job ID. Accepted, queued or running does not mean saved.

New Sessions and syncshot load the complete current Profile. Existing Sessions receive bounded turn-local reference corrections when core versions change. Knowledge takes effect on recall. User/Agent knowledge management and status queries require no Workspace; project writes do.

Asynchronous processing and status

digest, revise and optimize return persistent processing records and run in dedicated background Memory Sessions. Digest extracts durable information from an explicitly selected Session range; revise processes the requested correction for a specified memory; optimize consolidates a User or Agent Profile. Acceptance does not establish that saving or revision has completed.

Memory Power creates processing Sessions with category work and type memory, bound to dedicated instructions and restricted tools. Tools accept only the actual Session bound to the active processing request, and the host validates proposed changes before committing them. The Session type name itself grants no memory-processing permissions.

Calls made in a Session subscribe the original calling Session and Turn to the eventual succeeded, skipped or failed result. For digest, this is the calling Session, which may differ from the Session being read. Completion summaries contain status and resulting memory IDs, without source text. Feedback is persisted in a separate outbox and handled idempotently. It is injected only while the original Turn can receive it. If that Turn has ended, the result remains available in processing records; no new Turn starts automatically. The recorded delivery_status is delivered for injection or saved for retention without injection. Both finish delivery; saved does not trigger further attempts to inject the result. Delivery failures retry with backoff and do not change the memory commit status. Management-page requests have no chat recipient. Use processing records to check the result when needed, and avoid repeated polling or duplicating a saving confirmation already delivered for the Job.

ActionInputResult
memory.jobslimit?, offset?{items, total} of MemoryJobView records for the current Agent and Workspace; no source text
memory.job_statusjob_idOne MemoryJobView with kind, scope, related Memory Session, results or errors; no source text
memory.job_detailjob_id{job: MemoryJobView, changes: MemoryJobChangeDetail[]} with captured changes and source excerpts
memory.retryjob_idActual retry status for a failed explicit request; retry automatic batches from Processing records under their original budget

Statuses are queued, running, committing, retry_wait, succeeded, skipped and failed. Only succeeded establishes that changes were committed. Skipped means nothing needed saving; failed retains an error. Retry uses the original request scope and sources and does not establish success. A Memory Job is internal processing and does not create a user Task.

job_detail is a separate read endpoint that checks the current Job's Agent/Workspace scope, using the same scope checks as job_status. It returns the authorized source excerpts persisted for that request; lists and status contain no source text. Each change includes the operation, topic, optional memory ID, expected_version for existing content, fixed before/after snapshots, captured_at and original sources excerpts. The before snapshot is tied to the version actually read for this operation. Creating a memory uses before: null; invalidation preserves its text and marks it invalidated. Profile snapshots show the exact edited regions, with the version of the full Profile read for those edits.

Source excerpts come from the Job's authorized input, retain their role and available Session/message identifiers, and indicate when only part of the source is shown. The snapshots remain fixed even if the current memory later changes. Pending or failed changes are staged plans, not confirmation that they took effect. Records without captured snapshots return changes: []; missing historical content is not reconstructed from current memory.

Main Processing records shows a paginated list of target=user Jobs in descending time order. Agent Profile processing records is fixed to target=agent and the current Agent. Neither entry has a project filter. Select a record to inspect status details, the related Memory Session ID, commit results, changes and sources. Changes are shown one at a time, long text is divided into sections with differences highlighted, and sources are paginated. The list refreshes while visible records are active. Retry failed requests from their records. Background consolidation batches retain their original scope and sources, and retries remain subject to scope switches, cooldown, daily quota and attempt limits. Details and retries check access against the record's own scope.

Background consolidation

Automatic background consolidation currently does not support writing User memory. User memory updates require explicit saving or maintenance operations; ordinary chat does not trigger automatic inference. Agent/Workspace background consolidation is disabled by default and configured per scope through trusted host APIs. Main Settings has no scope switches. Each setting controls its Agent, project context and target combination; project sharing requires explicit authorization. Automatic processing commits only private Agent knowledge or explicitly shareable Workspace knowledge. It does not change either Profile or write User knowledge. Explicit remember, digest, revise and optimize requests follow their own requested scopes.

Trusted inputs are explicitly submitted corrections, persisted Task accept facts and Task revise facts with explicit feedback. Execution success, an ordinary Turn ending and opening a result do not constitute acceptance. Task publishes each fact atomically with its work state and captures bounded output text, roles, a fingerprint and the read range. Facts are archived before a Task is deleted; deleting a Task or forgetting knowledge does not erase every source copy. Task facts target the original Agent's private knowledge. A Workspace association does not grant sharing permission; using correction text in a project requires explicit authorization.

Maintenance runs every five minutes to replay published facts, reconcile existing Jobs and schedule one background batch when allowed. Turning a scope off still permits durable intake and reconciliation of existing commit receipts, but starts no new automatic computation. Work that has already begun may complete within its bounds. An empty queue makes no model calls. Private Session history is not scanned automatically. Memory Sessions, generated changes and completion feedback are not new original evidence.

A batch fixes one Agent, one target and knowledge mode, with at most 4 facts, 16 sources and 32,000 characters. Each scope reserves at most 2 automatic computations per UTC day, including retries, with at least 10 minutes between computations. Normal attempts retain the 120-second bound and each Job allows at most 3 attempts. These are computation and execution quotas, not monetary cost accounting. Explicit requests take priority at each Job boundary; active computations and atomic commits are not preempted.

Host APIs configure consolidation scopes. Inspect private Agent knowledge batches, errors, changes, sources and failed-job retries in that Agent's Processing records. Query Workspace batches through host APIs. Inputs become processed only after succeeded is reconciled with a published commit receipt or the Job explicitly returns skipped. Failures, source errors and quota deferrals retain input. An unfinished earlier fact blocks the continuous watermark. Automatic batches have no chat recipient: committed does not establish that a summary was delivered.

Local Cities using the same platform data root deduplicate events and batches under a shared scope file lock. Each batch remains bound to the original City's Job. Another City can see that ownership but does not take over or recompute a Job it cannot read. Preserve the original City's processing data for recovery. Automatic writes retain deletion suppression and do not receive explicit allow_recreation authorization. Exact-content suppression still cannot recognize every semantic rephrasing.

Host management actions

These actions are for trusted hosts and management pages, not ordinary model tools.

ActionInputResult
memory.dream.statusagent_id, optional workspace_id, target=agent/current_workspaceScope ledger, backlog and Job states readable by this City
memory.dream.configureSame scope plus enabledState after persisting the switch
memory.dream.correctionSame scope plus client UUID event_id, ISO occurred_at, content, workspace_share_allowedReceived, not processed or committed; retries must preserve the original parameters
memory.dream.retrySame scope plus batch_idQuota-controlled retry state for the original batch

The official Power assembly connects the reliable Task fact source. Standalone MemoryPower construction can supply dreaming.read_signals, a trusted replayable reader returning MemorySignalInput[]. Trusted hosts can also submit explicit feedback through the correction action. A source reader does not enable automatic processing or expand target permissions.

Document maintenance

Both scopes use deterministic MemoryProfile operations. Append, edit and delete require a base version and trusted sources. Replaying the same source request is idempotent; a request key cannot be reused for different content. Exact edits require unique matches, non-overlap, an unchanged version and retained source markers. Content changes preserve a backup.

Explicitly call memory.optimize with {"target":"user"} or {"target":"agent"} to submit a core memory consolidation Job. Agent targets bind to the calling Agent. The Coordinator schedules a dedicated Memory Session, limits processing budgets and checks commit versions. Use jobs/job_status to inspect status, job_detail to inspect changes and evidence, and retry for a failed request. Within the same request scope, repeated optimization of the same Profile version uses a stable source identity and reuses the Job. Digest deduplicates by its captured sources and extraction policy; unrelated changes to stored knowledge do not create a duplicate request.

The Profile file service exposes content, version and length reads. All reads and writes hold a local cross-process scope lock and recover pending operations before returning content or receipts. Append, edit and delete receipts retain their original committed version. The file service does not run optimization timers or create Jobs based on length. Consolidation preserves valid agreements without requiring a fixed target size.

Writes do not rewrite an existing Session's persistent system. When a core version changes, a turn-local reference update invalidates the earlier snapshot for that scope and supplies bounded current content. If truncated, omitted content cannot be recovered from earlier agreements. Use syncshot for a complete refresh. SOUL.md is independent Agent configuration.

User center and host APIs

  • memory.user_read: returns the one local user's base information.
  • memory.user_update: updates display_name without changing user_id.
  • memory.profile_read/status: target=user, or target=agent plus agent_id.
  • memory.profile_edit: the scope plus version and old_text/new_text edits.
  • memory.profile_delete: the scope plus version; backs up and deletes the document.

Read returns the version. Re-read after conflicts. The host generates replayable source references for management edits and deletions. A profile_id is not a knowledge ID accepted by ordinary read/revise/forget. Deleting a Profile stops use of its current content; backups, source ledgers, original Sessions and source-content copies in Jobs remain. Deletion does not establish that every historical copy was erased.

Knowledge storage, import and forgetting limits

Published scope manifests determine current effective knowledge records, versions, commit receipts and suppression entries. Read/search/list use those manifests. The wiki/evidence segments in logical memory IDs are namespaces and do not establish that content is read from matching directories.

The runtime does not automatically scan, migrate or fall back to existing wiki/evidence files. Callers must explicitly select records, use the SDK-level create_memory_import_changeset helper to construct a change set, then commit it through the Provider. This is not automatic migration or a chat-facing import action. Confirm sources, target scope and backups before importing. Missing original evidence is marked as an import source without inventing evidence.

Profile continues to use separate PROFILE.md files, source ledgers, backups and pending-operation recovery, with scope locks on all file entry points. It is outside the knowledge manifest and does not share an atomic transaction with knowledge commits.

Forget removes the specified knowledge from the current effective set and records a fingerprint of its normalized content to suppress identical content on later submissions. Suppression matches exact content fingerprints; it does not guarantee that a semantic rephrasing of the same fact cannot be extracted again. Original Sessions, source-content copies in Jobs and historical records remain. Forgetting does not physically erase every copy.

Configuration and storage

const memory_power = new MemoryPower({
  platform_root_path: "/absolute/platform-root",
});

Local User reads and writes require no identity callback. The host and Coordinator validate source authorization, accessible scopes and Memory Session tool permissions.

<platform-root>/user/user.json
<platform-root>/user/PROFILE.md
<platform-root>/user/memory/runtime/knowledge/current.json
<platform-root>/agents/<agent_id>/PROFILE.md
<platform-root>/agents/<agent_id>/memory/runtime/knowledge/current.json
<shared-root>/workspaces/<encoded-id>/runtime/knowledge/current.json
<platform-root>/memory/dreaming/scopes/<scope-hash>.json

This is a single-owner local system: authorized channels share the local User, and the host controls channel authorization. Data conversion requires confirmation of data roots and backups.

Memory tools include status, list, search, read, remember, digest, revise, forget and optimize, plus jobs, job_status, job_detail and retry. Search retrieves current effective memories. Explicit saving and deletion by ID use deterministic interfaces; digest, revise and optimize run asynchronously. Processing with nothing worth saving explicitly skips the write.