Memory Intelligence System - Architecture Vision

Versao: 2.1 (Target State — Core/Pro Split) Ultima Atualizacao: 2026-02-09 Autor: @architect (Aria) Epic: MIS — Memory Intelligence System Baseado Em: MIS-1 Investigation Documento Atual: MEMORY-SYSTEM.md (estado atual v1.0) Tags: memory, intelligence, session-digest, progressive-retrieval, self-learning, attention-routing, core-pro-split

NOTA: Este documento descreve o estado futuro do sistema de memoria apos todas as 7 stories do Epic MIS serem implementadas. Para o estado atual, consulte MEMORY-SYSTEM.md.

ARQUITETURA: O MIS segue o modelo Open Core do AIOX. Toda a inteligencia de memoria reside no repositorio privado aiox-pro (submodule pro/). O aiox-core (open source) fornece apenas extension points e funciona 100% sem memoria inteligente — exatamente como hoje.

Indice

1. Visao Geral
2. Core/Pro Separation Strategy
3. Design Principles
4. Arquitetura em 4 Camadas
5. Camada 1: Capture Layer
6. Camada 2: Storage Layer
7. Camada 3: Retrieval Layer
8. Camada 4: Evolution Layer
9. Session Digest Flow (PreCompact)
10. Agent Memory API
11. Pipeline Integration
12. Memory File Format
13. Attention Scoring & Tiers
14. Cognitive Sectors
15. Self-Learning & Auto-Evolution
16. Mapa de Storage Persistente
17. Mapa de Arquivos do Sistema
18. Diferencas: Estado Atual vs MIS
19. Story Roadmap
20. Referencias de Pesquisa

Visao Geral

O Problema (Estado Atual)

O sistema de memoria atual opera em duas camadas desconectadas (Claude Code nativo + AIOX Framework) com gaps criticos:

• Sem session-digest — conhecimento contextual evapora ao fechar sessao
• Sem retrieval inteligente — agentes carregam tudo-ou-nada (200 linhas de MEMORY.md)
• Sem self-learning — heuristicas, correcoes e axiomas perdidos entre sessoes
• 2,397 linhas de codigo orfao — modulos que se referenciam mutuamente sem consumidores
• ~14K linhas de dados orfaos — arquivos que ninguem le
• 8 broken paths — referencias a diretorios/arquivos que nao existem

A Solucao: Memory Intelligence System (MIS)

O MIS unifica as duas camadas em um sistema inteligente de 4 camadas, seguindo o modelo Open Core:

| Camada | Funcao | Repositorio | Story | |--------|--------|-------------|-------| | Cleanup | Remover dead code, preparar base | aiox-core | MIS-2 | | Capture | Captura conhecimento de sessao via hooks | aiox-pro | MIS-3 | | Storage | Armazena em Markdown com frontmatter YAML | aiox-pro | MIS-3, MIS-4 | | Retrieval | Recupera por relevancia com progressive disclosure | aiox-pro + extension points em aiox-core | MIS-4, MIS-6 | | Evolution | Aprende e evolui regras automaticamente | aiox-pro | MIS-5, MIS-7 |

Principios Chave (vs Estado Atual)

| Aspecto | Estado Atual | Com MIS (aiox-pro ativo) | Sem MIS (aiox-core only) | |---------|-------------|--------------------------|--------------------------| | Session end | Nada acontece | PreCompact digest captura aprendizados | Nada acontece (como hoje) | | Memory load | MEMORY.md (200 linhas, tudo-ou-nada) | Progressive disclosure (HOT/WARM/COLD) | MEMORY.md (como hoje) | | Agent scope | Memorias globais sem filtragem | Memorias privadas + compartilhadas por agente | Globais (como hoje) | | Learning | Manual (Claude decide salvar) | Automatico (correcoes, patterns, gotchas) | Manual (como hoje) | | Token usage | ~10K tokens fixos por sessao | 60-95% reducao via attention routing | ~10K tokens (como hoje) |

Core/Pro Separation Strategy

Principio Fundamental

aiox-core funciona 100% sem o MIS — exatamente como funciona hoje. Quando aiox-pro esta presente (submodule pro/), o MIS se conecta automaticamente via extension points. Zero configuracao manual.

Modelo Open Core

flowchart LR
    subgraph CORE["aiox-core (Open Source, MIT)"]
        direction TB
        C1["UnifiedActivationPipeline"]
        C2["gotchas-memory.js (mantido)"]
        C3["context-loader.js"]
        C4[".claude/settings.json (hook stubs)"]
        C5["Extension Points<br/>(isProAvailable checks)"]
    end

    subgraph PRO["aiox-pro (Privado, Submodule pro/)"]
        direction TB
        P1["pro/memory/session-digest.js"]
        P2["pro/memory/memory-index.js"]
        P3["pro/memory/memory-retriever.js"]
        P4["pro/memory/memory-loader.js"]
        P5["pro/memory/self-learner.js"]
        P6["pro/memory/rule-proposer.js"]
        P7["pro/memory/gotcha-capture.js"]
        P8["pro/pro-config.yaml<br/>memory.persistent: true"]
    end

    C5 -->|"isProAvailable()?"| CHECK{" "}
    CHECK -->|"Sim"| PRO
    CHECK -->|"Nao"| FALLBACK["Core funciona<br/>como hoje"]

    style CORE fill:#E8F5E9,stroke:#2E7D32
    style PRO fill:#E3F2FD,stroke:#1565C0
    style FALLBACK fill:#FFF9C4,stroke:#F9A825

Pattern de Integracao: pro-detector

O aiox-core ja possui o modulo bin/utils/pro-detector.js (Story PRO-5):

const { isProAvailable, loadProModule } = require('../../bin/utils/pro-detector');

// No UnifiedActivationPipeline (Tier 2):
if (isProAvailable()) {
  const memoryLoader = loadProModule('memory/memory-loader');
  if (memoryLoader) {
    const memories = await memoryLoader.loadForAgent(agentId, { budget: 2000 });
    enrichedContext.memories = memories;
  }
}
// Se pro/ nao existe → memoryLoader = null → nenhuma memoria carregada → funciona como hoje

Feature Gating

Features de memoria ja registradas em pro/feature-registry.yaml:

| Feature ID | Descricao | Story MIS | |-----------|-----------|-----------| | pro.memory.persistence | Persistent memory across sessions | MIS-3 | | pro.memory.extended | Extended context window for AI agents | MIS-4, MIS-6 | | pro.memory.search | Semantic search across memory stores | MIS-4 | | pro.memory.sync | Cross-device memory synchronization | Futuro |

Features adicionais a registrar:

| Feature ID (novo) | Descricao | Story MIS | |-------------------|-----------|-----------| | pro.memory.session_digest | PreCompact session digest capture | MIS-3 | | pro.memory.self_learning | Self-learning from corrections | MIS-5 | | pro.memory.auto_evolution | CLAUDE.md & rules auto-evolution | MIS-7 |

O Que Vai em Cada Repositorio

aiox-core (open source) — Extension Points Only

| Arquivo | Tipo | Descricao | |---------|------|-----------| | bin/utils/pro-detector.js | Existente | isProAvailable(), loadProModule() | | .aiox-core/development/scripts/unified-activation-pipeline.js | Modificacao | Adiciona if (isProAvailable()) no Tier 2 para memory loading | | .aiox-core/development/scripts/greeting-builder.js | Modificacao | Adiciona memory stats no greeting se pro disponivel | | .aiox-core/core/memory/gotchas-memory.js | Mantido | Path fix (MIS-2), funciona standalone | | .aiox-core/core/session/context-loader.js | Mantido | Path fix (MIS-2), funciona standalone | | .claude/settings.json | Modificacao | Hook stubs que chamam scripts em pro/ (graceful fail se ausente) |

aiox-pro (privado) — Toda a Inteligencia

| Arquivo | Camada MIS | Story | |---------|-----------|-------| | pro/memory/session-digest.js | Capture | MIS-3 | | pro/memory/gotcha-capture.js | Capture | MIS-3 | | pro/memory/memory-index.js | Storage | MIS-4 | | pro/memory/memory-retriever.js | Retrieval | MIS-4 | | pro/memory/self-learner.js | Evolution | MIS-5 | | pro/memory/memory-loader.js | Pipeline | MIS-6 | | pro/memory/agent-memory-api.js | Commands | MIS-6 | | pro/memory/rule-proposer.js | Evolution | MIS-7 | | pro/pro-config.yaml | Config | MIS-3 (enable memory flags) | | pro/feature-registry.yaml | Config | MIS-3 (add new feature IDs) |

Hook Configuration Strategy

Os hooks do Claude Code sao configurados em .claude/settings.json (aiox-core). O script apontado reside em pro/:

{
  "hooks": {
    "PreCompact": [
      {
        "type": "command",
        "command": "node pro/memory/session-digest.js --mode=precompact",
        "timeout": 10000
      }
    ]
  }
}

Graceful degradation: Se pro/ nao existe, o Node.js falha silenciosamente (Cannot find module), o hook nao executa, e o Claude Code continua normalmente. Isso e o comportamento padrao de hooks — falhas nao bloqueiam a sessao.

Alternativa mais robusta (recomendada): Um wrapper no core que verifica pro antes de chamar:

{
  "hooks": {
    "PreCompact": [
      {
        "type": "command",
        "command": "node .aiox-core/hooks/pro-hook-runner.js PreCompact",
        "timeout": 10000
      }
    ]
  }
}

// .aiox-core/hooks/pro-hook-runner.js (no core, ~20 linhas)
const { isProAvailable, loadProModule } = require('../bin/utils/pro-detector');
const hookEvent = process.argv[2]; // PreCompact, Stop, etc.

if (!isProAvailable()) process.exit(0); // silently exit

const hookHandler = loadProModule(`memory/hooks/${hookEvent.toLowerCase()}`);
if (hookHandler && typeof hookHandler.run === 'function') {
  hookHandler.run(process.env).catch(() => process.exit(1));
} else {
  process.exit(0);
}

Design Principles

7 principios derivados da investigacao de 10 repositorios open-source (MIS-1):

1. File-First (basic-memory pattern)

Memorias sao arquivos Markdown com frontmatter YAML. Git-friendly, human-readable, CLI-first. Se o index corromper, rebuild a partir dos arquivos.

2. Progressive Disclosure (claude-mem pattern)

Retrieval em 3 camadas para minimizar tokens:

• Index: Titulos + IDs (~50 tokens)
• Context: Chunks relevantes (~200 tokens)
• Detail: Memoria completa (~1000+ tokens)

3. Tiered Storage (openclaw pattern)

Memorias classificadas por durabilidade:

• Session: Efemera, morre ao final da sessao
• Daily: Consolidacao do dia, auto-flush
• Durable: Conhecimento permanente, nunca expira

4. Attention Routing (claude-cognitive pattern)

Cada memoria tem um attention score que determina tier de loading:

• HOT (>0.7): Sempre no contexto (~500 tokens max)
• WARM (0.3-0.7): Carregado sob demanda
• COLD (<0.3): Apenas via busca explicita

5. Cognitive Sectors (OpenMemory pattern)

Memorias classificadas por tipo cognitivo:

• Episodic: "O que aconteceu" (sessoes, eventos)
• Semantic: "O que eu sei" (fatos, conceitos)
• Procedural: "Como fazer" (patterns, workflows)
• Reflective: "O que eu aprendi" (meta-cognicao)

6. Self-Learning (claude-reflect pattern)

Correcoes do usuario sao capturadas, padroes extraidos, regras propostas com confidence score. Evolucao sempre via aprovacao do usuario.

7. Agent-Scoped (cognee pattern)

Cada agente tem memoria privada + acesso a memorias compartilhadas. Sem cross-contaminacao.

8. Open Core (AIOX PRO pattern)

Toda a inteligencia de memoria e uma feature premium. O core funciona identicamente sem ela. A integracao e automatica via extension points + isProAvailable().

Arquitetura em 4 Camadas

Diagrama Completo com Core/Pro Boundary

flowchart TB
    subgraph SESSION["Session Lifecycle"]
        direction LR
        SS([SessionStart]) --> WORK[Working] --> PC([PreCompact]) --> STOP([Stop])
    end

    subgraph CORE_BOUNDARY["aiox-core (Open Source)"]
        direction TB
        EXT["Extension Points<br/>in Pipeline"]
        HOOK_RUNNER[".aiox-core/hooks/<br/>pro-hook-runner.js"]
        GOTCHAS["gotchas-memory.js<br/>(standalone)"]
        CTX_LOADER["context-loader.js<br/>(standalone)"]
    end

    subgraph PRO_BOUNDARY["aiox-pro (Privado — pro/)"]
        subgraph CAPTURE["CAMADA 1: CAPTURE"]
            C1["session-digest.js<br/>PreCompact + Stop"]
            C2["gotcha-capture.js<br/>PostToolUseFailure"]
        end

        subgraph STORAGE["CAMADA 2: STORAGE"]
            ST1[".aiox/memories/shared/"]
            ST2[".aiox/memories/{agent}/"]
            ST3[".aiox/memories/index.json"]
        end

        subgraph RETRIEVAL["CAMADA 3: RETRIEVAL"]
            R1["memory-retriever.js<br/>Progressive Disclosure"]
            R2["memory-loader.js<br/>Pipeline Integration"]
            R3["agent-memory-api.js<br/>*recall, *remember"]
        end

        subgraph EVOLUTION["CAMADA 4: EVOLUTION"]
            E1["self-learner.js<br/>Correction + Heuristic"]
            E2["rule-proposer.js<br/>Auto-Evolution"]
        end
    end

    PC --> HOOK_RUNNER
    STOP --> HOOK_RUNNER
    HOOK_RUNNER -->|"isProAvailable?"| C1
    WORK --> GOTCHAS

    C1 --> STORAGE
    C2 --> STORAGE
    STORAGE --> RETRIEVAL
    RETRIEVAL --> EVOLUTION

    SS --> EXT
    EXT -->|"loadProModule('memory/memory-loader')"| R2

    style CORE_BOUNDARY fill:#E8F5E9,stroke:#2E7D32
    style PRO_BOUNDARY fill:#E3F2FD,stroke:#1565C0
    style CAPTURE fill:#FFCDD2,stroke:#C62828
    style STORAGE fill:#C8E6C9,stroke:#2E7D32
    style RETRIEVAL fill:#BBDEFB,stroke:#1565C0
    style EVOLUTION fill:#F3E5F5,stroke:#7B1FA2

Fluxo Sem Pro (aiox-core standalone)

flowchart LR
    SS([SessionStart]) --> PIPELINE["Pipeline carrega<br/>CLAUDE.md + rules<br/>+ MEMORY.md (200 linhas)"]
    PIPELINE --> CHECK{"isProAvailable()?"}
    CHECK -->|"NAO"| SKIP["Skip memory loading<br/>(como hoje)"]
    SKIP --> GREETING["Greeting sem<br/>memory stats"]

    PC([PreCompact]) --> HOOK["pro-hook-runner.js"]
    HOOK --> CHECK2{"pro/ existe?"}
    CHECK2 -->|"NAO"| EXIT["exit(0)<br/>Nada acontece"]

    style SKIP fill:#FFF9C4,stroke:#F9A825
    style EXIT fill:#FFF9C4,stroke:#F9A825

Relacionamento entre Modulos

flowchart LR
    subgraph CORE["aiox-core"]
        HR[".aiox-core/hooks/<br/>pro-hook-runner.js"]
        UAP["unified-activation-<br/>pipeline.js"]
        GM["gotchas-memory.js"]
        PD["bin/utils/<br/>pro-detector.js"]
    end

    subgraph PRO["aiox-pro (pro/)"]
        SD["memory/<br/>session-digest.js"]
        GC["memory/<br/>gotcha-capture.js"]
        MI["memory/<br/>memory-index.js"]
        MR["memory/<br/>memory-retriever.js"]
        ML["memory/<br/>memory-loader.js"]
        SL["memory/<br/>self-learner.js"]
        RP["memory/<br/>rule-proposer.js"]
        API["memory/<br/>agent-memory-api.js"]
    end

    subgraph COMMANDS["Agent Commands"]
        CMD_RECALL["*recall"]
        CMD_REMEMBER["*remember"]
    end

    HR -->|"loadProModule"| SD
    HR -->|"loadProModule"| GC
    UAP -->|"loadProModule"| ML
    PD --> HR
    PD --> UAP

    SD --> MI
    GC --> MI
    SL --> MI
    ML --> MR
    MR --> MI
    API --> MR
    RP --> SL

    CMD_RECALL --> API
    CMD_REMEMBER --> API

    style CORE fill:#E8F5E9,stroke:#2E7D32
    style PRO fill:#E3F2FD,stroke:#1565C0
    style COMMANDS fill:#FFF9C4,stroke:#F9A825

Camada 1: Capture Layer

Repositorio: aiox-pro (pro/memory/) Extension point no core: .aiox-core/hooks/pro-hook-runner.js

Visao Geral

A Capture Layer intercepta eventos de sessao via hooks do Claude Code e extrai conhecimento estruturado. Os scripts de captura residem em pro/memory/ e sao invocados pelo pro-hook-runner.js do core.

Hook Events Utilizados

| Hook Event | Quando Dispara | Script Pro | Fallback Core | |-----------|---------------|-----------|---------------| | PreCompact | Contexto proximo do limite | pro/memory/session-digest.js | Nada (exit 0) | | Stop | Sessao encerra | pro/memory/session-digest.js --final | Nada (exit 0) | | PostToolUseFailure | Tool falhou | pro/memory/gotcha-capture.js | gotchas-memory.js (core, basico) | | TaskCompleted | Task finalizada | pro/memory/session-digest.js --task | Nada (exit 0) |

Configuracao de Hooks

// .claude/settings.json (aiox-core — committed)
{
  "hooks": {
    "PreCompact": [
      {
        "type": "command",
        "command": "node .aiox-core/hooks/pro-hook-runner.js PreCompact",
        "timeout": 10000
      }
    ],
    "Stop": [
      {
        "type": "command",
        "command": "node .aiox-core/hooks/pro-hook-runner.js Stop",
        "timeout": 5000
      }
    ],
    "PostToolUseFailure": [
      {
        "type": "command",
        "command": "node .aiox-core/hooks/pro-hook-runner.js PostToolUseFailure",
        "timeout": 3000
      }
    ]
  }
}

O pro-hook-runner.js (~20 linhas, no core) verifica isProAvailable() e delega para o script pro correspondente. Se pro nao existe, exit silencioso.

Extractors e Classifiers (pro/memory/)

flowchart TD
    subgraph CORE_HOOKS["aiox-core"]
        HR["pro-hook-runner.js"]
    end

    subgraph PRO_CAPTURE["aiox-pro: pro/memory/"]
        subgraph EXTRACTORS["Extractors"]
            EX1["Session Digest Extractor<br/>Decisoes, erros, progresso"]
            EX2["Gotcha Extractor<br/>Erro 3x → auto-gotcha"]
            EX3["Correction Extractor<br/>Correcao → pattern"]
        end

        subgraph CLASSIFIERS["Classifiers"]
            CL1["Tier Classifier<br/>session | daily | durable"]
            CL2["Sector Classifier<br/>episodic | semantic |<br/>procedural | reflective"]
            CL3["Scope Classifier<br/>shared | agent-specific"]
        end

        EXTRACTORS --> CLASSIFIERS
        CLASSIFIERS --> PERSIST[("Persist to<br/>.aiox/memories/")]
    end

    HR -->|"isProAvailable()"| PRO_CAPTURE

    style CORE_HOOKS fill:#E8F5E9,stroke:#2E7D32
    style PRO_CAPTURE fill:#E3F2FD,stroke:#1565C0
    style PERSIST fill:#C8E6C9,stroke:#2E7D32

Camada 2: Storage Layer

Repositorio: aiox-pro (pro/memory/) gerencia o storage Storage location: .aiox/memories/ (gitignored, criado pelo pro)

Principio: Files as Memory

Cada memoria e um arquivo Markdown com frontmatter YAML. Arquivos sao a fonte da verdade. O index JSON e derivado e pode ser reconstruido a qualquer momento.

Estrutura de Diretorios

.aiox/memories/                          # Criado e gerenciado por pro/memory/
  shared/                                # Cross-agent memories
    durable/                             # Permanent knowledge
      2026-02-09-absolute-imports.md
    daily/                               # Day-level consolidation
      2026-02-09/
        session-001-digest.md
    session/                             # Ephemeral (cleaned on next start)
      current-session.md
  dev/                                   # @dev private memories
    durable/
    daily/
  qa/                                    # @qa private memories
    durable/
    daily/
  architect/                             # @architect private memories
    durable/
    daily/
  index.json                             # Search index (rebuilt from files)

# Claude Code nativo (nao gerenciado pelo MIS):
.claude/memory/MEMORY.md                 # Always loaded, 200 lines
.claude/agent-memory/{agent}/MEMORY.md   # Per-agent memory

Dual Storage Strategy

flowchart LR
    subgraph NATIVE["Claude Code Nativo (sempre funciona)"]
        N1[".claude/memory/MEMORY.md<br/>200 linhas max<br/>Sempre no system prompt"]
        N2[".claude/agent-memory/{agent}/<br/>MEMORY.md por agente"]
    end

    subgraph PRO_MANAGED["pro/memory/ gerencia (quando disponivel)"]
        F1["Shared Memories<br/>Markdown + frontmatter"]
        F2["Agent Memories<br/>Privadas por agente"]
        F3["index.json<br/>Search index"]
    end

    subgraph SYNC["Sync (pro apenas)"]
        S1["HOT memories<br/>→ MEMORY.md"]
        S2["Agent HOT<br/>→ agent MEMORY.md"]
    end

    PRO_MANAGED -->|"pro sync"| SYNC
    SYNC --> NATIVE

    style NATIVE fill:#E8F5E9,stroke:#2E7D32
    style PRO_MANAGED fill:#E3F2FD,stroke:#1565C0
    style SYNC fill:#FFF9C4,stroke:#F9A825

Sem pro: MEMORY.md nativo funciona como hoje — Claude decide o que salvar manualmente. Com pro: MIS sincroniza HOT memories para MEMORY.md, garantindo que estejam no system prompt.

Camada 3: Retrieval Layer

Repositorio: aiox-pro (pro/memory/memory-retriever.js, memory-loader.js) Extension point no core: unified-activation-pipeline.js (Tier 2 conditional load)

Progressive Disclosure (3 Niveis)

flowchart TD
    QUERY["Agent precisa de memoria"] --> LEVEL1

    subgraph LEVEL1["Nivel 1: Index Scan (~50 tokens)"]
        L1A["Busca por metadata:<br/>tags, tipo, agente, tier"]
        L1B["Retorna: lista de titulos + IDs"]
    end

    LEVEL1 -->|"match found"| LEVEL2

    subgraph LEVEL2["Nivel 2: Context Retrieval (~200 tokens)"]
        L2A["Carrega sumario + evidence<br/>de cada match"]
    end

    LEVEL2 -->|"need detail"| LEVEL3

    subgraph LEVEL3["Nivel 3: Full Detail (~1000+ tokens)"]
        L3A["Carrega memoria completa"]
    end

    style LEVEL1 fill:#C8E6C9,stroke:#2E7D32
    style LEVEL2 fill:#FFF9C4,stroke:#F9A825
    style LEVEL3 fill:#FFCDD2,stroke:#C62828

Token Savings

| Cenario | Tokens | Reducao | |---------|--------|---------| | Sem pro (core only, MEMORY.md bruto) | ~10,000 | 0% | | Com pro + Progressive Disclosure | ~2,000 | 80% | | Com pro + Attention Routing | ~1,000 | 90% | | Com pro + Agent Scoping | ~500 | 95% |

Camada 4: Evolution Layer

Repositorio: aiox-pro (pro/memory/self-learner.js, rule-proposer.js) Nenhum extension point no core — esta camada e 100% pro

Fluxo de Auto-Evolucao

flowchart TD
    subgraph INPUTS["Sinais (capturados pela Camada 1)"]
        I1["Correcao do usuario"]
        I2["Gotcha repetida (3x)"]
        I3["Pattern em 5+ sessoes"]
    end

    subgraph PRO_EVOLUTION["pro/memory/ (Evolution)"]
        A1["self-learner.js<br/>Extrai regra/heuristica"]
        A4["Confidence Scorer<br/>Score = evidence * recency"]
        P1["rule-proposer.js<br/>Gera proposta de mudanca"]
    end

    subgraph APPROVAL["Gate: User Approval"]
        G1{"Usuario aprova?"}
        G2["Aplicar + log"]
        G3["Rejeitar + lower confidence"]
    end

    I1 --> A1
    I2 --> A1
    I3 --> A1
    A1 --> A4
    A4 -->|"confidence > 0.9<br/>+ 5+ evidence"| P1
    A4 -->|"confidence < 0.9"| WAIT["Aguarda mais evidence"]

    P1 --> G1
    G1 -->|"Sim"| G2
    G1 -->|"Nao"| G3

    style PRO_EVOLUTION fill:#E3F2FD,stroke:#1565C0
    style APPROVAL fill:#C8E6C9,stroke:#2E7D32

Regra Inviolavel

NUNCA auto-modificar arquivos de configuracao do usuario. Sempre propor → apresentar → aguardar aprovacao explicita. Rejeicao abaixa confidence e registra motivo.

Session Digest Flow (PreCompact)

Fluxo com Core/Pro Boundary

sequenceDiagram
    participant CC as Claude Code
    participant HR as pro-hook-runner.js<br/>(aiox-core)
    participant PD as pro-detector.js<br/>(aiox-core)
    participant SD as session-digest.js<br/>(aiox-pro)
    participant FS as .aiox/memories/

    Note over CC: Contexto proximo do limite

    CC->>HR: PreCompact event fires
    HR->>PD: isProAvailable()?

    alt Pro NAO disponivel
        PD-->>HR: false
        HR->>HR: process.exit(0)
        Note over CC: Nada acontece (como hoje)
    else Pro disponivel
        PD-->>HR: true
        HR->>SD: loadProModule('memory/hooks/precompact')

        SD->>SD: Read transcript context
        SD->>SD: Extract: decisions, errors,<br/>corrections, progress
        SD->>SD: Classify: tier + sector + scope
        SD->>FS: Write memory files (.md)
        SD->>FS: Update index.json
        SD-->>CC: Inject summary:<br/>"5 memories persisted.<br/>Use *recall to access."
    end

    Note over CC: Context compacts normalmente

Capacidades Tecnicas do PreCompact

| Capacidade | Status | Nota | |-----------|--------|------| | Acesso ao transcript completo | Disponivel | Antes da compressao | | Execucao de scripts shell | Disponivel | Fire-and-forget com async | | Escrita de arquivos | Disponivel | session-digest.js escreve memories | | Timeout configuravel | 10 segundos | Suficiente para digest | | Modo async | Disponivel (Jan 2026) | Nao bloqueia compactacao |

Agent Memory API

Repositorio: aiox-pro (pro/memory/agent-memory-api.js) Sem pro: Comandos *recall, *remember nao existem (agente opera como hoje)

Comandos Disponiveis (com pro)

# Buscar memorias
*recall {query}                    # Busca em todas as memorias acessiveis
*recall --agent dev                # Apenas memorias do @dev
*recall --type procedural          # Apenas conhecimento procedural
*recall --tier durable             # Apenas memorias permanentes
*recall --recent 7d                # Ultimos 7 dias

# Salvar memorias manualmente
*remember "Always run tests before push"   # Salva como durable + procedural

# Gerenciar memorias
*forget {id}                       # Deleta memoria especifica
*memories                          # Lista memorias recentes (HOT + WARM)
*memories --stats                  # Estatisticas de uso

Mapeamento Agente → Memorias Acessiveis

Cada agente acessa:

1. Suas proprias memorias privadas (.aiox/memories/{agent}/)
2. Memorias compartilhadas (.aiox/memories/shared/)
3. Nunca memorias privadas de outros agentes

Pipeline Integration

Extension point no core: unified-activation-pipeline.js (1 check isProAvailable) Modulo pro: pro/memory/memory-loader.js

Tiered Memory Loading

sequenceDiagram
    participant UAP as UnifiedActivationPipeline<br/>(aiox-core)
    participant PD as pro-detector.js<br/>(aiox-core)
    participant ML as memory-loader.js<br/>(aiox-pro)
    participant MR as memory-retriever.js<br/>(aiox-pro)
    participant GB as GreetingBuilder<br/>(aiox-core)

    Note over UAP: ANTES: Claude Code ja carregou<br/>CLAUDE.md, rules, MEMORY.md

    rect rgb(255, 200, 200)
        Note over UAP: Tier 1 — HOT (<80ms) — Nativo, sem pro
        UAP->>UAP: Native MEMORY.md (ja carregado)
        UAP->>UAP: Native agent-memory (ja carregado)
    end

    rect rgb(255, 230, 180)
        Note over UAP,ML: Tier 2 — WARM (<120ms) — Pro conditional
        UAP->>PD: isProAvailable()?

        alt Pro disponivel
            PD-->>UAP: true
            UAP->>ML: loadProModule('memory/memory-loader')
            ML->>MR: queryMemories({agent, attention: >0.5})
            MR-->>ML: Top 10 scored memories (~2000 tokens)
            ML-->>UAP: {warmMemories, tokens, stats}
        else Pro NAO disponivel
            PD-->>UAP: false
            Note over UAP: Skip — funciona como hoje
        end
    end

    rect rgb(200, 230, 255)
        Note over UAP,ML: Tier 3 — COLD Index (<180ms) — Pro conditional
        alt Pro disponivel
            UAP->>ML: loadMemoryIndex()
            ML-->>UAP: {titles, IDs, count}
        end
    end

    UAP->>GB: buildGreeting(agent, context, memories?)
    GB-->>UAP: greeting (com ou sem memory stats)

Budget de Tokens

| Tier | Com Pro | Sem Pro (core only) | |------|---------|-------------------| | HOT (Tier 1) | ~500 tokens | ~500 tokens (MEMORY.md nativo) | | WARM (Tier 2) | ~2,000 tokens | 0 (skip) | | COLD (Tier 3) | ~200 tokens | 0 (skip) | | Total | ~2,700 | ~500 (como hoje) |

Memory File Format

Especificacao (arquivos em .aiox/memories/)

---
id: mem-2026-02-09-001
type: procedural               # episodic | semantic | procedural | reflective
tier: durable                  # session | daily | durable
agent: shared                  # shared | dev | qa | architect | ...
tags: [imports, typescript, pattern, coding-standard]
confidence: 0.95
created: 2026-02-09T14:30:00Z
last_accessed: 2026-02-09T16:00:00Z
access_count: 3
source: user-correction         # user-correction | session-digest | auto-gotcha |
                                # manual | heuristic | task-outcome
attention_score: 0.85           # HOT (>0.7) | WARM (0.3-0.7) | COLD (<0.3)
related_memories: [mem-2026-02-08-003]
evidence_count: 5
---

# Always Use Absolute Imports in AIOX

## Pattern
Use `@/` prefix for all imports. Never use relative imports (`../`).

## Evidence
- User correction in session abc123 (2026-02-09)
- Confirmed by CLAUDE.md rule (Absolute Imports, Artigo VI)
- Applied in 47 files across codebase

## Context
Non-negotiable coding standard. Constitution Article VI.

Attention Scoring & Tiers

Formula

attention_score = base_relevance * recency_factor * access_modifier * confidence

Decay rates por tier:
  session:  0.5   (metade por dia)
  daily:    0.1   (moderado)
  durable:  0.01  (muito lento)

Tier Assignment

| Attention Score | Tier | Pipeline | Comportamento | |----------------|------|----------|--------------| | > 0.7 | HOT | Tier 1 | Sync para MEMORY.md (sempre no prompt) | | 0.3 - 0.7 | WARM | Tier 2 | Injetado na ativacao (se dentro do budget) | | < 0.3 | COLD | Tier 3 | Apenas via *recall explicito | | < 0.1 (90+ dias) | ARCHIVE | — | Movido para .old/ |

Cognitive Sectors

4 Setores + Preferencia por Agente

| Agente | Setores Prioritarios | Razao | |--------|---------------------|-------| | @dev | Procedural, Semantic | COMO fazer e QUAIS convencoes | | @qa | Reflective, Episodic | O QUE APRENDEMOS e O QUE ACONTECEU | | @architect | Semantic, Reflective | O QUE SABEMOS e O QUE APRENDEMOS | | @pm | Episodic, Semantic | O QUE ACONTECEU e FATOS do projeto | | @devops | Procedural, Episodic | COMO OPERAR e O QUE ACONTECEU |

Decay por Setor

| Setor | TTL Base | Razao | |-------|---------|-------| | Episodic | 7 dias * access_modifier | Sessoes antigas perdem relevancia | | Semantic | 365 dias | Fatos permanecem validos | | Procedural | 30 dias * last_used_modifier | Workflows nao usados decaem | | Reflective | Infinito | Aprendizados sao permanentes |

Self-Learning & Auto-Evolution

100% em aiox-pro — nenhum componente de self-learning no core

Exemplos de Evolucao

Correcao → Regra:

Sessao 1: Usuario corrige "use npm not yarn" → confidence 0.3
Sessao 4: Mesmo pattern 5x → confidence 0.95
→ PROPOSTA: Adicionar a CLAUDE.md: "Package Manager: npm"
→ Usuario aprova → Regra aplicada

Gotcha → Warning:

Sessao 7: Erro "EACCES permission denied" 3x → auto-gotcha
→ Gotcha persiste por 5+ sessoes → promoted to Warning
→ PROPOSTA: Adicionar a rules/: "Warning: .aiox/ permissions"
→ Usuario aprova → Warning vira regra

Mapa de Storage Persistente

.aiox/                                        # Runtime state (gitignored)
├── memories/                                 # [PRO] Criado/gerenciado por pro/memory/
│   ├── shared/                               #   Cross-agent memories
│   │   ├── durable/                          #     Permanent knowledge (.md files)
│   │   ├── daily/{YYYY-MM-DD}/              #     Daily digests
│   │   └── session/                          #     Ephemeral (cleaned on restart)
│   ├── dev/                                  #   @dev private memories
│   ├── qa/                                   #   @qa private memories
│   ├── architect/                            #   @architect private memories
│   ├── pm/, devops/, ...                     #   Other agents
│   ├── index.json                            #   Search index (rebuilt from .md)
│   └── stats.json                            #   Usage analytics
├── gotchas.json                              # [CORE] gotchas-memory.js (standalone)
├── gotchas.md                                # [CORE] Human-readable gotchas
├── error-tracking.json                       # [CORE] Error tracking (MIS-2 cria)
├── session-state.json                        # [CORE] Inter-agent handoff
├── project-status.yaml                       # [CORE] Project status cache
└── codebase-map.json                         # [CORE] Codebase structure

~/.claude/projects/.../
├── memory/MEMORY.md                          # [NATIVO] Always loaded (200 lines)
└── {session-id}.jsonl                        # [NATIVO] Full transcript

.claude/agent-memory/                         # [NATIVO] Per-agent memory
├── aiox-architect/MEMORY.md
├── aiox-dev/MEMORY.md
└── .../MEMORY.md

Sem pro: Apenas [CORE] e [NATIVO] existem. [PRO] (.aiox/memories/) nunca e criado.

Mapa de Arquivos do Sistema

aiox-core (Open Source) — Extension Points

| Arquivo | Tipo | Story | Descricao | |---------|------|-------|-----------| | bin/utils/pro-detector.js | Existente (PRO-5) | — | isProAvailable(), loadProModule() | | .aiox-core/hooks/pro-hook-runner.js | Novo | MIS-3 | Wrapper: verifica pro, delega hook (~20 linhas) | | .aiox-core/development/scripts/unified-activation-pipeline.js | Modificacao | MIS-6 | Adiciona if (isProAvailable()) no Tier 2 | | .aiox-core/development/scripts/greeting-builder.js | Modificacao | MIS-6 | Memory stats no greeting se pro disponivel | | .aiox-core/core/memory/gotchas-memory.js | Path fix | MIS-2 | Corrige .aiox/error-tracking.json | | .aiox-core/core/session/context-loader.js | Path fix | MIS-2 | Corrige .aiox/session-state.json | | .claude/settings.json | Modificacao | MIS-3 | Hook stubs via pro-hook-runner.js |

aiox-pro (Privado) — Toda a Inteligencia

| Arquivo | Camada | Story | Descricao | |---------|--------|-------|-----------| | pro/memory/hooks/precompact.js | Capture | MIS-3 | Session digest no PreCompact | | pro/memory/hooks/stop.js | Capture | MIS-3 | Final flush no Stop | | pro/memory/hooks/tooltfailure.js | Capture | MIS-3 | Enhanced gotcha capture | | pro/memory/memory-index.js | Storage | MIS-4 | Index manager (build, search, update) | | pro/memory/memory-retriever.js | Retrieval | MIS-4 | Progressive disclosure retriever | | pro/memory/self-learner.js | Evolution | MIS-5 | Correction tracker + heuristic extractor | | pro/memory/memory-loader.js | Pipeline | MIS-6 | Pipeline integration (Tier 2/3 loading) | | pro/memory/agent-memory-api.js | Commands | MIS-6 | *recall, *remember, *forget | | pro/memory/rule-proposer.js | Evolution | MIS-7 | CLAUDE.md + rules auto-evolution | | pro/pro-config.yaml | Config | MIS-3 | Enable memory flags | | pro/feature-registry.yaml | Config | MIS-3 | Add MIS feature IDs |

Arquivos Removidos (MIS-2, aiox-core)

| Arquivo | Linhas | Razao | |---------|--------|-------| | .aiox-core/core/memory/timeline-manager.js | 746 | 0 consumers (orphan) | | .aiox-core/core/memory/file-evolution-tracker.js | 1,003 | 0 consumers (orphan) | | .aiox-core/core/memory/context-snapshot.js | 648 | 0 consumers (orphan) | | .aiox-core/elicitation/session-manager.js | — | Dead code | | .aiox/compound-analysis/ | ~14K | 0 readers (orphan data) |

Diferencas: Estado Atual vs MIS

| Aspecto | aiox-core hoje | aiox-core + aiox-pro (MIS) | aiox-core sem pro | |---------|---------------|---------------------------|------------------| | Camadas | 2 desconectadas | 4 integradas via pro | 2 desconectadas (como hoje) | | Session end | Nada | PreCompact digest + Stop flush | Nada (como hoje) | | Memory load | MEMORY.md tudo-ou-nada | Progressive HOT/WARM/COLD | MEMORY.md (como hoje) | | Agent scope | Global unico | Private + Shared por agente | Global (como hoje) | | Search | Nenhuma | FTS index + metadata | Nenhuma (como hoje) | | Learning | Manual | Automatico | Manual (como hoje) | | Dead code | 2,397 linhas | Removido | Removido (MIS-2) | | Token usage | ~10K fixo | ~2,700 (~73% reducao) | ~10K (como hoje) | | Hooks | Gemini-only | Claude Code native | Hook stubs (no-op) |

Story Roadmap

gantt
    title Epic MIS - Story Dependencies & Repositories
    dateFormat YYYY-MM-DD

    section aiox-core
    MIS-1 Investigation (Done)           :done, mis1, 2026-02-09, 1d
    MIS-2 Dead Code Cleanup              :active, mis2, after mis1, 1d

    section aiox-core + aiox-pro
    MIS-3 Session Digest                 :mis3, after mis1, 3d
    MIS-6 Pipeline Integration           :mis6, after mis4, 2d

    section aiox-pro
    MIS-4 Progressive Retrieval          :mis4, after mis3, 3d
    MIS-5 Self-Learning Engine           :mis5, after mis3, 3d
    MIS-7 Auto-Evolution                 :mis7, after mis5, 2d

| Story | Titulo | Repositorio | Depende De | Horas | |-------|--------|-------------|------------|-------| | MIS-1 | Investigation & Architecture Design | docs (aiox-core) | — | 12h (Done) | | MIS-2 | Dead Code Cleanup & Path Repair | aiox-core | MIS-1 | 4h | | MIS-3 | Session Digest (PreCompact Hook) | aiox-core (hook runner) + aiox-pro (digest) | MIS-1 | 14h | | MIS-4 | Progressive Memory Retrieval | aiox-pro | MIS-3 | 16h | | MIS-5 | Self-Learning Engine | aiox-pro | MIS-3, MIS-4 | 14h | | MIS-6 | Pipeline Integration & Agent Memory API | aiox-core (ext points) + aiox-pro (loader) | MIS-4 | 10h | | MIS-7 | CLAUDE.md & Rules Auto-Evolution | aiox-pro | MIS-5 | 8h | | Total | | | | ~78h |

Referencias de Pesquisa

Top 3 Repositorios de Inspiracao

| Repo | Fit Score | Pattern Incorporado | |------|-----------|-------------------| | basic-memory | 9/10 | File-first storage (Markdown + frontmatter, git-friendly) | | claude-cognitive | 9/10 | HOT/WARM/COLD attention tiers, multi-instance memory pool | | openclaw | 9/10 | Three-tier model, PreCompact session digest |

Documentacao Relacionada

| Recurso | Caminho | |---------|---------| | Estado Atual (v1.0) | MEMORY-SYSTEM.md | | Epic MIS Index | EPIC-MIS-INDEX.md | | MIS-1 Investigation | story-mis-1-investigation.md | | MIS-2 Dead Code Cleanup | story-mis-2-dead-code-cleanup.md | | Epic PRO Architecture | EPIC-PRO-INDEX.md | | ADR-PRO-001 Repository Strategy | adr-pro-001-repository-strategy.md | | ADR-PRO-003 Feature Gating | adr-pro-003-feature-gating-licensing.md | | Pro Detector | bin/utils/pro-detector.js | | Feature Registry | pro/feature-registry.yaml |

AIOX Memory Intelligence System — Architecture Vision v4.0.4 (Core/Pro Split) Target state apos Epic MIS completo (7 stories, ~78 horas) aiox-core: extension points + dead code cleanup aiox-pro: toda a inteligencia de memoria (Capture, Storage, Retrieval, Evolution) @architect (Aria) — arquitetando o futuro