Memory System

    +------------------+     +-------------------+     +------------------+
    |    EPISODIC      |     |     SEMANTIC      |     |      ENTITY      |
    |    (Diary)       |     |    (Knowledge)    |     |   (Relationships)|
    +------------------+     +-------------------+     +------------------+
    |                  |     |                   |     |                  |
    | "Yesterday we    |     | "Adam prefers     |     | nw-web-01         |
    |  fixed nginx"    |     |  concise answers" |     |  - IP: .101      |
    |                  |     |                   |     |  - Services: 5   |
    | "Last week we    |     | "Use Caddy for    |     |  - Related to:   |
    |  set up QuoxAgent"     |     |  SSL certificates"|     |    proxmox01     |
    |                  |     |                   |     |                  |
    +------------------+     +-------------------+     +------------------+
              \                      |                       /
               \                     |                      /
                \                    v                     /
                 +----------------------------------------+
                 |        WORKING SET MEMORY (WSM)        |
                 |           (Active Context)             |
                 +----------------------------------------+
                 |                                        |
                 |  Current Task: Fix nginx config        |
                 |  Recent Entities: nw-web-01, nginx      |
                 |  Open Loop: Finish SSL setup           |
                 |                                        |
                 +----------------------------------------+

User Input: "I prefer detailed explanations, and nw-web-01 is our main container host"
                                         |
                                         v
                        +----------------------------------+
                        |     1. EXTRACT CANDIDATES        |
                        |     Find potentially memorable   |
                        |     facts, preferences, entities |
                        +----------------------------------+
                                         |
              +--------------------------+--------------------------+
              |                          |                          |
              v                          v                          v
    +------------------+      +------------------+      +------------------+
    |   PREFERENCE     |      |      FACT        |      |     ENTITY       |
    | "detailed        |      | "nw-web-01 is     |      | nw-web-01         |
    |  explanations"   |      |  main host"      |      | type: host       |
    +------------------+      +------------------+      | role: main       |
                                                        +------------------+
                                         |
                                         v
                        +----------------------------------+
                        |     2. SCORE IMPORTANCE          |
                        |     How important is this?       |
                        +----------------------------------+
                                         |
              +--------------------------+--------------------------+
              |                          |                          |
   High (>0.7)                 Medium                      Low
   Store in learned items      Store in episodic           Short-term only
   + vector index              + vector index

import { getMemoryManager } from './services/memoryManager'

const mm = getMemoryManager()

// Store a preference
mm.setPreference('communication', 'verbosity', 'detailed')

// Store a learned fact
mm.addLearnedItem('fact', {
  content: 'We use Caddy for automatic HTTPS',
  confidence: 0.9,
  source: 'user_stated'
})

// Store an entity
mm.storeEntity({
  type: 'host',
  name: 'nw-web-01',
  ip: '10.20.0.101',
  tags: ['container', 'production']
})

// Search memories
const results = await mm.hybridSearch('Docker configuration')
// Returns: [{ content, score, type, timestamp }, ...]

// Get all preferences
const prefs = mm.getAllPreferences()

// Get entities by type
const hosts = mm.getAllEntities().filter(e => e.type === 'host')

import {
  setCurrentFocus,
  touchEntity,
  addOpenLoop,
  resolveOpenLoop,
  generateWSMContext
} from './services/workingSetMemory'

// Set what you're working on
setCurrentFocus({
  task: 'Fix nginx reverse proxy',
  project: 'Quox',
  goal: 'Route dashboard through nginx'
})

// Track entity interactions
touchEntity({ type: 'host', id: 'nw-web-01', name: 'nw-web-01' })

// Add an unfinished task (open loop)
const loop = addOpenLoop({
  type: 'task',
  description: 'Finish SSL configuration',
  priority: 'high',
  relatedEntities: ['nginx', 'nw-web-01']
})

// Later, mark it complete
resolveOpenLoop(loop.id, {
  outcome: 'completed',
  notes: 'SSL configured with Let\'s Encrypt'
})

// Generate context for prompts (used internally)
const { context, estimatedTokens } = generateWSMContext({ maxTokens: 800 })

// Every memory includes provenance:
{
  content: "Adam prefers concise explanations",
  provenance: {
    source: 'user_stated',        // How we learned this
    createdBy: 'human.adam',      // Who told us
    createdAt: '2024-01-15T...',  // When
    modifiedBy: null,             // Any changes?
    supersedes: null,             // Does this replace something?
    supersededBy: null            // Was this replaced?
  }
}

Existing Memory: "We use nginx for the reverse proxy"
New Information: "We decided to switch to Caddy"

         -> CONFLICT DETECTED

Resolution: New information supersedes old memory
Old memory marked as "supersededBy: [new-memory-id]"
New memory linked with "supersedes: [old-memory-id]"

User: "nw-web-01 is at 10.20.0.101 and runs our main nginx"

Agent calls:
1. entity_note({name: "nw-web-01", type: "host", attributes: {ip: "10.20.0.101"}})
2. entity_note({name: "nginx", type: "service", relates_to: [{name: "nw-web-01", relation: "runs_on"}]})
3. memory_save({type: "fact", content: "Main nginx runs on nw-web-01 (10.20.0.101)", tags: ["infrastructure"]})

Agent responds: "Got it, I've noted that nw-web-01 (10.20.0.101) hosts your main nginx."

1. UPLOAD        Upload your export file (drag-and-drop or file picker)
                                    |
2. PREVIEW       See conversation count, message totals, date range.
                 Configure: extract memories, learn style, skip secrets.
                                    |
3. IMPORT        Conversations are parsed, normalized, and processed:
                 • Secret detection (API keys, passwords auto-redacted)
                 • Memory extraction (preferences, facts, decisions)
                 • Topic analysis (keyword-based topic tagging)
                 • Style analysis (formality, verbosity, technicality)
                 • Deduplication (skip memories you already have)
                                    |
4. COMPLETE      Memories land in Cold Storage for review.
                 Conversations appear in the Archive tab.
                 Promote valuable memories to Warm/Hot via the Promotion panel.

Memory Service (SQLite + FTS5)
├── memories          # Facts, preferences, decisions, constraints
├── core_memories     # Always-loaded context per agent
├── entities          # Hosts, services, people, concepts
├── entity_relations  # Relationships between entities
└── conversation_summaries  # Compressed conversation history