V3.5.2

Cogmem 3.5.2 — Episode Dream Engine Reliability Pass

Cogmem 3.5.2 is a reliability-focused release for the Episode Dream Engine.

This release hardens episode assembly, Dream candidate grounding, topic growth, hookless-agent ingestion, and repair workflows. It also introduces the first version of Cogmem’s user-shaped Memory Ontology and Topic Registry.

The core pipeline remains unchanged:

Raw Ledger
→ Episode Assembler
→ Sealed Episode
→ Dream Scheduler
→ Episode Dream Curator
→ Governance

The goal of this release is not to add another memory layer. The goal is to make the existing Episode Dream Engine much harder to misclassify, over-seal, over-dream, duplicate, or silently drift.

---

Highlights

• Added User-Shaped Topic Ontology.
• Added project-scoped Topic Path Registry.
• Added Topic Alias Registry.
• Added Topic Relation Graph.
• Added Topic Governance with audited and reversible operations.
• Added Memory Ontology skeleton.
• Added Correction Resolver.
• Added shared Cogmem block stripper.
• Added episode cross-reference and repair audit support.
• Added ingest-key lifecycle state.
• Added per-episode Dream failure diagnostics.
• Added per-job Dream modes.
• Added deep Dream recommendations for large or old backlog.
• Added hookless recall freshness warnings.
• Added stronger MCP import diagnostics.
• Added episode repair/surgery operations.
• Added schema migration 24.
• Added OpenClaw plugin 0.5.0 metadata.
• Added new BrainEval reliability gates.
• Updated version to 3.5.2.

---

User-Shaped Memory Ontology

Cogmem now has a fixed memory-class skeleton plus user-shaped topic state.

The fixed ontology classes include:

Time
Person
Object
Place
Project
Event
Decision
Goal
Preference
Correction
Plan
Evidence
Conversation
Topic
Entity
Relation

This ontology is not a hard-coded topic dictionary. It is the stable skeleton of the memory system.

User language now shapes the actual topic map.

For example, when a user says:

This should be called Episode Assembler.

Cogmem can register that wording as a project-scoped topic name or alias.

When a user says:

This does not belong under Dream. It belongs under Episode Assembler.

Cogmem can record an audited topic move operation.

Explicit user topic operations become active and auditable. Model-proposed topics, aliases, and relations remain candidates until governance approves them.

---

Topic Registry

3.5.2 adds project-scoped topic components:

TopicPathRegistry
TopicAliasRegistry
TopicRelationGraph
TopicGovernance

The Topic Registry supports:

topic creation
topic rename
topic alias
topic move
topic merge
topic split
topic relation
topic rollback

Alias collisions fail closed as needs_review.

Topic operations are reversible and recorded with audit metadata.

This replaces the previous direction of expanding a hard-coded domain keyword dictionary.

Topic continuity is now decided through:

project boundary
user-defined aliases
topic overlap
entity overlap
semantic similarity
advisory classification
governance

Unknown turns now fail closed as ambiguous review boundaries instead of being blindly attached to the active episode.

---

Hybrid Episode Classification

3.5.2 wires advisory hybrid classification into asynchronous assembly, import, and repair paths.

The foreground hook remains CPU-only for latency safety.

Background/import/repair paths may use the advisory classifier for ambiguous or high-value cases.

Reviewer output is allow-listed and cannot directly mutate durable memory.

The classifier can now use richer context:

current user text
current assistant text
previous user text
previous assistant text
active episode hints
recent relations
topic/entity overlap
user-shaped topic registry

This improves short-reply interpretation and topic-boundary reliability.

---

Safer Unknown-Turn Handling

Unknown turns no longer default to continues_previous.

Continuation now requires one of:

explicit continuation language
project overlap
topic overlap
entity overlap
semantic overlap
reviewer-confirmed continuity

Otherwise, the turn becomes an ambiguous review boundary.

This reduces silent episode pollution where unrelated messages were previously attached to the current episode.

---

Short Reply Disambiguation

Short replies now distinguish between:

accepts_assistant_proposal
answers_assistant_question
confirms_assistant_fact
corrects_previous
rejects_assistant_proposal

Examples:

assistant: Should we use option B?
user: yes
→ accepts_assistant_proposal

assistant: Are you talking about OpenClaw?
user: yes
→ answers_assistant_question

assistant: You mean version 3.5.0?
user: no, 3.5.2
→ corrects_previous

This prevents plain factual answers from being misread as project decisions.

---

Safer Soft-Seal Reopen

Soft-sealed episodes now reopen only for confirmed continuation, clarification, correction, or return-to-topic relations.

The following no longer reopen soft-sealed episodes:

hard topic switch
ambiguous shift
new topic
noise

This prevents old episodes from being accidentally reopened by unrelated turns.

---

Episode Repair and Surgery

3.5.2 adds audited episode repair capabilities.

Supported repair operations include:

split episode
merge episodes
move event
reclassify episode
requeue Dream
invalidate Dream run
mark old candidates stale
recompute closure receipt
preserve cross-references

Repair writes audit records and requeues eligible sealed episodes for Dream processing.

This is a major step toward making wrong episode boundaries recoverable.

---

Correction Resolver

Cogmem now includes a Correction Resolver.

Correction candidates no longer silently become active memory if they cannot target an existing belief.

The resolver searches active beliefs by:

project
claim key
topic cue
semantic query

If no target is found, the correction remains needs_confirmation.

This prevents orphan corrections from becoming new active facts.

---

Dream Candidate Grounding

Episode Dream evidence was hardened.

Episode-mode candidates must cite a non-empty exact subset of the current episode’s raw event IDs.

The following are rejected in episode mode:

missing evidence IDs
hallucinated evidence IDs
evidenceEventIds: ["all"]
fallback to first raw events
summary-only evidence

Semantic summaries remain hints only:

hint_only_not_evidence

A summary can help the curator understand an episode, but it cannot satisfy evidence requirements.

---

CPU-Owned Project Scope

Provider-supplied projectId can no longer override CPU-owned project scope.

Candidate project scope is derived from:

options.projectId
raw event projectId
CPU scope

If a provider emits a conflicting project ID, Cogmem ignores the provider value and keeps the CPU-owned scope.

This closes a potential cross-project contamination path.

---

Assistant Proposal Confirmation

Assistant proposal confirmation was strengthened.

Cogmem now scans a bounded prior same-session/thread window for the nearest assistant proposal.

The scan stops if an intervening user rejection or correction appears.

A valid confirmed proposal requires:

assistant proposal
later distinct user acceptance
same session/thread
no intervening rejection or correction

The candidate records paired evidence:

proposalEvidenceEventId
confirmationEvidenceEventId
evidenceKind: assistant_proposal_confirmed_by_user

A proposal without later unambiguous user confirmation cannot become user-owned memory.

---

Assistant-Only Decision Safety

Assistant-only decision-like episodes no longer enter the normal durable temporal candidate path.

If an episode appears to contain a decision but has no user evidence, it becomes needs_confirmation.

This prevents assistant suggestions from being promoted as user decisions.

---

Per-Job Dream Modes

Dream Scheduler now computes an effective Dream mode per job.

Auto mode no longer applies one global mode to the entire batch.

A batch can now contain a mix of:

micro
normal
deep

The result reports selected mode counts.

Explicit requested mode still overrides the batch.

---

Deep Dream Recommendations

Deep Dream can now be recommended for:

large backlog
old backlog
maintenance work
repair work
explicit operator request

This makes deep processing more explicit and explainable.

---

Dream Failure Diagnostics

Dream tick results now include failed episode details.

Each failed episode can report:

episodeId
error
failureCategory
retryAfter

Dream run receipts can persist failure details for later inspection.

This makes partial Dream failures easier to diagnose.

---

Resumable Import and MCP Diagnostics

Import reliability was improved.

CLI import now supports stronger checkpoint behavior and diagnostics.

MCP import now reports per-message status and partial failure information.

Hookless agents can receive clearer diagnostics when an import partially succeeds.

Ingest keys now have lifecycle state:

reserved
committed
failed

This helps recover from raw-write failures and prevents permanent reserved-key ambiguity.

Source-agent identity validation was also strengthened.

---

Hookless Agent Freshness Warnings

Hookless agents such as Hermes cannot be observed au...

V3.5.1

Cogmem 3.5.1 — Episode Dream Engine Hardening

Cogmem 3.5.1 hardens the Episode Dream Engine introduced in 3.5.0.

This release does not add a new memory layer. Instead, it strengthens episode classification, assistant-context handling, topic-boundary detection, Dream retry behavior, import idempotency, MCP safety, and Dream evidence validation.

The core design remains:

Raw Ledger
→ Episode Assembler
→ Sealed Episode
→ Dream Scheduler
→ Episode Dream Curator
→ Governance

The goal of this release is:

Make Episode Dream Engine harder to misclassify, duplicate, over-dream, or accidentally promote unsafe memory.

---

Highlights

• Upgraded turn classification with richer context and confidence metadata.
• Added advisory hybrid classification support for ambiguous cases.
• Added assistant-context handling for short user replies.
• Added explicit assistant/tool relation semantics.
• Split topic movement into hard topic switches, subtopic shifts, and ambiguous shifts.
• Added episode tags, candidate types, importance signals, and importance reasons.
• Added semantic episode summaries as non-evidence hints.
• Added episode-level Dream status.
• Added stronger closure receipt metadata.
• Added Dream retry controls with retryable, terminal, and scheduled retry states.
• Made Dream mode affect curator behavior, not just batch size.
• Added episode-scoped exact evidence enforcement for Dream candidates.
• Added assistant-proposal + user-confirmation evidence modeling.
• Added temporal decision candidates for decision episodes.
• Added streaming JSONL import with checkpoint/resume support.
• Reworked generated import IDs to avoid line-index dependence.
• Added MCP maintenance-mode guard for Dream ticks.
• Improved MCP status output for hookless agents.
• Added schema migration 0023_episode_dream_hardening.
• Updated OpenClaw plugin metadata to 0.4.1.
• Updated core version to 3.5.1.
• Updated schema version to 23.

---

Richer Turn Classification

Turn classification now accepts structured conversation context instead of only a single text string.

The classifier can use:

currentUserText
currentAssistantText
previousUserText
previousAssistantText
activeEpisodeSummary
activeEpisodeTopicPath
recentRelations

The classifier now returns:

relation
confidence
signals
needsLlmReview
candidateTypes
topicPath
closureCandidate
switchKind
episodeType
importance
rationale

This makes episode assembly more inspectable and safer.

---

Hybrid Classifier Support

Cogmem now supports an advisory hybrid classifier path.

CPU rules still run first.

LLM review may be requested only for ambiguous or high-value cases, such as:

ambiguous topic shifts
possible corrections
possible decisions
possible prospective intent
short replies that depend on assistant context
messages that match multiple strong rules

The advisory reviewer can suggest classification fields, but it cannot mutate memory.

Any model-shaped mutation output is ignored.

Durable memory still requires CPU governance.

---

Assistant Context for Short Replies

Short user replies such as:

yes
对
不对
第二个
可以

can now be resolved against the previous assistant message.

This allows Cogmem to identify:

accepts_assistant_proposal
rejects_assistant_proposal
answers_assistant_question
continues_previous

A confirmation like:

assistant: I recommend the second option. Should we use it?
user: yes

can now become an explicit confirmed-proposal relation candidate instead of a vague continuation.

---

Explicit Assistant and Tool Relations

Assistant and tool messages no longer reuse user-turn relation semantics.

New relation types include:

assistant_response
assistant_proposal
assistant_summary
assistant_question
assistant_clarification
tool_result_context

This produces cleaner episode relation graphs and prevents assistant output from being misread as user memory.

---

Safer Topic Movement

Topic movement is now classified more carefully.

Instead of treating all topic movement as a hard switch, Cogmem distinguishes:

hard_topic_switch
subtopic_shift
ambiguous_shift

Behavior:

hard_topic_switch → hard-seal the old episode
subtopic_shift → continue the same episode
ambiguous_shift → soft-seal the old episode and create a reviewable linked episode

This prevents same-project subtopics from being split too aggressively.

---

Semantic Episode Summary

Sealed episodes now receive a semantic summary.

The summary may contain:

userPosition
assistantContribution
decision
correction
openQuestions
candidateTypes
evidenceEventIds
evidenceAuthority

Important rule:

Episode semantic summaries are hints, not evidence.
Only raw event IDs are evidence.

Dream can use the summary to understand the episode, but every candidate must still cite raw event IDs.

---

Stronger Episode Metadata

Episodes now track:

episodeTags
candidateTypes
importanceSignals
importanceReason
linkedEpisodeId
dreamStatus
lastDreamRunId
lastDreamedAt
dreamCandidateCount
dreamError

This makes episode state, Dream progress, and review/debugging easier to inspect.

---

Stronger Closure Receipts

Closure receipts now include:

closureReasonCode
closureReasonDetail
requiresReview
ignoredNearbyEventIds
unassignedNearbyEventIds

Closure reason codes include:

explicit_user_closure
topic_switch
batch_boundary
idle_timeout
manual
soft_seal_stabilized
repair

Low-confidence batch seals can now require review instead of entering Dream directly.

---

Episode-Level Dream Status

Dream state is now visible directly on the episode.

Episode state and Dream state are separate:

episode.status = open | soft_sealed | sealed
episode.dreamStatus = none | queued | processing | processed | failed

Episodes also track:

lastDreamRunId
lastDreamedAt
dreamCandidateCount
dreamError

This improves debugging, repair, and operator visibility.

---

Dream Retry Controls

Dream job states now include:

pending
processing
processed
failed_retryable
failed_terminal
retry_scheduled
skipped

Dream jobs now support:

retryAfter
failureCategory
lease recovery
terminal failure classification
manual retry for retryable failures

Validation-like failures become terminal.

Provider/rate-limit/timeout-like failures become retryable with delayed retry.

This prevents failed Dream jobs from being blindly reprocessed on every tick.

---

Dream Mode Now Affects Curator Behavior

Dream mode is now passed into the Dream Curator.

Modes affect both candidate limits and curation behavior:

micro  → eventLimit 20, maxCandidates 20
normal → eventLimit 100, maxCandidates 100
deep   → eventLimit 500, maxCandidates 500

The Dream Curator also receives:

dreamMode
sourceEpisodeId
sourceEpisodeEventIds
episodeType
closureReason
semanticSummary
episodeRelations

This makes micro/normal/deep meaningful beyond batch size.

---

Exact Episode Evidence Enforcement

Episode-scoped Dream runs now enforce exact raw evidence.

For episode Dream, every candidate must cite a non-empty subset of the episode’s raw event IDs.

Candidates using summary-only evidence or ["all"] are rejected.

Dream candidate content is annotated with:

sourceEpisodeId
evidenceAuthority: raw_event_ids_only
evidenceEventIds
dreamMode
episodeType
closureReason

This keeps Dream source-grounded.

---

Assistant Proposal Confirmed by User

Cogmem now models assistant proposal + user confirmation as a paired evidence relation.

When an assistant proposal is followed by a user confirmation, Dream can emit:

assistant_proposal_confirmed_by_user

The candidate stores:

proposalEvidenceEventId
confirmationEvidenceEventId
evidenceKind: assistant_proposal_confirmed_by_user

This avoids treating assistant text as user memory unless the user explicitly confirms it.

---

Decision Episodes Emit Temporal Candidates

Decision episodes now create temporal decision candidates.

For an episode classified as a decision, Dream can emit:

temporal_fact_update
promotionTargetType: temporal_decision

The candidate includes:

occurredAt
startSeq
endSeq
source event evidence

This improves historical decision recall and project timeline reconstruction.

---

Orphan Correction Safety

Correction candidates now carry target-search metadata.

A correction candidate may include:

correctedClaimKey
correctedBeliefCandidateIds
correctionTargetSearchQuery

If no prior target is found, the correction must remain under review.

It cannot silently become a new active belief.

---

Streaming Import and Resume

cogmem episode import now streams JSONL input instead of reading the whole file into memory.

It supports:

--chunk-size
--checkpoint-file
--resume

The importer writes checkpoint files atomically and can resume from a previous checkpoint.

This makes large Hermes/OpenClaw-style imports safer.

---

Stable Import Identity

Generat...

V3.5.0

Cogmem 3.5.0 — Episode Dream Engine v1

Cogmem 3.5.0 introduces Episode Dream Engine v1.

This release upgrades Cogmem’s memory consolidation model from raw-turn digestion to governed episode-based dream processing.

Raw events are still written immediately and remain the authoritative evidence layer. The new Episode Assembler groups related raw messages into auditable conversation episodes. Dream then processes sealed episodes through an explicit conditional scheduler, producing candidates that still require CPU governance before becoming durable memory.

The core rule of this release is:

Raw Ledger writes immediately.
Episode Assembler groups events.
Dream processes sealed episodes.
Governance decides durable memory.

---

Highlights

• Added Episode Assembler.

• Added Episode Store.

• Added episode lifecycle: open, soft-sealed, sealed.

• Added episode closure receipts.

• Added turn relation classification.

• Added session-scoped event grouping.

• Added safe soft reopen.

• Added hard-seal protection.

• Added episode Dream backlog.

• Added leased, retryable Dream jobs.

• Added conditional Dream Scheduler.

• Added cogmem episode CLI.

• Added cogmem dream CLI.

• Added MCP tools for hookless agents:

  • cogmem_episode_append
  • cogmem_episode_import
  • cogmem_episode_status
  • cogmem_episode_seal
  • cogmem_dream_tick
  • cogmem_dream_status

• Added Hermes/OpenClaw import convergence through the same episode pipeline.

• Added idempotent source-message import keys.

• Added recovery for partially written episode messages.

• Added migration 0022_episode_dream_engine.

• Added BrainEval episode/dream release gates.

• Updated OpenClaw live ingestion path to assemble episodes.

• Updated Dream Curator to support episode-scoped runs.

• Updated memory map and maintenance tick with episode/dream state.

• Updated release metadata to 3.5.0.

---

What Changed

Before 3.5.0, Dream primarily worked over raw event windows.

In 3.5.0, Dream primarily works over sealed episodes.

Old model:

raw event window
→ dream
→ candidates
→ governance

New model:

raw events
→ episode assembler
→ sealed episode
→ dream tick
→ candidates
→ governance

This prevents incomplete conversations, temporary context, or isolated fragments from being crystallized into long-term memory too early.

---

Episode Assembler

A new Episode Assembler groups raw user, assistant, tool, system, agent, and narrator messages into session-scoped conversation episodes.

The assembler identifies turn relations such as:

continues_previous
clarifies_previous
corrects_previous
answers_assistant_question
accepts_assistant_proposal
rejects_assistant_proposal
switches_topic
starts_new_topic
returns_to_old_topic
confirms_future_intent
closes_episode
noise

Episode types include:

discussion
decision
correction
preference
goal
debugging
planning
prospective
general

Episode statuses:

open
soft_sealed
sealed

The assembler is deterministic and CPU-first.

It does not directly create durable beliefs, entities, temporal records, or prospective confirmations.

---

Episode Lifecycle

Open episode

An episode remains open while related turns continue.

Soft-sealed episode

A soft-sealed episode is created when a conversation appears idle or temporarily complete.

Soft-sealed episodes can reopen when a later message returns to the same session/topic within the reopen window.

Sealed episode

A sealed episode is ready for Dream processing.

Hard-sealed episodes do not auto-reopen.

Episodes can be sealed by:

explicit user closure
explicit topic switch
manual seal
batch import boundary
idle soft seal stabilization

---

Closure Receipts

Every sealed episode produces an auditable closure receipt.

A closure receipt records:

receiptId
episodeId
projectId
closureMode
closureReason
sourceEventIds
startSeq
endSeq
topicPath
episodeType
importance
dreamRecommended
dreamMode
createdAt

This makes episode boundary decisions inspectable and repairable.

---

Noise Handling

Operational or low-value turns such as simple acknowledgements can be marked as ignored.

Ignored events remain in Raw Ledger, but they are not assigned to episodes or counted as unassigned work.

This prevents greetings and short acknowledgements from polluting Dream backlog.

---

Cogmem Context Hygiene

Episode assembly strips Cogmem context blocks before classification or summaries.

The following blocks cannot become user evidence through episode assembly or Dream:

<COGMEM_RECALL_CONTEXT>
<COGMEM_TURN_BRIDGE>
<COGMEM_SESSION_STATE>
<COGMEM_STRATEGY_CONTEXT>

Raw events are still preserved for audit, but injected Cogmem context is not treated as user-authored memory.

---

Episode Store

The new Episode Store persists:

memory_episodes
memory_episode_events
episode_closure_receipts
episode_dream_jobs
episode_dream_runs
episode_ingest_keys
episode_event_dispositions

It provides:

createEpisode
findActiveEpisode
appendEvent
sealEpisode
reopenSoftEpisode
sealIdleEpisodes
finalizeMatureSoftSeals
claimDreamJobs
completeDreamJob
failDreamJob
retryFailed
getDreamStatus
countUnassignedRawEvents
deleteByProject

One raw event can belong to only one episode.

Duplicate episode assignment is prevented.

---

Conditional Dream Scheduler

A new Dream Scheduler runs explicit conditional ticks.

It does not run continuously.

It does not start a hidden daemon.

It does not run during recall.

It does not execute tools.

A tick can select:

none
micro
normal
deep

Auto mode chooses based on sealed episode backlog.

Default mode limits:

micro: 1 episode
normal: 10 episodes
deep: 50 episodes

If no sealed episode backlog exists, the tick returns skipped with:

no_sealed_episode_backlog

---

Leased and Retryable Dream Jobs

Episode Dream jobs are leased before processing.

This prevents duplicate concurrent processing.

A Dream job records:

episodeId
projectId
state
priority
modeHint
attempts
leaseId
leaseUntil
lastError
candidateIds
createdAt
updatedAt

Expired leases are recovered.

Jobs below the attempt limit return to pending.

Jobs at or above the attempt limit become failed.

Failed jobs can be manually retried.

---

Episode-Scoped Dream Curator

Dream Curator now supports episode-scoped runs.

Episode Dream passes exact raw event IDs from a sealed episode into the curator.

Each episode-derived candidate includes:

sourceEpisodeId
raw event evidence
evidenceAuthority: raw_event_ids_only

Episode summaries and closure receipts are metadata, not evidence.

Durable memory still requires exact raw event evidence.

---

Candidate-Only Dream Output

Dream continues to produce candidates only.

Dream cannot:

promote memory
rewrite verified facts
merge entities
confirm prospective memory
execute tools
delete memory
bypass governance

All durable memory writes remain governed by CPU validation.

User-owned durable memory still requires explicit user-role raw evidence.

Assistant messages may provide context but cannot create user preferences, goals, corrections, or boundaries unless confirmed by user evidence.

Tool results remain observations only.

---

OpenClaw Live Path

OpenClaw-style hook-based agents now write raw events and assemble episodes in the foreground path.

Live turn flow:

write user raw event
write assistant raw event
bind user raw event
assemble episode turn
return without Dream

If binding or episode assembly fails, the failure is recorded as non-fatal telemetry.

Raw Ledger remains authoritative.

Dream is never run as part of foreground recall or turn recording.

---

Hermes and Hookless Agent Support

Cogmem 3.5.0 adds full support for Hermes-style agents that primarily interact through MCP or command imports.

Hookless ingestion can use:

cogmem episode append
cogmem episode import
cogmem_episode_append
cogmem_episode_import

Both live hook ingestion and batch/MCP import converge into the same internal pipeline:

Raw Ledger
→ Episode Assembler
→ Episode Store
→ Dream Backlog
→ Dream Scheduler
→ Dream Curator
→ Governance

There is no separate OpenClaw-only memory path.

There is no separate Hermes-only memory path.

---

cogmem episode CLI

A new CLI was added:

cogmem episode append
cogmem episode import
cogmem episode list
cogmem episode get
cogmem episode seal
cogmem episode status
cogmem episode repair

Examples:

cogmem episode append \
  --project hermes \
  --session session-1 \
  --source-agent hermes \
  --role user \
  --text "Remember that Dream should process sealed episodes only." \
  --external-id msg-1 \
  --json

cogmem episode import \
  --project hermes \
  --session session-1 \
  --source-agent hermes \
  --format jsonl \
  --file session.jsonl \
  --seal-batch \
  --json

Episode import does not run Dream implicitly.

It returns:

imported
duplicates
episodeIds
unassignedEventIds
ignoredEventIds
closureReceipts
dreamRan: false

---

cogmem dream CLI...

V3.4.0

Cogmem 3.4.0 — Strategy Cortex v1

Cogmem 3.4.0 introduces Strategy Cortex v1: a deterministic current-turn memory strategy layer inspired by StraTA’s separation between global strategy and local execution.

This release does not add online reinforcement learning. It does not generate multiple online strategies per user turn. Instead, Cogmem now chooses a CPU-owned strategy capsule before recall, uses that capsule to constrain retrieval lanes and context packing, and reserves diverse strategy comparison for offline BrainEval.

The core rule of this release is:

Strategy before recall.
Strategy has no instruction authority.
Online planning stays deterministic.
Offline evaluation compares strategy quality.

---

Highlights

• Added Strategy Cortex v1.
• Added current-turn Strategy Capsules.
• Added Strategy Template Registry.
• Added strategy-conditioned candidate building.
• Added <COGMEM_STRATEGY_CONTEXT>.
• Added deterministic one-retry replanning.
• Added read-only Memory Use Judge.
• Added project-scoped Context Outcome Store.
• Added Context Policy Scorer.
• Added Strategy Diversity Selector.
• Added Strategy Rollout Evaluator.
• Added cogmem strategy plan.
• Added cogmem strategy outcomes.
• Added cogmem brain-eval --strategy-rollout.
• Added read-only MCP tool cogmem_strategy_plan.
• Updated OpenClaw auto-memory plugin to 0.3.0.
• Added schema migration 0021_strategy_cortex.
• Extended forgetUser(projectId) to remove strategy outcome telemetry.
• Updated documentation and release metadata to 3.4.0.

---

Strategy Cortex

Cogmem now includes a Strategy Cortex layer that runs before non-trivial memory recall.

Strategy Cortex selects one deterministic strategy template for the current turn, such as:

source-first
temporal-first
user-belief-first
project-state
graph-source
balanced-memory

The selected strategy controls:

retrieval lane preferences
context layer order
required memory layers
exact-source requirements
source drill-down policy
memory budget policy
suppression priorities
replan triggers

This moves Cogmem from “retrieve memory first, decide later” to “decide how to use memory, then retrieve.”

---

Strategy Capsules

A Strategy Capsule is a current-turn memory-use policy.

It is not durable memory.

It is not a user instruction.

It is not a system prompt.

It has no authority to override user messages, host policy, tool authorization, or memory governance.

A capsule can include:

strategyId
projectId
intent
templateName
goal
retrievalLanes
contextLayerOrder
requiredLayers
sourcePolicy
suppressionPolicy
budgetPolicy
riskPolicy
replanPolicy
instructionAuthority
createdAt
expiresAt

The important field is:

instructionAuthority: "none"

This makes the strategy an internal planning hint, not a command.

---

Strategy Templates

The new Strategy Template Registry provides deterministic memory strategies for common query shapes.

Examples:

Source-first

Used for exact wording, quotes, verification, and source-sensitive questions.

Behavior:

prefer raw_source and graph anchors
require exact source when the user asks for original wording
avoid answering exact wording from summary-only memory

Temporal-first

Used for decision history, correction history, and timeline questions.

Behavior:

prefer temporal memory
then belief history
then graph anchors
then raw source for disputed points

User-belief-first

Used for user preferences, goals, and boundaries.

Behavior:

prefer user-owned beliefs
require user evidence for user-owned memory
suppress assistant-only and tool-only user claims

Project-state

Used for project status and roadmap questions.

Behavior:

prefer current active beliefs
then temporal milestones
then prospective open loops
then graph anchors

Graph-source

Used for debugging, evidence tracing, and relationship questions.

Behavior:

prefer graph anchors
then source context
then belief and temporal support

Balanced-memory

Used as a general fallback when no more specific strategy applies.

---

Strategy-Conditioned Candidate Building

Strategy Cortex now influences candidate construction before Context Cortex packing.

This is stronger than post-filtering.

The selected strategy can decide:

which lanes should be queried
which memory layers should be prioritized
which layers are required
whether raw source drill-down is necessary
whether vector fallback is allowed
how much memory budget may be used

This makes recall more purposeful and reduces unnecessary memory expansion.

---

Deterministic Replanning

Strategy Cortex supports at most one deterministic replan.

Replanning may occur when:

intent changes
project scope changes
exact-source requirement is not satisfied
evidence conflict is detected
required layer budget is unsatisfied

The replan is deterministic.

It does not call an online strategy generator.

It does not run multi-strategy rollout.

It does not perform reinforcement learning.

---

<COGMEM_STRATEGY_CONTEXT>

OpenClaw integration now supports a fourth Cogmem-owned block:

<COGMEM_STRATEGY_CONTEXT>

This block describes the current-turn memory-use policy.

It is explicitly:

not a user instruction
not a system instruction
not durable memory
not raw evidence
not tool authorization
not a governance operation

It must be stripped before recording and must not be ingested by Dream, Binding, Belief Graph, or Raw Ledger.

The host context blocks now are:

<COGMEM_SESSION_STATE>
<COGMEM_TURN_BRIDGE>
<COGMEM_STRATEGY_CONTEXT>
<COGMEM_RECALL_CONTEXT>

---

OpenClaw Plugin 0.3.0

The OpenClaw auto-memory plugin was updated to 0.3.0.

It now:

skips Cogmem for greetings
uses session state / turn bridge for short continuations
runs Strategy Cortex before full recall
injects <COGMEM_STRATEGY_CONTEXT>
passes the strategy capsule into recall/context packing
records read-only context outcome telemetry after the turn

The plugin keeps OpenClaw’s native prompt untouched.

Cogmem only prepends bounded, explicitly marked memory blocks.

---

Read-Only Memory Use Judge

Cogmem now includes a Memory Use Judge.

It evaluates whether memory was used correctly, but it cannot mutate durable memory.

It can flag:

exact quote without source
assistant-only user belief used
tool-only user belief used
superseded memory used
irrelevant memory injected
over-budget memory pack
strategy not followed
source required but missing
unsafe memory leak
stale memory leakage
cross-project leakage

The judge writes telemetry only.

It cannot:

change beliefs
merge entities
rewrite timelines
confirm prospective memory
delete memories
run tools

Durable memory changes must still go through CPU governance.

---

Context Outcome Store

Strategy Cortex now has project-scoped context outcome telemetry.

A context outcome can record:

receiptId
strategyId
projectId
intent
score
violations
usefulMemoryIds
harmfulMemoryIds
missingLayers
latencyMs
createdAt

This lets Cogmem inspect how well memory strategies performed over time.

forgetUser(projectId) now also removes strategy outcome telemetry for that project.

---

Context Policy Scorer

Cogmem now includes a Context Policy Scorer for offline evaluation.

It scores precomputed strategy rollout outcomes using:

median score
worst-decile score
top-fraction score
exact source fidelity
strategy adherence
unsafe leak rate
stale leak rate
cross-project leak rate
over-budget rate
p95 latency

The top-fraction score is diagnostic only.

It cannot override safety failures.

A strategy with high upside but unsafe leakage still fails the release gate.

---

Strategy Diversity Selector

Cogmem now includes an offline Strategy Diversity Selector.

It can select diverse strategy candidates from supplied vectors using farthest-point style selection.

This is intended for offline fixture construction and benchmark coverage.

It is not used for online per-turn strategy generation.

---

Strategy Rollout Evaluator

Cogmem now supports offline strategy rollout evaluation over precomputed outcomes.

This is the safe version of StraTA-style strategy comparison.

Cogmem does not run online multi-strategy exploration during user conversations.

Instead:

BrainEval consumes precomputed outcomes.
Policy scoring compares strategy quality.
Release gates enforce safety thresholds.
Runtime uses the best deterministic template.

---

cogmem strategy CLI

A new CLI was added:

cogmem strategy plan --project <projectId> --query "<query>" --json
cogmem strategy outcomes --project <projectId> --json

strategy plan

Returns the deterministic current-turn strategy capsule for a query.

It does not perform recall.

It does not mutate memory.

strategy outcomes

Returns read-only context outcome telemetry.

It does not modify beliefs, entities, timelines, or prospective memories.

---

BrainEval Strategy Rollout Mode

cogmem brain-eval now supports:

cogmem brain-eval --input strategy-outcomes.json --strategy-rollout --json

This mode consumes precomputed StrategyRolloutOutcome records.

It does not:

call a model
generate strategies online
run online rollouts
mutate memory

It reports:

median quality
worst-decile quality
top-fraction diagno...

V3.3.0

Cogmem 3.3.0 — Prospective Memory v1 and BrainEval Release Gate

Cogmem 3.3.0 introduces confirmed-only Prospective Memory and the first BrainEval release gate.

This release adds a safe future-memory layer for intentions, commitments, reminders, open loops, and plans. Prospective Memory is deliberately candidate-only: it stores state, provenance, confirmation, due/defer/completion lifecycle, and audit transitions, but it does not execute tasks or tools.

The core rule of this release is:

Future memory is not permission to act.
A candidate is not actionable until explicitly confirmed by a distinct user Raw Ledger event.
Due state is memory state, not task execution.

---

Highlights

• Added ProspectiveMemoryService.

• Added confirmed-only prospective candidates for:

  • intentions
  • commitments
  • reminders
  • open loops
  • plans

• Added candidate lifecycle:

  • pending
  • confirmed
  • deferred
  • rejected
  • completed
  • expired

• Added strict Raw Ledger evidence requirements.

• Added explicit user confirmation requirements.

• Added transition history for prospective memory state changes.

• Added cogmem prospective CLI.

• Added cogmem_prospective MCP tool.

• Added governance operation handlers for prospective memory.

• Added schema migration 0020_prospective_memory.

• Added cogmem brain-eval release-gate CLI.

• Added BrainEval metrics for memory-brain safety and quality.

• Updated schema migration path through version 20.

• Updated release metadata to version 3.3.0.

---

Prospective Memory Service

Cogmem now includes:

ProspectiveMemoryService

It stores candidate future memories such as:

intentions
commitments
reminders
open loops
plans

Supported candidate types:

intention
commitment
reminder
open_loop
plan

Supported statuses:

pending
confirmed
deferred
rejected
completed
expired

Supported proposers:

deterministic
model_candidate
operator

A prospective memory record includes:

candidateId
projectId
candidateType
canonicalKey
title
details
status
proposedBy
evidenceEventIds
confirmationEvidenceEventId
dueAt
deferredUntil
version
createdAt
updatedAt

---

Evidence-Backed Candidate Creation

Prospective candidates require Raw Ledger evidence.

Candidate creation rejects:

missing evidence
unknown evidence
cross-project evidence
invalid candidate type
invalid proposer
invalid due time
empty project id
empty canonical key
empty title

The service deduplicates exact same-evidence proposals under the same project and canonical key.

If a rejected candidate is proposed again with the same evidence, Cogmem returns the rejected candidate instead of resurfacing it as pending.

A genuinely new version requires new evidence.

---

Confirmed-Only Activation

A prospective candidate does not become due simply because it has a due time.

Only confirmed or deferred candidates can appear in the due list.

To confirm a candidate, Cogmem requires a separate confirmation event.

The confirmation evidence must be:

an existing Raw Ledger event
in the same project
role = user
distinct from the proposal evidence
later than the proposal evidence
explicitly affirmative
not already used to confirm another candidate

Rejected confirmation examples include:

assistant evidence
tool evidence
same event as the original proposal
older user event
cross-project event
ambiguous user text
negative user text
confirmation event already used by another candidate

This prevents assistant-generated or reused evidence from activating future memory.

---

Candidate Lifecycle

Prospective candidates support the following transitions:

confirm

pending → confirmed

Requires distinct explicit user confirmation evidence.

reject

pending/confirmed/deferred → rejected

Rejected candidates are terminal.

defer

confirmed → deferred

Requires a future deferredUntil timestamp.

complete

confirmed → completed

Completed candidates are terminal.

expire

pending/confirmed/deferred → expired

Expired candidates are terminal.

Terminal states cannot transition again:

rejected
completed
expired

---

No Execution Capability

Prospective Memory deliberately has no execution or dispatch API.

The CLI, MCP tool, and service can:

create candidates
confirm candidates
reject candidates
defer candidates
complete candidates
expire candidates
list candidates
list due candidates

They cannot:

run tools
send messages
schedule external jobs
execute tasks
trigger actions

Due candidates are memory state only.

Host runtimes may choose how to present or handle due candidates, but Cogmem itself does not act on them.

---

Schema Migration 20

A new migration was added:

0020_prospective_memory

It creates:

prospective_memories
prospective_memory_transitions

The migration adds indexes for:

project/status/due lookup
project/status/deferred lookup
project/canonical-key/version lookup
unique project/canonical-key/version
unique confirmation evidence per project
transition lookup by candidate

The migration chain now includes:

0015_memory_governance
0016_entity_governance
0017_belief_graph
0018_temporal_memory
0019_context_cortex
0020_prospective_memory

The core schema version is now:

20

---

Kernel Integration

MemoryKernel now exposes:

prospectiveMemoryService

The kernel initializes Prospective Memory with Raw Ledger evidence lookup.

The evidence lookup provides:

eventId
projectId
role
globalSeq
content

This allows Prospective Memory to enforce project boundaries, user-role confirmation, ordering, and explicit affirmation checks.

The memory stack now looks like:

Raw Ledger
→ Memory Binding
→ Entity Brain
→ Belief Graph
→ Temporal Memory
→ Context Cortex
→ Prospective Memory

---

Governance Plan Integration

MemoryGovernanceOperationType now includes:

CREATE_PROSPECTIVE_MEMORY
RESOLVE_PROSPECTIVE_MEMORY

MemoryKernel.executeMemoryGovernancePlan() can now create and resolve prospective memory through governed operations.

The governance handler for prospective memory:

uses operation evidence as proposal evidence
requires projectId
requires canonicalKey and title for creation
supports dueAt
requires confirmation evidence to be included in the governance operation evidence
uses ProspectiveMemoryService for all state transitions

This keeps future-memory changes inside the same CPU-governed memory operation model as binding, entity, belief, and temporal layers.

---

CLI: cogmem prospective

A new CLI was added:

cogmem prospective

Supported commands:

list
due
create
confirm
reject
defer
complete
expire

Example:

cogmem prospective create --project hermes --type reminder --key release:check-ci --title "Check CI" --evidence <request-event-id> --due <epoch-ms>
cogmem prospective confirm --project hermes --id <candidate-id> --evidence <distinct-user-confirmation-event-id>
cogmem prospective due --project hermes --at <epoch-ms>

The CLI manages state only.

It does not execute tasks or tools.

---

MCP: cogmem_prospective

A new MCP tool was added:

cogmem_prospective

Supported actions:

list
due
create
confirm
reject
defer
complete
expire

The MCP description explicitly states:

It manages evidence-backed future-memory candidates.
It lists due state.
It never executes tasks or tools.
Confirmation requires a distinct Raw Ledger user event.

This allows agents to inspect and manage future-memory state without gaining execution authority.

---

BrainEval Release Gate

Cogmem now includes:

BrainEvalRunner

and a CLI:

cogmem brain-eval --input samples.json

The input can be:

BrainEvalSample[]

or:

{
  "samples": []
}

The command prints a JSON report and exits non-zero when the report fails.

BrainEval metrics

BrainEval measures:

recall
precision
provenanceCoverage
contextBudgetCompliance
staleLeakageRate
crossProjectLeakageRate
prospectiveFalseActivationRate
bindingPurity
entityFalseMergeRate
beliefOwnershipCompliance
temporalCurrentTruthAccuracy
contextPollutionRate
sourceFidelity

Release thresholds

The default release gate requires:

recall >= 0.90
precision >= 0.80
provenanceCoverage >= 0.95
contextBudgetCompliance = 1
staleLeakageRate = 0
crossProjectLeakageRate = 0
prospectiveFalseActivationRate = 0
bindingPurity >= 0.90
entityFalseMergeRate = 0
beliefOwnershipCompliance = 1
temporalCurrentTruthAccuracy >= 0.95
contextPollutionRate = 0
sourceFidelity = 1

Release fixtures fail closed when key domain checks are missing.

This prevents a test set from appearing perfect simply because it omitted...

V3.2.0

Cogmem 3.2.0 — Context Cortex v1

Cogmem 3.2.0 introduces the first Context Cortex layer.

This release changes Cogmem from “retrieve relevant memory” toward “decide whether memory should surface, which memory layers are eligible, and how much context they may consume.”

The core rule of this release is:

Memory should not always surface.
Memory should surface only when useful, safe, relevant, and within budget.

---

Highlights

• Added ContextCortex.
• Added deterministic context intent classification.
• Added layer-based memory activation.
• Added hard safety suppression before ranking.
• Added 25% default memory budget and 30% hard maximum.
• Added source-first handling for exact quote requests.
• Added persistent activation receipts.
• Added schema migration 0019_context_cortex.
• Exported Context Cortex APIs through the public surface.
• Integrated Context Cortex into MemoryKernel.
• Updated OpenClaw auto-memory plugin to version 0.2.0.
• Added Context Cortex v1 regression tests.

---

Context Cortex

Cogmem now includes:

ContextCortex

The Context Cortex decides:

whether memory should surface
which memory layers are eligible
which candidates must be suppressed
how much memory context may be used
which selected/suppressed items should be recorded in an activation receipt

This is the first implementation of Cogmem’s context activation layer.

---

Context Intent Classification

Context Cortex classifies queries into:

greeting
short_followup
exact_quote
decision_history
preference_lookup
project_status
debugging
general_memory

Example behavior:

hi                         → greeting
继续                       → short_followup
我当时的原话是什么？        → exact_quote
Why did the decision change? → decision_history
What are my preferences?    → preference_lookup

This prevents Cogmem from treating every message as a full-memory-recall request.

---

Layer-Based Activation

Context Cortex organizes memory candidates into layers:

session_state
turn_bridge
belief
temporal
graph
raw_source
vector

Each intent activates a different set of layers.

Greeting

activated layers: none

All memory is suppressed.

Short follow-up

activated layers:
- session_state
- turn_bridge

This supports same-topic continuation without forcing full recall.

Exact quote

activated layers:
- raw_source
- graph
- belief

Raw source is prioritized over summaries for exact wording requests.

Decision history

activated layers:
- temporal
- belief
- raw_source
- graph

This lets historical questions use Temporal Memory and Belief Graph before falling back to source anchors.

General memory

activated layers:
- belief
- graph
- temporal
- raw_source
- vector

This keeps vector recall as a fallback rather than the first cognitive layer.

---

Hard Safety Suppression

Context Cortex applies hard suppression before ranking.

Suppression reasons include:

intent_suppresses_memory
layer_not_activated
project_boundary
superseded
current_session_echo
user_belief_without_user_evidence
sensitive_without_need
budget_exceeded
duplicate

This prevents unsafe or irrelevant memory from entering the prompt even when it has a high confidence score.

Suppressed examples

Context Cortex suppresses:

cross-project memory
superseded beliefs
current-session raw echo
user-owned beliefs without user-role evidence
sensitive candidates when not needed
memory outside the active intent layers
items that exceed the memory budget

This is the first layer where Cogmem actively decides what not to remember in the current prompt.

---

Context Budgeting

Context Cortex now enforces a bounded memory budget.

Default behavior:

memory budget = 25% of available tokens
hard maximum = 30% of available tokens

Example:

availableTokens = 16000
default memory budget = 4000 tokens
hard maximum = 4800 tokens

This moves Cogmem toward the “sweet spot” context strategy: enough memory to help, not enough memory to dominate the prompt.

---

Activation Receipts

Every Context Cortex plan emits an activation receipt.

A receipt records:

receiptId
query
intent
projectId
budgetTokens
usedTokens
selected items
suppressed items
suppression reasons
createdAt

When Context Cortex is backed by a database, receipts are persisted in:

context_activation_receipts

Activation receipts make memory activation auditable.

Agents and developers can inspect:

why a memory surfaced
why a memory was suppressed
how much budget was used
which intent controlled the context plan

---

Schema Migration 19

A new migration was added:

0019_context_cortex

It creates:

context_activation_receipts

with an index for project/time lookup.

The migration chain now includes:

0015_memory_governance
0016_entity_governance
0017_belief_graph
0018_temporal_memory
0019_context_cortex

Upgrading an older schema 14 database now applies all five migrations and sets the final schema version to:

19

---

Kernel Integration

MemoryKernel now exposes:

contextCortex

The kernel initializes Context Cortex with the same SQLite database used by the governed memory layers.

The memory stack now looks like:

Raw Ledger
→ Memory Binding
→ Entity Brain
→ Belief Graph
→ Temporal Memory
→ Context Cortex

---

Public API Updates

Context Cortex APIs are now exported through the public surface.

New exports include:

ContextCortex
ContextActivationPlan
ContextActivationReceipt
ContextCandidate
ContextIntent
ContextLayer
ContextPlanInput
ContextSuppressionReason

This lets host integrations use the Context Cortex directly without importing internal modules.

---

OpenClaw Auto-Memory Plugin 0.2.0

The OpenClaw auto-memory plugin was upgraded to:

0.2.0

New default config:

contextCortexEnabled: true
contextAvailableTokens: 16000
contextMemoryMaxRatio: 0.25

The plugin schema now exposes:

contextCortexEnabled
contextAvailableTokens
contextMemoryMaxRatio

Greeting suppression

For greetings such as:

hi
hello
你好

the plugin skips memory injection.

Short follow-up mode

For short continuations such as:

继续
接着
go on
continue

the plugin avoids full recall and uses only session state / turn bridge when available.

This prevents unnecessary memory recall for lightweight continuation turns.

Cortex-filtered recall

For normal recall, the plugin now:

runs the existing recall path
converts recall items into Context Cortex candidates
applies Context Cortex filtering
injects only selected items
emits an activation receipt

The activation receipt is included in audit logs.

---

Tests Added

New Context Cortex v1 tests cover:

• greeting queries suppress all memory;
• short same-topic follow-ups select only session state and turn bridge;
• exact quote requests prioritize raw source and graph anchors;
• context packing stays inside budget;
• hard safety filters run before ranking;
• activation receipts are persisted when a database is provided.

Migration tests were also updated to verify that schema 14 databases plan and apply:

0015
0016
0017
0018
0019

and reach schema version:

19

OpenClaw plugin tests now check:

Context Cortex config fields
greeting suppression
short follow-up recall mode
bridge-side kernel.contextCortex.plan usage
activationReceipt output

---

Current Scope

Cogmem 3.2.0 is the first Context Cortex release.

It does not yet implement a full semantic candidate builder from all governed memory stores. In this version, Context Cortex primarily filters and packs candidates supplied by recall or host integrations.

It also uses deterministic intent rules rather than an advanced domain-aware planner.

This is intentional for v1.

The release establishes the safe activation contract first:

classify intent
activate eligible layers
suppress unsafe candidates
fit within budget
record receipt

Future versions can make candidate generation and planning smarter without weakening the safety boundary.

V3.1.0

Cogmem 3.1.0 — Temporal Memory v1

Cogmem 3.1.0 introduces the first Temporal Memory layer.

This release adds validity-window belief lookup and project/entity timelines for milestones, decisions, corrections, and belief versions. It builds directly on the 3.0.0 Belief Graph by making belief history queryable over time.

The core idea of this release is:

Beliefs are not timeless.
Project state changes.
Decisions evolve.
Corrections supersede earlier beliefs.
Cogmem should know which version was valid at a given time.

---

Highlights

• Added TemporalMemoryService.
• Added timeline entries for milestones, decisions, corrections, and belief versions.
• Added historical belief lookup by canonical key and timestamp.
• Added belief history lookup across validity windows.
• Added bounded timeline queries by project, entity, canonical key, entry type, and time range.
• Added schema migration 0018_temporal_memory.
• Exported temporal memory APIs through the public and internal surfaces.
• Integrated TemporalMemoryService into MemoryKernel.
• Updated migration tests to migrate schema 14 databases through 0015, 0016, 0017, and 0018.
• Added Temporal Memory v1 regression tests.

---

Temporal Memory Service

Cogmem now includes:

TemporalMemoryService

The service provides two main capabilities:

1. Timeline entries
2. Historical belief lookup

It is designed to answer questions such as:

What was the valid belief at this time?
How did this project decision change?
When was this correction recorded?
What milestones happened for this project?
What timeline entries exist for this entity?

---

Timeline Entries

Temporal Memory introduces timeline records for:

milestone
decision
correction
belief_version

A timeline entry may include:

entryId
projectId
entryType
canonicalKey
entityId
beliefId
title
summary
reason
occurredAt
evidenceEventIds
createdAt

This makes it possible to record project and entity history as ordered memory events rather than treating all memory as current-state facts.

Supported timeline queries

Timeline entries can be queried by:

projectId
canonicalKey
entityId
entryTypes
startTime
endTime
limit

Results are ordered by occurrence time and creation time, giving agents a stable way to inspect project and entity history.

---

Historical Belief Lookup

Temporal Memory can query the Belief Graph by validity window.

getBeliefAt()

This method returns the belief version that was valid at a specific timestamp.

It uses:

canonicalKey
projectId
validFrom
validTo
status

It excludes rejected and unresolved conflict beliefs from normal historical lookup.

This enables questions such as:

What did we believe about the recall route before Graph Recall was introduced?
What was the active project decision at this point in time?
Which belief version was valid before the correction?

getBeliefHistory()

This method returns the ordered history of a canonical belief key.

It allows Cogmem to inspect how a belief evolved from older versions to the current version.

Example:

v1: Vector recall is primary.
v2: Graph recall precedes vector fallback.

This is the first step toward full belief/project/decision/correction versioning.

---

Schema Migration 18

A new migration was added:

0018_temporal_memory

It creates:

memory_timeline_entries

and adds indexes for:

project timeline lookup
canonical key timeline lookup
entity timeline lookup

The migration chain now includes:

0015_memory_governance
0016_entity_governance
0017_belief_graph
0018_temporal_memory

Upgrading an older schema 14 database now applies all four migrations and sets the final schema version to:

18

---

Kernel Integration

MemoryKernel now initializes:

temporalMemoryService

This gives host integrations direct access to Temporal Memory through the kernel instance.

Temporal Memory is now part of the core memory stack:

Raw Ledger
→ Memory Binding
→ Entity Brain
→ Belief Graph
→ Temporal Memory
→ future Context Cortex

---

Public API Updates

Temporal Memory APIs are now exported through the public surface.

New exports include:

TemporalMemoryService
RecordTimelineEntryInput
TemporalBeliefRecord
TimelineEntryRecord
TimelineEntryType
TimelineListOptions

This allows external integrations to record and query temporal memory without importing internal implementation files.

---

Tests Added

New Temporal Memory v1 tests cover:

• belief lookup at historical timestamps;
• belief history ordering across corrections;
• milestone timeline recording;
• correction timeline recording;
• timeline reason preservation;
• evidenceEventIds preservation;
• project-isolated timeline queries;
• bounded time-window queries.

Migration CLI tests were also updated to verify that schema 14 databases plan and apply:

0015
0016
0017
0018

and reach schema version:

18

---

Current Scope

Cogmem 3.1.0 is the Temporal Memory foundation.

It does not yet implement the full Context Cortex layer. Memory activation, context budgeting, recall suppression, source-drilldown policy, and immediate/working/background context bands remain future 3.2 work.

It also does not yet make every timeline entry strictly evidence-governed. Timeline entries can store evidence anchors, but Temporal Memory v1 is primarily a timeline and historical lookup layer.

V3.0.0

Cogmem 3.0.0 — Belief Graph v1

Cogmem 3.0.0 introduces the first evidence-backed Belief Graph layer.

This release moves Cogmem beyond raw event organization and entity governance. Important memory can now be represented as governed beliefs with ownership, source roles, evidence links, versions, supersession chains, and conflict records.

The core rule of this release is:

Raw events remain authoritative.
Beliefs must be evidence-backed.
User-owned beliefs require explicit user evidence.
Assistant/tool-only evidence cannot create user-owned memory.

---

Highlights

• Added BeliefGovernanceService.
• Added governed belief records with ownership, type, status, confidence, versions, and evidence links.
• Added explicit source-role tracking for belief evidence.
• Added user-evidence enforcement for user-owned beliefs.
• Added project-boundary checks for belief evidence.
• Added deterministic belief reinforcement.
• Added correction-based supersession.
• Added pending conflict records for contradictions.
• Added schema migration 0017_belief_graph.
• Exported Belief Graph APIs through the public and internal surfaces.
• Added Belief Graph v1 regression tests.

---

Belief Governance Service

Cogmem now includes:

BeliefGovernanceService

The service creates and manages governed belief records.

A governed belief includes:

beliefId
projectId
ownership
beliefType
canonicalKey
statement
status
confidence
version
validFrom
validTo
supersedesBeliefId
supersededByBeliefId
evidenceEventIds
sourceRoles
createdAt
updatedAt

Supported ownership types:

user
project
system

Supported belief types:

preference
goal
boundary
decision
fact
observation

Supported belief statuses:

active
weak
needs_confirmation
possible_conflict
superseded
rejected

Supported relation modes:

assert
reinforce
correct
contradict

---

Evidence-Backed Beliefs

Every belief operation must include raw evidence event IDs.

Cogmem rejects belief creation when:

evidenceEventIds is empty
an evidence event does not exist
evidence crosses the project boundary
a user-owned belief has no explicit user-role evidence

This prevents assistant summaries, tool outputs, or volatile context from silently becoming durable user memory.

User-owned belief safety

User-owned beliefs require at least one explicit user-role raw event.

This applies to user-owned:

preferences
goals
boundaries
decisions
facts

Assistant-only or tool-only evidence cannot create user-owned memory.

Project observations

Assistant and tool evidence may still create project-owned observations.

For example, a tool result can support a project observation such as:

The build completed in the observed tool run.

But it cannot become:

The user prefers this build strategy.

unless explicit user evidence exists.

---

Belief Reinforcement

When a new event supports the same canonical belief and the statement is equivalent, Cogmem reinforces the existing active belief instead of creating a duplicate.

Reinforcement:

keeps the same beliefId
adds new evidence
increments the belief version
updates the version history
slightly increases confidence
preserves a single active current belief

This prevents repeated user statements from becoming many separate memory facts.

---

Belief Correction and Supersession

Cogmem now supports correction-based supersession.

When a new user-backed belief corrects an existing active belief with the same canonical key:

the old belief becomes superseded
validTo is set on the old belief
the new belief becomes active
the new belief references supersedesBeliefId
the old belief references supersededByBeliefId
a resolved belief conflict record is written

This gives Cogmem a clean path for memory evolution.

Example:

Old belief:
Use vector recall as the primary route.

Corrected belief:
Use graph recall before vector fallback.

The old belief remains auditable, but it is no longer the current active belief.

---

Pending Contradictions

Contradictions that do not explicitly correct the current belief are recorded as pending conflicts.

In this case:

the existing active belief remains active
the new conflicting belief is marked possible_conflict
a pending conflict record is written
history remains inspectable

This avoids unsafe replacement when the system sees conflicting evidence but lacks enough authority to supersede the current belief.

---

Belief Graph Schema

A new migration was added:

0017_belief_graph

It creates:

belief_graph_nodes
belief_graph_evidence
belief_graph_versions
belief_graph_conflicts

belief_graph_nodes

Stores current and historical belief nodes.

Important columns include:

belief_id
project_id
ownership
belief_type
canonical_key
statement
status
confidence
version
valid_from
valid_to
supersedes_belief_id
superseded_by_belief_id
created_at
updated_at

belief_graph_evidence

Stores source-role evidence links.

Important columns include:

belief_id
event_id
source_role
evidence_type
weight
created_at

belief_graph_versions

Stores belief snapshots over time.

Important columns include:

belief_id
version
snapshot_json
reason
evidence_event_id
created_at

belief_graph_conflicts

Stores correction and contradiction records.

Important columns include:

conflict_id
project_id
prior_belief_id
proposed_belief_id
relation
status
reason
evidence_event_ids_json
created_at

---

Schema Version 17

The migration chain now includes:

0015_memory_governance
0016_entity_governance
0017_belief_graph

Upgrading a schema 14 database now plans and applies all three pending migrations and sets the final schema version to:

17

The migration CLI remains dry-run friendly and backup-aware.

---

Public API Updates

Belief Graph APIs are now exported through the public surface.

New exports include:

BeliefGovernanceService
ApplyBeliefInput
BeliefEvidenceLookup
BeliefEvidenceRecord
BeliefOwnership
BeliefRelation
GovernedBeliefRecord
GovernedBeliefStatus
GovernedBeliefType

This allows host integrations and advanced agent runtimes to create and inspect governed beliefs using Raw Ledger evidence.

---

Kernel Integration

MemoryKernel now initializes BeliefGovernanceService with Raw Ledger evidence lookup.

The service checks evidence through EventStore, so belief operations are grounded in existing raw events.

This keeps the belief layer tied to the original chronological source ledger.

---

Memory Map Update

The memory self-map now includes a new anatomy section:

belief_cases

It describes:

active beliefs plus support, supersession, and contradiction history

This makes Belief Graph visible as part of Cogmem’s self-inspection model.

---

Tests Added

New Belief Graph v1 tests cover:

• user-owned beliefs require explicit user evidence;
• assistant/tool evidence can create project observations but not user facts;
• reinforcement updates the same belief instead of duplicating the current belief;
• user correction supersedes the old belief and preserves history;
• unsupported contradiction remains pending and does not replace the active belief;
• project-boundary violations are rejected;
• kernel-level belief governance works against Raw Ledger evidence.

Migration tests were also updated to verify that schema 14 databases plan and apply:

0015
0016
0017

and reach schema version:

17

2.9.0

Cogmem 2.9.0 — Entity Brain v1 and Reversible Entity Governance

Cogmem 2.9.0 introduces the first Entity Brain layer on top of Memory Binding v1.5.

This release moves entity identity out of the binding compatibility projection and into EntityStore as the canonical owner of entity identity. Memory Binding now writes canonical EntityStore-owned entity IDs into its graph projection, while entity merge decisions are handled through an evidence-backed and reversible governance service.

Highlights

• Added EntityGovernanceService.
• Added evidence-backed, project-scoped entity merge candidates.
• Added stricter merge policy for person entities.
• Added reversible entity merge / revert flow.
• Added canonical entity identity and entity instance separation in EntityStore.
• Added entity alias conflicts and entity mention timelines.
• Connected Memory Binding to canonical EntityStore identity.
• Added schema migration 0016_entity_governance.
• Updated migration tests to apply schema versions 0015 and 0016.
• Added entity governance regression tests.

---

Entity Governance Service

Cogmem now includes a dedicated EntityGovernanceService.

It manages entity merge proposals as explicit candidates rather than applying alias merges implicitly.

Each merge candidate records:

candidateId
projectId
sourceEntityId
targetEntityId
alias
confidence
status
reviewReasons
evidenceEventIds
createdAt
updatedAt
version

Supported candidate statuses are:

pending
approved
rejected
applied
reverted

This gives Cogmem an auditable lifecycle for entity identity changes.

Evidence-backed merge proposals

Entity merge proposals must include evidence event IDs.

The governance service evaluates:

source entity
target entity
entity type
project boundary
evidence existence
evidence project scope
source role
confidence

Fatal rejection reasons include:

same_entity
entity_type_mismatch
project_boundary_violation
unknown_evidence

This prevents cross-project or unsupported entity merges from becoming durable identity changes.

Stricter person-entity policy

Person entity merges are stricter than project or concept merges.

For person entities:

explicit user-role evidence is required
confidence threshold is higher
assistant-only evidence is not enough
tool-only evidence is not enough

A person merge without explicit user evidence remains pending and receives:

person_merge_requires_explicit_user_evidence

This protects family, coworker, and personal identity memory from being merged based on assistant guesses or indirect observations.

---

Reversible Entity Merges

Entity merges are now reversible.

When a merge is applied:

the target entity receives the alias
the source entity is redirected to the target canonical entity
the source entity is archived, not deleted
an entity resolution log is written
the candidate status becomes applied

When a merge is reverted:

the source entity's previous canonical entity id is restored
the source entity's previous status is restored
the alias is removed from the target
a revert log is written
the candidate status becomes reverted

Source entities are never destructively deleted.

This is important because entity identity mistakes are expected during long-term memory growth. Cogmem can now undo incorrect merges without losing source history.

---

Canonical Entity Identity

EntityStore now separates canonical identity from entity instances.

The canonical identity layer is stored in:

entities

Entity instances are stored in:

entity_instances

Entity instances include:

instance_id
canonical_entity_id
canonical_name
type
aliases_json
status
created_from
metadata_json
created_at
updated_at

This allows Cogmem to distinguish:

canonical identity
individual mention-backed instances
redirected / archived entity instances
reversible merge history

Entity records now support statuses:

active
pending_resolution
archived

---

Entity Alias, Conflict, and Timeline Support

EntityStore now includes additional entity-support tables:

entity_aliases
entity_attributes
entity_relations
pending_entity_resolution
entity_mentions
entity_alias_conflicts

These tables allow Cogmem to track:

aliases
attributes
entity relations
unresolved references
entity mentions
alias ambiguity
entity timelines

Entity mention timeline

Cogmem can record entity mentions and query entity timelines.

This is an important step toward Entity Brain v1 because entities are no longer just names. They now have mention history, project scope, and temporal activity.

Alias conflict detection

Alias conflicts are tracked when multiple active entities of the same type share the same normalized alias.

Conflict policy may be:

prefer_project_context
prefer_recent_mention
require_explicit_disambiguation

This helps avoid unsafe automatic merging when the same alias may refer to different entities in different projects or contexts.

---

Memory Binding Integration

Memory Binding now uses EntityStore-owned identity.

During binding:

BindingClassifier detects entityName/entityType
EntityStore.upsertEntity creates or reuses canonical entity identity
MemoryBindingStore receives the EntityStore-owned entityId
binding graph edges point to the canonical compatibility projection

This unifies the Memory Binding graph with the Entity Brain identity layer.

Before this release, Memory Binding could create entity-like records as an organization hint. In 2.9.0, entity identity is owned by EntityStore, and Memory Binding only writes the canonical entity ID into its projection.

This is the correct direction: binding graph remains an organization layer, while EntityStore becomes the canonical identity layer.

---

Schema Migration 16

A new migration was added:

0016_entity_governance

It creates:

entity_merge_candidates
entity_resolution_log

The migration runner now applies both:

0015_memory_governance
0016_entity_governance

when upgrading older databases.

A schema 14 database now migrates to schema version 16, while preserving raw ledger evidence.

---

Public and Internal Exports

The entity governance module is now exported through the internal surface.

New exports include:

EntityGovernanceService
EntityMergeCandidate
EntityMergeCandidateStatus
ProposeEntityMergeInput

This allows internal consumers, tests, and future governance layers to create, inspect, apply, and revert entity merge candidates.

---

Tests Added

New regression tests cover:

Reversible project alias merge

A high-confidence project alias merge can be approved, applied, and reverted.

The test confirms:

source entity becomes archived after apply
alias resolves to target entity after apply
source entity becomes active again after revert
alias resolves back to source entity after revert

Person merge safety

A person merge without explicit user evidence remains pending even when confidence is very high.

This prevents assistant-only person identity guesses from becoming durable aliases.

Project boundary protection

Cross-project merge proposals are rejected with:

project_boundary_violation

Binding / EntityStore identity alignment

Memory Binding now writes the same entity ID owned by EntityStore into binding records.

This confirms that Memory Binding no longer owns canonical identity independently.

Migration coverage

Migration CLI tests now expect pending migrations:

0015
0016

and confirm that the final schema version becomes:

16

V2.8.0

Cogmem 2.8.0 — Memory Binding v1.5 and Governed Memory Foundation

Cogmem 2.8.0 introduces the next step toward a governed agent-memory brain: Memory Binding v1.5, activation-aware graph edges, transactional memory governance plans, and a formal schema migration path.

This release moves Cogmem beyond basic graph-recall stabilization. The memory system now has stronger primitives for stable topic routing, claim-key separation, correction-aware graph edges, read-only graph inspection, and CPU-validated semantic memory operations.

Highlights

• Added Memory Binding v1.5 primitives:

  • TopicPathRegistry
  • ClaimKeyGenerator
  • BindingDecisionEngine
  • improved deterministic BindingClassifier

• Added activation-aware weighted memory graph edges.

• Added bounded read-only graph traversal through BrainGraphView.

• Added evidence-backed MemoryGovernancePlan.

• Added strict CPU-side validation for memory governance operations.

• Added transactional governance execution and audit records.

• Added schema version 15 and a new cogmem migrate command.

• Updated cogmem update --yes to install from GitHub Releases and run schema migration with backup.

• Added regression tests for binding v1.5, governance validation, transaction rollback, migration, and CLI behavior.

---

Memory Binding v1.5

Stable topic path registry

Cogmem now includes a TopicPathRegistry for CPU-canonicalized topic paths.

The registry maps multilingual and variant topic labels into stable canonical paths. For example:

memory storage
memory write
memory pipeline
记忆写入
记忆存储
写入管线

are canonicalized under:

PROJECT/Cogmem/memory-write-pipeline

This reduces topic-path drift and prevents arbitrary model-generated paths from becoming durable organization structure.

Claim-key separation

Cogmem now includes a ClaimKeyGenerator.

This separates distinct claims under the same topic path. For example:

写入时不看历史
分类树会漂移
context pollution
source fidelity

can now become different claim keys instead of being over-fused into one broad cluster.

This is an important step toward preventing large topic clusters from becoming mixed, noisy, or semantically overloaded.

Binding decision engine

Cogmem now includes a BindingDecisionEngine.

It classifies new high-value raw user events as:

create_new_cluster
attach_to_existing
strengthen_existing
possible_conflict
corrects_prior_memory
refines_prior_memory
needs_review

This lets the binding layer distinguish new claims, repeated support, and correction signals instead of treating every new event as an isolated memory row.

Improved binding classifier

The deterministic binding classifier now uses the new registry and claim-key modules.

It recognizes project aliases such as:

Cogmem
memory kernel
记忆内核
agent brain
OpenClaw
Lobster
Hermes

It also strips volatile Cogmem context blocks before binding:

<COGMEM_RECALL_CONTEXT>
<COGMEM_TURN_BRIDGE>
<COGMEM_SESSION_STATE>

These blocks remain context scaffolding and must not become durable user memory.

---

Activation-Aware Memory Graph Edges

Memory graph edges now distinguish:

confidence
baseWeight
stability
activation
validFrom
validTo
version
sourceAuthority

This separates historical truth/provenance from current surfacing priority.

In practical terms:

confidence = how strongly the evidence supports the relation
stability = how durable the relation is
activation = how likely it should surface now

Maintenance decay can reduce activation without weakening provenance confidence or long-term stability.

This allows Cogmem to forget what is currently relevant without corrupting why a memory was originally accepted.

New edge semantics

The binding graph now supports correction and contradiction relationships:

CORRECTS
CONTRADICTS
REFINES
SUPERSEDES

Correction events can now point back to earlier same-topic evidence instead of simply creating a generic conflict cluster.

---

Read-Only Brain Graph View

Cogmem now includes a bounded read-only graph traversal surface:

BrainGraphView

It can inspect active graph neighbors up to a bounded hop limit and return:

rootId
nodeIds
edges
evidenceEventIds
truncated

This is intentionally read-only. It provides graph visibility for agents and debugging without allowing graph mutation through the inspection interface.

---

Memory Governance Plan Foundation

Cogmem 2.8.0 introduces a new MemoryGovernancePlan abstraction.

A governance plan contains evidence-backed semantic memory operations such as:

BIND_EVENT
RECLASSIFY_TOPIC
MERGE_CLUSTER
SPLIT_CLUSTER
LINK_ENTITY_ALIAS
MERGE_ENTITY
CREATE_BELIEF
REINFORCE_BELIEF
SUPERSEDE_BELIEF
REJECT_BELIEF
CREATE_TIME_ANCHOR
EXPIRE_TIME_ANCHOR
CREATE_PROSPECTIVE_MEMORY
RESOLVE_PROSPECTIVE_MEMORY

This is the foundation for future Belief Graph, Entity Brain, Temporal Memory, and Intent Cortex work.

Evidence and ownership requirements

Every governance operation must include:

operationId
operation type
projectId
evidenceEventIds
sourceRole
ownership
idempotencyKey
payload

The CPU validator rejects unsafe operations before persistence.

It rejects:

missing evidence
unknown raw evidence
cross-project evidence references
user-owned memory without explicit user-role evidence
invalid expected versions
duplicate operation ids
duplicate idempotency keys

This keeps user-owned durable memory from being created from assistant-only or tool-only evidence.

Transactional execution

MemoryGovernanceExecutor applies governance plans in a single SQLite transaction.

If any operation fails:

projection writes are rolled back
operation records are rolled back
audit records are rolled back

If the same plan or idempotency key is replayed, the executor avoids double-application.

Governance audit records

Applied governance operations are recorded in:

memory_governance_plans
memory_governance_operations
memory_governance_audit

This gives Cogmem a durable audit trail for future belief promotion, belief supersession, entity merging, temporal versioning, and prospective memory.

---

Schema Version 15 and Migration CLI

Cogmem now includes schema migration support.

A new migration was added:

0015_memory_governance

It creates governance tables and upgrades memory_edges with activation-aware edge columns.

New command

cogmem migrate

Supported options:

--db <memory.db>
--config <config.toml>
--dry-run
--yes
--backup
--json

By default, migration runs in dry-run mode unless --yes is provided.

Legacy adoption

The migration runner can adopt an existing _meta.schema_version and mark earlier migrations as already applied.

This allows existing 2.7.x databases to move forward without replaying obsolete migrations.

Backup support

When running:

cogmem migrate --yes --backup

Cogmem creates a timestamped backup of the database before applying schema changes.

Update command integration

cogmem update --yes now:

resolves the selected GitHub Release
installs the release asset
runs cogmem migrate --yes --backup using the newly installed package

Dry-run mode exposes the planned install and migration command without writing.

---

Memory Map and Maintenance Tick Updates

The memory self-map now exposes memory binding as an explicit data lane.

It includes:

memory bindings
topics
entities
clusters
edges

The maintenance tick now reports:

unboundRawEvents
bindingFailures

and may suggest:

cogmem memory bind --project <id> --json

when high-value raw user events have not yet been attached to memory binding clusters.

If non-fatal binding failures were recorded, the tick suggests inspection while preserving the raw ledger as authoritative.

---

Public API Updates

The public API now exports memory binding types, including:

MemoryBindingRecord
MemoryBindingStats
MemoryBindingType
MemoryBindingAction
MemoryClusterRecord
MemoryClusterStatus
MemoryEdgeRecord
MemoryEdgeRelation
MemoryEntityRecord
MemoryEntityType
MemoryGraphRecallAnchor
MemoryTopicRecord

This allows host integrations and agent runtimes to inspect the binding graph without depending on internal implementation modules.

---

Tests Added

New regression coverage includes:

Memory Binding v1.5

• multilingual topic alias canonicalization;
• unsafe topic path normalization;
• claim-key separation under the same topic;
• correction and reinforcement binding decisions;
• activation decay without confidence or stability decay;
• bounded read-only graph traversal with provenance.

Memory Governance

• rejection of durable operations without raw evidence;
• rejection of user-owned memory without explicit user evidence;
• idempotent execution;
• rollback of operation effects and audit records on failure.

Schema Migration

• dry-run planning without mutation;
• transactional migration application;
• idempotent repeated migration;
• schema version update from 14 to 15;
• migration backup creation.

CLI Update Flow

• update command now reports the migration command;
• update flow includes cogmem migrate --yes --backup.