agentlas

MemorySphere: how session compaction connects to long-term memory

How structured checkpoints, automatic curation and scoped recall help an agent continue its work, with clear ownership and cache dependencies.

Two connected memory paths: session checkpoints preserve active work, while Memory Tickets feed automatic curation and canonical One and Agent memory. The next context combines the checkpoint, recent changes and scoped recall.

Two kinds of remembering

An agent working through a long task needs to remember what it is doing now. An agent returning next week needs to remember what it learned. Those are related jobs, but they have different lifetimes. A pending tool call belongs to the current session. A recurring procedure may deserve a place in long-term memory. Treating both as one growing summary makes it harder to tell what should guide the next action.

MemorySphere is the name for our integration work across those two horizons. Session compaction builds a smaller account of active work. Automatic curation decides which new observations should become durable learning. Recall selects the learning relevant to the next request. The connection between them preserves source identity and ownership, so the system can reuse a result without treating every summary as fresh evidence.

This development note describes the implementation. Installed-product availability remains under verification.

A checkpoint carries the current job

A checkpoint is a structured record of where a session has reached. It carries the goal, continuing constraints, recent corrections, completed work, open questions and the next useful action. Its frontier identifies the point in the source conversation that the record covers. The next turn combines that checkpoint with conversation changes beyond the frontier instead of assuming the checkpoint already contains everything.

Consider an illustrative task: prepare a report, preserve the original measurements, and send it only after review. A useful checkpoint retains the review condition even when the data preparation is finished. If the owner changes the destination later, the new destination belongs in the latest state. Older wording can leave the model's active input while its source remains available separately.

Tool state needs the same care. A completed file write and a requested upload with no confirmed result are different facts. An unsettled effect remains unsettled in the checkpoint. Compaction must not turn an uncertain external action into a completed action, or turn the absence of a result into permission to repeat it. Execution receipts and the host journal remain the evidence for what actually ran.

Conceptual example: follow a report through compaction, a correction and restart. The controls are illustrative and do not run an agent or access real memory.

Extract the change, keep the coverage

A Ticket is a bounded intake record for a possible learning. It names the source coverage and the new material to consider. An Episode records the covered work as an experience, while a recap is its compact account for later continuation. These representations need to agree about which original events they cover. Otherwise, the same turn can enter memory through several routes and look like several independent observations.

The intended flow reuses already prepared material and extracts the delta: what changed since the previous covered point. The checkpoint answers what the session should do next. The Ticket answers what the curator should consider retaining. They can refer to the same original events without requiring a second curator to rediscover the same learning from a generated recap.

A generated memory view is an output, not a new original to learn from. That distinction reduces opportunities for a paraphrase to acquire the weight of new evidence. Model interpretation can still be wrong.

On the integrated Desktop Claude harvest path, an owner-bound byte cursor identifies newly appended source material. Complete UTF-8 events and intake receipts advance together in a canonical transaction. The append harvester itself does not reanalyze the whole file with a model. Detected truncation or replacement resets its source generation; the harvested session hypothesis still needs separate curation to become durable learning.

Curation is automatic and bounded

The curator turns a candidate learning into a durable decision. Core’s bounded decision protocol has six actions: add, revise, merge, supersede, noop and defer. They cover creating an entry, updating or combining supplied originals, replacing an outdated entry, leaving memory unchanged, or postponing a decision. Desktop’s automatic intake separately chooses durable memory, session context, discard or defer, with reference-based lifecycle updates such as superseding prior entries. These paths share the goal of governed learning; they do not have an identical six-action wire protocol.

Ordinary learning is processed automatically. The unused manual approval writer and candidate controls have been retired, while historical approval provenance remains audit data. In Core’s decision path, the model supplies judgment and the host checks mutation authority. A proposed revision must name a supplied eligible original and match its current revision and scope. A merge cannot invent a target outside that bounded inventory. Unrecognized applicability rules require deferral rather than silently widening use.

For example, an illustrative procedure may change from checking one output format to checking two. Revision can be appropriate when the evidence supports it. Conflicting original-language wording should not be overwritten merely because the English looks similar. These mechanical checks constrain writes; they do not constitute an exhaustive verifier of the model’s interpretation.

One authority, several useful views

Canonical means the authoritative stored memory record from which recall and derived views are built. One and Agent views organize canonical entries by actor, with scope and applicability metadata. These inspection projections help the owner understand stored learning. Appearing in a view does not establish that an entry is eligible for a particular recall request.

The ownerScope identifies the account and store partition. Actor, project and applicability boundaries are separately bound. A project can describe where a learning originated without granting every participant permission to use it. Common contracts and views organize host storage; physical relocation requires its own validated migration.

PM Soul contains manually maintained instructions and project context, including manually recorded facts. Learned memory has a separate origin in experience. Reading PM Soul or a package declaration can identify its source without turning it into learned memory. Combining these materials in a prompt preserves their different origins and authority.

Record or viewWhat it describesWhat it does not grant
Session checkpointThe covered state of one ongoing jobAccess to another actor's private session
One or Agent memory viewCanonical entries organized by actor, with scope and applicability metadataGuaranteed eligibility for the current recall request
Project source linkWhere a learning came fromPermission for every project participant to recall it

Preserve the original meaning and identity

A durable entry needs more than a sentence. It retains connections to the original actor, source and operation, together with revision information. Those identifiers let the host distinguish a corrected original from a second observation that happens to contain the same words. They also make a later change explainable without relying on similarity alone.

Original-language wording matters here. An English rendering can aid retrieval while native wording preserves the owner’s meaning. Core’s decision path requires corresponding native output when changing the English text of a target with native text or merging such targets. Retired originals retain their wording under existing governance. This contract constrains permitted output; it does not certify semantic fidelity.

Superseding an entry makes its replacement current while preserving the relationship to the earlier record. Forgetting removes the governed derived bodies, including exact mapped legacy One archive bodies, while retaining content-free provenance and revocation markers. A tombstone prevents the forgotten source or matching learning from returning through replay. This controls Agentlas recall and reuse; it does not establish erasure of a provider’s historical conversation.

Observe package sources at the reader

An agent package can declare instructions, skills, knowledge and tools. A declaration alone does not establish consumption. In covered integrations, source observation sits at the authorized reader: record metadata for original bytes actually read, while the existing reader continues to decide whether the read is allowed.

Core’s registered library, CLI and MCP readers observe eligible knowledge and tool originals when consumed. Integrated package readers also observe admitted instructions and skills. Repository plugin distributions carry the same memory runtime dependencies. Metadata can include a stable identity, asset digest, revision and bounded byte range without copying the body into a second catalogue. An unread declaration is not evidence, and repository integration does not by itself verify an installed plugin copy.

Generated memory views and private memory databases must not become portable instruction sources. A copied path, matching slug or digest cannot establish read authority. Source metadata supports tracing and freshness; it does not expand permissions or substitute for an authorized original reader.

Make restart a validation boundary

Core stores a normalized pending decision before its final canonical mutation. The independent Terminal also persists the bounded result in its original SQLite run journal before attempting remote completion. After restart, a fresh server request must match the original account, operation and snapshot before that result is reused. Recovery can then finish delivery without repeating judgment. A crash before pending storage may still repeat inference.

CAS, or compare-and-swap, applies a change only when the compared state still matches the state the decision used. Core checks original revisions and relevant authority, so a stored decision cannot overwrite a newer edit merely because it survived a crash. Its final canonical mutation and completion receipt share a transaction. These checks establish consistency, not whether the model chose the best learning.

An epoch is a monotonically advancing boundary used to invalidate work from an earlier memory state. Owner forget advances that boundary. A pending decision admitted before the change must not restore forgotten content after restart. Account switching requires a similar recheck: returning to the original account can resume eligible work, while a different account cannot inherit its checkpoint, pending judgment or recall.

The graph is a projection

The memory ontology describes relationships such as an entry's source, actor, project and replacement. The Graph presents those relationships for exploration. It is derived from canonical records; drawing an edge does not create permission to read the node at its other end.

An outbox is a durable queue of projection work produced alongside a canonical change. It lets a graph or view catch up after an interruption without becoming another writer of learned memory. If projection delivery is delayed, the canonical record still defines what is current. A stale graph cannot overrule a later revision, supersession or forget boundary.

The system can navigate the same learning in several ways while keeping one authority for its meaning and status. A connection can explain selection without making another agent's private checkpoint shared knowledge.

Reuse selection when its dependencies hold

Recall involves reading eligible entries, ranking them against the current request and choosing a bounded context. Repeating that work on every turn is unnecessary when the selection and its dependencies remain valid. A host cache keeps the selected memory prefix: the block of selected learning prepared for the model's input.

Covered scoped readers narrow the candidate set before local ranking. App and Alive readers additionally validate their declared receiver and visibility domain. Ranking uses local lexical and vector information; it does not need a conversational model to decide which stored text to consider. These checks retain their reader-specific scope rather than implying one universal policy contract across every host.

A generation is the host's identity for a particular governed selection. It depends on the owner and epoch, source revisions, actor and task boundaries, and the checkpoint frontier. A new request can require a new selection even when no memory entry changed. A correction can change relevance; an account change can change authority.

Changes to selected originals invalidate the selection. Unrelated writes can be handled through bounded change tracking where supported. Missing tracking information requires repair or a fresh scoped selection. Reusing selection can reduce host computation, but selecting additional relevant learning can increase the input. A smaller number of database reads is not automatically a smaller prompt.

Delivery needs an acknowledgment

The host also needs to know whether selected memory reached the continuing model context. An acknowledgment, or ACK, is the host's recorded confirmation for a particular delivery and context identity. Only a supported continuing transport with a valid ACK and current dependency fence can omit a block it has already delivered.

Failed, cancelled or uncertain delivery cannot establish that acknowledgment. Restart, credential rotation or context identity changes can require the selected memory to be sent again. A stateless transport still needs the full logical input. Fresh instructions, recent conversation changes and the current request remain part of each turn even when a memory block is reusable.

This is distinct from a provider's billed prompt cache. Agentlas can track its own selection and delivery decisions; that does not prove how a provider accounts for cached tokens. The integration therefore separates host reuse, transport reuse and provider billing. Cost or latency claims require observing the complete model call and its reported usage, not counting a smaller host-side block.

Shared contracts across separate harnesses

Desktop, the daemon and the independent Core and Terminal paths do not become one process through this integration. Each harness still owns its input admission, execution journal, cancellation and provider connection. Shared memory contracts define the records and fences they can agree on; they do not imply shared RAM or a transferable live execution handle.

A host obtains authority from its actual account, source reader and session boundary. Missing private context identity retains the existing scoped input path. Recognizing an actor family can support eligible recall without rewriting original identifiers.

Subscription CLIs, API transports and local models remain model adapters within those harnesses. A common contract helps review sibling paths consistently, but a source-level contract passing through a simulated adapter does not establish that every installed provider, operating system or mobile connection has accepted the integration.

A group handoff carries a bounded result

A parent coordinating a group needs the member's result and the next decision it enables. It usually does not need the member's entire working conversation. A bounded handoff can carry the relevant result, unresolved question and source reference without copying a private checkpoint into the parent's memory.

Completed and terminal results remain distinct. If a member later fails or stops, an earlier successful subturn cannot replace the terminal reason or erase an uncertain effect. Queued reports also retain custody: the original account, store and child run remain bound to the pending delivery across restart.

An account change can hold an eligible report for the original owner while preventing another account from receiving it. Returning to that owner can deliver the retained result without rerunning the member's task. Explicit Stop remains a terminal action, including after an earlier abort request. A durable queue is useful only when recovery preserves those boundaries rather than converting every held record into fresh work.

Optional App sharing names the receiver

The App integration adds a separate owner choice: share an eligible existing memory with an exact registered App and, where the runtime establishes membership, a particular agent in that App. This is a receiver setting on canonical memory. It is not a new requirement to approve ordinary learning or a global permission for published apps to read private memory.

The original actor and source stay attached to the learning. A project origin does not create App permission, and public sensitivity does not grant access by itself. Member memory enters the corresponding member's context rather than a common leader prompt. An unknown target or unsupported membership cannot be filled in from names or prose.

The captured App authority is checked around dispatch and results. Withdrawing sharing, changing the roster, forgetting the entry or switching accounts invalidates that selection and requests cancellation through the existing controls. These checks concern optional recall. They do not imply that automatic App learning, Alive execution or every team and firm route is covered by this work.

Architecture and availability

Source custody, revision checks, account isolation, checkpoint restoration and bounded delivery are separate parts of the architecture. Installed-product availability remains a separate question from the source description.

A checkpoint retains the current task and corrections. A continuing transport may reuse delivered context only when its acknowledgment and dependency boundaries remain valid; other paths keep their scoped fallback. Host reuse alone does not establish provider-billed savings.

The architecture gives the next turn a structured current job, keeps durable learning attached to its original meaning and scope, and rechecks authority during recovery. Review the installed release and current runtime before relying on a capability.

Agentlas UpdatesProduct releases, decisions, and field notes from the Agentlas team.
View all updates
MemorySphere: how session compaction connects to long-term memory — Agentlas Updates