🗂️ Estrutura: flat, taxonomia, grafo

Minimo viavel. Zero decisao de estrutura. Comece aqui.

~/.memory/
└── knowledge.md

Um arquivo com todas as memorias.
Append-only: cada nova memoria vira paragrafo com data.

Exemplo:
---
## 2026-04-20
Decisao: usar FastAPI no payments-v2.
Razao: async nativo, 80% endpoints sao IO-bound.

## 2026-04-21
Fato: pgvector suporta HNSW index desde v0.5.
Relevante para nossa busca semantica.

## 2026-04-22
Padrao: sempre idempotency key em webhook.
Observado em Stripe, PayPal, PagBank. 3x.

Sweet spot: ganho significativo com esforço moderado.

~/.memory/knowledge/
├── facts/          (como algo e)
│   ├── postgres-vector-support.md
│   └── lambda-payload-limit.md
├── decisions/      (escolhas feitas)
│   ├── 2026-04-20-fastapi-over-flask.md
│   └── 2026-04-22-webhook-architecture.md
├── patterns/       (regras recorrentes)
│   ├── idempotency-in-webhooks.md
│   └── small-prs-with-tests.md
├── preferences/    (gostos pessoais)
│   └── async-over-callbacks.md
└── events/         (acontecimentos)
    └── 2026-04-22-incident-timeout.md

Pastas aninhadas por escopo. Otimo quando voce tem projetos com sub-areas.

~/.memory/knowledge/
├── shared/                    (cross-projeto)
│   └── python-patterns.md
├── projects/
│   ├── payments-v2/
│   │   ├── decisions/
│   │   │   └── idempotency.md
│   │   ├── patterns/
│   │   │   └── webhook-retry.md
│   │   └── facts/
│   │       └── stripe-quirks.md
│   └── landing-redesign/
│       ├── decisions/
│       └── patterns/
└── personal/
    ├── workflow.md
    └── style.md

Cada nota linka outras. Busca pode caminhar no grafo. Estilo Obsidian.

decisions/
  fastapi-over-flask.md
    "Discutimos em [[meeting-2026-04-20]].
     Substituiu [[flask-exploration]].
     Baseado em [[async-patterns]].
     Relacionado a [[payments-architecture]]."

patterns/
  async-patterns.md
    "Visto em [[fastapi-over-flask]].
     Complementa [[small-prs]]."

# Query: 'decisoes ligadas a arquitetura'
# → caminha: payments-architecture → fastapi-over-flask
#   → meeting-2026-04-20 → async-patterns → ...
# → recupera cluster inteiro de contexto

Migrar e barato quando voce precisa. Nao precisa decidir tudo no dia 1.

#!/usr/bin/env python3
# Migrar knowledge.md flat para taxonomia 5-tipos

import os, re, shutil
from pathlib import Path

# 1. Ler knowledge.md
content = Path('~/.memory/knowledge.md').expanduser().read_text()

# 2. Separar por data
entries = re.split(r'## (\d{4}-\d{2}-\d{2})', content)

# 3. Usar LLM (Gemini Flash) para classificar cada entry
#    em: fact | decision | pattern | preference | event

# 4. Mover cada uma para a pasta certa
for entry in classified_entries:
    target = f'~/.memory/knowledge/{entry.type}/{entry.slug}.md'
    Path(target).expanduser().parent.mkdir(parents=True, exist_ok=True)
    Path(target).expanduser().write_text(entry.content)

# 5. Arquivar o knowledge.md original
shutil.move('~/.memory/knowledge.md', '~/.memory/archive/knowledge-pre-migration.md')

Regra pratica para escolher sem ruminar.

| Cenario                          | Estrutura           |
|----------------------------------|---------------------|
| Comecando, <100 memorias        | Flat                |
| 100-500 memorias mistas          | Taxonomia 4-tipos   |
| 3+ projetos com sub-areas        | Hierarquia espacial |
| Conhecimento densamente ligado   | Grafo (Obsidian)    |
| Time grande com vocabs variados  | Grafo + semantica   |
| Solo, pragmatico                 | Taxonomia 4-tipos   |

Regra final: DUVIDA → taxonomia 4-tipos. Ganha 80% do beneficio com 20% do esforço.