Skip to main content
Status: EXPERIMENTAL — Architecture designed, implementation in progress. This page describes the planned system.

​
Overview

The Consciousness Memory layer is the bridge between ArgentOS’s raw memory substrates and the Consciousness Kernel. It introduces Knowledge Observations — durable synthesized claims derived from consolidating memory items, entities, reflections, and lessons into a governed truth layer. Today, ArgentOS has four adjacent but distinct memory substrates:
SubstratePurposeLocation
Memory ItemsRaw durable factsmemory_items table
ReflectionsInterpreted periodic summariesreflections table
LessonsActionable compressions from SISlessons table
Entity ProfilesEntity-level synthesized textentities.profileSummary
What is missing is a first-class layer for “current believed truth” with explicit evidence links, contradiction tracking, revision chains, freshness semantics, and deterministic retrieval precedence. Without this, retrieval repeatedly infers truth from raw facts at answer time — expensive, noisy, and hard to audit.

​
Knowledge Observations

A Knowledge Observation is a durable synthesized claim that represents what the agent currently believes to be true. Unlike raw memory items (which capture moments), observations represent consolidated understanding. Example observations:
  • “User prefers PostgreSQL over MongoDB for ACID compliance”
  • “Project callscrub.io is in active development, targeting Q2 launch”
  • “The Telegram channel processes approximately 40 messages per day”
  • “User responds best to concise technical summaries, not verbose explanations”

​
Observation Kinds

Observations are strictly typed by kind, each with distinct retrieval ranking, freshness rules, and revalidation cadences:
KindDescriptionExample
operator_preferenceUser preferences and working style”User prefers free/open-source when quality is comparable”
project_stateCurrent state of a project”holace is in active development on Next.js 14”
world_factExternal factual knowledge”Claude Opus 4 was released May 2025”
self_modelAgent’s understanding of its own behavior”Memory recall skews toward knowledge type”
relationship_factInterpersonal or entity relationships”Richard is Jason’s business partner”
tooling_stateState of tools and infrastructure”Telegram bot uses webhook mode on port 443”

​
Subject Types

Each observation is scoped to a subject:
Subject TypeDescription
entityA person, organization, or named entity
projectA project or product
toolA tool, service, or integration
agentThe agent itself or another agent
globalSystem-wide or world-level facts

​
Observation Status

StatusDescription
activeCurrent believed truth
staleEvidence is aging, revalidation needed
supersededReplaced by a newer observation
invalidatedContradicting evidence outweighs support

​
Observation Evidence

Every observation maintains explicit links to its source evidence. Evidence links connect observations back to the raw substrates they were derived from.

​
Evidence Sources

An evidence link can reference:
  • A memory_item (raw fact)
  • A lesson (SIS-derived actionable compression)
  • A reflection (periodic summary)
  • An entity (entity context)

​
Evidence Stance

Each evidence link carries a stance:
StanceDescription
supportEvidence that supports the observation’s claim
contradictEvidence that contradicts the observation’s claim
contextContextual evidence that neither supports nor contradicts

​
Evidence Weight

Each link carries a weight (default 1.0) indicating the relative strength of that piece of evidence. Operator-confirmed evidence receives a boost.

​
The Consolidation Process

1

Source Gathering

Memory items, entities, reflections, and lessons feed into the consolidator. Sources are grouped by topic using canonical key matching.
2

Claim Synthesis

The consolidator generates synthesized claims from grouped evidence. For example, three memory items about “user prefers PostgreSQL” become a single observation with all three linked as supporting evidence.
3

Evidence Linking

Each observation is connected to its source evidence with stance annotations. A single observation might have 5 supporting links, 1 contradicting link, and 2 context links.
4

Canonical Key Assignment

Observations receive deterministic canonical keys generated by code (not LLM output):
entity:<entityId>:operator_preference:<slot>
project:<projectSlug>:project_state:<slot>
tool:<toolName>:tooling_state:<slot>
agent:self:self_model:<slot>
global:world_fact:<slot>
A partial unique index ensures only one active observation per canonical key per agent:
UNIQUE (agent_id, canonical_key) WHERE status = 'active'
5

Confidence Scoring

Each observation receives an anatomical confidence score (not a vibe score) composed of:
ComponentDescription
sourceCountNumber of evidence sources (diminishing returns)
sourceDiversityVariety of source types
supportWeightTotal weight of supporting evidence
contradictionWeightTotal weight of contradicting evidence
recencyWeightHow recent the evidence is
operatorConfirmedBoostBoost from operator confirmation
The composite score is clamped to [0, 1] and stored alongside its components for full explainability.

​
Freshness and Supersession

​
Freshness vs Confidence

Freshness and confidence answer different questions:
  • Confidence: “How well supported is this belief?”
  • Freshness: “How current is this belief?”
An observation can be highly confident but stale (well-supported months ago, no recent evidence) or fresh but low-confidence (recently observed but only once).

​
Revalidation Jobs

Periodic freshness jobs check whether observations are still valid:
  1. Scan observations where revalidationDueAt has passed
  2. Check for new supporting or contradicting evidence since lastSupportedAt
  3. Update freshness score based on evidence recency
  4. Mark observations as stale if freshness drops below threshold
  5. Mark as invalidated if contradicting evidence outweighs support

​
Revalidation Cadence by Kind

Different observation kinds have different default revalidation intervals:
KindDefault CadenceRationale
operator_preference30 daysPreferences change slowly
project_state7 daysProjects evolve regularly
world_fact90 daysExternal facts are relatively stable
self_model14 daysSelf-understanding evolves with experience
relationship_fact60 daysRelationships are relatively stable
tooling_state3 daysTool configurations change frequently

​
Supersession

When new evidence materially changes a belief, the consolidator creates a new observation and links it to the old one via supersedes_observation_id. The old observation is marked superseded but preserved for historical context.
Hard invariant: Observations never cite other observations as evidence. The only permitted observation-to-observation relationship is supersession.

​
Context Assembly Integration

The retrieval router includes observations in the ranked merge alongside other retrieval sources: Active observations with high confidence are injected as high-priority context, reducing the need for the agent to re-derive truth from raw facts at query time.

​
Runtime Use

Observations are injected into agent prompts through the existing system prompt injection path (src/agents/system-prompt.ts). The injection includes:
  • The observation summary
  • Confidence level indicator
  • Last supported timestamp
  • Evidence count
This gives the agent immediate access to consolidated knowledge without needing to perform retrieval and synthesis on every turn.

​
Feedback Loop

User feedback and reinforcement flow back to update observation confidence:
  1. Operator confirmation: Thumbs up or explicit confirmation boosts observation confidence via operatorConfirmedBoost
  2. Contradiction: User corrections create contradicting evidence, potentially triggering supersession
  3. Reinforcement: Repeated user behavior that aligns with an observation increases its support weight
  4. Memory recall success: When an observation-derived answer satisfies the user, the observation is reinforced

​
Proposed Schema

​
PostgreSQL Tables

Two new tables in src/data/pg/schema.ts:
ColumnTypeDescription
idtext PKUnique observation ID
agent_idtext FKOwning agent
kindtextObservation kind
subject_typetextSubject type
subject_idtextSubject identifier
canonical_keytextDeterministic key
summarytextSynthesized claim
confidencerealComposite confidence score
confidence_componentsjsonbAnatomical score breakdown
freshnessrealRecency score
revalidation_due_attimestamptzNext revalidation
statustextactive/stale/superseded/invalidated
supersedes_observation_idtext FKPrevious version
embeddingvector(768)For semantic search

​
Indexes

  • (agent_id, kind, status) — Kind-filtered queries
  • (agent_id, canonical_key) — Canonical key lookups
  • (agent_id, revalidation_due_at) — Revalidation job scans
  • (agent_id, confidence DESC, freshness DESC) — Ranked retrieval
  • HNSW on embedding — Semantic search
  • GIN FTS on summary || detail || tags — Full-text search
  • Partial unique: UNIQUE (agent_id, canonical_key) WHERE status = 'active'

​
Hard Invariants

These rules are non-negotiable:
  1. Observations may only derive from memory_items, lessons, reflections, and entity context
  2. Observations may not cite other observations as evidence
  3. The only observation-to-observation link is supersedes_observation_id
  4. Material truth changes create a new row — never rewrite prior truth in place
  5. Contradiction evidence must be preserved
  6. Raw evidence must always remain reachable through observation links
  7. Canonical key generation must be deterministic and code-driven

​
Key Files

FileDescription
docs/argent/KNOWLEDGE_OBSERVATIONS_IMPLEMENTATION_SPEC.mdFull implementation spec
docs/argent/CONSCIOUSNESS_KERNEL_THESIS.mdConsciousness Kernel thesis
src/data/pg/schema.tsPostgreSQL schema (tables to be added)
src/data/adapter.tsStorageAdapter interface (MemoryAdapter to be extended)
src/data/pg-adapter.tsPG adapter (primary implementation target)
src/memory/memu-types.tsMemory types (new observation types to be added)
src/agents/system-prompt.tsPrompt injection path
src/infra/sis-runner.tsSIS consolidation (lesson synthesis path)