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, seguirías teniendo todas tus notas y tareas como archivos .md que puedes abrir con cualquier programa.

¿Por qué otra aplicación de notas?

Porque seguía teniendo que elegir entre un buen software y ser dueño de mis datos:

Usé Obsidian a diario durante dos años. En algún momento, alrededor del plugin número 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 lograr la versión en la que todo lo importante simplemente funciona sin configuración y el formato de datos nunca te toma como rehén.

Related MCP server: MindOS

Qué obtienes

• Notas en Markdown — archivos en el disco con la estructura de carpetas que quieras. Edítalos desde cualquier aplicación; Persona observa el sistema de archivos y se mantiene al día

• Tareas — escribe fix login bug #backend !! friday y ordena la prioridad, la etiqueta de proyecto y la fecha de vencimiento en el frontmatter. Vista Kanban incluida

• Chat de IA — se conecta a Ollama automáticamente si está en ejecución (gratuito 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 local de voz a texto mediante parakeet.cpp en Apple Silicon

• Servidor MCP — Claude Code, Cursor y otros agentes pueden leer y escribir directamente en tu espacio de trabajo

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, basta con persona.

¿Quieres que la IA funcione gratis y en privado?

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

Actualización:

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

Desinstalación:

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

La resolución de problemas se explica en detalle más abajo en este README.

El stack

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

Contribuciones

Las issues y los PRs son bienvenidos, especialmente los informes de errores de uso real. Si algo te parece raro, probablemente lo sea; dímelo.

Licencia

MIT

Si Persona te salva un poco de cordura, una estrella ayuda a que otras personas lo encuentren.

Extras opcionales

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

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 ejecutes persona, una breve guía de configuración te acompaña por tres pasos en el navegador:

1. Espacio de trabajo — donde Persona guarda tus notas (~/Persona por defecto). Se crean Notes/, Projects/ y .persona/tasks/ automáticamente.

2. IA — opcional. Se detecta y conecta un Ollama en ejecución sin configuración; si no, añade cualquier clave de API compatible con OpenAI. Puedes omitirlo en cualquier momento y configurarlo más tarde en Configuración → IA (⌘,).

3. Listo — se crea una nota Notes/Welcome.md como visita guiada del espacio de trabajo: las tres vistas, atajos de teclado y comandos de terminal. Ábrela de nuevo cuando quieras desde la paleta de comandos (⌘K → "Abrir la nota de bienvenida").

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

Comandos

Qué se guarda 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ítalos en cualquier editor, o en Finder: Persona observa 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 cambiar); cada pestaña conserva su propia posición de desplazamiento e historial de deshacer. Etiquetas generadas por IA: pulsa ⌘S (o el botón ✨) y Persona sugiere etiquetas para tu nota, añadidas automáticamente como frontmatter YAML.

• Tareas — lista de tareas personal rápida. Escribe Buy domain tomorrow #personal ! en el cuadro de añadido rápido; las fechas, los proyectos y la prioridad se analizan por ti. Las tareas recurrentes también funcionan: Water plants every week se reabre sola con la próxima fecha de vencimiento cuando la completas. Pulsa Triage (o ejecuta persona triage) y la IA revisa tus tareas abiertas — señala prioridades incorrectas, fechas de vencimiento ausentes, proyectos sin etiquetar, tareas obsoletas y duplicados — y aplica cada sugerencia con un clic. Nunca cambia una tarea sin tu aprobación.

• Tablero de pines — fija notas o tareas importantes (menú ⋯ en el árbol de archivos o en la fila de tareas) y permanecen fijadas en la parte superior de la barra lateral en cada pestaña. Haz clic en un pin para saltar directamente a él; pasa el cursor por encima para desfijarlo. Los pins se guardan en .persona/pins.json y sobreviven a los 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 un pequeño chip de estado por cada acción que realice.

• Agentes — ejecuciones de IA en segundo plano para trabajo de varios pasos. Dale a Persona una tarea como «organiza mis notas de la bandeja de entrada» y la resuelve con herramientas, en directo, sin necesidad de mantener un chat abierto. Las ejecuciones se guardan en .persona/agents/ y pueden cancelarse, reintentarse o eliminarse.

• Búsqueda semántica — tus notas se incrustan localmente y se buscan por significado, de modo que «esa cosa que escribí sobre acampar» encuentra la nota que menciona el bosque, la tienda de campaña y la lluvia, aunque nunca diga «acampar». Alimenta la paleta de comandos (⌘P), persona search y el chat: cuando no adjuntas contexto, el asistente recupera 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 o desactivar desde Ajustes → Módulos; los módulos activados se muestran en la barra lateral, los desactivados siguen siendo accesibles desde ⌘K.

• Importar — importa exportaciones de Obsidian, Bear, Roam, Notion o de carpetas simples desde Ajustes → Importar. Todo queda en Imported/<source>/ y nunca sobrescribe notas existentes.

Teclado

IA

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

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

El asistente de chat puede escribir: puede crear y editar notas, crear carpetas, mover y renombrar archivos, y gestionar tus tareas: crearlas, actualizarlas, completarlas y eliminarlas. Solo elimina archivos o carpetas cuando se lo pides explícitamente. Los proveedores sin soporte de herramientas pasan automáticamente a un chat de solo lectura.

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

1. Una URL base de embeddings explícita (opcional, Ajustes → IA): apúntala a cualquier proveedor compatible con 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 necesidad de clave de API.

3. De lo contrario, el endpoint de tu proveedor de chat.

El índice se reconstruye en segundo plano cuando se inicia el servidor, cuando cambian tu clave de API o tu modelo de embeddings, e incrementalmente cada vez que se guarda una nota. La búsqueda por palabras clave sigue ganando en las coincidencias exactas; los resultados semánticos aparecen como «Mejores coincidencias» cuando aportan valor. Si no hay ninguna fuente de embeddings disponible, la búsqueda recurre silenciosamente a palabras clave únicamente.

Entrada de voz (macOS). El cuadro de chat tiene un botón de micrófono para el reconocimiento de voz local mediante parakeet.cpp. Requiere ffmpeg (brew install ffmpeg) y un modelo GGUF compatible con parakeet. Descarga un parakeet-cli precompilado para macOS desde la página de lanzamientos 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 Ajustes → Apariencia. El tema se guarda en tu configuración y sigue la apariencia de macOS cuando está 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 previa):

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 (p. ej. HOME=$PWD/.testhome npm run dev:server en otra terminal, de modo que la configuración del servidor termine 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}) + Streamable HTTP en http://127.0.0.1:4321/mcp.

Configuración completa → docs/mcp.md.

Contribuciones

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

• Mantén la promesa local-first: todo son archivos simples, sin cuentas, sin nube, sin bloqueo.

• El servidor nunca debe enviar tus archivos a nadie que no sea el proveedor de IA que configuraste explícitamente; el índice de embeddings es local.

• Ejecuta npm run typecheck y npm run build antes de abrir un PR, y añade una prueba en 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