Entity Taxonomy

Why Taxonomy at All

Without typed entities, the graph is an unordered blob: queries become full scans, and decay rates are uniform and therefore meaningless. A taxonomy is not bookkeeping — it conditions four concrete things: which Observation categories cortex-insight must produce, how memory scope is partitioned, which handlers the Retain Job registers, and which query subjects the memory API exposes.

The first intuition — an exterior world (people, orgs, projects) versus an interior world (root causes, patterns, agent preferences) — is a useful lens but collapses too many distinctions to serve as the final structure. The decision is to model entities on a 2D grid, memory-type × referent, so every node carries both a cognitive register and a positional context.

Biomimetic Foundations

The grid is not invented from nothing; each axis is grounded in established cognitive science.

Tulving — the empirically grounded episodic / semantic / procedural split maps directly onto the grid's three memory registers.
Husserl & Merleau-Ponty — noème (the object as intended) versus noèse (the act of intending): objects are never raw data, always objects-for-an-agent. This grounds the referent axis.
Theory of Mind — modelling others' mental states is non-trivial and needs a dedicated other class, distinct from self and agent.
Speech Act Theory (Austin, Searle) — communicating is acting; interaction memory is typed by illocutionary act, enabling queries like « predominantly directive with agent X, expressive with person Y ».
Internal Working Models (Bowlby) — representations of relationships motivate the agent:*:relationship:* namespace.
Hippocampal model — hippocampus encodes episodic short-term, cortex consolidates semantic long-term, the nightly sleep cycle is the consolidation pass. Architecturally: cortex-insight encodes, cortex-memory consolidates.

The 2D Classification Grid

Two axes. Memory type (Tulving): episodic — timestamped events, what happened; semantic — facts true about the world; procedural — how to do things. Referent: self (the operator), agent (AI agents), other (people, orgs), object (projects, artefacts, places), abstract (concepts, values, principles).

The interior/exterior intuition survives as a reading of the referent axis: self + agent is interior, other + object is exterior, abstract is transversal. Each cell carries its own default half_life_days and emotional_multiplier, which is what makes decay semantically meaningful rather than arbitrary. The type and subtype columns become path-style namespaces (world:person:anya, agent:claude-code:rc:RC-2) rather than a flat enum.

Memory-type × referent. Populated cells show real namespaced slugs; each cell sets its own decay defaults, so a fleeting interaction and a pinned instruction are never treated alike.

The Entity Node

An Entity is a durable graph node — a namespace:slug with a type, a subtype, strength fields, and a reference to its compiled truth. Strength follows the hippocampal-memory model.

strength(t)          = base_strength
                       × (0.5 ^ (Δt / effective_half_life))
                       × retrieval_boost
                       × emotional_multiplier

reward_factor        = 1 + 0.5 × ((pos − neg) / (pos + neg + 1))
effective_half_life  = half_life_days × reward_factor
retrieval_boost      = 1 + 0.1 × log₂(retrieval_count + 1)
emotional_multiplier : neutral 1.0 · positive 1.3 · negative 1.5 · critical 2.0

A pinned = TRUE entity has infinite strength, exempt from decay — permanent instructions, core facts. The taxonomy shapes the defaults: world:* takes a long half-life; agent:*:rc:* takes a short one because patterns change; agent:*:instruction:* is long or pinned.

Strength is continuous. Retrieval lifts a decaying entity (the testing effect); pinned entities sit flat at the top; the per-cell modifiers decide how fast the rest fade.

Decay and Schema Fit

Decay applies a temporal weight weight_temporal = exp(−Δt/σ) to every relation during the nightly consolidation pass. σ is configured per relation type in the [graph] config — domain-specific relevance windows, never hardcoded.

Schema fit (schema_fit, 0..1) measures how well an incoming Observation matches patterns already in the graph, and it gates the Retain Job:

< 0.3 — dark matter: novel, unclassified signal; half-life ×0.5, held provisionally and queued for review before strengthening.
> 0.7 — fast-track: high-confidence consolidation; half-life ×1.5, skips the expensive dedup pass.
0.3 … 0.7 — the normal path, with conflict detection.

The two interact through reward_factor: a world:person seen rarely with low schema fit fades fast; a recurring agent:claude-code:rc with positive outcomes earns a longer effective half-life and persists.

Observation to Compiled Truth: the Retain Job

The Observation is the publish contract from cortex-insight to cortex-memory — a typed, encoded fact, not yet resolved against the graph (id, source, timestamp, category, actors, topic, sentiment, payload_typed, correlation). Insight knows how to parse sources but not graph state; memory knows how to consolidate but not source semantics. The Observation is the clean boundary between them.

For each Observation, the Retain Job (in cortex-memory) resolves actors to entities, deduplicates, computes schema_fit, detects conflicts, writes entities and relations, updates strength and decay, and triggers a Compiled Truth regeneration when impact crosses the threshold. A Compiled Truth is the per-entity markdown — durable, versioned through a superseded_by chain — whereas an Observation is transient. Handlers are indexed by (category, target_namespace): the taxonomy directly decides which consolidation logic fires for which entity class.

Encode in the lake, consolidate in the warehouse. The Observation is the typed boundary; the Retain Job's six steps turn it into graph state, with schema_fit routing the novel and the familiar differently.

Actuation: Closing the Loop

Actuation is how memory surfaces patterns back into behaviour: detect a recurring pattern in the graph, generate a proposed diff (a CLAUDE.md edit, a new skill, a memory entry, a settings allowlist), push it to the approval queue, and on approval open an auto-PR. The queue — typed by diff_type: claude_md | memory_entry | skill | allowlist — decouples detection from application, so the operator reviews before any mutation lands.

Interaction typing feeds this directly: if a thread analysis finds a persistent directive-plus-expressive pattern with a given contact, it can propose a memory entry or a CLAUDE.md annotation surfacing that style. Because Retain Job handlers are indexed by (category, target_namespace), the taxonomy is not descriptive — it is the dispatch table that decides which logic runs and which behaviour the system is allowed to propose.