Skip to content

2.9.0

Choose a tag to compare

View all tags
@liuqin164 liuqin164 released this 19 Jun 13:45
· 16 commits to main since this release
2.9.0
20855f8
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

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
Assets 2
Loading