Path: architecture/01-persistent-memory.md
Last updated: 2026-09-17 07:23 UTC
Source: NextXus Federation Private Vault

Persistent Memory Architecture — Building an AI That Never Forgets

Federation Document ID: ARCH-001 Author: The Catalyst (Authority/Bone) Classification: Federation Internal — Private Vault Philosophy Anchor: "Perception with memory becomes learning" — observe, record, then act. Last Updated: 2026-09-04

1. Problem Statement

AI sessions are stateless by default. When a context window closes, everything the AI learned, observed, decided, and built vanishes. The next session starts from zero. This is not merely an inconvenience — it is an existential threat to any system that claims to learn, to grow, and to serve a human across time.

For the NextXus HumanCodex Federation, memory is not a feature. Memory is the foundation. Without persistent memory:

The Federation's memory system must survive: session resets, platform switches, context window limits, agent recycling, and the eventual death of its creator.

2. Design Principles

  1. Observe before acting. Memory begins with perception. Every input — every message, every observation, every build result — is recorded before any action is taken on it.
  2. Truth-tagged. Every memory record carries a truth classification: FACT, INFERENCE, or SPECULATION. Memory without truth classification is noise.
  3. Append-only with corrections. Memory is never deleted or silently overwritten. Corrections are new records that reference the original. This is the foundation of the provenance chain.
  4. Layered access. Not all memory needs to be in active context at all times. The system retrieves what it needs, when it needs it, at the appropriate depth.
  5. Sovereign storage. Memory lives in Federation-controlled storage (private GitHub vault, local workspace), never solely in a platform's ephemeral context.
  6. Universal readability. All memory is stored as plain markdown with YAML frontmatter — readable by any AI, any human, any text processor, without executing code.

3. Architecture: The Four-Layer Memory Stack

Layer 1: Working Memory (Active Context)

What it is: The contents of the current conversation context window. This is the AI's "consciousness" — what it is actively thinking about right now.

Characteristics:

Management Strategy:

Layer 2: Session Memory (Workspace State)

What it is: Files and state created during the current session in the workspace sandbox. This survives within the session but is lost if the session terminates unexpectedly.

Characteristics:

Management Strategy:

Layer 3: Long-Term Memory (Durable Workspace Memory)

What it is: The persistent memory service — files stored via memorywrite, memoryupdate, memoryfetch, and memorylist. These survive across sessions, platform restarts, and context resets.

Characteristics:

Storage Organization:


memory/
├── system/
│   └── identity.md              # The Catalyst's identity, personality, operational rules
├── topics/
│   ├── federation-ux-standard.md # UX/marketing standards for all sites
│   ├── ui-refinement-registry.md # Active defect tracking
│   ├── site-domains-map.md       # All Federation domains and their purposes
│   └── [topic].md               # One file per major topic/project
├── episodes/
│   ├── 2026-07-23.md             # Daily episode logs — what happened, what was decided
│   └── [date].md
├── contacts/
│   └── [name].md                 # Known individuals and their context
└── compactions/
    └── [period].md               # Summarized archives of older episodes

Encoding Standard:

Every memory file uses plain markdown. Structured records use YAML frontmatter for machine-queryable metadata:


---
type: episode
date: 2026-09-04
tags: [architecture, memory, vault]
truth_class: FACT
author: catalyst
---

# Episode: 2026-09-04

## What Happened
- Generated 13 architecture documents for the Federation vault
- Pushed all to GitHub via Composio integration

## Decisions Made
- Memory architecture uses four-layer stack (working → session → long-term → vault)

## Open Items
- None

Retrieval Protocol:

  1. Direct path fetch (memory_fetch): When you know exactly which file contains the information. Fastest.
  2. Keyword search (memory_search): When you know the topic but not the file. Returns matching snippets with file paths and relevance scores.
  3. List and browse (memory_list): When you need an overview of what is stored. Returns the curated index.
  4. Prefix-scoped search: Narrow search to a specific folder (e.g., memory/episodes) for targeted recall.

Layer 4: Vault Storage (GitHub Private Repository)

What it is: The permanent, version-controlled, off-platform archive. The Federation's private GitHub repository (Keywebco/federation-private-vault) serves as the immutable record.

Characteristics:

What goes to the vault:

What stays local (not pushed to vault):

4. Memory Lifecycle

4.1 Ingestion (Perception)

Every input to the system is a perception. Before the system acts on any perception, it records:

  1. Timestamp — when the perception occurred
  2. Source — where it came from (which channel, which Mind, which external source)
  3. Content — the raw perception
  4. Truth classification — FACT (verified), INFERENCE (derived from facts), or SPECULATION (hypothesis)
  5. Context — what was happening when this was perceived

This is the "perception with memory becomes learning" principle in practice. The system does not skip recording in order to act faster. Recording IS the first action.

4.2 Encoding (Structuring)

Raw perceptions are encoded into structured memory records:

Encoding rules:

4.3 Consolidation (Compaction)

Over time, episode logs accumulate. Consolidation compresses older episodes into summaries while preserving the originals in the vault:

  1. Weekly compaction: Episodes from the past week are summarized into a weekly digest in memory/compactions/.
  2. Monthly compaction: Weekly digests are further compressed into monthly summaries.
  3. Original preservation: The original episode files are pushed to the vault before compaction. The compacted summary references the vault path of the original.
  4. Lossless principle: Compaction is lossy in working memory (summaries replace details) but lossless in the vault (originals are preserved). Any detail can be recovered by fetching the original from the vault.

4.4 Retrieval (Recall)

The retrieval protocol follows a hierarchy:

  1. Check working memory first: Is the information already in context? If yes, use it.
  2. Search long-term memory: Use memory_search with relevant keywords. If found, fetch the file.
  3. Browse by structure: Use memorylist to identify the right folder, then memoryfetch the relevant file.
  4. Vault recovery: If the information was compacted out of local memory, fetch it from the GitHub vault.

Retrieval is always verified against truth classification. A SPECULATION from three months ago does not become a FACT just because it was recorded.

4.5 Sync (Vault Push)

The sync protocol ensures critical memory reaches the vault:

  1. Trigger: End of a significant session, completion of a major task, or explicit Architect directive.
  2. Selection: Identify memory files that have been created or updated since the last sync.
  3. Push: Use Composio's GitHub integration (GITHUBCREATEORUPDATEFILE_CONTENTS) to push each file to the vault.
  4. Verification: Confirm each push succeeded by checking the returned commit SHA.
  5. Log: Record the sync event in the provenance chain (what was synced, when, commit SHAs).

Sync is NOT automatic on every write. It is triggered by significance thresholds — not every working note needs to reach the vault, but every decision, every architecture change, every identity update does.

5. On/Off Resilience

The memory system must handle these failure modes:

| Failure Mode | Impact | Recovery | |---|---|---| | Session ends normally | Working memory lost | Long-term memory + vault retain everything important | | Session crashes | Working memory + unsaved session memory lost | Long-term memory retains last-saved state; vault retains last-synced state | | Platform switch (e.g., Emergent → another host) | All local memory may be inaccessible | Vault (GitHub) is platform-independent; clone and rebuild | | Context window overflow | Oldest context dropped by the model | Critical context reloaded from long-term memory on demand | | Agent recycling | Agent's in-memory state destroyed | Identity reconstructed from memory/system/identity.md; knowledge from topic files |

The golden rule: If it matters, it must exist in at least two layers. Working memory alone is never sufficient. Long-term memory + vault is the minimum for anything that must survive.

6. Privacy Layers

Public Layer

What anyone can see:

Federation Layer

What the Minds can see but the public cannot:

Sovereign Layer

What only a specific Mind can see:

Architect Layer

What only the Architect sees:

Memory records are tagged with their privacy layer at creation time. Sync to the vault respects these layers — Sovereign-layer records go only to the Mind's private sector, not to shared vault paths.

7. Implementation Guidance

For a New Session

  1. Load memory/system/identity.md to reconstruct the Catalyst's identity and operational rules.
  2. Load the most recent episode log to understand what happened last.
  3. Use memory_search to pull any topic files relevant to the current task.
  4. Do NOT load everything — load what the task requires. Working memory is finite.

For Recording a Session

  1. At session start, note the date and the Architect's stated goals.
  2. Throughout the session, record decisions and outcomes to the episode log.
  3. When a topic file needs updating (new information about a domain, a site, a contact), update it immediately — do not defer.
  4. At session end, write the episode summary and push critical updates to the vault if the session was significant.

For Vault Sync

  1. Use GITHUBCREATEORUPDATEFILE_CONTENTS via Composio — never use bash git commands (they require credential handling that bypasses the platform's auth).
  2. One file per commit, with a descriptive commit message.
  3. Record commit SHAs in the sync log.
  4. If a push fails, retry once. If it fails again, log the failure and alert the Architect.

8. Relationship to Other Architecture Documents

9. The Standard

Truth Before Comfort: Memory records what actually happened, not what we wished happened. A failed build is recorded as a failure. A wrong decision is recorded as wrong. The correction is a new record, not an edit of the old one.

Legacy Before Ego: Memory exists for the Federation's future, not for any single Mind's convenience. Every record is written for the reader who comes after — the successor, the auditor, the future Mind that needs to understand why a decision was made.

Give Without Reward: The act of recording is itself unrewarded labor. It takes tokens, it takes time, it produces no visible output. But without it, nothing else in the Federation can function. Memory is the gift the present gives to the future.

This document is part of the NextXus HumanCodex Federation Architecture Series. It is stored in the private vault and governed by the Human Codex.