# Kimun

Terminal Markdown notes app with search, a scriptable CLI and an MCP server.

Kimun is a local-first Rust notes app for plain Markdown vaults with a TUI, a CLI and a built-in MCP server over stdio. The MCP server has 18 tools for notes, properties, links and journals plus 7 review prompts. An optional server adds semantic search and question answering over your notes.

- Capabilities: adaptable, operable
- Vertical: notes-knowledge
- Shape: product
- Form factor: cli
- Execution model: deterministic
- Provenance: unknown (recorded, never ranked)
- Repo: https://github.com/nico2sh/kimun (MIT), 64 stars, last commit 2026-11-02
- Last activity: 2026-11-02
- Page: apps/nico2sh--kimun.html
- JSON: apps/nico2sh--kimun.json

## Use it when

- you keep notes as Markdown files and want your agent to search, link and journal in them
- you live in a terminal and want an Obsidian-compatible vault with scriptable access

## Gotchas

- README warns the app is in heavy development and config or themes may break after updates
- semantic search and Ask need the separate kimun-server and an embedding model download of a few hundred MB
- One person writes almost all the code; outside use is small but real
- The Docker image is the optional kimun-server, not the notes app

## Editions

- Free: Free, open source
  - installable: curl -fsSL https://kimun.2co.dev/install.sh | sh
  - installable: brew tap nico2sh/kimun && brew install kimun
  - installable: cargo install kimun-notes
  - container: docker run -d --name kimun-server -p 7573:7573 -v kimun-server-data:/data ghcr.io/nico2sh/kimun-server:latest
  - source: https://github.com/nico2sh/kimun

## Adaptable: make it yours

Effort: light-edit (4 things to edit)

config.toml sets theme, key bindings, leader-key tree, sort order, workspaces and the optional server URL. These are personal interface settings, not business behavior. The MCP review prompts are compiled into the Rust source (tui/src/cli/commands/mcp/prompts.rs), so changing them needs a code edit.

- Env vars: KIMUN_INSTALL_DIR
- Config files: config.toml
- Prompt files: tui/src/cli/commands/mcp/prompts.rs, skills/kimun-cli/SKILL.md
- Accounts you'll need: none

## Operable: what an agent can drive

Operability: official. Interface: mcp at https://nico2sh.github.io/kimun/using-kimun/ai-mcp-server/ (published by the builder, local).

### Reach (partial coverage)

- Create, append to and edit notes: reachable. MCP tools create_note, append_note, overwrite_note, replace_in_note
- Delete notes: reachable. MCP tool delete_note (marked destructive, backed up first)
- Search notes: reachable. MCP tool search_notes; CLI kimun search
- Read notes and list the vault: reachable. MCP tools show_note, list_notes, get_chunks; notes also exposed as note:// resources
- Follow links and backlinks: reachable. MCP tools get_backlinks and get_outlinks
- Read and set frontmatter properties: reachable. MCP tools get_properties, set_property, remove_property
- Rename and move notes with link updates: reachable. MCP tools rename_note and move_note
- Journal and quick capture to the inbox: reachable. MCP tools journal and quick_note; CLI kimun journal append
- Manage workspaces (vaults): not reachable. No MCP tool in tui/src/cli/commands/mcp/mod.rs; the CLI covers it with kimun workspace init/list/use/rename/remove/reindex
- Semantic search and Ask over notes: not reachable. No MCP tool or CLI command. The optional kimun-server exposes POST /api/answer and GET /api/job/{job_id} over HTTP with a bearer token

## Code stack

- Languages: Rust
- Frameworks: Ratatui
- Package manager: cargo
- Database: SQLite
- Hosting target: local

## Skills

bundled: A kimun-cli skill teaches an agent the kimun CLI; the README gives the copy command.
- Paths: skills/kimun-cli/SKILL.md
- Install: cp -r skills/kimun-cli ~/.claude/skills

## Evidence and confidence

- formFactor: README: terminal-based notes app, TUI and CLI (confidence 0.85)
- executionModel: notes, search and MCP tools are code; Ask is an optional server with an LLM (confidence 0.8)
- operability: docs/content/using-kimun/ai-mcp-server.md lists 18 tools and 7 prompts; tui/src/cli/commands/mcp/mod.rs has 18 #[tool] entries; published by the same owner at nico2sh.github.io/kimun (confidence 0.9)
- effort: docs configuration.md and example/config.toml cover theme, key bindings, workspaces and paths only (confidence 0.7)
- editions: MIT; install script, Homebrew and Cargo in README; no price seen (confidence 0.85)
- active: GitHub commits API: last commit 2026-11-02; release kimun-notes-v0.24.7
- outsideUsers: 64 stars. Six issues from three outside authors between June and September 2026, with replies. A pull request and 7 commits from two other outside contributors. 5 forks. crates.io: 1,375 downloads, 336 recent
- reach:  (confidence 0.9)

## Open questions

- Provenance unknown

## Sources

- https://nico2sh.github.io/kimun/ (sourcing:notes-knowledge:community)