S239 Technical Reference — Vitto Memory System V2

Session: 239 | Date: 2026-03-19 | Branch: session-238-239 (shared concurrent) Spec: docs/superpowers/specs/2026-03-19-vitto-memory-system-v2-design.md Plan: docs/superpowers/plans/2026-03-19-vitto-memory-system-v2.md

1. Architecture Overview

Dual-System Design

Memory Scope Hierarchy

Organization (company-wide rules, policies)
  └─ Space (team/workspace context)
       └─ Universe (per-project knowledge)
            └─ User (personal preferences, conversation history)

Conflict Resolution Rules:

• Preferences: User > Universe > Space > Organization (user knows best)
• Policies: Organization > Space > Universe > User (compliance wins)
• Detection: Tag-based (policy, compliance, mandatory) + overridable: boolean field

Schema Changes

vitto-memories collection — new fields:

{
  scope: 'organization' | 'space' | 'universe' | 'user',  // NEW
  scopeId: string,        // NEW — maps to orgId/spaceId/universeId/userId
  status: 'active' | 'quarantine' | 'archived' | 'rejected',  // NEW
  prospectiveQuestions: string[],  // NEW — generated by ProspectiveIndexerPlugin
  history: MemoryVersion[],       // NEW — version history for audit/revert
}

2. New Backend Services

All services live in APIs/backend-vitto-api/src/app/mind/.

Core Services (mind/services/)

Enhanced Services

Deprecated Services

3. Cognitive Plugin System

Interface

APIs/backend-vitto-api/src/app/mind/plugins/
├── cognitive-plugin.types.ts          # Plugin interface + BaseCognitivePlugin
├── cognitive-plugin-registry.service.ts  # Registry with lifecycle execution
├── index.ts                           # Barrel exports
└── built-in/
    ├── prospective-indexer.plugin.ts   # Future-question enrichment
    └── on-demand-recall.plugin.ts      # Dynamic memory injection

Lifecycle Hooks

Message arrives
  → onBeforeContextAssembly()   // Modify what gets assembled (sequential, context-chaining)
  → Context assembled
  → onBeforeResponse()          // Last-chance memory injection (sequential)
  → LLM responds
  → onAfterResponse()           // Extract learnings (parallel, fire-and-forget)
  → onMemoryAdmission()         // Gate what gets stored (AND-gate: any reject = reject)
  → onMemoryConsolidation()     // Influence merge/prune (sequential)

Built-in Plugins

4. Intelligence Innovations

DopamineRouterService (Fast/Slow Recall)

Scoring formula: score = (novelty × 0.4) + (complexity × 0.3) + (valence × 0.2) + explicitRecallBonus

Hot Cache: In-memory Map, 5-min TTL, 1000 entries max (LRU), invalidated on memory write.

MemoryAdmissionService (5-Factor Gate)

Thresholds: ≥0.6 admit | 0.35-0.6 quarantine | <0.35 reject

ConversationGenomeService (Virtual Context)

Compresses N messages into structured genome:

{
  topics: string[],      // Key discussion topics
  decisions: string[],   // Decisions made during conversation
  facts: string[],       // Facts established
  artifacts: string[],   // Code, files, URLs mentioned
  summary: string,       // 2-3 sentence overview
  tokenCount: number,    // ~1K tokens vs ~10K raw
}

Heuristic v1: Keyword extraction, no LLM calls. LLM v2 planned (recompile every 5 messages with cheap model).

TOON Serialization

// JSON (38 tokens):
{"user":{"name":"Paco","role":"executive","preferences":{"tone":"casual"}}}

// TOON (18 tokens):
u{n:Paco|r:executive|p{t:casual}}

40-60% token reduction. 23-key abbreviation map. Roundtrip-safe (serialize/deserialize).

5. Frontend Components

All in libs/libs-ai/vitto-hub/src/lib/components/.

Frontend Types (@libs-ai/vitto-core)

export type MemoryScope = 'organization' | 'space' | 'universe' | 'user';
export type MemoryStatus = 'active' | 'quarantined' | 'archived';
export interface MemoryEntry { /* scope, scopeId, status, prospectiveQuestions, history */ }
export interface ConversationGenome { /* topics, decisions, facts, artifacts, summary */ }
export interface RouteDecision { /* route, score, reasoning, tokenBudget, cacheable */ }
export interface AdmissionScore { /* totalScore, factors, decision, reasoning */ }
export interface MemoryExportResult { /* files, totalMemories, stats */ }

6. MongoDB Vector Search Indexes

New collection: chat_message_embeddings — flat (one doc per message) replaces nested chat_sessions.messages[].embedding.

7. Test Coverage

File: APIs/backend-vitto-api/src/app/mind/__tests__/memory-pipeline-e2e.spec.ts

Plus per-service unit tests: ~200+ additional tests across individual spec files.

8. MCP Intelligence Captured

Decisions Logged (5)

Conventions Added (4)

1. Soul/Brain separation — Soul is NOT a memory scope; Brain uses 4-scope hierarchy
2. Cognitive plugins required — All memory innovations must be CognitivePlugins, not hardcoded
3. Flat embedding collections — Never nest embeddings in parent documents
4. Quarantine tier mandatory — Gated memories go to quarantine, never permanently deleted

Lessons Reflected (10)

See intelligence({ action: "recall", situation: "memory architecture" }) for full list.

9. Known Issues & Future Work

Issues to Address

Planned Tasks (from spec)

10. File Inventory

New Files Created

APIs/backend-vitto-api/src/app/mind/
├── services/
│   ├── dopamine-router.service.ts           # Fast/slow route decision
│   ├── dopamine-router.service.spec.ts      # 40+ tests
│   ├── memory-admission.service.ts          # 5-factor admission gate
│   ├── memory-admission.service.spec.ts     # 60 tests
│   ├── conversation-genome.service.ts       # Conversation compression
│   ├── window-manager.service.ts            # Sliding window context
│   ├── toon-serializer.service.ts           # TOON format
│   ├── toon-serializer.service.spec.ts      # 48 tests
│   ├── soul-compressor.service.ts           # Soul → 150-token brief
│   ├── soul-compressor.service.spec.ts      # 42 tests
│   └── memory-export.service.ts             # Markdown export
│       └── memory-export.service.spec.ts    # 45 tests
├── plugins/
│   ├── cognitive-plugin.types.ts            # Plugin interface
│   ├── cognitive-plugin-registry.service.ts # Registry + execution
│   ├── index.ts                             # Barrel
│   └── built-in/
│       ├── prospective-indexer.plugin.ts    # Future questions
│       └── on-demand-recall.plugin.ts       # Dynamic injection
├── conflict/
│   └── __tests__/
│       └── memory-conflict-resolver.service.spec.ts  # 25 tests
└── __tests__/
    └── memory-pipeline-e2e.spec.ts          # 70 E2E tests

libs/libs-ai/vitto-hub/src/lib/components/
├── memory-manager/
│   ├── memory-scope-filter/                 # Scope pill filter
│   ├── memory-version-history/              # Edit timeline + revert
│   └── genome-viewer/                       # Genome visualization
├── memory-quarantine/                       # Quarantine review dashboard
└── memory/
    └── genome-viewer/                       # Standalone genome viewer

libs/libs-ai/vitto-core/src/lib/models/
└── memory-v2.models.ts                      # Frontend types

APIs/backend-ai-api/src/app/agents/schemas/
└── chat-message-embedding.schema.ts         # Flat embedding collection

Modified Files

APIs/backend-vitto-api/src/app/mind/
├── mind.module.ts                           # Registered all V2 services
├── memory/vitto-memory.types.ts             # Added MemoryScope, MemoryStatus
├── memory/vitto-memory-recall.service.ts    # Added scopeAwareRecall()
├── conflict/memory-conflict-resolver.service.ts  # Added resolve()
├── recall/dopamine-router.service.ts        # @deprecated
└── soul-compression.service.ts              # @deprecated

libs/libs-ai/vitto-hub/src/lib/components/
├── index.ts                                 # Added V2 component exports
└── memory-manager/memory-manager.component.ts  # Integrated V2 components

libs/libs-ai/vitto-core/src/index.ts         # Added V2 type exports

docs/english/Plans/
└── S239-vector-search-index-handoff.md      # Cowork agent handoff

Generated: 2026-03-19 | Session 239 | Claude Code on gspace1