Metadata-Version: 2.4
Name: metis-brain
Version: 0.1.1
Summary: CLI second brain for your markdown notes
Project-URL: Homepage, https://github.com/itsautomata/metis
Project-URL: Repository, https://github.com/itsautomata/metis
Project-URL: Issues, https://github.com/itsautomata/metis/issues
Author: itsautomata
License-Expression: MIT
License-File: LICENSE
Keywords: cli,embeddings,knowledge-base,markdown,note-taking,obsidian,rag,second-brain,semantic-search
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing :: Indexing
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: chromadb>=0.6.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: keyring>=25.0.0
Requires-Dist: lxml-html-clean>=0.4.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pymupdf>=1.24.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: scikit-learn>=1.5.0
Requires-Dist: trafilatura>=1.12.0
Requires-Dist: typer>=0.15.0
Requires-Dist: youtube-transcript-api>=1.0.0
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown


<p align="center">
  <img src="https://raw.githubusercontent.com/itsautomata/metis/main/assets/metis_draft.gif" alt="metis" width="330">
</p>

## metis
a cli second brain for your markdown notes: [obsidian](https://obsidian.md/download) (recommended), an alternative, or just a normal folder.

ingest anything. search by meaning. chat with your knowledge. discover connections.

---

## setup

### install

**uv (recommended).** installs metis in its own isolated environment, so no dependency is missing and nothing collides with your other packages.

```bash
uv tool install metis-brain   # no uv? run: curl -LsSf https://astral.sh/uv/install.sh | sh
```

**pip**
requires python 3.10+. it installs into your current environment, so isolate it. easiest is pipx (isolated, no venv to manage):

```bash
pipx install metis-brain
```

or a manual virtualenv:

```bash
python3 -m venv .venv
source .venv/bin/activate     # windows: .venv\Scripts\activate
pip install metis-brain
```

> a venv-installed `metis` only works while that venv is active. pipx and `uv tool install` avoid this: isolated and always on your PATH.

**git (for development):**

```bash
git clone https://github.com/itsautomata/metis
cd metis
uv tool install -e .             # global
uv tool install -e . --force     # update the global install
# or in a virtualenv:
uv venv && source .venv/bin/activate && uv pip install -e "."
```

then set up, whichever way you installed:

```bash
metis init                  # guided: vault, provider, key, and models in one flow
metis --install-completion  # enable tab completion for commands
exec $SHELL                 # restart shell to apply
```

`metis init` runs a guided wizard; `metis --no-input init` / `metis --yes init` write defaults for CI.

prefer to set things by hand:

```bash
metis secret set provider-key  # your one key (works for any provider via base_url)
metis secret set x-token       # optional, for full x/twitter extraction
metis secret set               # interactive, you pick which key you want to set
metis secret list              # show which keys are set (no values)
metis doctor                   # verify the whole setup: key, provider, models, index
metis models                   # show the chat + embedding models (and provider) in use
```

quick changes via `metis config vault <path>`. for everything else, edit `~/.metis/config.yaml`.

### upgrade

```bash
uv tool upgrade metis-brain               # installed with uv
pipx upgrade metis-brain                  # installed with pipx
pip install --upgrade metis-brain         # installed with pip
git pull && uv tool install -e . --force  # dev / git clone
```

### uninstall

```bash
uv tool uninstall metis-brain     # installed with uv (or the editable/dev install)
pipx uninstall metis-brain        # installed with pipx
pip uninstall metis-brain         # installed with pip, inside the venv
```

---

## commands

<p align="center">
  <img src="https://raw.githubusercontent.com/itsautomata/metis/main/assets/metis_op.png" alt="metis splash: the four commands to start" width="520">
</p>

run `metis --help` or `metis <command> --help` for all options. `--yes` / `--no-input` make any command non-interactive for scripts and CI; `METIS_ACCESSIBLE=1` swaps the arrow-key menus for numbered prompts (screen readers, no-arrow terminals).

### ingest

save anything to your vault: summarized, tagged, embedded, and linked back to the source.

```bash
metis ingest https://en.wikipedia.org/wiki/Metis_(mythology)
metis ingest ~/books/project-hail-mary.pdf
metis ingest lecture-notes.md
metis ingest paper.pdf --folder research/ai
metis ingest https://www.youtube.com/watch?v=abc123 --lang fr
metis ingest https://arxiv.org/abs/2401.12345
metis ingest paper1.pdf paper2.pdf https://arxiv.org/abs/2402.00001
```

accepts one source or many at once. supports pdfs, urls, markdown, arxiv papers, youtube videos, and x/twitter posts. `--folder` organizes into vault subfolders.

> interactive: `--pick-folder` (vault folders) / `--pick-lang` (transcript languages)

---

### search

```bash
metis search "what role did titans play in greek mythos"
```

semantic search. finds by meaning, not keywords. pick a result to chat about it. add `--json` for machine-readable output (also on `metis doctor`).

---

### chat

```bash
metis chat "how does project hail mary handle the fermi paradox?"
metis chat "what does he say about nash equilibrium?" --note game_theory/intro
metis chat "question" --note game_theory/intro --save
metis chat "question" --expand
```

answers grounded in your vault with sources cited. `--note` scopes to a specific note and offers to save the Q&A. `--save` saves without prompting. `--expand` searches wikipedia when your vault doesn't have enough.

> interactive: `--pick` (choose vault note to ask about)

---

### link

```bash
metis link
metis link --write
metis link --verbose
```

discovers connections between notes. `--write` adds links in your vault's style, auto-detected: `[[wikilinks]]` for obsidian and similar apps, `[markdown](links)` for a plain folder (override with `metis config link-style`). `--verbose` explains why notes are connected.

> interactive: `--pick` (choose vault note to find connections for)

---

### sync

```bash
metis sync
```

re-indexes the vault after you edit notes.

---

### reindex

```bash
metis reindex
metis reindex --dry-run   # preview: how many notes would re-embed, no api calls
```

rebuilds the whole vector index from scratch. run it after changing your
`embedding_model`: the old vectors live in a different space, so metis refuses
search/link/health until you reindex. `--dry-run` reports how many notes would be
re-embedded (one call per chunk) without spending anything.

---

## classification & clustering

metis learns from your vault to help you organize.

**auto-categorization:** when you ingest without `--folder`, metis suggests a folder based on your vault's content. accept, override, or pick from menu. every choice improves future suggestions.

**vault health:**

```bash
metis health
metis health --misplaced
metis health --split hermes_folder
metis health --unique
```

checkup on your vault structure. shows folder alignment, suggests which notes might belong in a different folder, and proposes subfolder splits for large folders.

**folder descriptions:**

```bash
metis folders
metis folders --edit
```

list folders with their ML descriptions. `--edit` opens in your editor to refine how the classifier understands each folder.

---

## config

```bash
metis config                       # show current settings
metis config vault ~/obsidian/my-vault
metis config folder metis-ingested
metis config link-style wikilink   # or markdown, or auto (default: detect from the vault)
```

for anything not covered above, edit `~/.metis/config.yaml`:

```yaml
# ~/.metis/config.yaml

vault_path: ~/obsidian/my-vault
output_folder: metis-ingested

openai:
  # base_url points at any OpenAI-compatible provider.
  # leave empty for OpenAI; set it for OpenRouter, Ollama, a local server, etc.
  base_url: ""              # e.g. https://openrouter.ai/api/v1
  chat_model: gpt-4o
  embedding_model: text-embedding-3-small
```

api keys live in your os keychain via `metis secret set`, or a `METIS_*` env var for automation (`METIS_PROVIDER_KEY`, `METIS_EMBEDDING_KEY`, `METIS_X_BEARER`). keys never go in the config file. one key covers both chat and embeddings; set an `embedding-key` only if you split embeddings to a different provider. run `metis doctor` to check your setup: it verifies the key, the provider, the models, and the index in one pass.

> changing `embedding_model` re-spaces the whole index. metis will refuse until you run `metis reindex`.
>
> on a gateway like OpenRouter, embedding ids are vendor-prefixed; metis auto-adapts the default `text-embedding-3-small` to `openai/text-embedding-3-small`.
