Governed Memory Architecture

Luna memory is artifact-first. Durable memory state lives in canonical JSON artifacts; retrieval systems only index and rank those artifacts.

Layers

• L1 Session Memory: bounded Discord turn history, isolated per channel or thread.
• 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.

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.

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:

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:

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.

Governed artifact materialization (architecture, 1ce1e022b2de)

Capability

• Governed artifact materialization produces reviewed documentation updates for artifact, materialization, lineage, lich, confirmation, approval.
• Materialized content is generated from deterministic templates, not copied from the operator prompt.

Governance Model

• The architecture artifact remains bounded to approved documentation roots.
• Governance metadata records target selection, content digest, and materialization lineage.
• Replay metadata preserves the selected target, content hash, and intent classification.

Execution Flow

• LegionCommander classifies the objective into artifact intents.
• The materializer selects a bounded documentation target for each intent.
• confirmation_runner queues artifact_execute only after Lich approval.
• artifact_patch_safe writes the approved bundle and records worker result metadata.

Safety Boundaries

• Runtime code execution policy is not broadened by artifact materialization.
• Source, test, script, generated API, secret, absolute, and traversal paths remain denied.
• The architecture boundary separates intent decomposition, artifact synthesis, Lich approval, and worker execution.

Current Limitations

• Generated prose is intentionally template-bounded and does not infer unobserved implementation details.
• Ambiguous equal-score targets fail closed for human repair instead of guessing.

Future Roadmap

• Use roadmap artifacts to sequence future expansion after governed documentation is reviewed.