Friday

Friday

Camada de memória cognitiva persistente auto-hospedada para agentes de codificação de IA.

Persiste decisões de arquitetura, esquemas e restrições entre sessões por meio do Model Context Protocol (MCP).

O Problema

Arquitetura

Motor Duplo

Ciclo de Vida da Memória

Início Rápido

SDK Python

Configuração do MCP

Regras do Agente

Referência da API

_{Friday Neural Studio — Visualizador de grafo de conhecimento 3D em tempo real com WebGL, renderizando topologias de serviços, mapas de calor de acesso dinâmicos e consolidação automatizada de memória.}

O Problema: Amnésia de Sessão

Agentes modernos de codificação de IA (Cursor, Claude Code, Antigravity, VS Code) são excelentes em geração de código isolada. No entanto, em fluxos de engenharia contínuos, os desenvolvedores encontram uma limitação estrutural: Amnésia de Sessão.

As soluções alternativas atuais se enquadram em três padrões profundamente falhos:

                  ┌─────────────────────────────────────────────────────────┐
                  │          WHY STANDARD APPROACHES BREAK DOWN             │
                  └─────────────────────────────────────────────────────────┘

   1. Context Windows (RAM)           2. Static Rules Files             3. Standard Vector RAG
  ┌─────────────────────────┐       ┌─────────────────────────┐       ┌─────────────────────────┐
  │ • Ephemeral volatile    │       │ • Linear token tax      │       │ • Matches text phrasing,│
  │   memory (clears on     │       │   (2,500 tokens burned  │       │   NOT system topology   │
  │   every new thread)     │       │   on every trivial fix) │       │ • Blind to directed     │
  │ • Lost-in-the-middle    │       │ • Stale rules accumu-   │       │   call graphs & schema  │
  │   degradation on 50k+   │       │   late & conflict       │       │   dependencies          │
  │   token prompts         │       │ • Zero cross-tool sync  │       │ • Hallucinates blast    │
  │ • High latency & cost   │       │   (Cursor ≠ Claude CLI) │       │   radii of refactors    │
  └─────────────────────────┘       └─────────────────────────┘       └─────────────────────────┘

1. Janelas de Contexto São Voláteis: Janelas de contexto funcionam como RAM de trabalho, não como armazenamento durável. Limpar um thread ou reiniciar um agente redefine o estado. Inserir 50 mil+ tokens no prompt introduz a queda de atenção "perdido no meio" e aumenta a latência de inferência.
2. Arquivos de Regras Estáticos Incorrem em Imposto Linear de Tokens: Manter arquivos de regras grandes (.cursorrules, AGENTS.md) força o modelo a reler milhares de linhas a cada tecla digitada, levando a instruções contraditórias e fragmentação entre editores.
3. Busca Vetorial Não Captura a Topologia do Sistema: A similaridade de cosseno de embeddings corresponde à formulação do texto, não a dependências relacionais. A busca vetorial não consegue percorrer grafos direcionados: $$\text{Tabela: accounts} \longrightarrow \text{FK: subscriptions} \longrightarrow \text{Serviço: BillingService} \longrightarrow \text{Worker: InvoicePoller}$$

Arquitetura: Substrato Cognitivo Multicamadas

O Friday roda como um serviço de fundo auto-hospedado, fornecendo um substrato de memória estruturado em quatro camadas, acessado por meio do Model Context Protocol (MCP):

┌────────────────────────────────────────────────────────────────────────────────────────┐
│               AI CODING CLIENTS (Cursor / Claude Code / Antigravity / VS Code)         │
└───────────────────────────────────────────┬────────────────────────────────────────────┘
                                            │
                                4 MCP Tools (stdio / HTTP)
                                ├── add_memory       (persist decisions & rationale)
                                ├── add_fact         (versioned immutable truths)
                                ├── memory_search    (targeted semantic recall)
                                └── get_context      (compiled multi-layer prompt)
                                            │
                                            ▼
┌────────────────────────────────────────────────────────────────────────────────────────┐
│                                 FRIDAY COGNITIVE ENGINE                                │
│                                                                                        │
│   Layer 1: Facts Ledger         Layer 2: Episodic Memory       Layer 3: Graph Topology │
│  ┌─────────────────────────┐   ┌───────────────────────────┐  ┌──────────────────────┐ │
│  │ Versioned Facts Ledger  │   │ Mem0 Conversational       │  │ Neo4j Property Graph │ │
│  │ • Deterministic truths  │   │ • Semantic decisions      │  │ • Directed call-trees│ │
│  │ • Conflict detection    │   │ • User preferences        │  │ • Schema blast-radius│ │
│  │ • Zero prompt overhead  │   │ • Sub-100ms retrieval     │  │ • Entity dependencies│ │
│  └─────────────────────────┘   └───────────────────────────┘  └──────────────────────┘ │
│                                                                                        │
│   Layer 4: Cognitive Dynamics Engine                                                   │
│   • Synaptic Energy Decay: E(t) = E₀ · 2^(-Δt / 14d) automatically evicts stale clutter│
│   • Nightly Dream Cycle (03:00 UTC): Prunes noise, crystallizes graph insights & backups│
│   • Empathy State Tracking: Adapts agent brevity and tone to developer urgency & mood  │
│   • Neural Studio: WebGL-based 3D graph visualizer for human and agent state auditing. │
│   • Persona Synchronization: /export/persona compiles canonical rules on-demand.       │
└────────────────────────────────────────────────────────────────────────────────────────┘

As 4 Camadas de Memória Explicadas:

Matriz de Comparação Arquitetural

Arquitetura de Motor Duplo: Processamento de Fundo Desacoplado

Uma decisão arquitetural fundamental no Friday é:

"Por que o Friday mantém um LLM de worker de fundo (como Groq, DeepSeek ou Ollama local) no servidor, completamente separado do modelo de fronteira que roda no Cursor, Claude Code ou Antigravity?"

Agentes de codificação interativos exigem baixa latência, enquanto a manutenção do grafo de conhecimento exige extração e síntese contínuas de dados. O Friday impõe uma Arquitetura de Motor Duplo que desacopla claramente os fluxos de trabalho de front-line dos desenvolvedores dos pipelines de dados de fundo:

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                        THE DUAL-ENGINE ARCHITECTURE MODEL                                 │
├────────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                        │
│   INTERACTIVE AGENT (Frontline Client)       BACKGROUND WORKER (Async Engine)      │
│   ┌─────────────────────────────────────┐     ┌─────────────────────────────────────┐  │
│   │ Client: Cursor / Claude / Antigravity│     │ Engine: Self-Hosted Friday Server   │  │
│   │ Model: Frontier (Claude 3.5 / GPT-4o)│     │ Model: Fast Worker (Groq / Ollama)  │  │
│   │ Role: Complex code generation       │     │ Role: Async graph extraction        │  │
│   │ Context: Lean, task-specific prompt │     │ Role: Conflict pruning & decay      │  │
│   │ State: Ephemeral session lifetime   │     │ State: 24/7 background persistent   │  │
│   └──────────────────┬──────────────────┘     └──────────────────▲──────────────────┘  │
│                      │                                           │                     │
│                      │ 1. MCP Tools (memory_search, add_memory)  │ 2. Microsecond      │
│                      ▼                                           │    Async Parsing    │
│   ┌──────────────────────────────────────────────────────────────┴──────────────────┐  │
│   │                        FRIDAY PERSISTENT MEMORY ARCHITECTURE                    │  │
│   │                                                                                 │  │
│   │   Layer 1: Facts Ledger (Deterministic S3-style Hash Table)                     │  │
│   │   Layer 2: Episodic Memory (Mem0 Conversational Thread History)                 │  │
│   │   Layer 3: Vector Embeddings (ChromaDB Semantic Chunks)                         │  │
│   │   Layer 4: Property Knowledge Graph (Neo4j Directed Topology)                   │  │
│   │   Memory Lifecycle: Dynamic Decay (E(t)) & Nightly Dream Cycle (03:00 UTC)    │  │
│   └─────────────────────────────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────────────────────────────┘

Por Que Desacoplar o Processamento de Fundo é Essencial:

1. ⚡ Execução no IDE com Latência Zero (Desacoplamento Não Bloqueante)

Quando você digita no Cursor ou Claude Code e um agente registra uma decisão importante via add_memory, o modelo Consciente não pode pausar por 4–6 segundos enquanto um LLM analisa entidades semânticas, identifica chaves estrangeiras e executa mutações Cypher.

• Com o worker Subconsciente desacoplado do Friday, a chamada MCP responde em < 40ms.
• O motor Subconsciente (ex.: Groq rodando Llama-3 a 500+ tokens/seg) consome o evento de forma assíncrona, conectando nós e relações do grafo em segundo plano sem roubar um único milissegundo do fluxo do desenvolvedor.

2. 💰 Otimização de Custos de Tokens em 95%+

Modelos de raciocínio de fronteira (Claude 3.5 Sonnet, GPT-4o) custam $3,00 a $15,00 por milhão de tokens. Usar esses modelos caros para manutenção estrutural rotineira — como extrair triplas (Entity A $\longrightarrow$ RELATION $\longrightarrow$ Entity B), verificar hashes de fatos ou aplicar decaimento sináptico — desperdiça orçamentos massivos de tokens.

• O Friday descarrega tarefas estruturais para APIs de fundo ultra-rápidas e ultra-baratas (Groq, DeepSeek Flash) ou modelos auto-hospedados totalmente gratuitos (Ollama, vLLM).
• Seu modelo de fronteira só gasta tokens no que importa: resolver problemas complexos de engenharia.

3. 🌙 Consolidação Autônoma em Segundo Plano (O Ciclo do Sonho)

Sua sessão de codificação termina quando você fecha o IDE ou coloca o laptop para dormir. Mas a evolução da memória não pode parar quando o laptop fecha:

• O motor Subconsciente do Friday vive no seu servidor em nuvem ou local 24/7.
• Às 03:00 UTC todas as noites, enquanto você dorme, o Subconsciente acorda para executar o Ciclo do Sonho: calcular decaimento sináptico, podar ruído de baixa energia, destilar aprendizados episódicos diários em fatos estratégicos permanentes e enviar snapshots criptografados para o Git.

4. 🛡️ Defesa Contra Alucinação e Poluição de Contexto

Despejar um grafo monolítico de 500 nós ou 100 decisões históricas diretamente no prompt do seu editor causa Diluição de Instruções: o LLM fica confuso, esquece restrições recentes e alucina padrões desatualizados.

• O Subconsciente atua como um firewall inteligente.
• Ele digere o contexto bruto, resolve contradições, calcula o decaimento de energia ($E(t)$) e serve apenas os fatos cristalizados de alta energia diretamente relevantes para sua tarefa ativa (~280 tokens em vez de 5.000).

Gerenciamento do Ciclo de Vida da Memória: Decaimento, Consolidação e Calibração

O Friday implementa gerenciamento ativo do ciclo de vida da memória para garantir que agentes de IA retenham restrições críticas sem inchaço de contexto ou interferência de instruções obsoletas:

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                          FRIDAY MEMORY LIFECYCLE ENGINE                                │
├────────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                        │
│  🔥 Dynamic Memory Heat & Decay           🌙 The Dream Cycle (Nightly 03:00 UTC)      │
│  ┌───────────────────────────────────┐    ┌────────────────────────────────────────┐   │
│  │ Exponential Synaptic Decay        │    │ 1. Synaptic Pruning (Evaporates noise) │   │
│  │ • E(t) = E₀ · 2^(-Δt / T_half)    │───>│ 2. Episodic Synthesis (Distills gems)  │   │
│  │ • Recall Potentiation (+0.25)     │    │ 3. Neo4j Crystallization (Graph edges) │   │
│  │ • Soft Archive if E < 0.25        │    │ 4. Autonomous Backup to Git            │   │
│  └───────────────────────────────────┘    └────────────────────────────────────────┘   │
│                                                                                        │
│  🤍 Adaptive Context & Persona Calibration                                             │
│  ┌──────────────────────────────────────────────────────────────────────────────────┐  │
│  │ Multi-Dimensional Response Calibration                                           │  │
│  │ • Interaction Modes: tactical_sprint | deep_architecture | casual_brainstorm     │  │
│  │ • Task Context & Urgency Detection (0.0 to 1.0)                                  │  │
│  │ • Dynamic Response Calibration: Brevity (high/med/low) & Tone Tuning             │  │
│  └──────────────────────────────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────────────────────────────┘

1. 🔥 Calor Dinâmico e Decaimento da Memória

Memórias e fatos verificados não são texto estático — eles têm energia. Diretivas ativas e frequentemente recuperadas permanecem brilhantes ($E > 1.0$). Detalhes irrelevantes ou desatualizados sofrem decaimento exponencial de meia-vida ($T_{half} = 14\text{ dias}$): $$E(t) = E_0 \times 2^{-\frac{\Delta t}{T_{half}}}$$ Quando uma memória é consultada durante a codificação, ela recebe um reforço de potencialização de recuperação ($+0.25$), evitando que conhecimento obsoleto polua o prompt do agente, preservando ao mesmo tempo invariantes arquiteturais centrais (decay_immune: True).

2. 🌙 O Ciclo do Sonho

Toda noite às 03:00 UTC (ou sob demanda via client.run_dream_cycle()), o Friday entra no Ciclo do Sonho:

• Poda Sináptica: Identifica fatos frios/obsoletos e os move para armazenamento arquivado.
• Síntese Episódica: Agrupa conversas recentes e destila 1–2 insights estratégicos cristalizados.
• Cristalização no Neo4j: Conecta insights de alta confiança ao grafo de propriedades com arestas CRYSTALLIZED_INTO.
• Sincronização Autônoma com Git: Dispara commits automatizados no repositório preservando snapshots do grafo.

3. 🤍 Calibração Adaptativa de Contexto e Persona

O Friday monitora o contexto de interação do desenvolvedor (sprint urgente de correção de bugs, exploração de arquitetura tarde da noite ou brainstorming casual). O motor ajusta dinamicamente as características de resposta do agente:

• Calibração de Brevidade: high (zero enrolação, código primeiro) vs. detailed (detalhamento sistêmico).
• Calibração de Tom: technical_concise (código primeiro, direto) vs. architectural_detailed (detalhamento sistêmico).
• Injetado automaticamente em /export/persona para que todos os agentes calibrem naturalmente sua saída.

Benchmarks DeepEval

Avaliamos cinco cenários realistas de engenharia usando o framework de avaliação DeepEval:

1. Raio de Impacto do Esquema de Banco de Dados (avaliando percorrimento do grafo de chamadas downstream)
2. Ciclo de Vida de Refresh de Autenticação (avaliando fidelidade de restrições versionadas)
3. Garantia de Idempotência de Webhooks (avaliando casos de borda de condição de corrida)
4. Reservas de Ambiente e Portas (avaliando recuperação estática de verdades)
5. Consistência de Toolchain Multiagente (avaliando sincronização entre ferramentas no Cursor e Claude CLI)

Reproduzindo Benchmarks Localmente

python benchmarks/benchmark_deepeval.py

Início Rápido

Opção A: Instalação com Um Comando (Recomendado)

Execute o script de instalação autocontido:

curl -fsSL https://raw.githubusercontent.com/friday-memory/friday/main/install.sh | bash

O script verifica a disponibilidade do Docker, aloca as portas necessárias (8000, 7474, 7687), gera segredos de API aleatórios e seguros, grava um .env validado e inicia o Friday via Docker Compose.

Opção B: Configuração Manual via Docker Compose

1. Clone o Repositório:

   git clone https://github.com/friday-memory/friday.git
   cd friday
   

2. Configure o Ambiente (.env):

   cp .env.example .env
   

   # Master API key for endpoint security
   BRAIN_API_KEY=choose_a_strong_secret_key
   
   # Fast Subconscious LLM provider (Groq or DeepSeek)
   DEEPSEEK_API_KEY=your_key_here
   DEEPSEEK_BASE_URL=https://api.deepseek.com
   DEEPSEEK_MODEL=deepseek-chat
   
   # Mem0 key for vector memory (optional)
   MEM0_API_KEY=your_mem0_key_here
   
   # Neo4j database credentials
   NEO4J_URI=bolt://neo4j:7687
   NEO4J_USER=neo4j
   NEO4J_PASSWORD=choose_a_strong_password
   

3. Inicie a Pilha:

   make up
   # or: docker compose up -d
   

4. Verifique a Saúde:

   curl http://localhost:8000/health
   

   {
     "status": "healthy",
     "service": "friday-cognitive-substrate",
     "version": "1.4.4",
     "layers": {
       "L1_core": "healthy",
       "L2_mem0": "healthy",
       "L3_chromadb": "healthy",
       "L4_neo4j": "healthy"
     }
   }
   

SDK Python (friday-memory)

O cliente Python oficial para o Friday está disponível no PyPI como friday-memory. Conecte seus fluxos de trabalho de agentes, pipelines LangChain ou scripts autônomos diretamente ao Friday sem código repetitivo:

pip install --upgrade friday-memory

Cliente Síncrono

from friday import Friday

# Automatically resolves FRIDAY_URL and FRIDAY_API_KEY from environment
with Friday(api_key="your_secret_key", base_url="http://localhost:8000") as client:
    # 1. Health check
    status = client.health()
    print("Friday Status:", status["status"])

    # 2. Store architectural decision
    client.add_memory(
        "PostgreSQL 16 selected with pgvector for hybrid retrieval",
        project="backend-api",
    )

    # 3. Commit scoped ground-truth fact with auto-conflict resolution
    client.add_fact("Production database endpoint is db.internal.net:5432", project="backend-api")

    # 4. Query multi-hop dependency blast radius before refactoring
    blast = client.get_blast_radius(entity="OrdersTable", depth=2, project="backend-api")
    print(
        f"Impacted components ({blast['total_impacted']}):",
        [n["name"] for n in blast["impacted_nodes"]],
    )

    # 5. Multi-layer search (L2 Facts + L3 ChromaDB + L4 Knowledge Graph)
    context = client.search("database connection configuration", project="backend-api")
    print(context["results"])

    # 5. Cognitive State & Dynamic Response Calibration
    state = client.get_cognitive_state()
    print("Active Mode:", state["current_mode"])  # tactical_sprint, deep_architecture, etc.

    # 6. Trigger Nightly Dream Cycle Consolidation (Consolidates & Prunes)
    dream_report = client.run_dream_cycle(half_life_days=14.0)
    print("Crystallized Insights:", dream_report["crystallized_insights"])

    # 7. Apply Synaptic Decay
    decay_report = client.apply_decay(half_life_days=14.0)
    print("Active Facts Remaining:", decay_report["active_facts_count"])

Cliente Assíncrono (FastAPI / Agentes de Trabalho)

import asyncio
from friday import AsyncFriday


async def main():
    async with AsyncFriday(api_key="your_secret_key") as client:
        # Commit context concurrently
        await client.add_memory("Redis cluster deployed for token bucket rate limiting")
        facts = await client.get_facts(min_energy=0.5)
        print(f"Verified high-energy facts: {len(facts)}")


asyncio.run(main())

Integração LangChain (FridayRetriever)

pip install "friday-memory[langchain]"

from friday.integrations.langchain import FridayRetriever
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough
from langchain_openai import ChatOpenAI

retriever = FridayRetriever(
    api_key="your_secret_key",
    base_url="http://localhost:8000",
    project="reeldm",
)

# Connect directly to LCEL chains
prompt = ChatPromptTemplate.from_template(
    "Answer using verified system memory:\n{context}\n\nQuestion: {question}"
)

chain = {"context": retriever, "question": RunnablePassthrough()} | prompt | ChatOpenAI()

Configuração do Cliente (MCP)

O Friday fornece um servidor oficial do Model Context Protocol (MCP) via stdio ou HTTP, permitindo recuperação de contexto em tempo real para todos os IDEs suportados.

 ┌───────────────────────┐
 │   Cursor (Desktop)    │──┐
 └───────────────────────┘  │
 ┌───────────────────────┐  │
 │    Claude Code CLI    │──┼── MCP Protocol (stdio transport)
 └───────────────────────┘  │   FRIDAY_URL="http://127.0.0.1:8000"
 ┌───────────────────────┐  │   BRAIN_API_KEY="your_secret_key"
 │    Antigravity IDE    │──┤
 └───────────────────────┘  │
 ┌───────────────────────┐  │
 │  Windsurf / VS Code   │──┤
 └───────────────────────┘  │
 ┌───────────────────────┐  │
 │       Codex CLI       │──┘
 └───────────────────────┘
                            ▼
             ┌──────────────────────────────┐
             │     FRIDAY CENTRAL BRAIN     │
             │   (Localhost or Remote VM)   │
             │   FastAPI + Mem0 + Neo4j     │
             └──────────────────────────────┘

{
  "mcpServers": {
    "friday": {
      "command": "python",
      "args": ["-m", "mcp.server"],
      "cwd": "/path/to/friday",
      "env": {
        "FRIDAY_URL": "http://localhost:8000",
        "BRAIN_API_KEY": "your_secret_key"
      }
    }
  }
}

{
  "mcpServers": {
    "friday": {
      "command": "ssh",
      "args": [
        "-i", "/path/to/ssh_key.pem",
        "-o", "StrictHostKeyChecking=no",
        "ubuntu@YOUR_SERVER_IP",
        "docker exec -i fridays-brain-app python /app/mcp_server/server.py"
      ]
    }
  }
}

claude mcp add friday \
  -e FRIDAY_URL="http://localhost:8000" \
  -e BRAIN_API_KEY="your_secret_key" \
  -- python -m mcp.server

{
  "mcpServers": {
    "friday": {
      "command": "python",
      "args": ["-m", "mcp.server"],
      "cwd": "/path/to/friday",
      "env": {
        "FRIDAY_URL": "http://localhost:8000",
        "BRAIN_API_KEY": "your_secret_key"
      }
    }
  }
}

[mcp.servers.friday]
command = "python"
args = ["-m", "mcp.server"]
cwd = "/path/to/friday"

[mcp.servers.friday.env]
FRIDAY_URL = "http://localhost:8000"
BRAIN_API_KEY = "your_secret_key"

{
  "cline.mcpServers": {
    "friday": {
      "command": "python",
      "args": ["-m", "mcp.server"],
      "cwd": "/path/to/friday",
      "env": {
        "FRIDAY_URL": "http://localhost:8000",
        "BRAIN_API_KEY": "your_secret_key"
      }
    }
  }
}

Referência de Ferramentas

Agentes conectados acessam automaticamente quatro primitivas MCP principais:

Referência de Variáveis de Ambiente

Exportação de Diretrizes Dinâmicas (/export/persona)

O Friday pode compilar fatos armazenados e restrições arquiteturais em diretrizes markdown sincronizadas sob demanda, prevenindo desvios de regras entre equipes:

# Export canonical AGENTS.md
curl -s "http://localhost:8000/export/persona?target=agents" \
  -H "X-Brain-Key: your_key" > AGENTS.md

# Export Cursor .cursorrules
curl -s "http://localhost:8000/export/persona?target=cursor" \
  -H "X-Brain-Key: your_key" > .cursorrules

Motor Universal de Diretrizes para Agentes (Regras Multi-Agente)

Diferentes assistentes de codificação por IA dependem de diferentes formatos de instrução de workspace. O Friday inclui um motor CLI integrado que gera diretrizes de memória padronizadas e bidirecionais para qualquer editor ou executor de agente autônomo:

1. Listar Alvos Suportados

friday rules list

2. Gerar Regras para Sua Ferramenta

Gere um arquivo de regras otimizado para um agente específico:

friday rules generate --target claude
friday rules generate --target cursor
friday rules generate --target gemini

Ou gere arquivos de regras padronizados para todas as ferramentas suportadas de uma vez:

friday rules generate --all

3. Adaptadores Personalizados Extensíveis para Agentes

Para agentes proprietários, ferramentas corporativas internas ou frameworks recém-lançados, registre e gere arquivos de regras adaptados personalizados:

friday rules custom \
  --key myagent \
  --name "Internal SRE Agent" \
  --file ".myagent/rules.md"

Cada arquivo de regras gerado aplica o Protocolo Bidirecional de Zero-Amnesia:

• Portão de Leitura Pré-Tarefa: Consulta automaticamente friday:get_context e friday:memory_search antes de formular planos de implementação.
• Portão de Escrita Pós-Tarefa: Persiste automaticamente decisões arquiteturais, esquemas e correções de bugs via friday:add_fact e friday:add_memory.

Recursos

1. Extração Automatizada de Grafo de Conhecimento

Toda memória gravada via add_memory é analisada assincronamente pelo worker Subconscious. Entidades e relações tipadas são automaticamente conectadas ao Neo4j sem definições manuais de esquema:

Input:
"Billing engine connects to Stripe API for recurring charges. Webhook dispatched to /api/webhooks/stripe."

Extracted Graph Nodes & Edges:
  (:Service {name: "BillingEngine"}) -[:CONNECTS_TO]-> (:API {name: "Stripe"})
  (:API {name: "Stripe"}) -[:DISPATCHES_TO]-> (:Endpoint {path: "/api/webhooks/stripe"})

2. Neural Studio (Visualizador de Grafo 3D Interativo)

Um visualizador 3D WebGL baseado em navegador, alimentado por Three.js, para exploração de grafo de conhecimento em tempo real e telemetria do sistema:

• Layout Agrupado por Domínio: Agrupa entidades por domínio arquitetural (API, Serviços, Armazenamento, Autenticação, Infraestrutura) para evitar emaranhamento visual em mais de 1.000 nós e esclarecer limites de serviço.
• Mapa de Calor Dinâmico de Acesso: Codifica nós por cores com base na frequência e recência de recuperação, com filtros interativos para diretrizes ativas (Hot ≥ 0.7) e contexto antigo/depreciado (Decayed < 0.4).
• Consolidação de Memória com 1 Clique: Envia consolidação de memória em segundo plano diretamente da interface, sintetizando conversas episódicas e cristalizando relações Neo4j verificadas.
• HUD de Status ao Vivo: Indicador em tempo real exibindo o modo operacional ativo (Sprint, Arquitetura Profunda, Brainstorm) e a saúde do sistema.
• Inspetor de Nós Interativo: Inspecione metadados, reforce pesos de prioridade (+0.25), rastreie cadeias de relacionamento bidirecionais e foque suavemente a câmera 3D nos nós alvo.
• CRUD ao Vivo e Exportação de Topologia: Crie, renomeie ou vincule entidades interativamente e exporte capturas de tela de canvas em alta resolução para documentação do sistema.

3. Livro-Razão de Fatos Versionado e Resolução Inteligente de Conflitos

Constantes determinísticas de projeto são registradas com histórico de versão imutável e isolamento de projeto (reeldm, friday, global). Chaves conflitantes (Key: Value) substituem automaticamente versões mais antigas dentro do mesmo namespace de projeto:

# Add initial constraint (project-scoped)
POST /facts -> {"content": "Payment Gateway: Stripe", "project": "billing"}
# Recorded: id="c41b8a9", superseded=false

# Update constraint — automatically detects conflicting key 'Payment Gateway'
POST /facts -> {"content": "Payment Gateway: DodoPayments", "project": "billing"}
# Prior fact marked superseded=true; active fact updated without hallucination.

4. Análise de Raio de Impacto de Dependências

Antes de modificar esquemas de banco de dados, refatorar middleware compartilhado ou remover endpoints, os agentes consultam get_blast_radius para calcular impactos transitivos downstream até 4 hops de distância na Camada 4:

# Query blast radius for a service or entity
GET /graph/blast-radius?entity=UserSession&depth=2&project=backend-api
# Returns: directly impacted services, traversal distance, and edge relationship types.

Estrutura do Repositório

friday/
├── friday/                  # Official Python SDK & CLI (client, rules engine, types)
├── gateway/                 # FastAPI REST application & routing (Neo4j + ChromaDB + Mem0)
├── layers/                  # Pluggable cognitive adapters (ChromaDB, Neo4j, Decay)
├── pipelines/               # Background entity extraction, Dream Cycle & fact pipelines
├── orchestrator/            # Multi-layer retrieval router & cognitive state engine
├── mcp/                     # Model Context Protocol stdio server
├── studio/                  # Three.js Neural Studio 3D visualizer
├── benchmarks/              # DeepEval evaluation suite
├── tests/                   # Pytest test suite (100% green)
├── docker-compose.yml       # Production container definition
├── Makefile                 # Developer task automation
└── pyproject.toml           # Tooling & packaging configuration

Referência da API

Todos os endpoints autenticados exigem o cabeçalho de solicitação X-Brain-Key.

Desenvolvimento

# Install dependencies
make install

# Run test suite
make test

# Code formatting & linting
make lint
make format

# Start local dev server
make dev

Armazenamento Serverless Opcional (libSQL / Turso & Cloud Run)

O Friday suporta um modelo de execução serverless opcional apoiado por libSQL remoto (Turso) ou transações SQLite locais, ideal para ambientes efêmeros como Google Cloud Run.

• Limite de Armazenamento Duplo: SQLite transacional para implantações locais de nó único; driver libSQL remoto para instâncias serverless distribuídas com zero dependência de estado local.
• Gateway FastAPI Serverless: gateway.serverless:create_app expõe todos os endpoints principais de memória, fato, grafo e blueprint com isolamento por escopo de projeto e leituras autenticadas.
• Runbook de Migração e Qualificação: Scripts privados de exportação/importação, migrações de esquema e verificações de qualificação estão documentados em docs/serverless-migration.md.

Nota: O armazenamento serverless é totalmente opcional e não altera a implantação padrão do Docker Compose ou o roteamento do cliente.

Contribuindo

Revise CONTRIBUTING.md para diretrizes de pull requests, convenções de commit e padrões arquiteturais.

Contribuidores

Shobhit Singh Criador e Mantenedor

Dan Strong Contribuidor de Código Aberto

Licença

O Friday é licenciado sob a Licença MIT.