Chronica

Servidor MCP de memória persistente para Claude Desktop — lembra contexto, tempo e tópicos entre sessões

Documentação

Chronica 🗝️

Uma camada de memória persistente para Claude Desktop via MCP
Um servidor MCP que dá memória de longo prazo ao Claude Desktop

"Conversas com IA esquecem tudo quando a sessão termina.
Chronica lembra — para que o Claude possa continuar exatamente de onde você parou."

O que é Chronica?

Chronica é um servidor MCP (Model Context Protocol) que dá ao Claude Desktop memória persistente e estruturada entre sessões.

Quando você inicia uma nova conversa, o Claude chama chronica_compose_opening com o nome do projeto atual — e o cumprimenta com conhecimento de:

✅ A hora atual (fuso horário local do PC, detectado automaticamente)
✅ Até cinco entradas de memória recentes com escopo do projeto (pré-visualização do título, tipo, recência — não o corpo completo do texto)
✅ Itens abertos de pergunta / ação desse recorte, destacados para acompanhamento

Cada turno do usuário também pode sincronizar JSON leve de tempo/recência via chronica_session_tick. Sem o argumento project em compose_opening, memórias de outros projetos podem se misturar — as descrições das ferramentas exigem sempre passá-lo (ou confirmar o nome com list_threads primeiro).

Chega de "não tenho contexto de sessões anteriores". Chronica resolve isso no nível da arquitetura.

O que é Chronica?

Chronica é um servidor MCP que dá ao Claude Desktop memória entre conversas.

As conversas com IA são redefinidas quando a sessão termina.
Com Chronica, o Claude carrega um resumo de memória com nome do projeto via chronica_compose_opening no início da conversa e pode continuar naturalmente de onde parou (os detalhes são obtidos via chronica_search conforme necessário).

Recursos / Funcionalidades

Ferramenta	Descrição
`compose_opening`	Gera texto de resumo com hora atual, as 5 entradas mais recentes do `project` especificado e itens em andamento (pergunta/ação). `project` é obrigatório (para evitar mistura)
`session_tick`	JSON leve para cada turno (hora atual, "há quantos dias", tópicos recentes). Como MCP não permite push, recomendado chamar a cada turno
`save_entry`	O Claude salva automaticamente o conteúdo da conversa (notas, decisões, tarefas — 5 tipos)
`search`	Busca memórias por tags, tipo e thread
`timeline`	Obtém linha do tempo com período especificado
`summarize`	Gera resumos diários, semanais e de decisões
`get_last_seen`	Obtém a hora da última conversa
`create_thread`	Cria thread (tópico de conversa)
`list_threads`	Obtém lista de threads
`get_thread_info`	Obtém detalhes de uma thread

UI de Curadoria (tela de curadoria)

Interface de administração feita com Streamlit para organizar as memórias acumuladas.

📋 Listagem de memórias (filtro por tipo e tag)
🗑️ Exclusão de memórias desnecessárias (sem edição — apenas exclusão)
📊 Visualização do uso de tokens (TOP 10, taxa de uso)

📸 Capturas de tela

UI de Curadoria — Painel de gerenciamento de memórias

Curation UI

Claude Desktop — Invocação automática de ferramentas

Claude Desktop Tools

Claude Desktop — Memória salva e resposta personalizada

Claude Desktop Memory

Arquitetura

Claude Desktop (Sonnet)
        │ MCP Protocol (STDIO)
        ▼
Chronica MCP Server (Python)
  └── src/chronica/
        ├── tools.py       # 10 MCP tools
        ├── opening.py     # Context generation
        ├── summarize.py   # Summary generation
        ├── store.py       # SQLite persistence
        └── timeparse.py   # Relative time parsing
        │ SQLite
        ▼
data/chronica.sqlite3

Filosofia de design: Chronica é a fonte única de verdade para tempo e estrutura de memória. O Claude atua puramente como interface — prevenindo alucinações ao confiar apenas na saída estruturada do Chronica.

Requisitos

Python 3.10+
Claude Desktop (com suporte a MCP)
Windows / macOS

Instalação

Configuração rápida (recomendado)

Execute o seguinte na raiz do projeto para configurar ambiente virtual, pacotes de dependência e configuração do Claude Desktop de uma só vez.

# Windows (PowerShell)
.\setup.ps1

# Windows (cmd)
setup.bat

# macOS / Linux
chmod +x setup.sh
./setup.sh

Após a conclusão, reinicie o Claude Desktop / Claude Code.

Se estiver usando Claude Code
Após a configuração, abra a pasta Chronica e inicie uma conversa — o Chronica será carregado automaticamente via .mcp.json. Na primeira vez, pode ser solicitada permissão para usar o servidor MCP.

Se aparecer "Nenhum servidor MCP adicionado"
A versão MSIX baixada de claude.ai usa um caminho de configuração diferente. Execute .\setup.ps1 novamente para gravar a configuração em ambos os caminhos.

Configuração manual

1. Clone o repositório

git clone https://github.com/Nic9dev/Chronica.git
cd Chronica

2. Crie o ambiente virtual

python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS
source .venv/bin/activate

3. Instale as dependências

pip install -r requirements.txt

4. Configure o Claude Desktop

Adicione o seguinte ao arquivo de configuração do Claude Desktop (claude_desktop_config.json).

Localização do arquivo de configuração:

Windows (versão MSIX / baixado de claude.ai): %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\claude_desktop_config.json
Windows (versão legada / instalador exe): %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Executar .\setup.ps1 detecta automaticamente as versões MSIX e legada e grava a configuração no caminho apropriado.

{
  "mcpServers": {
    "chronica": {
      "command": "C:/path/to/Chronica/.venv/Scripts/python.exe",
      "args": ["C:/path/to/Chronica/run_server.py"],
      "env": {
        "PYTHONPATH": "C:/path/to/Chronica/src"
      }
    }
  }
}

⚠️ Substitua a parte C:/path/to/Chronica pelo seu caminho real.
⚠️ No Windows, use / (\ não é aceito).

5. Reinicie o Claude Desktop

Após a configuração, reinicie o Claude Desktop.
Inicie uma nova conversa e confirme que o Claude carrega as memórias automaticamente.

Uso

Após a primeira inicialização

Ao iniciar uma nova conversa, o Claude chama chronica_compose_opening para carregar o contexto. Ao chamar, passe o nome do projeto atual em project (se não souber, confirme com chronica_list_threads etc.). As instruções do lado MCP orientam que esta ferramenta seja chamada antes das outras ao verificar situação/memória.

Ativar/desativar o conector (alternável por conversa)

Abra o menu pelo botão "+" ou "/" no chat e ative/desative o Chronica em "Conectores".

Conector	Salvar memórias	Recuperar memórias	Percepção de tempo
LIGADO	Automático	Automático	Sim
DESLIGADO	Não	Não	Não

LIGADO: Salvar, recuperar memórias e percepção de tempo são automáticos.
DESLIGADO: As ferramentas do Chronica não são usadas nessa conversa. Útil para consultas temporárias sem uso de memória.

Uso diário

Salvar memórias: Basta conversar normalmente. O Claude salva automaticamente as informações importantes.
Buscar memórias: Pergunte naturalmente, como "me diga o que decidimos na semana passada".
UI de Curadoria: Quando as memórias acumularem, organize-as aqui:

# Windows (PowerShell)
.\run_curation.ps1

# Windows (cmd)
run_curation.bat

# または
python -m streamlit run app_curation.py

💡 Dicas: Continuidade entre conversas

Início da conversa: Em chronica_compose_opening, sempre passe project="..." (evita misturar memórias de outros projetos). Se o nome estiver ambíguo, confirme com chronica_list_threads antes de chamar.
Registros detalhados: compose_opening traz apenas o resumo das 5 mais recentes. Para logs de trabalho longos, chame em seguida chronica_search com project (e tag volN se necessário).

Ao iniciar uma nova conversa (vol.2, vol.3 etc.), por exemplo, diga algo como:

Chame chronica_search com project "nome-do-projeto" e tag "vol2" para verificar o conteúdo do trabalho anterior e os itens pendentes.

⚠️ Se você disser apenas "verifique o trabalho anterior", o Claude pode consultar o próprio histórico da conversa em vez do Chronica. O ponto-chave é especificar compose_opening com project e o project/tag na busca.

Roadmap

Fase 2 (em breve)

Detecção automática de memórias duplicadas (TF-IDF + similaridade de cosseno)
Exclusão em lote (seleção múltipla)
Busca de texto completo
Função de exportação (JSON / CSV)

Fase 3 (futuro)

Sincronização em nuvem (Supabase + E2EE)
Suporte a múltiplos dispositivos

Fase 4 (futuro)

SaaS e suporte multi-tenant

Licença

Licença MIT — consulte LICENSE para detalhes.

Autor

Nic9 (にく９)
Construiu diversos sistemas estudando sozinho com IA, partindo de zero em programação.
Chronica nasceu como "uma base pessoal para continuar convivendo com IA por muito tempo".

Contribuições

Issues e PRs são bem-vindos!
Relatos de bugs e sugestões de recursos: Issues.