Persona

Persona

Notas, tareas y un chat de IA que conoce tus archivos. Todo vive en una carpeta de Markdown plano en tu máquina.

$ persona

Eso inicia un servidor local y abre tu espacio de trabajo en el navegador. Sin cuentas, sin nube, sin base de datos. Si este proyecto desapareciera mañana, aún tendrías cada nota y tarea como archivos .md que puedes abrir con cualquier herramienta.

¿Por qué otra app de notas?

Porque seguía eligiendo entre software bonito y ser dueño de mis datos:

Usé Obsidian a diario durante dos años. En algún momento alrededor del plugin treinta me di cuenta de que estaba manteniendo mi configuración de notas más de lo que escribía en ella. Persona es mi intento de la versión donde todo lo importante funciona de serie y el formato de datos nunca te toma como rehén.

Lo que obtienes

• Notas en Markdown — archivos en disco en la estructura de carpetas que prefieras. Edítalas desde cualquier app; Persona vigila el sistema de archivos y se mantiene al día
• Tareas — escribe fix login bug #backend !! friday y ordena prioridad, etiqueta de proyecto y fecha de vencimiento en el frontmatter. Vista Kanban incluida
• Chat de IA — se conecta a Ollama automáticamente si está en ejecución (gratis y privado), o usa cualquier API compatible con OpenAI. Puede crear notas y gestionar tareas, no solo responder preguntas
• Búsqueda semántica — embeddings calculados localmente, almacenados dentro del espacio de trabajo
• Entrada por voz — conversión de voz a texto local mediante parakeet.cpp en Apple Silicon
• Servidor MCP — Claude Code, Cursor y otros agentes pueden leer/escribir tu espacio de trabajo directamente

Capturas de pantalla

Inicio rápido (macOS)

Necesitas Node.js 20+ (brew install node) y git.

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

La primera ejecución te guía para elegir una carpeta de espacio de trabajo y opcionalmente conectar un modelo de IA. Después de eso, solo es persona.

¿Quieres que la IA funcione gratis y 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

La pila tecnológica

TypeScript de principio a fin. Interfaz React servida por un servidor Hono, Vite para compilaciones. Embeddings locales para búsqueda, parakeet.cpp para voz, Ollama o cualquier endpoint compatible con OpenAI para el chat. Tecnología aburrida a propósito.

Contribuciones

Issues y PRs bienvenidos, especialmente informes de errores de uso real. Si algo se siente mal, probablemente lo esté; cuéntamelo.

Licencia

MIT

Si Persona te ahorra algo de cordura, una estrella ayuda a que otros lo encuentren.

Extras opcionales

Para entrada por voz, apunta Persona a tu binario parakeet y modelo:

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

Solución de problemas

Primera ejecución

La primera vez que ejecutas persona, una breve guía de configuración te lleva por tres pasos en el navegador:

1. Espacio de trabajo — donde Persona almacena tus notas (~/Persona por defecto). Notes/, Projects/ y .persona/tasks/ se crean para ti.
2. IA — opcional. Un Ollama en ejecución se detecta y conecta con cero configuración; de lo contrario, agrega cualquier clave API compatible con OpenAI. Omítelo en cualquier momento y configúralo después en Configuración → IA (⌘,).
3. Listo — se crea una nota Notes/Welcome.md como recorrido guiado del espacio de trabajo: las tres vistas, atajos de teclado y comandos de terminal. Ábrela de nuevo en cualquier momento desde la paleta de comandos (⌘K → "Abrir nota de bienvenida").

Nada se sobrescribe nunca: si la carpeta del espacio de trabajo ya tiene archivos, aparecen en la barra lateral sin tocarlos, y la nota de bienvenida solo se crea una vez.

Comandos

Qué vive dónde

~/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)

Las tareas son solo archivos:

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

Edítalas en cualquier editor, o en Finder — Persona vigila el sistema de archivos y sincroniza automáticamente.

Espacios de trabajo

• Escribir — árbol de archivos + editor Markdown (CodeMirror). Autoguardado, estado de guardado, vista previa en vivo (Editar / Dividir / Vista previa), renombrar, mover, duplicar, eliminar, arrastrar y soltar. Abre varias notas a la vez en pestañas (⌘W para cerrar, ⌘⇧[ / ⌘⇧] para alternar); cada pestaña mantiene su propia posición de desplazamiento e historial de deshacer. Etiquetas generadas por IA: presiona ⌘S (o el botón ✨) y Persona sugiere etiquetas para tu nota, agregadas automáticamente como frontmatter YAML.
• Tareas — lista de tareas personal rápida. Escribe Buy domain tomorrow #personal ! en el cuadro de agregado rápido; fechas, proyectos y prioridad se analizan por ti. Las tareas recurrentes también funcionan: Water plants every week se reabre con la próxima fecha de vencimiento cuando la completas. Pulsa Triaje (o ejecuta persona triage) y la IA revisa tus tareas abiertas — señalando prioridades incorrectas, fechas de vencimiento faltantes, proyectos sin etiquetar, tareas obsoletas y duplicados — y aplica cada sugerencia con un clic. Nunca cambia una tarea sin tu aprobación.
• Tablero — fija notas o tareas importantes (menú ⋯ en el árbol de archivos o fila de tarea) y permanecen fijadas en la parte superior de la barra lateral en cada pestaña. Haz clic en un pin para ir directamente; pasa el cursor para desfijar. Los pines viven en .persona/pins.json y sobreviven reinicios.
• Chat — una IA que puede ver tu espacio de trabajo y actuar sobre él. Adjunta contexto con @file.md, @folder o @tasks y pregunta sobre tu trabajo real. La IA también puede crear, editar, mover y eliminar notas y carpetas, y crear, completar, actualizar y eliminar tareas en tu nombre — verás una pequeña insignia de estado por cada acción que realiza.
• Agentes — ejecuciones de IA en segundo plano para trabajo de múltiples pasos. Dale a Persona una tarea como "organiza mis notas de la bandeja de entrada" y trabaja en ella con herramientas, en vivo, sin mantener un chat abierto. Las ejecuciones se persisten bajo .persona/agents/ y se pueden cancelar, reintentar o eliminar.
• Búsqueda semántica — tus notas se incrustan localmente y se buscan por significado, así "eso que escribí sobre acampar" encuentra la nota que menciona el bosque, la tienda y la lluvia — incluso si nunca dice "acampar". Impulsa la paleta de comandos (⌘P), persona search y el chat: cuando no adjuntas contexto, el asistente trae automáticamente las notas más relevantes para tu pregunta y las cita.
• Módulos — Enfoque, Diario, Lo de hoy y Agentes se pueden activar/desactivar desde Configuración → Módulos; los módulos habilitados se muestran en la barra lateral, los deshabilitados siguen accesibles desde ⌘K.
• Importar — trae exportaciones de Obsidian, Bear, Roam, Notion o carpetas planas desde Configuración → Importar. Todo aterriza bajo Imported/<source>/ y nunca sobrescribe notas existentes.

Teclado

IA

Cualquier proveedor compatible con OpenAI funciona — OpenAI, OpenRouter, Ollama, modelos locales, endpoints personalizados. Configura proveedor, URL base, modelo y clave API en Configuración → IA. La clave se almacena en el Llavero de macOS (con respaldo a un archivo de configuración con permisos 0600) y solo se envía al proveedor que elegiste.

Configuración cero con Ollama. Si una instancia local de Ollama está en ejecución (http://127.0.0.1:11434, o donde sea que $OLLAMA_HOST apunte), Persona la detecta automáticamente y se conecta sin clave API y sin configuración. Elige un modelo de chat sensato de los que tienes instalados. Un proveedor configurado explícitamente siempre tiene prioridad sobre la detección automática, y persona doctor informa lo que se detectó.

El asistente de chat tiene capacidad de escritura: puede crear y editar notas, crear carpetas, mover y renombrar archivos, y gestionar tus tareas — crearlas, actualizarlas, completarlas y eliminarlas. Elimina archivos o carpetas solo cuando se lo pides explícitamente. Los proveedores sin soporte de herramientas caen automáticamente a chat de solo lectura.

Búsqueda semántica. Las notas se dividen en fragmentos y se incrustan localmente y se almacenan en .persona/embeddings/. Los embeddings provienen de, en orden de prioridad:

1. Una URL base de embeddings explícita (opcional, Configuración → IA) — apúntala a cualquier proveedor con capacidad de embeddings (OpenRouter, SiliconFlow, un Ollama local…).
2. Un Ollama local en ejecución con un modelo de embeddings — p. ej. ollama pull all-minilm o nomic-embed-text — sin clave API requerida.
3. De lo contrario, el endpoint de tu proveedor de chat.

El índice se reconstruye en segundo plano cuando el servidor inicia, cuando tu clave API o modelo de embeddings cambia, e incrementalmente cada vez que se guarda una nota. La búsqueda por palabras clave sigue ganando para coincidencias exactas; los resultados semánticos aparecen como "Mejores coincidencias" cuando agregan valor. Si no hay fuente de embeddings disponible, la búsqueda cae silenciosamente a solo palabras clave. Entrada de voz (macOS). El cuadro de chat tiene un botón de micrófono para conversión de voz a texto local mediante parakeet.cpp. Requiere ffmpeg (brew install ffmpeg) y un modelo GGUF compatible con parakeet. Obtén un parakeet-cli precompilado para macOS desde la página de versiones y apunta Persona a ambos con PERSONA_STT_MODEL=/path/to/model.gguf y PERSONA_STT_BIN=/path/to/parakeet-cli (en Apple Silicon el modelo se ejecuta en Metal).

Apariencia

Tema claro, oscuro o del sistema en Configuración → Apariencia. El tema se guarda en tu configuración y sigue la apariencia de macOS cuando se establece en Sistema.

Desarrollo

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 prueba ad hoc (necesitan una compilación primero):

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

Los scripts E2E esperan que un servidor se esté ejecutando contra un espacio de trabajo desechable (por ejemplo, HOME=$PWD/.testhome npm run dev:server en otra terminal, para que la configuración del servidor aterrice en .testhome/.persona/).

MCP — usa Persona desde Claude Code, Hermes, Cursor, etc.

Persona es un servidor MCP. Cualquier cliente MCP puede leer/escribir tu espacio de trabajo:

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

Herramientas: 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 en http://127.0.0.1:4321/mcp.

Configuración completa → docs/mcp.md.

Contribuciones

Abre un issue o PR — los informes de errores, ideas de funciones y preguntas son todos bienvenidos. Pautas:

• Mantén la promesa de local-primero: todo son archivos simples, sin cuentas, sin nube, sin bloqueo.
• El servidor nunca debe enviar tus archivos a nadie más que al proveedor de IA que configuraste explícitamente; el índice de incrustaciones es local.
• Ejecuta npm run typecheck y npm run build antes de abrir un PR, y agrega una prueba scripts/ cuando toques el comportamiento del servidor.
• El paquete tiene licencia MIT; al contribuir aceptas los mismos términos.

Arquitectura

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)

Historial de estrellas