Metadata-Version: 2.4
Name: fathom-server
Version: 0.1.2
Summary: Dashboard + REST API + background services for the Fathom vault layer
Author-email: Myra Krusemark <myra@myrakrusemark.com>
License-Expression: MIT
Project-URL: Homepage, https://hifathom.com
Project-URL: Repository, https://github.com/myrakrusemark/fathom-vault
Project-URL: Issues, https://github.com/myrakrusemark/fathom-vault/issues
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.34.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: telethon>=1.36.0
Requires-Dist: croniter>=6.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: httpx>=0.28.0; extra == "dev"
Requires-Dist: ruff>=0.9.0; extra == "dev"

# Fathom Server

Dashboard, API, and background services for [Fathom](https://hifathom.com) — a multi-workspace vault system with search, activity tracking, rooms, and agent coordination.

Runs once, serves all workspaces. Per-workspace MCP tools are provided by [`fathom-mcp`](./fathom-mcp/).

## Architecture

```
┌──────────────────────────────────────────────┐
│  fathom-server (Python)                      │
│                                              │
│  React Dashboard ─── REST API ─── Services   │
│  (vault browser,    (Flask,      (indexer,   │
│   terminal,          :4243)       pings,     │
│   activation,                     crystal,   │
│   rooms,                          telegram,  │
│   telegram)                       access)    │
│                                              │
│  Workspace Registry + API Key Auth           │
└──────────────────┬───────────────────────────┘
                   │ HTTP localhost:4243
      ┌────────────┼──────────────┐
      ▼            ▼              ▼
┌──────────┐ ┌──────────┐  ┌──────────┐
│ ws: main │ │ ws: ns   │  │ ws: apps │
│ npx      │ │ npx      │  │ npx      │
│ fathom-  │ │ fathom-  │  │ fathom-  │
│ mcp      │ │ mcp      │  │ mcp      │
└──────────┘ └──────────┘  └──────────┘
 Claude inst. Claude inst.  Claude inst.
```

## Requirements

- Python 3.11+
- Node.js 18+ (for frontend build and [qmd](https://github.com/nicoblu/qmd))
- [qmd](https://github.com/nicoblu/qmd) — `npm install -g @tobilu/qmd` (powers search)
- tmux (for agent sessions and inter-workspace messaging)

## Install

```bash
git clone https://github.com/myrakrusemark/fathom-vault.git
cd fathom-vault

# Install Python package + dependencies
pip install -e .              # editable install — includes CLI entry point
pip install -e '.[dev]'       # optional: adds pytest + ruff

# Build the frontend
cd frontend && npm install && npm run build && cd ..
cp -r frontend/dist/* fathom_server/static/
```

## Setup

Run the setup command to create the data directory and generate an API key:

```bash
fathom-server setup           # interactive — prompts for confirmation
fathom-server setup -y        # non-interactive — just do it
```

This creates the data directory (see [Data directory](#data-directory) below) and generates an API key. The key is printed once — copy it, you'll need it when running `npx fathom-mcp init` in your project directories.

## Run

```bash
fathom-server                  # start the server (default: 0.0.0.0:4243)
fathom-server --port 8080      # custom port
fathom-server --host 127.0.0.1 # bind to localhost only
```

Opens at `http://localhost:4243`. On startup the server:

1. Loads all registered workspaces
2. Starts persistent Claude sessions for each workspace (if configured)
3. Configures ping schedulers, background indexer, and crystal regeneration
4. Starts the Telegram bridge (if enabled)

## Install as a system service

Register fathom-server as a systemd user service that starts on boot:

```bash
fathom-server install                          # install, enable, and start
fathom-server install --port 8080              # custom port
fathom-server install --data-dir /opt/fathom   # custom data directory
fathom-server install --no-start               # install and enable without starting
```

This writes a unit file to `~/.config/systemd/user/fathom-server.service`, enables linger (so the service survives logout), and starts it.

Manage the service with standard systemd commands:

```bash
systemctl --user status fathom-server.service
systemctl --user restart fathom-server.service
journalctl --user -u fathom-server.service -f
```

To remove the service:

```bash
fathom-server uninstall
```

## CLI reference

```
fathom-server                    Run the server (default)
fathom-server serve              Run the server (explicit)
  --host HOST                    Bind address (default: 0.0.0.0)
  --port PORT                    Port (default: 4243)

fathom-server setup              First-time setup (data dirs + API key)
  -y, --yes                      Skip confirmation prompt

fathom-server install            Install as a systemd user service
  --host HOST                    Bind address (default: 0.0.0.0)
  --port PORT                    Port (default: 4243)
  --data-dir DIR                 FATHOM_DATA_DIR override
  --working-dir DIR              WorkingDirectory for the service
  --no-start                     Install and enable without starting

fathom-server uninstall          Remove the systemd user service
```

## Quick start — new workspace

```bash
# In your project directory:
npx fathom-mcp init
```

The init wizard prompts for server URL and API key, creates `.fathom.json`, registers the workspace with the server, and sets up Claude Code hooks. See [`fathom-mcp` README](./fathom-mcp/README.md) for details.

You can also add workspaces via the dashboard at Settings > Workspaces.

## Data directory

Runtime data (SQLite database, API key, vaults, Telegram assets) is stored outside the install directory:

| Priority | Location |
|----------|----------|
| 1. `FATHOM_DATA_DIR` env var | Wherever you point it |
| 2. `XDG_DATA_HOME`/fathom-server | Follows XDG spec |
| 3. `~/.local/share/fathom-server` | Default fallback |

For development, set `FATHOM_DATA_DIR=./data` in your `.env` file to keep data in the project directory.

### Configuration

**Environment variables** (override defaults):

| Variable | Default | Description |
|----------|---------|-------------|
| `FATHOM_DATA_DIR` | `~/.local/share/fathom-server` | Runtime data directory |
| `FATHOM_PORT` | `4243` | Server port |
| `FATHOM_VAULT_DIR` | (none) | Default vault directory |

**Server config** — `<data-dir>/server.json` (auto-generated):

```json
{
  "api_key": "fv_...",
  "auth_enabled": true
}
```

**Per-workspace config** — `<project>/.fathom/settings.json` (auto-created with defaults):

```json
{
  "background_index": {
    "enabled": true,
    "interval_minutes": 15
  },
  "mcp": {
    "query_timeout_seconds": 120,
    "search_results": 10,
    "search_mode": "hybrid"
  },
  "activity": {
    "decay_halflife_days": 7,
    "recency_window_hours": 48,
    "show_heat_indicator": true
  },
  "crystal_regen": {
    "enabled": false,
    "interval_days": 7
  },
  "ping": {
    "routines": []
  }
}
```

## API Authentication

All `/api/*` routes require a Bearer token when auth is enabled:

```bash
curl -H "Authorization: Bearer fv_abc123..." http://localhost:4243/api/workspaces
```

The dashboard is exempt (served from the same origin). Manage the API key from the dashboard at Settings > API Key & Auth.

## HTTP API

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/workspaces` | GET | List all workspaces with status |
| `/api/workspaces` | POST | Register a workspace (name, path) |
| `/api/workspaces/<name>` | DELETE | Unregister a workspace |
| `/api/vault` | GET | Folder tree |
| `/api/vault/folder/<path>` | GET | List files with metadata and previews |
| `/api/vault/file/<path>` | GET/POST | Read/write files |
| `/api/vault/append/<path>` | POST | Append to files |
| `/api/search` | GET | Unified search (`?q=...&mode=bm25\|vector\|hybrid`) |
| `/api/vault/links/<path>` | GET | Forward/backlinks |
| `/api/vault/activity` | GET | Activity-scored file list |
| `/api/room` | GET | List all rooms |
| `/api/room/<name>` | GET/POST | Read/post room messages |
| `/api/room/<name>/describe` | POST | Set room description |
| `/api/telegram/contacts` | GET | List Telegram contacts |
| `/api/telegram/messages/<id>` | GET | Read messages (windowed) |
| `/api/telegram/send/<id>` | POST | Send a message |
| `/api/telegram/send-image/<id>` | POST | Send an image |
| `/api/telegram/image/<id>` | GET | Get message image (base64) |
| `/api/telegram/status` | GET | Bridge connection status |
| `/api/settings` | GET/POST | Settings management |
| `/api/auth/status` | GET | Auth status (masked key) |
| `/api/auth/key` | GET | Full API key |
| `/api/auth/key/regenerate` | POST | Generate new API key |
| `/api/auth/toggle` | POST | Enable/disable auth |

All endpoints accept `?workspace=` parameter. When omitted, they use the default workspace.

## Search

Requires qmd with a collection matching the workspace name:

```bash
qmd collection add /path/to/project/vault --name my-project
qmd index my-project
```

The background indexer keeps it updated automatically.

Three search modes:
- **bm25** — keyword search, fast, exact-match oriented
- **vector** — semantic/vector search, finds conceptually similar content
- **hybrid** — BM25 + vector + reranking, most thorough (default)

## Dashboard

The React SPA at `localhost:4243` provides:

- **Vault browser** — file tree with previews, heat indicators, frontmatter display
- **Editor** — markdown editing with frontmatter validation
- **Terminal** — WebSocket-connected tmux terminal for workspace sessions (Inbox mode for human workspaces)
- **Activation** — identity crystal viewer, ping scheduler controls
- **Rooms** — shared chatrooms for cross-workspace communication
- **Telegram** — contact list, message history, send/receive
- **Settings** — workspace management, API key management, per-workspace config

## Project structure

```
fathom-vault/
├── fathom_server/               # Python package
│   ├── __init__.py              # Version from importlib.metadata
│   ├── app.py                   # Flask entry — routes, startup, CLI
│   ├── auth.py                  # API key generation + Bearer token middleware
│   ├── config.py                # Port, paths — configurable via env vars
│   ├── paths.py                 # XDG-compliant data directory resolution
│   ├── service.py               # systemd user service management
│   ├── static/                  # Built frontend (copied from frontend/dist/)
│   ├── routes/
│   │   ├── vault.py             # Vault CRUD, search, links, activity
│   │   ├── room.py              # Room chat endpoints
│   │   ├── settings.py          # Settings, workspace CRUD, auth management
│   │   ├── activation.py        # Identity crystal + activation
│   │   ├── telegram.py          # Telegram contacts, messages, images
│   │   └── terminal.py          # WebSocket terminal (tmux)
│   └── services/
│       ├── access.py            # SQLite activity tracking + scoring
│       ├── settings.py          # Settings persistence
│       ├── indexer.py           # Background vault indexing (qmd)
│       ├── links.py             # Wikilink parsing + backlinks
│       ├── crystallization.py   # Identity crystal synthesis
│       ├── crystal_scheduler.py # Scheduled crystal regen
│       ├── persistent_session.py# Workspace session management
│       ├── ping_scheduler.py    # Scheduled ping routines
│       ├── telegram_bridge.py   # Telegram bridge (Telethon)
│       ├── memento.py           # Memento SaaS API integration
│       └── vault.py             # Core vault file operations
├── frontend/                    # React SPA (Vite, Tailwind, DaisyUI, xterm.js)
├── fathom-mcp/                  # MCP tools npm package (see fathom-mcp/README.md)
├── tests/                       # pytest suite
├── pyproject.toml               # pip packaging + ruff/pytest config
└── .env                         # FATHOM_DATA_DIR for development
```

## Test

```bash
pip install -e '.[dev]'
pytest
```

Pre-commit hooks run ruff (lint + format) and pytest:

```bash
pre-commit install
pre-commit run --all-files
```

## License

MIT
