personal-notes
Optional integration that lets the assistant use Ollama-hosted chat models and embeddings through its API as local LLM/embedding backends.
Optional integration that lets the assistant use OpenAI chat models for tool calling and OpenAI embeddings for retrieval, configured through environment variables.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Personal AI Assistant — RAG + MCP
Assistente pessoal de estudos em Python que responde perguntas sobre notas pessoais usando RAG (Retrieval-Augmented Generation), um agente com tool/function calling, uma API REST (FastAPI) e um servidor MCP (Model Context Protocol) que permite usar as mesmas ferramentas direto no Claude Desktop / Claude Code.
Transparência sobre este projeto Este repositório foi criado em novembro de 2026, com assistência de IA (Claude Code), como projeto de estudo e portfólio. Ele não é derivado de nenhum trabalho de cliente ou empregador. Todos os documentos em
data/sample/são fictícios (nomes de pessoas e do grupo de estudos são inventados). Os resultados de testes e as saídas mostradas abaixo foram copiados de execuções reais; não há métricas de qualidade de retrieval inventadas.
Problema
Anotações de estudo, planos e atas ficam espalhados em vários arquivos. Buscar por palavra exata é limitado e um LLM sozinho não conhece essas notas (e pode inventar respostas).
Related MCP server: ContextPull
Solução
Ingestão: lê
.md,.txte.json, divide em chunks com overlap e gera embeddings.Vector store em SQLite: vetores salvos como JSON; similaridade de cosseno com numpy.
Retrieval híbrido leve: cosseno + sobreposição de palavras-chave (rerank simples) e remoção de chunks quase duplicados.
Agente: o LLM decide chamar ferramentas (
search_notes,add_note,list_sources,get_current_date) no formato de tool calling da OpenAI, com no máximo N passos, validação de argumentos com Pydantic e erros devolvidos ao modelo para ele corrigir. As respostas citam as fontes ([fonte: arquivo]).Gestão de contexto: contagem aproximada de tokens, orçamento de contexto para os trechos recuperados, janela de histórico + resumo acumulado (rolling summary).
Interfaces: CLI, API REST e servidor MCP (stdio) compartilhando a mesma camada de serviço.
Tudo roda offline e sem chave de API por padrão: embeddings por hashing (bag-of-words)
e um FakeLLM determinístico. OpenAI e Ollama são opcionais via variáveis de ambiente.
Arquitetura
flowchart LR
subgraph Interfaces
CLI["CLI<br/>python -m assistant"]
API["FastAPI<br/>/health /ingest /search /chat"]
MCP["Servidor MCP (stdio)<br/>search_notes, add_note, list_sources<br/>resource notes://sources"]
end
CLI --> SVC
API --> SVC
MCP --> SVC
SVC["AssistantService"] --> AGENT["Agent loop<br/>(max N passos)"]
AGENT <--> LLM["LLM provider<br/>FakeLLM | OpenAI | Ollama (/v1)"]
AGENT --> TOOLS["ToolRegistry<br/>(Pydantic)"]
AGENT --> CTX["Context<br/>token budget + memória"]
TOOLS --> RET["Retriever<br/>cosseno + keywords + dedupe"]
SVC --> ING["Ingestão<br/>md/txt/json → chunks"]
ING --> EMB["Embedder<br/>hash | OpenAI | Ollama"]
RET --> EMB
ING --> DB[("SQLite<br/>vector store")]
RET --> DBStack usada
Item | Uso |
Python 3.12 | linguagem |
Pydantic 2 | validação de argumentos das tools e dos modelos da API |
numpy | similaridade de cosseno |
SQLite ( | vector store persistente |
FastAPI + Uvicorn | API REST |
| servidor MCP via stdio (no SDK 2.x, |
httpx | chamadas ao Ollama |
| LLM/embeddings OpenAI ou endpoint compatível |
pytest, ruff, GitHub Actions | qualidade e CI |
Versões instaladas no ambiente em que os testes foram executados: mcp 2.3.0, fastapi 0.165.0, pydantic 2.14.4, numpy 2.5.5 (macOS, Python 3.12.16).
Estrutura
src/assistant/
__main__.py # CLI
config.py # Settings via variáveis de ambiente
chunking.py # chunks por palavras com overlap
embeddings.py # HashingEmbedder (offline), OpenAIEmbedder, OllamaEmbedder
store.py # vector store SQLite
ingest.py # leitura de md/txt/json e indexação incremental (hash do conteúdo)
retrieval.py # busca híbrida + dedupe
context.py # contagem de tokens, orçamento, memória da conversa
llm.py # OpenAIChatLLM e FakeLLM
tools.py # ferramentas + validação Pydantic
agent.py # loop de tool calling
service.py # camada compartilhada
api.py # FastAPI
mcp_server.py # servidor MCP
data/sample/ # notas fictícias em português
tests/ # pytest (unidade, agente, API, MCP)Como rodar
Pré-requisito: Python 3.12.
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]" # adicione ,openai para usar OpenAI: ".[dev,openai]"
cp .env.example .env # opcional; os padrões já funcionam offlineOs comandos abaixo leem variáveis de ambiente do shell. O arquivo
.envé só um modelo: carregue-o comset -a; source .env; set +ase quiser usá-lo.
1. Ingestão das notas de exemplo
python -m assistant ingestSaída real (primeira execução; numa segunda execução os 6 arquivos aparecem como "sem mudança"):
Arquivos: 6 | indexados: 6 | sem mudança: 0 | chunks novos: 8 | total de chunks no banco: 82. Perguntar ao agente (modo offline, LLM_PROVIDER=fake)
python -m assistant ask "Qual a temperatura do forno para o pão de queijo?"Pelas suas notas:
- Receita: pão de queijo de liquidificador (versão da caderneta) [fonte: receita-pao-de-queijo.txt]
- Asse em forno pré-aquecido a 200 °C por 25 a 30 minutos, até dourar. [fonte: receita-pao-de-queijo.txt]
- 1 xícara de queijo meia cura ralado [fonte: receita-pao-de-queijo.txt]Com --json aparecem as fontes e as chamadas de ferramenta:
python -m assistant ask "Quem ficou responsável pelos testes no grupo?" --json{
"answer": "Pelas suas notas:\n- Bruno fica responsável pelo pipeline de ingestão; Carla pelos testes; Ana pela API. [fonte: reuniao-grupo-estudos.md]\n- Ata — Grupo de Estudos \"Vetores\" (grupo fictício) [fonte: reuniao-grupo-estudos.md]\n- Escolha do projeto final do grupo. [fonte: reuniao-grupo-estudos.md]",
"sources": [
"reuniao-grupo-estudos.md"
],
"steps": 2,
"tool_calls": [
{
"name": "search_notes",
"arguments": "{\"query\": \"Quem ficou responsável pelos testes no grupo?\", \"k\": 3}",
"ok": true
}
]
}O
FakeLLMnão é um modelo de linguagem: ele escolhe a ferramenta por regras simples e monta uma resposta extrativa (frases dos trechos recuperados com mais termos em comum com a pergunta). Por isso às vezes inclui uma frase pouco útil, como o título do documento. Ele existe para que testes e demo rodem sem chave de API. Para respostas geradas de verdade, useLLM_PROVIDER=openaiouLLM_PROVIDER=ollama.
Busca direta, sem LLM:
python -m assistant search "Morro do Pai Inácio" -k 2[0.426] viagem-chapada-diamantina.md#0: # Plano de viagem: Chapada Diamantina (rascunho) **Período:** 12 a 18 de julho **Base:** Lençóis (BA…(Só 1 resultado voltou porque os demais ficaram abaixo do score mínimo de 0.05.)
3. API REST
python -m assistant serve-api --port 8101 # padrão: 127.0.0.1:8101Em outro terminal:
curl -s 127.0.0.1:8101/health
# {"status":"ok","version":"0.1.0","chunks_indexed":8,"embedder":"hash-bow-1024","llm_provider":"fake"}
curl -s -X POST 127.0.0.1:8101/search -H 'Content-Type: application/json' \
-d '{"query": "polvilho azedo", "k": 2}'
# {"results":[{"source":"receita-pao-de-queijo.txt","chunk_index":0,"text":"Receita: pão de queijo ...","score":0.44}]}
# (texto do chunk abreviado aqui)
curl -s -X POST 127.0.0.1:8101/chat -H 'Content-Type: application/json' \
-d '{"message": "Quem ficou responsável pelos testes no grupo?"}'
# devolve session_id, answer, sources, steps e tool_calls; reenvie o session_id para manter o históricoEntradas inválidas retornam 422 (ex.: {"query": "a"}), caminho inexistente em /ingest
retorna 404, e falhas de configuração do LLM em /chat retornam 503. Cada requisição gera
um log JSON em stderr com request_id, method, path, status e duration_ms, e a resposta
traz o header x-request-id.
4. Servidor MCP
python -m assistant serve-mcp # stdio; normalmente quem inicia é o cliente MCPFerramentas expostas: search_notes(query, k), add_note(title, content), list_sources().
Resource: notes://sources (JSON com os documentos indexados).
Exemplo de configuração para o Claude Desktop (claude_desktop_config.json) ou para o
Claude Code (.mcp.json no projeto). Use caminhos absolutos:
{
"mcpServers": {
"personal-notes": {
"command": "/CAMINHO/ABSOLUTO/personal-ai-assistant-rag-mcp/.venv/bin/python",
"args": ["-m", "assistant", "serve-mcp"],
"env": {
"ASSISTANT_DB_PATH": "/CAMINHO/ABSOLUTO/personal-ai-assistant-rag-mcp/assistant.sqlite3"
}
}
}
}No Claude Code também dá para registrar pela linha de comando:
claude mcp add personal-notes \
-e ASSISTANT_DB_PATH=/CAMINHO/ABSOLUTO/assistant.sqlite3 \
-- /CAMINHO/ABSOLUTO/.venv/bin/python -m assistant serve-mcpRode python -m assistant ingest antes, para o banco ter conteúdo. A integração foi testada
automaticamente com o cliente do próprio SDK (tests/test_mcp.py, in-process e via subprocesso
stdio); a conexão manual pelo Claude Desktop não foi testada neste ambiente.
Provedores opcionais
Variável | Valores | Padrão |
|
|
|
|
|
|
| chave / URL de endpoint compatível | vazio |
| URL do Ollama |
|
| nome do modelo |
|
Trocar o embedder exige apagar o banco e reindexar (o store guarda o nome do embedder e recusa misturar vetores de modelos diferentes).
Testes
ruff check .
pytest -q
pytest -q tests/test_mcp.py # só os testes MCPResultados reais obtidos em 19/11/2026 (macOS, Python 3.12.16):
ruff check . -> All checks passed!
pytest -q -> 34 passed in 1.72s
pytest -q tests/test_mcp.py -> 2 passed in 1.11sO que os testes cobrem: chunking/overlap, embeddings determinísticos, vector store e rejeição de
embedder diferente, retrieval e dedupe, orçamento de tokens e memória, validação das tools,
loop do agente com FakeLLM (incluindo recuperação após erro de argumento, limite de passos e
citação automática de fontes), endpoints da API via TestClient e o servidor MCP (in-process e
via stdio). A CI (.github/workflows/ci.yml) roda ruff check e pytest em Python 3.12.
Implementado vs. planejado
Funcionalidade | Status |
Ingestão md/txt/json, chunking com overlap, reindexação incremental | Implementado |
Embeddings offline (hashing) | Implementado e testado |
Embeddings OpenAI / Ollama | Implementado, não testado com serviço real |
Vector store SQLite + cosseno (numpy) | Implementado |
Retrieval híbrido (cosseno + keywords) e dedupe | Implementado (rerank simples, sem BM25 completo) |
Agente com tool calling, validação Pydantic, max passos, citações | Implementado e testado com |
LLM OpenAI / Ollama (endpoint compatível) | Implementado, não testado com serviço real |
Orçamento de tokens, janela de histórico, rolling summary | Implementado (contagem aproximada; resumo extrativo) |
API REST (/health, /ingest, /search, /chat) com logs JSON | Implementado e testado |
Servidor MCP (stdio) com tools + resource | Implementado e testado com o cliente do SDK |
Avaliação de qualidade do retrieval (dataset + métricas) | Planejado |
Resumo da conversa gerado pelo LLM | Planejado |
Persistência das sessões de chat da API | Planejado (hoje ficam em memória) |
Autenticação na API | Planejado |
Busca vetorial indexada (ex.: sqlite-vec) para bases grandes | Planejado |
Limitações
O embedder por hashing é lexical, não semântico: sinônimos não são encontrados.
A busca carrega todos os vetores na memória a cada consulta (ok para centenas/poucos milhares de chunks, não para bases grandes).
Contagem de tokens aproximada (~4 caracteres por token).
add_notesalva a nota apenas no banco, não em arquivo.Sessões do
/chatvivem em memória e se perdem ao reiniciar.Não há métricas de qualidade de respostas; os testes verificam comportamento, não acurácia.
Próximos passos
Criar um pequeno conjunto de perguntas/respostas esperadas e medir hit rate / MRR do retrieval.
Testar com Ollama local e com a OpenAI e documentar as diferenças.
Trocar o resumo extrativo por um resumo gerado pelo LLM.
Adicionar BM25 de verdade e comparar com o rerank atual.
Licença
MIT — veja LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.
A self-hostable feed of reminders, learnings and work that Claude and ChatGPT can read and write
Zotero MCP server for Claude and ChatGPT: search, citations, safe writes, PDF passages and pages.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceIndexes local files (PDF, TXT, CSV, Markdown) with embeddings for semantic search. Provides both CLI and MCP server interfaces so Claude Desktop can search and read your local documents.MIT
- AlicenseNot gradedqualityBmaintenanceTurns a local folder of documents into a queryable index that an LLM agent can pull from on demand, keeping only a compact table of contents in context. Exposes five tools (index, search, read, grep, neighbours) over a single offline SQLite FTS5 store so the model retrieves exact, citable sections instead of being handed whole files.MIT
- FlicenseNot gradedqualityAmaintenanceExposes a local hybrid (vector + BM25) index of scattered notes, docs, PDFs, and chat logs to AI hosts like Claude Desktop, Cursor, and Cline, letting agents search and get cited answers. It publishes a set of tools, resources, and prompts so any MCP-compatible client can query that knowledge base with section-level citations.-
- FlicenseNot gradedqualityAmaintenanceEnables AI agents and MCP hosts to query a local, machine-resident index of scattered notes, project docs, PDFs, Office files, and chat exports using hybrid vector + BM25 retrieval with section-level citations. Exposes tools, resources, and prompts so hosts like Claude Desktop, Cursor, and Cline can search, ask, and explore linked knowledge through natural language.-