Metadata-Version: 2.4
Name: recalla
Version: 0.2.0
Summary: A local-first, agent-native second brain. Pull it, run it, own it.
Project-URL: Homepage, https://github.com/recalla/recalla
Project-URL: Repository, https://github.com/recalla/recalla
Project-URL: Issues, https://github.com/recalla/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.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>=1.0.0; extra == 'mcp'
Description-Content-Type: text/markdown

# 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

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

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

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

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

```bash
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)

```json
{
  "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.

```markdown
---
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](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](LICENSE).
