Principles of Personal Memory: From User Signals to Task Context

For setup, configuration, and everyday commands, see Personal Memory. This page explains the internal mechanisms: the record model, formation paths, task matching, and how correction and forgetting work. Personal Memory turns the long-term requirements you state explicitly and the collaboration experiences that can be reused into normalized records. Each record keeps its owner, scope, applicable conditions, source, and lifecycle, and the system only provides it in related tasks. This design satisfies four product requirements at once: records are traceable, content is correctable, context has boundaries, and a plugin failure never blocks the current work.

Core components

Component	Responsibility
Experience Journal	Appends user signals, task results, and application feedback; supports deduplication and failure replay
Reflection	Identifies preferences, policies, or experiences with long-term value from structured events
Consolidation	Merges near-duplicate records, adds evidence, tightens scope, and retires invalid versions
Personal Memory Provider	Saves and queries normalized Personal Memory; provides one contract for Local and Remote
Context Director	Filters, ranks, and controls the injected context for the current task
Context Manifest	Provides summaries, application reasons, and stable IDs so the Agent can expand full content on demand

Record model

A Personal Memory Record is made of its content and its governance information:

Field	Product role
Stable ID	Supports expansion, correction, forgetting, rollback, and history tracking
`scope`	Distinguishes global user memory from project-scoped memory
`projectKey`	Binds a project-scoped record to a stable project identity
`memoryType`	Distinguishes Core Profile, Collaboration Policy, and Personal Episode
`memoryClass`	Marks user facts, user preferences, collaboration habits, or personal project conventions
selectors	Limit the applicable paths, tasks, operations, and phases
`authority`	Distinguishes what you set explicitly from what the system inferred
evidence	Keeps the minimum evidence needed to form or correct a record
lifecycle	Represents `trial`, `proven`, or `superseded`
application	Records the most recent application reason and its actual result

The Provider stores the structured state that Comet maintains automatically, shared by the CLI, Dashboard, Skill, and Hook. The user-readable Markdown is for viewing and management, and it can also be used to rebuild state after index corruption.

Record formation paths

Set explicitly by you

user.signal represents a long-term preference, correction, or forgetting that you initiate. The coordinator first writes the event to the Journal, then completes the deterministic handling synchronously. A clear long-term requirement can go straight to proven, because the current user is the authoritative source for this kind of content. The system also recognizes one-off phrasing such as “don’t commit this time”; that requirement keeps constraining the current task but is not written to long-term memory.

Inferred candidates from the system

Task completion, verification, Review, and context-application results can form inferred candidates. Reflection converts the related Personal Episodes into Learning Deltas (memory change instructions):

Operation	Meaning
`create`	Create a new record
`update`	Add evidence or tighten the scope of an existing record
`supersede`	Retire conflicting or invalid old records
`forget`	Execute a forgetting you explicitly requested
`noop`	Evidence is insufficient; no long-term content is formed

Consolidation merges near-duplicate records, keeps the more specific selectors (applicable conditions), and attaches new evidence to existing records. System-inferred content starts in trial and joins related tasks at lower priority; after one successful application it can be promoted to proven.

What the Experience Journal does

The Experience Journal is an append-only, replayable machine event log with three responsibilities:

Deduplicate with stable eventIds so retries do not produce repeated learning.
Correlate events from recovery, re-verification, and cross-session continuation with episodeId.
Keep the replay capability after a background Reflection failure, without blocking the current workflow.

The Journal stores structured context and evidence references, not full transcripts, full diffs, raw logs, or hidden reasoning. Old Personal Episodes that finished Consolidation can be compressed; records still in use keep the necessary evidence chain.

Task matching

The Provider first returns the available candidates, and Context Director then runs layered matching against the current request:

project → path → task → operation → phase

Ranking also considers the following:

proven outranks trial.
What you set explicitly outranks what the system inferred.
Precise project and path selectors outrank broad global content.
A recent successful application improves later ranking.
A correction, or taking part in a failure, lowers ranking and triggers a later Reflection.
superseded records never enter task context.

Your current requirements, system constraints, and project policies always have higher priority. Personal Memory only provides collaboration context; it never changes the system permission boundaries.

Progressive context

Comet controls how much context gets injected by providing it in layers:

Key Core Profile entries can enter the context in full.
A few directly related, stable Collaboration Policies can enter in full.
Other relevant candidates enter the Context Manifest first.
The Agent expands the content, source, and verification it needs by stable ID.

The Context Manifest is a slim index. For each candidate it provides a title, summary, stable ID, and whyApplied. whyApplied comes from the real match conditions, such as “the current project matches”, “the current path matches”, “you set this explicitly”, or “it was applied successfully recently”. The character budget limits only the content injected in one task. A saved record shows up in the context or the Manifest only when it hits the current conditions.

Application feedback

When Context Director provides a record, it creates an application record. After the task, one of these results can be written:

Result	Later effect
`used-successfully`	Raises reuse strength; a `trial` can be promoted
`ignored`	Affects ranking slightly; does not judge the content wrong
`overridden`	Records that the content was overridden by a higher-priority requirement this time
`corrected`	Triggers a correction or replacement
`contributed-to-failure`	Lowers reuse strength and triggers re-distillation

The retrieval hit rate measures relevance; application results measure real task value. Both kinds of information drive later ranking and the lifecycle.

Correction, forgetting, and replay

A correction creates an updated normalized record and marks the conflicting old version superseded. System-inferred content can never overwrite content you set explicitly. Forgetting writes a tombstone. The tombstone is stored separately from the lifecycle, so replaying historical events can still recognize content you already withdrew. forget keeps the rollback capability by default; --permanent performs a permanent deletion. When an explicit operation fails, the Provider keeps the original state and returns the actual error.

Local and Remote Providers

The Personal Memory domain accesses the Provider through one status / query / apply contract.

Local Provider

Keeps a user-readable profile.md and project records.
The machine index can be rebuilt after an upgrade or corruption.
Identifies the same repository with a stable repository identity.
The main workspace and linked worktrees share project-scoped Personal Memory.
Different repositories are isolated from each other.

Remote Provider

Uses the same versioned Provider contract as Local.
Tokens are supplied through environment variables only.
Once Remote is enabled, Local is no longer read at the same time.
A Remote failure returns the actual state and does not read Local data.

Project configuration can control automatic learning and task retrieval separately:

memory:
  learning: true
  retrieval: true

Turning off learning stops new records from forming and keeps existing data. Turning off retrieval stops memory from being provided to tasks, while the Dashboard and explicit management operations stay available.

Failure isolation

Where it fails	Product behavior
Explicit add, correct, forget, or rollback	Returns the actual error and keeps the original state
Journal background processing	Records the diagnostic and keeps the replay capability
Semantic Reflection	Explicit user signals stay on the deterministic path; inference tasks are deferred
Task retrieval	The current workflow continues and no failed content is provided
Personal Memory plugin disabled	Learning and retrieval stop; other workflows and Project Knowledge continue

Return to Personal Memory, or continue with Agent Learning Loop.

​Core components

​Record model

​Record formation paths

​Set explicitly by you

​Inferred candidates from the system

​What the Experience Journal does

​Task matching

​Progressive context

​Application feedback

​Correction, forgetting, and replay

​Local and Remote Providers

​Local Provider

​Remote Provider

​Failure isolation