Persona

Persona

Notas, tarefas e um chat de IA que conhece seus arquivos. Tudo vive em uma única pasta de Markdown simples na sua máquina.

$ persona

Isso inicia um servidor local e abre seu workspace no navegador. Sem contas, sem nuvem, sem banco de dados. Se este projeto desaparecesse amanhã, você ainda teria todas as notas e tarefas como arquivos .md que podem ser abertos com qualquer ferramenta.

Por que outro aplicativo de notas?

Porque eu ficava escolhendo entre software bonito e ter controle dos meus dados:

Usei o Obsidian diariamente por dois anos. Em algum lugar por volta do plugin trinta, percebi que estava mais ocupado mantendo minha configuração de notas do que escrevendo nela. Persona é minha tentativa da versão onde tudo que importa funciona de fábrica e o formato dos dados nunca te faz refém.

O que você ganha

• Notas em Markdown — arquivos no disco na estrutura de pastas que você preferir. Edite-os de qualquer aplicativo; Persona observa o sistema de arquivos e se mantém atualizado
• Tarefas — escreva fix login bug #backend !! friday e ele organiza prioridade, tag de projeto e data de vencimento no frontmatter. Visualização Kanban incluída
• Chat de IA — conecta-se ao Ollama automaticamente se estiver em execução (gratuito e privado), ou use qualquer API compatível com OpenAI. Ele pode criar notas e gerenciar tarefas, não apenas responder perguntas
• Busca semântica — embeddings calculados localmente, armazenados dentro do workspace
• Entrada por voz — transcrição de fala local via parakeet.cpp no Apple Silicon
• Servidor MCP — Claude Code, Cursor e outros agentes podem ler/escrever seu workspace diretamente

Capturas de tela

Início rápido (macOS)

Você precisa de Node.js 20+ (brew install node) e git.

git clone https://github.com/jayamitkatariya/personacli.git
cd personacli
npm install --allow-scripts=persona
npm install -g . --allow-scripts=persona
persona

A primeira execução guia você na escolha de uma pasta de workspace e, opcionalmente, na conexão de um modelo de IA. Depois disso, é só persona.

Quer que a IA rode gratuita e privada?

brew install ollama && ollama pull llama3.2
persona   # detects ollama automatically, no config

persona doctor   # health check: node, workspace, server, AI config
persona path     # print workspace path

cd personacli && git pull
npm install --allow-scripts=persona
npm install -g . --allow-scripts=persona

npm uninstall -g persona
pkill -f "dist/server/index"
rm -rf ~/.persona

A stack

TypeScript de ponta a ponta. Interface React servida por um servidor Hono, Vite para builds. Embeddings locais para busca, parakeet.cpp para voz, Ollama ou qualquer endpoint compatível com OpenAI para chat. Tecnologia simples de propósito.

Contribuindo

Issues e PRs são bem-vindos, especialmente relatos de bugs de uso real. Se algo parecer errado, provavelmente está; me avise.

Licença

MIT

Se Persona te poupar um pouco de sanidade, uma estrela ajuda outras pessoas a encontrá-lo.

Extras opcionais

Para entrada por voz, aponte o Persona para seu binário e modelo parakeet:

export PERSONA_STT_BIN=/path/to/parakeet-cli
export PERSONA_STT_MODEL=/path/to/model.gguf
persona

Solução de problemas

Primeira execução

Na primeira vez que você executar persona, um guia de configuração rápido orienta você por três etapas no navegador:

1. Workspace — onde o Persona armazena suas notas (~/Persona por padrão). Notes/, Projects/ e .persona/tasks/ são criados para você.
2. IA — opcional. Um Ollama em execução é detectado e conectado com zero configuração; caso contrário, adicione qualquer chave de API compatível com OpenAI. Pule a qualquer momento e configure depois em Configurações → IA (⌘,).
3. Concluído — uma nota Notes/Welcome.md é criada como um tour guiado do workspace: as três visualizações, atalhos de teclado e comandos de terminal. Abra-a novamente a qualquer momento pela paleta de comandos (⌘K → "Abrir nota de boas-vindas").

Nada é sobrescrito: se a pasta do workspace já tiver arquivos, eles aparecem na barra lateral intactos, e a nota de boas-vindas é criada apenas uma vez.

Comandos

O que fica onde

~/Persona/                  ← your workspace (choose it on first run)
├── Notes/                  ← plain Markdown, organised however you like
├── Projects/
│   └── my-project/
│       └── PRD.md
├── Imported/               ← notes brought in from other apps
│   ├── obsidian/
│   ├── bear/
│   ├── roam/
│   ├── notion/
│   └── plain/
└── .persona/
    ├── tasks/              ← tasks are Markdown files with frontmatter
    ├── agents/             ← background agent runs (JSON)
    ├── pins.json           ← your pinboard (pinned notes & tasks)
    └── embeddings/         ← local semantic-search index (notes, not secrets)

Tarefas são apenas arquivos:

---
type: task
status: todo
priority: high
due: 2026-08-12
project: Personal
---
Finish Persona PRD

Edite-os em qualquer editor, ou no Finder — Persona observa o sistema de arquivos e sincroniza automaticamente.

Workspaces

• Escrever — árvore de arquivos + editor Markdown (CodeMirror). Salvamento automático, status de salvamento, pré-visualização ao vivo (Editar / Dividir / Pré-visualizar), renomear, mover, duplicar, excluir, arrastar e soltar. Abra várias notas ao mesmo tempo em abas (⌘W para fechar, ⌘⇧[ / ⌘⇧] para alternar); cada aba mantém sua própria posição de rolagem e histórico de desfazer. Tags geradas por IA: pressione ⌘S (ou o botão ✨) e o Persona sugere tags para sua nota, adicionadas automaticamente como frontmatter YAML.
• Tarefas — lista de tarefas pessoal rápida. Digite Buy domain tomorrow #personal ! na caixa de adição rápida; datas, projetos e prioridade são interpretados para você. Tarefas recorrentes também funcionam: Water plants every week se reabre com a próxima data de vencimento quando você a conclui. Clique em Triagem (ou execute persona triage) e a IA revisa suas tarefas abertas — sinalizando prioridades erradas, datas de vencimento ausentes, projetos sem tag, tarefas obsoletas e duplicatas — e aplica cada sugestão com um clique. Ela nunca muda uma tarefa sem sua aprovação.
• Quadro de avisos — fixe notas ou tarefas importantes (menu ⋯ na árvore de arquivos ou na linha da tarefa) e elas permanecem fixadas no topo da barra lateral em todas as abas. Clique em um alfinete para ir direto até ele; passe o mouse para desafixar. Os alfinetes ficam em .persona/pins.json e sobrevivem a reinicializações.
• Chat — uma IA que pode ver seu workspace e agir sobre ele. Anexe contexto com @file.md, @folder ou @tasks e pergunte sobre seu trabalho real. A IA também pode criar, editar, mover e excluir notas e pastas, e criar, concluir, atualizar e excluir tarefas em seu nome — você verá um pequeno indicador de status para cada ação que ela executa.
• Agentes — execuções de IA em segundo plano para trabalho com várias etapas. Dê ao Persona uma tarefa como "organize minhas notas da caixa de entrada" e ele trabalha nela com ferramentas, ao vivo, sem manter um chat aberto. As execuções são persistidas em .persona/agents/ e podem ser canceladas, repetidas ou excluídas.
• Busca semântica — suas notas são incorporadas localmente e buscadas por significado, então "aquela coisa que escrevi sobre acampar" encontra a nota que menciona a floresta, a barraca e a chuva — mesmo que nunca diga "acampar". Ela alimenta a paleta de comandos (⌘P), persona search e o chat: quando você não anexa contexto, o assistente puxa automaticamente as notas mais relevantes para sua pergunta e as cita.
• Módulos — Foco, Diário, Coisas de Hoje e Agentes podem ser ativados/ desativados em Configurações → Módulos; módulos habilitados aparecem na barra lateral, os desabilitados permanecem acessíveis via ⌘K.
• Importar — traga exportações do Obsidian, Bear, Roam, Notion ou pastas simples de Configurações → Importar. Tudo vai para Imported/<source>/ e nunca sobrescreve notas existentes.

Teclado

IA

Qualquer provedor compatível com OpenAI funciona — OpenAI, OpenRouter, Ollama, modelos locais, endpoints personalizados. Configure provedor, URL base, modelo e chave de API em Configurações → IA. A chave é armazenada no Chaveiro do macOS (com fallback para um arquivo de configuração com permissão 0600) e só é enviada ao provedor que você escolheu.

Zero configuração com Ollama. Se uma instância local do Ollama estiver em execução (http://127.0.0.1:11434, ou onde $OLLAMA_HOST apontar), o Persona a detecta automaticamente e conecta sem chave de API e sem configuração. Ele escolhe um modelo de chat sensato entre os que você tem instalados. Um provedor configurado explicitamente sempre tem precedência sobre a detecção automática, e persona doctor informa o que foi detectado.

O assistente de chat tem capacidade de escrita: ele pode criar e editar notas, criar pastas, mover e renomear arquivos, e gerenciar suas tarefas — criar, atualizar, concluir e excluir. Ele exclui arquivos ou pastas apenas quando você pede explicitamente. Provedores sem suporte a ferramentas caem automaticamente para chat somente leitura.

Busca semântica. As notas são divididas em blocos e incorporadas localmente, armazenadas em .persona/embeddings/. Os embeddings vêm, em ordem de prioridade:

1. Uma URL base de embedding explícita (opcional, Configurações → IA) — aponte para qualquer provedor com capacidade de embeddings (OpenRouter, SiliconFlow, um Ollama local…).
2. Um Ollama local em execução com um modelo de embedding — ex. ollama pull all-minilm ou nomic-embed-text — sem chave de API necessária.
3. Caso contrário, o endpoint do seu provedor de chat.

O índice é reconstruído em segundo plano quando o servidor inicia, quando sua chave de API ou modelo de embedding muda, e incrementalmente sempre que uma nota é salva. A busca por palavras-chave ainda vence para correspondências exatas; resultados semânticos aparecem como "Melhores correspondências" quando agregam valor. Se nenhuma fonte de embedding estiver disponível, a busca cai silenciosamente para apenas palavras-chave. Entrada de voz (macOS). A caixa de chat tem um botão de microfone para transcrição de fala local via parakeet.cpp. Requer ffmpeg (brew install ffmpeg) e um modelo GGUF compatível com parakeet. Pegue um parakeet-cli pré-compilado para macOS na página de releases e aponte o Persona para ambos com PERSONA_STT_MODEL=/path/to/model.gguf e PERSONA_STT_BIN=/path/to/parakeet-cli (em Apple Silicon o modelo roda em Metal).

Aparência

Tema claro, escuro ou do sistema em Configurações → Aparência. O tema é salvo na sua configuração e segue a aparência do macOS quando definido como Sistema.

Desenvolvimento

npm run dev        # Vite dev server (5173) + API server (4321), hot reload
npm run build      # production build: server + CLI + web app
npm run typecheck

Scripts de teste ad-hoc (é preciso compilar antes):

npm run build
node scripts/tool-test.mjs       # unit-level tests for AI tools, tasks, fs
node scripts/mcp-test.mjs        # E2E: MCP server via stdio (Persona tools over MCP)
node scripts/e2e-chat-test.mjs   # E2E: AI chat performs file & task operations
node scripts/e2e-chat2-test.mjs  # E2E: chat reads notes and cites sources

Os scripts E2E esperam que um servidor esteja rodando contra um workspace descartável (por exemplo, HOME=$PWD/.testhome npm run dev:server em outro terminal, para que a configuração do servidor vá para .testhome/.persona/).

MCP — use o Persona a partir do Claude Code, Hermes, Cursor, etc.

O Persona é um servidor MCP. Qualquer cliente MCP pode ler/gravar seu workspace:

persona mcp --help
claude mcp add persona -- persona mcp   # Claude Code
# Hermes/Cursor/Windsurf: { "mcpServers": { "persona": { "command": "persona", "args": ["mcp"] } } }

Ferramentas: 15 (list_folder, read_note, create_note, write_note, append_note, create_folder, move_file, rename_file, delete_file, list_tasks, create_task, update_task, delete_task, search, get_workspace_info) + recursos (persona://workspace, persona://file/{path}) + HTTP Streamable em http://127.0.0.1:4321/mcp.

Configuração completa → docs/mcp.md.

Contribuindo

Abra uma issue ou PR — relatos de bugs, ideias de recursos e perguntas são todos bem-vindos. Diretrizes:

• Mantenha a promessa local-first: tudo são arquivos simples, sem contas, sem nuvem, sem lock-in.
• O servidor nunca deve enviar seus arquivos para ninguém além do provedor de IA que você configurou explicitamente; o índice de embeddings é local.
• Execute npm run typecheck e npm run build antes de abrir um PR, e adicione um teste scripts/ quando mexer no comportamento do servidor.
• O pacote é licenciado sob MIT; ao contribuir, você concorda com os mesmos termos.

Arquitetura

persona CLI ── spawns ──▶ local Hono server (127.0.0.1:4321 — first free port)
                              │  REST API + SSE events
                              ├─ filesystem (chokidar watcher)
                              ├─ tasks (Markdown + frontmatter)
                              ├─ AI (OpenAI-compatible, streaming)
                              └─ embeddings (semantic index, local JSON)
                              │
                              ▼
                    React app (prebuilt, served by the server)

Histórico de Estrelas