Metadata-Version: 2.4
Name: recalla
Version: 0.5.0
Summary: A local-first, agent-native second brain. Pull it, run it, own it.
Project-URL: Homepage, https://github.com/Tensorboyalive/recalla
Project-URL: Repository, https://github.com/Tensorboyalive/recalla
Project-URL: Issues, https://github.com/Tensorboyalive/recalla/issues
Author: recalla contributors
License: Apache-2.0
License-File: LICENSE
Keywords: agents,knowledge-graph,local-first,mcp,obsidian,pkm,second-brain
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: <3.14,>=3.10
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.0.0; extra == 'mcp'
Provides-Extra: semantic
Requires-Dist: fastembed<1,>=0.3.0; extra == 'semantic'
Requires-Dist: onnxruntime<1.24; (platform_system == 'Darwin' and platform_machine == 'x86_64') and extra == 'semantic'
Description-Content-Type: text/markdown

<div align="center">

<br/>

# 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.

<br/>

[![pypi](https://img.shields.io/pypi/v/recalla?label=pypi&color=A1ED63&labelColor=093328)](https://pypi.org/project/recalla/)
[![npm](https://img.shields.io/npm/v/create-recalla?label=create-recalla&color=A1ED63&labelColor=093328)](https://www.npmjs.com/package/create-recalla)
[![license](https://img.shields.io/badge/license-Apache--2.0-A1ED63?labelColor=093328)](./LICENSE)
[![tests](https://img.shields.io/badge/tests-158%20passing-A1ED63?labelColor=093328)](#)
[![ci](https://img.shields.io/badge/ci-cross--platform-A1ED63?labelColor=093328)](#)
[![local-first](https://img.shields.io/badge/local--first-no%20telemetry-093328?labelColor=A1ED63)](#privacy)

[install](#install) · [how it works](#how-it-works) · [cli](#cli) · [mcp](#mcp-and-the-local-api) · [the ecosystem](#the-ecosystem) · [privacy](#privacy)

</div>

---

```console
$ 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.

<br/>

## 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. |

<br/>

## install

```bash
# 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:

```bash
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](https://github.com/Tensorboyalive/recalla-obsidian/releases/latest).

<br/>

## how it works

```mermaid
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.

<br/>

## the ecosystem

four repos, one project. they snap together.

```mermaid
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**](https://github.com/Tensorboyalive/recalla) | the engine: cli, retrieval, local json api, mcp server |
| [**recalla-obsidian**](https://github.com/Tensorboyalive/recalla-obsidian) | the obsidian plugin (release 0.1.1) |
| [**create-recalla**](https://github.com/Tensorboyalive/create-recalla) | the `npx` scaffolder for a fresh vault |
| [**recalla-starter**](https://github.com/Tensorboyalive/recalla-starter) | a template vault to start from |

<br/>

## 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`
&nbsp;&nbsp;(flags: `--dry-run` `--force` `--limit` `--redact`)

<br/>

## 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=`

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

<br/>

## 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 |

<br/>

## 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).

<br/>

## 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.

<br/>

## 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](./LICENSE).

<div align="center"><br/><sub>recalla · a second brain that stays yours</sub></div>
