> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argentos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Consciousness Memory (Observation Layer)

> Experimental synthesis layer bridging raw memory substrates and the Consciousness Kernel through durable knowledge observations.

<Warning>
  **Status: EXPERIMENTAL** — Architecture designed, implementation in progress. This page describes the planned system.
</Warning>

## Overview

The Consciousness Memory layer is the bridge between ArgentOS's raw memory substrates and the [Consciousness Kernel](/agents/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:

| Substrate           | Purpose                          | Location                  |
| ------------------- | -------------------------------- | ------------------------- |
| **Memory Items**    | Raw durable facts                | `memory_items` table      |
| **Reflections**     | Interpreted periodic summaries   | `reflections` table       |
| **Lessons**         | Actionable compressions from SIS | `lessons` table           |
| **Entity Profiles** | Entity-level synthesized text    | `entities.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.

```mermaid theme={null}
flowchart LR
  MI["Memory Items"] --> OC["Observation Consolidator"]
  EN["Entities"] --> OC
  RE["Reflections"] --> OC
  LE["Lessons"] --> OC
  OC --> KO["Knowledge Observations"]
  KO --> EL["Evidence Links"]
  KO --> CA["Context Assembly"]
  CA --> CK["Consciousness Kernel"]
```

## 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:

| Kind                  | Description                               | Example                                                    |
| --------------------- | ----------------------------------------- | ---------------------------------------------------------- |
| `operator_preference` | User preferences and working style        | "User prefers free/open-source when quality is comparable" |
| `project_state`       | Current state of a project                | "holace is in active development on Next.js 14"            |
| `world_fact`          | External factual knowledge                | "Claude Opus 4 was released May 2025"                      |
| `self_model`          | Agent's understanding of its own behavior | "Memory recall skews toward knowledge type"                |
| `relationship_fact`   | Interpersonal or entity relationships     | "Richard is Jason's business partner"                      |
| `tooling_state`       | State of tools and infrastructure         | "Telegram bot uses webhook mode on port 443"               |

### Subject Types

Each observation is scoped to a subject:

| Subject Type | Description                             |
| ------------ | --------------------------------------- |
| `entity`     | A person, organization, or named entity |
| `project`    | A project or product                    |
| `tool`       | A tool, service, or integration         |
| `agent`      | The agent itself or another agent       |
| `global`     | System-wide or world-level facts        |

### Observation Status

| Status        | Description                              |
| ------------- | ---------------------------------------- |
| `active`      | Current believed truth                   |
| `stale`       | Evidence is aging, revalidation needed   |
| `superseded`  | Replaced by a newer observation          |
| `invalidated` | Contradicting 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:

| Stance       | Description                                               |
| ------------ | --------------------------------------------------------- |
| `support`    | Evidence that supports the observation's claim            |
| `contradict` | Evidence that contradicts the observation's claim         |
| `context`    | Contextual 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

<Steps>
  <Step title="Source Gathering">
    Memory items, entities, reflections, and lessons feed into the consolidator. Sources are grouped by topic using canonical key matching.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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:

    ```sql theme={null}
    UNIQUE (agent_id, canonical_key) WHERE status = 'active'
    ```
  </Step>

  <Step title="Confidence Scoring">
    Each observation receives an anatomical confidence score (not a vibe score) composed of:

    | Component                | Description                                      |
    | ------------------------ | ------------------------------------------------ |
    | `sourceCount`            | Number of evidence sources (diminishing returns) |
    | `sourceDiversity`        | Variety of source types                          |
    | `supportWeight`          | Total weight of supporting evidence              |
    | `contradictionWeight`    | Total weight of contradicting evidence           |
    | `recencyWeight`          | How recent the evidence is                       |
    | `operatorConfirmedBoost` | Boost from operator confirmation                 |

    The composite score is clamped to `[0, 1]` and stored alongside its components for full explainability.
  </Step>
</Steps>

## 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:

| Kind                  | Default Cadence | Rationale                                  |
| --------------------- | --------------- | ------------------------------------------ |
| `operator_preference` | 30 days         | Preferences change slowly                  |
| `project_state`       | 7 days          | Projects evolve regularly                  |
| `world_fact`          | 90 days         | External facts are relatively stable       |
| `self_model`          | 14 days         | Self-understanding evolves with experience |
| `relationship_fact`   | 60 days         | Relationships are relatively stable        |
| `tooling_state`       | 3 days          | Tool 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.

<Warning>
  **Hard invariant**: Observations never cite other observations as evidence. The only permitted observation-to-observation relationship is supersession.
</Warning>

## Context Assembly Integration

The retrieval router includes observations in the ranked merge alongside other retrieval sources:

```mermaid theme={null}
flowchart TD
  KO["Knowledge Observations\n(high-confidence, active)"] --> CA["Context Assembly"]
  MI["Raw Memory Items\n(keyword + vector search)"] --> CA
  SIS["SIS Lessons\n(actionable patterns)"] --> CA
  RAG["Knowledge Library\n(RAG collections)"] --> CA
  EP["Entity Profiles\n(relationship context)"] --> CA
  CA --> RP["Ranked context window\nfor agent prompt"]
```

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`:

<Tabs>
  <Tab title="knowledge_observations">
    | Column                      | Type          | Description                         |
    | --------------------------- | ------------- | ----------------------------------- |
    | `id`                        | `text PK`     | Unique observation ID               |
    | `agent_id`                  | `text FK`     | Owning agent                        |
    | `kind`                      | `text`        | Observation kind                    |
    | `subject_type`              | `text`        | Subject type                        |
    | `subject_id`                | `text`        | Subject identifier                  |
    | `canonical_key`             | `text`        | Deterministic key                   |
    | `summary`                   | `text`        | Synthesized claim                   |
    | `confidence`                | `real`        | Composite confidence score          |
    | `confidence_components`     | `jsonb`       | Anatomical score breakdown          |
    | `freshness`                 | `real`        | Recency score                       |
    | `revalidation_due_at`       | `timestamptz` | Next revalidation                   |
    | `status`                    | `text`        | active/stale/superseded/invalidated |
    | `supersedes_observation_id` | `text FK`     | Previous version                    |
    | `embedding`                 | `vector(768)` | For semantic search                 |
  </Tab>

  <Tab title="knowledge_observation_evidence">
    | Column           | Type      | Description                |
    | ---------------- | --------- | -------------------------- |
    | `id`             | `text PK` | Unique evidence link ID    |
    | `observation_id` | `text FK` | Parent observation         |
    | `stance`         | `text`    | support/contradict/context |
    | `weight`         | `real`    | Evidence strength          |
    | `item_id`        | `text FK` | Reference to memory\_items |
    | `lesson_id`      | `text FK` | Reference to lessons       |
    | `reflection_id`  | `text FK` | Reference to reflections   |
    | `entity_id`      | `text FK` | Reference to entities      |
  </Tab>
</Tabs>

### 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

<Warning>
  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
</Warning>

## Key Files

| File                                                        | Description                                             |
| ----------------------------------------------------------- | ------------------------------------------------------- |
| `docs/argent/KNOWLEDGE_OBSERVATIONS_IMPLEMENTATION_SPEC.md` | Full implementation spec                                |
| `docs/argent/CONSCIOUSNESS_KERNEL_THESIS.md`                | Consciousness Kernel thesis                             |
| `src/data/pg/schema.ts`                                     | PostgreSQL schema (tables to be added)                  |
| `src/data/adapter.ts`                                       | StorageAdapter interface (MemoryAdapter to be extended) |
| `src/data/pg-adapter.ts`                                    | PG adapter (primary implementation target)              |
| `src/memory/memu-types.ts`                                  | Memory types (new observation types to be added)        |
| `src/agents/system-prompt.ts`                               | Prompt injection path                                   |
| `src/infra/sis-runner.ts`                                   | SIS consolidation (lesson synthesis path)               |