recalla 0.2.0

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

recalla

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

recalla turns a folder of markdown notes into a fast, token-cheap layer that any LLM or agent can read: compressed entity cards, a wikilink graph, and a local HTTP API + MCP surface. No cloud. No account. No telemetry. Your notes never leave your machine.

It works with plain markdown and with Obsidian vaults. It is agent-agnostic: Claude, Cursor, Codex, or any MCP client can read your brain through it.

Why

Your knowledge is in markdown. Agents are expensive to feed raw markdown. recalla builds an index of small cards (roughly a quarter the tokens of the full note) plus a graph the agent can walk in a few hops, so it finds the right context fast and cheap, then reads full notes only when it needs the detail.

Install

pip install recalla          # core engine + CLI
pip install 'recalla[mcp]'   # also install the MCP server

Requires Python 3.10+. The core has one dependency (PyYAML). The local server is pure standard library.

Quickstart (60 seconds)

The fastest path (no Python knowledge needed to scaffold):

npx create-recalla my-vault   # scaffold a runnable vault in one command
cd my-vault
pip install recalla
recalla index                    # build the .recalla/ index
recalla serve                    # local API at http://127.0.0.1:8090

Or with the Python CLI directly:

recalla init my-vault      # scaffold a vault (or run inside an existing one)
cd my-vault
recalla index              # build the .recalla/ index
recalla serve --watch      # local API, auto-reindexing as you edit notes

In another terminal:

curl 'http://127.0.0.1:8090/bootstrap'
curl 'http://127.0.0.1:8090/find?q=welcome'
curl 'http://127.0.0.1:8090/walk?id=how-it-works&hops=2'

Already have an Obsidian vault? Point at it and index in place:

cd ~/Documents/my-obsidian-vault
recalla init . --name my-vault   # writes recalla.config.yaml only
recalla index
recalla serve

Commands

Command	What it does
recalla init [path]	Scaffold a new vault (writes recalla.config.yaml + starter notes)
recalla index	Build .recalla/ (cards, graph, bootstrap, meta)
recalla serve [--watch]	Run the local read API on 127.0.0.1:8090 (optionally auto-reindex)
recalla ingest <adapter> <source>	Import a source (markdown, plaintext, chatgpt) into the vault
recalla doctor	Validate the vault (broken links, duplicates, schema); CI-friendly
recalla status	Show index build stats
recalla mcp	Run the MCP server over stdio (needs [mcp] extra)

The vault is discovered via --vault PATH, the RECALLA_VAULT env var, or by walking up from the current directory to find recalla.config.yaml. No paths are hardcoded.

API

All endpoints are GET and return JSON, bound to localhost only.

Endpoint	Purpose
/bootstrap	~2K-token orientation: counts, categories, top hubs
/find?q=&limit=	Fuzzy entity lookup by title / alias / id
/search?q=&limit=	Keyword search across cards
/card?id=	One compressed card
/walk?id=&hops=&limit=	BFS neighbors with their cards
/recent?days=&limit=	Recently updated notes
/raw?id=	Full markdown body (verbatim)

Use with an MCP agent (Claude Desktop, Cursor, Claude Code)

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

Tools exposed: recalla_bootstrap, recalla_find, recalla_search, recalla_card, recalla_walk, recalla_recent, recalla_raw.

Note schema

Notes are markdown with optional YAML frontmatter. Nothing is mandatory, but the richer the frontmatter, the better the cards.

---
title: Theo Sakalidis
category: people
status: active
aliases: [theo]
tags: [cofounder]
related: [cevi-ai]
created: 2026-01-01
updated: 2026-06-01
---

# Theo Sakalidis

Short lead paragraph becomes the card summary.

## Timeline

- **2026-05-15**: a dated event becomes part of the entity's history.

Link entities with [[wikilinks]]. Links become the graph.

Privacy

recalla is local-first by design. It reads your files, writes an index next to them in .recalla/, and serves on 127.0.0.1. It makes no network calls and ships no telemetry. Add .recalla/ to your .gitignore (the scaffolder does this for you) so the rebuildable index stays out of git.

Roadmap

See docs/roadmap.md. Short version: v0.1 is the read engine (this). Next come the MCP polish + npx create-recalla scaffolder, source ingestion adapters, hierarchical retrieval, and the optional Recalla OS protocol layer (daily ritual, ledgers) plus configurable personas.

License

Apache-2.0. See LICENSE.