samong

# Samong 🧠

[![CI](https://github.com/waanvar/samong/actions/workflows/ci.yml/badge.svg)](https://github.com/waanvar/samong/actions/workflows/ci.yml)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

**A local-first knowledge base for the notes already in your repositories**

You solved it once and wrote it down. Six months later the note is still in the
repo and you cannot find it. Point Samong at a project root and the `.md` files
you would commit become searchable and linked — and readable by the AI tools you
already work with. Plain Markdown,
[Obsidian](https://obsidian.md)-compatible (`[[wikilink]]` /
`[[wikilink|alias]]`), no account, no cloud, one binary.

![Samong — the graph is the workspace, with note titles, hub sizing and folder clusters](docs/graph-dark.png)

## Why Samong

- 📁 **A note is a `.md` file you would commit.** Point it at a repository, not
  at a special notes folder. `.gitignore` is respected and dependency
  directories are always skipped, so a project root indexes your ADRs, runbooks
  and design docs without dragging in `node_modules` — and `samong doctor` tells
  you exactly what counted and what did not.
- 🤖 **Your notes become an agent's memory.** `samong-mcp` speaks MCP, so Claude
  Code and Claude Desktop search, read and write the same knowledge base you do.
  No pasting context back in every session ([setup](docs/AI-AGENT.md)).
- 🗺 **The graph is the workspace, not a novelty tab.** A vault is a shape;
  typing dims everything that does not match, so a query becomes a place.
- 🔎 **Notes are addressed by path, not by title.** One repository holds twenty
  files called `README.md`. A title cannot tell them apart, and an index keyed on
  titles silently collapses them — so search results, the API and the MCP tools
  all carry the real path.
- 📚 **Learn from documentation you never commit.** `.gitignore` answers "what do
  I distribute?"; a knowledge base has to answer "what do I learn from?".
  `scope.include` pulls a dependency's own docs in as read-only reference notes —
  one project, one brain, no second vault.
- 🔗 **One repository per vault, links across all of them.** `[[other-vault/note]]`
  resolves across every registered vault, and backlinks come back the other way
  without any cross-vault index to keep in sync.
- 🧭 **Ranked by relevance *and* connectedness.** When the words cannot tell two
  notes apart, the one the rest of your notes point at comes first. Capped at a
  25% boost, so a popular note never outranks one that plainly matches better.
- 🧠 **Semantic search, optional and local.** Build with `--features semantic`
  and run `samong embed` to rank by meaning as well as by words, with a
  multilingual model that never leaves your machine. Off by default on purpose:
  see below.
- ⚡ **Fast, and yours.** Link graph in [redb](https://github.com/cberner/redb),
  search in [tantivy](https://github.com/quickwit-oss/tantivy), incremental
  reindexing that only touches changed files. Every index lives in
  `<vault>/.brain/` and can be rebuilt from the `.md` files at any time — there
  is nothing to lock you in.

## Install

### With Rust already installed

```sh
cargo install samong
```

Builds all four binaries with the web UI inside them. Needs Rust 1.88 or newer.

> Publishing this crate needs `cargo publish --allow-dirty`: the web UI is
> embedded at compile time from `web/dist`, which is gitignored yet deliberately
> included in the package, so `cargo` sees 55 files git does not track.
> `packaging/check-publish-tree.sh` runs first and refuses if anything *outside*
> `web/dist` is uncommitted, so the flag cannot quietly ship source edits.

### Just open it

Download, extract, **double-click**:

| | |
|---|---|
| **Windows** | `Open Samong.exe` |
| **macOS** | `Samong.app` |
| **Linux** | `samong-app` (copy `samong.desktop` to `~/.local/share/applications/` for a menu entry) |

No terminal, no configuration, no account. On the very first run it makes a
vault at **`Documents/Samong`** with two notes in it, indexes them, and opens
your browser. Everything after that is your own folder of Markdown files.

The `⏻` button in the top right stops it — the server outlives the browser tab,
so closing the tab is not the same as quitting.

> Already have notes somewhere? Use **+ Add vault…** in the vault menu and point
> it at that folder. Nothing is moved or converted.

Two environment variables exist for the awkward cases, because a double-clicked
program has no arguments: `SAMONG_PORT` when 3000-3011 are all taken by
something that stays, and `SAMONG_NO_OPEN=1` to start without a browser.
If the launcher fails it writes `~/.config/samong/launcher.log` and opens it.

### Download a binary (recommended)

Grab one from [Releases](https://github.com/waanvar/samong/releases), extract,
run. Direct links that always point at the newest release:
[Linux](https://github.com/waanvar/samong/releases/latest/download/samong-x86_64-linux.tar.gz) ·
[Windows](https://github.com/waanvar/samong/releases/latest/download/samong-x86_64-windows.zip) ·
[macOS Apple Silicon](https://github.com/waanvar/samong/releases/latest/download/samong-aarch64-macos.tar.gz) ·
[macOS Intel](https://github.com/waanvar/samong/releases/latest/download/samong-x86_64-macos.tar.gz). **No Rust or Node needed** — the web UI is already inside the binary. Four
platforms: `x86_64-linux`, `x86_64-windows`, `aarch64-macos` (Apple Silicon),
`x86_64-macos` (Intel).

Verify what you downloaded against the `.sha256` published beside it:

```sh
sha256sum -c samong-x86_64-linux.tar.gz.sha256
```

#### ⚠️ The binaries are not code-signed

Samong has no code-signing certificate yet, so the OS will get in the way:

**macOS** — Gatekeeper *refuses* to open it (not merely a warning). One command
after extracting clears it:

```sh
xattr -d com.apple.quarantine samong samong-server samong-mcp
```

**Windows** — SmartScreen warns; choose **More info → Run anyway**.

> Both happen to any open-source project without a paid certificate and are not a
> sign that something is wrong with the file — but do check the checksum above,
> and only download from the official Releases page.

### Or build from source

Needs [**Rust**](https://rustup.rs) (stable) and [**Node.js**](https://nodejs.org)
20+ (Node only if you want the web UI, which is embedded into the binary at build
time — without it you get the CLI + API).

```sh
git clone https://github.com/waanvar/samong.git
cd samong
cd web && npm install && npm run build   # build the web UI first (it gets embedded)
cd .. && cargo install --path .          # installs samong / samong-server / samong-mcp
```

> **Order matters**: build the web UI before `cargo build`/`cargo install` —
> `samong-server` **embeds the web UI into the binary**, so it ships as a single
> file with no UI folder alongside it. (To build without installing, use
> `cargo build --release`; binaries land in `target/release/`.)

Update to the latest version later with `samong update` (see *Updating* below).

## Quickstart

```sh
mkdir my-vault && cd my-vault
samong new "My First Note"         # create + index
samong vault add my-vault .        # register in ~/.config/samong
samong-server start               # opens http://127.0.0.1:3000 in your browser
```

`samong-server start` serves the embedded web UI and opens your browser — no UI
files needed alongside it. Change the port with `--port 8080`, skip the browser
with `--no-open` (the old `samong-server --port 8080` form still works).

![The same vault in the light theme](docs/graph-light.png)

## CLI commands

| Command | What it does |
|---|---|
| `samong new <title>` | Create a note + index it |
| `samong edit <title>` | Open in `$EDITOR`, reindex on close |
| `samong rename <old> <new>` | Rename + rewrite every `[[wikilink]]` pointing at it |
| `samong delete <title>` | Delete + warn about dangling backlinks |
| `samong links <title> [--all-vaults]` | Forward links + backlinks (incl. cross-vault) |
| `samong orphans` / `samong broken` | Unlinked notes / links to missing notes |
| `samong search <q> [--vault <name>\|--all-vaults] [--limit N]` | Full-text search |
| `samong graph [--all-vaults]` | Link-graph edges |
| `samong list` | List every note |
| `samong reindex [--full]` | Sync the index (changed files only / everything) |
| `samong embed [--reference]` | Embed notes for semantic search (needs `--features semantic`) |
| `samong pack <dir> [--include-reference]` | Copy the publishable part of the vault out — notes and manifest, never the index |
| `samong watch` | Watch the vault, keep the index fresh |
| `samong vault add/list/remove` | Manage the central registry |
| `samong vault install <git-url>` | Install someone else's vault as read-only reference notes |
| `samong vault update [name]` | Pull the latest content for installed vaults |
| `samong vault verify [name] [--require-signature]` | Check installed vaults are what their publishers published |
| `samong doctor` | Report what counts as a note, what was skipped, and any ambiguous titles |
| `samong update [--check]` | Update to the latest GitHub release (--check only reports) |
| `samong-app` | The double-click launcher: finds or creates a vault, serves, opens the browser |

### What counts as a note (vault scope)

One rule: **a note is a `.md` file you would commit.** Point `samong vault add`
straight at a project root — no configuration needed. Samong will:

- respect `.gitignore`, so `node_modules/`, `dist/` and `target/` never get indexed
- always skip dependency directories even when they are not gitignored
  (`node_modules`, `vendor`, `site-packages`, `__pycache__`, `Pods`, `bower_components`)
- skip every dot-directory (`.git`, `.obsidian`, `.brain`)

`samong doctor` shows what that adds up to:

```sh
samong doctor
# vault: /home/me/myproject
# gitignore: respected
# 4 note(s) in scope
# skipped 90 .md file(s) not tracked as notes (web 90)
```

To adjus