Skip to content

Governed Memory Architecture

AncientOS memory exists to preserve personal AI continuity without making a model, provider, transport, database, transcript, or retrieval result the source of identity.

LifeVault is the AncientOS kernel service and logical memory continuity layer. It defines what durable memory means, how memory is reviewed, how it is promoted, how it is superseded, and how it remains portable across storage backends. Storage backends such as pgvector/Postgres, SQLite, files, artifact directories, append-only audits, and future databases are implementation surfaces behind LifeVault. They may store, index, rank, or replay memory evidence, but they do not define memory truth by themselves.

The Governance Kernel defines where optional LifeVault Retention appears in the Objective to Loop lifecycle. Lifecycle traces, Oracle reports, Zeus evidence, approvals, schedules, and dispatch records remain evidence unless LifeVault promotes them under policy.

AncientOS memory is artifact-first. Durable memory state lives in canonical reviewable artifacts; retrieval systems only index and rank those artifacts. Applications and transports use these kernel memory capabilities through governed context assembly. Discord history, raw chat logs, Oracle reports, Rubick ontology records, Meepo transition packets, Keeper task state, and provider outputs may supply evidence or context, but they are not automatically LifeVault memory.

No storage migration is implied by this doctrine.

Continuity Doctrine

Memory continuity means the operator's long-term AI relationship can retain durable facts, context, provenance, and trust boundaries across:

  • model and provider changes
  • transport changes
  • runtime prompt/profile changes
  • storage backend changes
  • hardware and runtime location changes
  • continuity-safe upgrades and migrations

Frontier models are infrastructure, not identity. Storage backends are infrastructure, not memory identity. LifeVault is the logical continuity layer that keeps memory portable, reviewable, and governed while infrastructure changes.

Memory must remain:

  • artifact-backed
  • provenance-preserving
  • review-gated before promotion
  • bounded at retrieval time
  • replayable where used for context
  • explicit when injected into prompts
  • fail-closed on missing authority, missing evidence, or ambiguous scope
  • separated from posture governance, transition integrity, and Oracle explanation surfaces

Layers

  • L0 Evidence Inputs: source documents, operator statements, runtime reports, Discord messages, Oracle evidence, Rubick posture records, Meepo transition packets, audits, provider results, and imported datasets. Evidence inputs are not memory until normalized and governed.
  • L1 Session Memory: bounded turn/session context, isolated per channel, thread, user, or request scope. Session context is not durable LifeVault memory unless explicitly promoted through review.
  • L2 Working Memory: active project, task, and operational facts stored as working_memory_entry artifacts.
  • L3 Semantic Retrieval Memory: local retrieval index records stored as semantic_memory_entry artifacts, with optional local pgvector indexing.
  • L4 Archive Layer: cold storage and retention lifecycle artifacts. Archive transitions preserve source artifacts by default.
  • L5 Supersession Layer: records that a promoted memory has been superseded, deprecated, corrected, merged, or split without deleting historical evidence.

Memory Authority Hierarchy

When memory surfaces disagree, use this hierarchy:

Rank Authority surface Authority rule
1 Approved operator correction or explicit operator-authored memory decision Highest memory authority when captured as a governed artifact or review decision.
2 Promoted LifeVault memory artifact Canonical durable memory for retrieval and context assembly.
3 LifeVault review, promotion, supersession, archive, and retention artifacts Canonical lifecycle evidence for why a memory is active, rejected, archived, superseded, or deprecated.
4 Canonical project/docs artifacts referenced by memory provenance Authoritative for their own documented subject; require review before becoming durable memory.
5 Oracle evidence and operational reports Read-only explanatory evidence; not memory authority unless promoted into LifeVault.
6 Rubick ontology/settings records Posture and ontology authority; not memory authority unless referenced as provenance for a LifeVault memory record.
7 Meepo transition packets and audits Transition integrity evidence; not memory authority except for proving whether a memory-affecting transition remained valid.
8 Retrieval candidates, search rankings, embeddings, pgvector/Postgres rows, SQLite rows, files, caches, and indexes Retrieval/storage evidence only. They rank, store, or replay artifacts; they do not define durable memory truth.
9 Discord history, raw conversation logs, model outputs, provider transcripts, and unreviewed imports Context inputs only. They must not become durable memory without normalization and review.

If authority cannot be determined, memory use fails closed or asks for review.

Source-Of-Truth Rules

  • LifeVault is the logical source of truth for memory continuity.
  • Promoted LifeVault artifacts are the source of truth for durable memory.
  • Lifecycle artifacts are the source of truth for status: unpromoted, promoted, rejected, archived, superseded, deprecated, corrected, merged, or split.
  • Storage backends are never source of truth by themselves. pgvector/Postgres, SQLite, files, indexes, and caches must be rebuildable from canonical artifacts.
  • Discord history is not memory truth. It may be evidence for a future memory proposal.
  • Oracle explains memory evidence and operational state but does not create, promote, deprecate, or repair memory.
  • Rubick governs posture and ontology visibility but does not promote memory.
  • Meepo revalidates transition integrity for memory-affecting state changes but does not decide memory truth.
  • Retrieval results are not truth. They are bounded candidate selections with evidence references.
  • Direct prompt injection from retrieval is forbidden. Callers must explicitly include assembled context and preserve trace evidence.

Canonical Schemas

The deterministic CLI materializes schema files under the configured memory root at schemas/*.schema.json.

  • working_memory_entry
  • semantic_memory_entry
  • retrieval_candidate
  • memory_review
  • memory_promotion
  • archive_manifest
  • retention_policy
  • prune_recommendation
  • storage_health_report
  • retrieval_session
  • context_assembly_report
  • time_context_report
  • freshness_report
  • staleness_assessment
  • maintenance_window
  • schedule_window
  • operational_clock_snapshot
  • ingestion_job
  • ingestion_source
  • normalized_document
  • chunk_manifest
  • embedding_index_record
  • ingestion_review
  • ingestion_promotion
  • ingestion_rejection
  • ingestion_health_report
  • ingestion_checkpoint
  • retrieval_context_window
  • context_candidate
  • context_priority_report
  • context_budget_report
  • retrieval_trace
  • context_relevance_score
  • operational_state_report
  • container_health_snapshot
  • repo_status_report
  • update_status_report
  • operational_drift_report
  • reboot_requirement_report
  • relationship_edge
  • entity_snapshot
  • project_context_map
  • operational_dependency_map

Governed Flow

  1. ingest-memory creates a working_memory_entry.
  2. The local embedding/index step creates a semantic_memory_entry.
  3. search-memory creates bounded retrieval_candidate artifacts and a retrieval_session.
  4. review-memory records a human or governed review decision.
  5. promote-memory only promotes candidates with approving memory_review artifacts.
  6. assemble-context includes promoted memory only and writes a context_assembly_report.

Retrieval cannot directly mutate prompts, runtime behavior, tools, or long-term state. Callers must explicitly include assembled context.

Retrieval Classes

AncientOS distinguishes retrieval classes so request-scoped context does not become durable memory by accident:

Retrieval class Purpose Authority
Session retrieval Recover bounded current-interaction context. Request/session scoped only; not durable memory.
Working retrieval Surface active project, task, and operational facts. Requires working_memory_entry provenance; promotion status controls context eligibility.
Semantic retrieval Rank promoted memories by meaning, freshness, trust, governance, and project relevance. Rankings are advisory; promoted artifacts remain authority.
Operational retrieval Assemble bounded operational context such as repo health, dependency maps, or status reports. Read-only evidence; does not repair or mutate state.
Evidence retrieval Retrieve source artifacts, audits, Oracle reports, Rubick records, or Meepo packets as evidence. Evidence only unless promoted through LifeVault.
Archive retrieval Recover cold or historical memory with archive penalties. Preserves provenance; does not reactivate memory without review.
Relationship retrieval Traverse entity and dependency relationship artifacts. Relationship artifacts are local evidence; derived maps are not hidden authority.

Unknown retrieval class, ambiguous scope, stale authority, or missing evidence must fail closed.

Promotion Rules

Memory promotion is the transition from evidence or working memory into durable retrievable continuity. Promotion requires:

  • a candidate artifact with provenance
  • a review artifact with an explicit promote decision
  • a promoter identity or governed promotion actor
  • scope and sensitivity classification
  • status update on the promoted memory artifact
  • audit/provenance linking candidate, review, and promotion

Promotion must not:

  • occur directly from retrieval ranking
  • occur directly from Discord history or raw transcripts
  • occur from model output alone
  • bypass review because a source appears in pgvector/Postgres, SQLite, files, or an index
  • silently rewrite old memory
  • mutate runtime prompts automatically

Memory-affecting promotions that depend on prior approval should use Meepo transition revalidation before durable status changes. Meepo verifies that transition assumptions still match; it does not decide memory truth.

Supersession And Deprecation Rules

Memory should be corrected through explicit lifecycle records, not silent rewrites.

Lifecycle action Meaning Rule
Supersede A newer memory replaces an older memory for active use. Preserve the older artifact and link superseded_by / supersedes evidence.
Deprecate A memory is no longer recommended for active use but remains historically meaningful. Keep retrieval-visible only where historical context is requested.
Correct A memory contained a wrong or outdated claim. Create a corrected memory and link the correction reason.
Merge Multiple memories are consolidated into one active memory. Preserve source memories and link them as merged inputs.
Split One broad memory is divided into narrower records. Preserve the source artifact and link split outputs.
Archive A memory moves to cold or archive tier. Preserve source artifacts and apply archive ranking penalties.
Reject A candidate is not durable memory. Preserve rejection reason; do not include in context assembly.

Deprecation and supersession affect retrieval ranking and context eligibility. They must not delete evidence by default.

Fragmentation Risks

Memory fragmentation happens when continuity facts scatter across surfaces that do not share a lifecycle. AncientOS tracks these risks explicitly:

  • LifeVault vs pgvector/Postgres disagreement
  • LifeVault vs SQLite or file artifact disagreement
  • promoted memory contradicted by unpromoted Discord history
  • raw imports treated as memory without review
  • Oracle reports mistaken for memory source of truth
  • Rubick posture/ontology records mistaken for memory facts
  • Meepo transition audits mistaken for memory decisions
  • duplicate memories without supersession links
  • stale memories not deprecated or archived
  • provider/model outputs retained without provenance
  • transport-specific context treated as global continuity
  • retrieval indexes rebuilt from incomplete artifacts
  • memory summaries that omit source artifact ids

Fragmentation mitigation:

  • prefer canonical artifact ids over copied prose
  • keep provenance links on every promoted memory
  • use supersession instead of overwriting
  • use archive-first retention instead of delete-first retention
  • treat indexes as rebuildable
  • expose uncertainty when memory authority is unclear
  • route corrections through review and promotion

Ranking

Retrieval ranking combines:

  • semantic similarity
  • recency weighting
  • freshness scoring
  • trust weighting
  • governance weighting
  • archive tier penalties
  • active project weighting
  • roadmap relevance
  • operational state relevance

Archive penalties reduce ranking for cold or archived material without deleting it.

Knowledge Ingestion Lifecycle

Governed ingestion produces reviewable artifacts before content becomes eligible for governed retrieval:

flowchart LR Source[ingestion_source] --> Document[normalized_document] Document --> Manifest[chunk_manifest] Manifest --> Index[embedding_index_record] Index --> Job[ingestion_job] Job --> Review[ingestion_review] Review --> Promotion[ingestion_promotion] Review --> Rejection[ingestion_rejection]

The pipeline supports Markdown, text, JSON, CSV, PDF text extraction, Notion-style exports, Airtable-style exports, CRM exports, roadmap documents, and local documentation trees. Ingestion never mutates prompts or runtime behavior directly.

Operational Context Assembly

assemble-operational-context writes a replayable context assembly chain:

flowchart TD Query[query] --> Candidate[context_candidate] Candidate --> Score[context_relevance_score] Score --> Priority[context_priority_report] Priority --> Budget[context_budget_report] Budget --> Trace[retrieval_trace] Trace --> Window[retrieval_context_window]

Only promoted governed memory can enter the final context window. The caller must explicitly include the returned context; retrieval itself cannot mutate prompts.

CLI

Run with:

python -m luna_core.memory_cli --help

python -m app.memory_cli remains as a thin compatibility wrapper.

Commands:

  • ingest-memory
  • search-memory
  • assemble-context
  • archive-memory
  • review-memory
  • promote-memory
  • memory-health
  • memory-retention-report
  • time-status
  • freshness-check
  • maintenance-report
  • clock-snapshot
  • ingest-path
  • ingest-document
  • ingest-report
  • classify-document
  • chunk-document
  • ingestion-health
  • assemble-operational-context
  • retrieval-trace
  • explain-context-selection
  • context-health
  • operational-status
  • container-health
  • repo-health
  • reboot-status
  • drift-report
  • explain-relationships
  • dependency-map
  • project-context
  • memory-pressure
  • stale-context-report
  • orphaned-artifacts
  • retrieval-drift

Retention And Archive Lifecycle

Memory tiers are Hot, Warm, Cold, and Archive. The default policy is archive-first, not delete-first.

Governance artifacts are preserved by default:

  • reviews
  • promotions
  • archive manifests
  • retention policies
  • health reports
  • provenance records

memory-retention-report emits recommendations only. It does not delete artifacts.

pgvector Integration

pgvector support is optional, local-only, and additive. Set LUNA_MEMORY_PGVECTOR_ENABLED=1 to require local pgvector availability.

When pgvector is enabled, Luna syncs the local artifact-derived semantic index into a local luna_semantic_memory_index table and queries it for nearest-neighbor ordering. When pgvector is enabled but unavailable, retrieval fails closed and returns no candidates. When disabled, Luna uses the deterministic local artifact index.

No cloud embedding APIs or hosted vector databases are used.

Local pgvector table shape:

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE IF NOT EXISTS luna_semantic_memory_index (
  semantic_memory_id text PRIMARY KEY,
  working_memory_id text NOT NULL,
  embedding vector(64) NOT NULL,
  content_hash text NOT NULL,
  governance_score double precision NOT NULL,
  trust_score double precision NOT NULL,
  tier text NOT NULL,
  created_at timestamptz NOT NULL
);

The table is an index, not authority. Rebuilds must derive from artifact files.

Future Ingestion

Future sources should follow this path:

External source -> local snapshot -> canonical artifact -> retrieval index -> retrieval candidate -> memory review -> promotion or rejection.

Supported future source categories:

  • Notion exports
  • local files
  • PDFs
  • Airtable exports
  • CRM exports
  • personal knowledge archives

Each importer should preserve source provenance, avoid direct prompt mutation, and emit reviewable artifacts before promotion.