Persona

Notes, tasks, and an AI chat that knows your files. Everything lives in one folder of plain Markdown on your machine.

$ persona

That starts a local server and opens your workspace in the browser. No accounts, no cloud, no database. If this project vanished tomorrow, you'd still have every note and task as .md files you can open with anything.

Why another notes app?

Because I kept choosing between nice software and owning my data:

I used Obsidian daily for two years. Somewhere around plugin thirty I realized I was maintaining my note setup more than writing in it. Persona is my attempt at the version where everything important just works out of the box and the data format never holds you hostage.

Related MCP server: MindOS

What you get

• Markdown notes — files on disk in whatever folder structure you like. Edit them from any app; Persona watches the filesystem and keeps up

• Tasks — write fix login bug #backend !! friday and it sorts out priority, project tag and due date into frontmatter. Kanban view included

• AI chat — connects to Ollama automatically if it's running (free and private), or use any OpenAI-compatible API. It can create notes and manage tasks, not just answer questions

• Semantic search — embeddings computed locally, stored inside the workspace

• Voice input — local speech-to-text via parakeet.cpp on Apple Silicon

• MCP server — Claude Code, Cursor and other agents can read/write your workspace directly

Screenshots

Quick start (macOS)

You need Node.js 20+ (brew install node) and git.

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

First run walks you through picking a workspace folder and optionally connecting an AI model. After that it's just persona.

Want the AI to run free and private?

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

Updating:

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

Uninstalling:

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

Troubleshooting lives in full detail further down this README.

The stack

TypeScript end to end. React UI served by a Hono server, Vite for builds. Local embeddings for search, parakeet.cpp for voice, Ollama or any OpenAI-compatible endpoint for chat. Boring tech on purpose.

Contributing

Issues and PRs welcome, especially bug reports from real usage. If something feels off, it probably is; tell me.

License

MIT

If Persona saves you some sanity, a star helps other people find it.

Optional extras

For voice input, point Persona at your parakeet binary and model:

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

Troubleshooting

First run

The first time you run persona, a short setup guide walks you through three steps in the browser:

1. Workspace — where Persona stores your notes (~/Persona by default). Notes/, Projects/ and .persona/tasks/ are created for you.

2. AI — optional. A running Ollama is detected and connected with zero setup; otherwise add any OpenAI-compatible API key. Skip any time and set it up later in Settings → AI (⌘,).

3. Done — a Notes/Welcome.md note is created as a guided tour of the workspace: the three views, keyboard shortcuts and terminal commands. Open it again any time from the command palette (⌘K → "Open Welcome note").

Nothing is ever overwritten: if the workspace folder already has files, they appear in the sidebar untouched, and the welcome note is only created once.

Commands

What lives where

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

Tasks are just files:

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

Edit them in any editor, or in Finder — Persona watches the filesystem and syncs automatically.

Workspaces

• Write — file tree + Markdown editor (CodeMirror). Autosave, save status, live preview (Edit / Split / Preview), rename, move, duplicate, delete, drag & drop. Open several notes at once in tabs (⌘W to close, ⌘⇧[ / ⌘⇧] to cycle); each tab keeps its own scroll position and undo history. AI-generated tags: press ⌘S (or the ✨ button) and Persona suggests tags for your note, added automatically as YAML frontmatter.

• Tasks — fast personal task list. Type Buy domain tomorrow #personal ! in the quick-add box; dates, projects and priority are parsed for you. Recurring tasks work too: Water plants every week reopens itself with the next due date when you complete it. Hit Triage (or run persona triage) and the AI reviews your open tasks — flagging wrong priorities, missing due dates, untagged projects, stale tasks and duplicates — and applies each suggestion with one click. It never changes a task without you approving.

• Pinboard — pin important notes or tasks (⋯ menu in the file tree or task row) and they stay pinned to the top of the sidebar on every tab. Click a pin to jump straight to it; hover to unpin. Pins live in .persona/pins.json and survive restarts.

• Chat — an AI that can see your workspace and act on it. Attach context with @file.md, @folder or @tasks and ask about your actual work. The AI can also create, edit, move and delete notes and folders, and create, complete, update and delete tasks on your behalf — you'll see a small status chip for each action it takes.

• Agents — background AI runs for multi-step work. Give Persona a task like "organize my inbox notes" and it works through it with tools, live, without holding a chat open. Runs are persisted under .persona/agents/ and can be cancelled, retried, or deleted.

• Semantic search — your notes are embedded locally and searched by meaning, so "that thing I wrote about camping" finds the note that mentions the forest, the tent, and the rain — even if it never says "camping". It powers the command palette (⌘P), persona search, and the chat: when you don't attach context, the assistant automatically pulls in the notes most relevant to your question and cites them.

• Modules — Focus, Journal, Today's Stuff, and Agents are toggleable from Settings → Modules; enabled modules show in the sidebar, disabled ones stay reachable from ⌘K.

• Import — bring in Obsidian, Bear, Roam, Notion, or plain-folder exports from Settings → Import. Everything lands under Imported/<source>/ and never overwrites existing notes.

Keyboard

AI

Any OpenAI-compatible provider works — OpenAI, OpenRouter, Ollama, local models, custom endpoints. Configure provider, base URL, model and API key in Settings → AI. The key is stored in the macOS Keychain (falls back to a 0600-permissioned config file) and is only ever sent to the provider you chose.

Zero setup with Ollama. If a local Ollama instance is running (http://127.0.0.1:11434, or wherever $OLLAMA_HOST points), Persona detects it automatically and connects with no API key and no configuration. It picks a sensible chat model from the ones you have installed. An explicitly configured provider always takes precedence over auto-detection, and persona doctor reports what was detected.

The chat assistant is write-capable: it can create and edit notes, create folders, move and rename files, and manage your tasks — create, update, complete and delete them. It deletes files or folders only when you explicitly ask it to. Providers without tool support automatically fall back to read-only chat.

Semantic search. Notes are chunked and embedded locally and stored in .persona/embeddings/. Embeddings come from, in priority order:

1. An explicit embedding base URL (optional, Settings → AI) — point this at any embeddings-capable provider (OpenRouter, SiliconFlow, a local Ollama…).

2. A running local Ollama with an embedding model — e.g. ollama pull all-minilm or nomic-embed-text — no API key required.

3. Otherwise, your chat provider's endpoint.

The index rebuilds in the background when the server starts, when your API key or embedding model changes, and incrementally whenever a note is saved. Keyword search still wins for exact matches; semantic results appear as "Best matches" when they add value. If no embedding source is available, search silently falls back to keyword-only.

Voice input (macOS). The chat box has a mic button for local speech-to-text via parakeet.cpp. Requires ffmpeg (brew install ffmpeg) and a parakeet-compatible GGUF model. Grab a prebuilt parakeet-cli for macOS from the releases page and point Persona at both with PERSONA_STT_MODEL=/path/to/model.gguf and PERSONA_STT_BIN=/path/to/parakeet-cli (on Apple Silicon the model runs on Metal).

Appearance

Light, dark, or system theme in Settings → Appearance. The theme is saved in your config and follows your macOS appearance when set to System.

Development

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

Ad-hoc test scripts (need a build first):

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

The E2E scripts expect a server to be running against a throwaway workspace (e.g. HOME=$PWD/.testhome npm run dev:server on another terminal, so the server's config lands in .testhome/.persona/).

MCP — use Persona from Claude Code, Hermes, Cursor, etc.

Persona is an MCP server. Any MCP client can read/write your workspace:

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

Tools: 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) + resources (persona://workspace, persona://file/{path}) + Streamable HTTP at http://127.0.0.1:4321/mcp.

Full setup → docs/mcp.md.

Contributing

Open an issue or PR — bug reports, feature ideas and questions are all welcome. Guidelines:

• Keep the local-first promise: everything is plain files, no accounts, no cloud, no lock-in.

• The server must never send your files to anyone but the AI provider you explicitly configured; the embeddings index is local.

• Run npm run typecheck and npm run build before opening a PR, and add a scripts/ test when you touch server behaviour.

• Package is MIT licensed; by contributing you agree to the same terms.

Architecture

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)

Star History