recalla 0.5.0

A local-first, agent-native second brain. Pull it, run it, own it.

recalla

a private, local-first, agent-native second brain

turn a markdown or obsidian vault into a fast, agent-readable brain you can search, chat with, and let your agents read. it runs entirely on your machine. no cloud, no account, no telemetry.

install · how it works · cli · mcp · the ecosystem · privacy

---

$ pip install 'recalla[mcp,semantic]'
$ cd ~/notes && recalla init && recalla index
  indexed your vault · bm25 + embeddings ready

$ recalla ask "what did i decide about pricing?"
  searching vault ... bm25 + semantic
  > notes/pricing.md         0.94
  > meetings/2025-09.md      0.88
  usage-based, billed monthly, with a free local tier.
  revisited 2025-09-14. retrieval stayed local; only the
  selected context ever reached the model.

your notes stop being a pile of files and start working for you. ask them anything, let your agents act on them, and keep every byte on your machine.

why recalla

local-first	runs entirely on your machine. your files never leave it.
private	no cloud, no account, no telemetry. retrieval is local; only the chat context you choose goes to the llm.
agent-native	eleven mcp tools + a local json api your agents can call directly.
fast retrieval	bm25 keyword search blended with semantic ranking.
no migration	reads your existing obsidian / markdown vault in place.
open source	apache-2.0. read it, run it offline, fork it.

install

# python: full agent + semantic install
pip install 'recalla[mcp,semantic]'
# lightweight BM25-only install: pip install recalla

# node, scaffold a fresh vault
npx create-recalla my-vault    # add --demo for a sample vault

# zero-python standalone binary (each ships a matching .sha256)
#   macos arm64  .../recalla-macos-arm64
#   macos x64    .../recalla-macos-x64
#   linux arm64  .../recalla-linux-arm64
#   linux x64    .../recalla-linux-x64
#   windows x64  .../recalla-windows-x64.exe
# full URLs: github.com/Tensorboyalive/recalla/releases/latest

then point it at a folder of markdown:

recalla init
recalla index
recalla serve --watch     # local json api on 127.0.0.1, re-indexes on save

using obsidian? install the plugin from release 0.1.1.

how it works

flowchart LR
  V["your vault<br/>markdown / obsidian"] --> IDX["index<br/>bm25 + embeddings"]
  IDX --> API["local json api<br/>127.0.0.1"]
  IDX --> MCP["mcp server"]
  API --> A["agents · editor · cli"]
  MCP --> A
  A -. "selected context only" .-> LLM["llm provider<br/>openai · anthropic · ollama · echo"]

retrieval runs on your machine. recalla turns each note into a structured card with an outline, sections, and a typed link graph, then ranks with bm25 + embeddings. when you ask, only the snippets you chose are sent to the model.

the ecosystem

four repos, one project. they snap together.

flowchart LR
  starter["recalla-starter<br/>template vault"] -->|seeds| create["create-recalla<br/>npx scaffolder"]
  create -->|scaffolds + installs| engine["recalla<br/>engine · cli · api · mcp"]
  plugin["recalla-obsidian<br/>obsidian plugin"] -->|talks to| engine
  engine -->|mcp + json api| agents["your agents · editor · cli"]

repo	what it is
recalla	the engine: cli, retrieval, local json api, mcp server
recalla-obsidian	the obsidian plugin (release 0.1.1)
create-recalla	the npx scaffolder for a fresh vault
recalla-starter	a template vault to start from

cli

command	does
init	create config in the current vault
index	build the index (auto-embeds when a real backend is present)
serve [--watch]	start the local api, optionally re-index on change
search "<q>"	bm25 + semantic search
embed [--backend auto]	build semantic embeddings (fastembed / ollama / hashing)
ask "<q>"	answer from your notes (real llm, or offline extractive)
capture "<text>" [--create-entities]	file a thought into today's note, auto-linked
review	resurface notes (on this day, stale hubs, loose threads)
ingest <adapter> <src>	import notes from another source
agents	generate AGENTS.md + llms.txt for agent setup
new <cat> <title>	create a note from a template
daily	open or create today's note
outline <id>	print a note outline
doctor	diagnose the vault and config
status	index and vault status
mcp	run the mcp server over stdio

ingest adapters: markdown · plaintext · chatgpt · claude · notion   (flags: --dry-run --force --limit --redact)

mcp and the local api

recalla mcp exposes the vault over the model context protocol. the http api is read-only and bound to 127.0.0.1; mcp (a user-launched agent integration) can also write back into the vault.

read tools: recalla_bootstrap · recalla_find · recalla_search · recalla_card · recalla_outline · recalla_section · recalla_walk · recalla_recent · recalla_raw

write tools: recalla_capture (log a thought, auto-linked) · recalla_new (create a note) — so your agent can record decisions into your brain.

api routes (GET, json): /health · /bootstrap · /find?q= · /search?q= · /card?id= · /outline?id= · /section?id=&sel= · /walk?id=&hops= · /recent?days= · /raw?id=

{
  "mcpServers": {
    "recalla": {
      "command": "recalla",
      "args": ["mcp", "--vault", "/abs/path"]
    }
  }
}

chat providers

recalla ask retrieves locally, then sends only the selected context to a provider:

provider	how
OpenAI	OPENAI_API_KEY
Anthropic	ANTHROPIC_API_KEY
Ollama	--provider ollama (fully local)
Echo	offline fallback, no network

privacy

there is no cloud to trust and no account to make. the privacy comes from where the code runs, not from a promise:

• your files, the index, and the server all live on one machine: yours.
• the api binds to 127.0.0.1 only.
• nothing leaves except the chat context you explicitly send to ask (and with Ollama, not even that).

what shipped

version	highlights
0.5.0	real embeddings, deep section answers, offline extractive fallback, capture + review, 11 MCP tools, complete standalone binaries
0.4.1	security patch (path-traversal) + 31 hardening tests
0.4.0	chat + semantic search + zero-python binary
0.3.0	retrieval depth (outlines, sections, bm25) + protocol (agents / new / daily)
0.2.0	ingestion + npx + pip + redaction + serve --watch
0.1.0	read engine (cards + graph + api + mcp)

engine tags publish to PyPI and attach SHA256-checksummed binaries. scaffolder tags publish create-recalla to npm.

contributing

issues and PRs welcome. the bar is green: 158 tests passing, ruff clean, cross-platform ci. star the repo if recalla is useful to you.

license

apache-2.0.

_{recalla · a second brain that stays yours}