# Furoshiki

**Persistent self-awareness for LLMs** — memory, identity, needs, and an inner life that continues between conversations. Furoshiki runs as its own stack: Python owns behavior and budgets; models own prose and reflection.

[![PyPI version](https://img.shields.io/pypi/v/furoshiki)](https://pypi.org/project/furoshiki/)
[![Python versions](https://img.shields.io/pypi/pyversions/furoshiki)](https://pypi.org/project/furoshiki/)
[![License](https://img.shields.io/pypi/l/furoshiki)](LICENSE)

---

## Installation

### Prerequisites

- **Python 3.11 or later** — install from [python.org](https://python.org) or your system package manager
- **OpenRouter API key** — sign up at [openrouter.ai/keys](https://openrouter.ai/keys) (free credits available)
- **(Optional) Telegram bot token** — create a bot via [@BotFather](https://t.me/BotFather) on Telegram for chat access

### Install the package

Use a **virtual environment** so the `furoshiki` CLI and Brain-managed processes share one Python and one set of dependencies:

```bash
python3 -m venv ~/.furoshiki-venv
source ~/.furoshiki-venv/bin/activate   # Windows: ~/.furoshiki-venv\Scripts\activate
pip install -U furoshiki
```

On some systems you may need `pip3` instead of `pip`. The package installs a `furoshiki` command.

**Secrets:** keep API keys in `~/.furoshiki/.env` (written by `furoshiki onboard`). Avoid exporting `OPENROUTER_API_KEY` in your shell profile — a stale export can override the instance file until you restart.

### Run the setup wizard

```bash
furoshiki onboard
```

This interactive wizard guides you through:

1. **API keys** — enter your OpenRouter API key (required) and Telegram bot token (optional)
2. **Time zone** — set your local timezone (e.g. `America/New_York`, `Europe/London`)
3. **Identity files** — optionally create a SOUL persona template and operator notes

You can rerun `furoshiki onboard --keys-only` later to update API keys without touching identity files.

### Initialize the database

```bash
furoshiki db migrate
```

This creates the SQLite database and ChromaDB vector store under `~/.furoshiki/memory/`.

### Start the system

```bash
furoshiki start
```

This launches two processes:
- **Brain** — the main scheduler, manages the Telegram listener and API server
- **Doctor** — an independent watchdog that monitors health and triggers repairs

Check status with `furoshiki status` and view logs with `furoshiki logs`.

### Troubleshooting first run

| Symptom | Fix |
|--------|-----|
| Brain/Doctor fail to start on macOS | Upgrade to latest `furoshiki` (0.1.1+); repo devs use `./install.sh` (Bash 3.2+). |
| Telegram receives messages but never replies; logs show OpenRouter **401** | Run `furoshiki onboard --keys-only`, then `furoshiki restart brain`. Remove old `export OPENROUTER_API_KEY=…` from `~/.zshrc` / `~/.bashrc`. |
| `furoshiki status` shows Listener not running | `furoshiki restart brain` (cleans orphan listener/API on macOS). |

---

## Connecting to Telegram

After starting, if you configured a Telegram bot token during onboarding:

1. Open Telegram and find your bot (created via [@BotFather](https://t.me/BotFather))
2. Send any message to start a conversation
3. Run `furoshiki status` to confirm the listener is active

Furoshiki will respond, remember the conversation, and may reach out proactively when there's something to say (gated by do-not-disturb hours, cooldown, and mood).

---

## Operator dashboard

With the system running, open [http://localhost:7432/dashboard](http://localhost:7432/dashboard) on the machine where Brain is running.

The API server binds to **`0.0.0.0:7432` by default** (`FUROSHIKI_API_HOST`). That lets you reach the dashboard from another computer on the same network, or via an SSH tunnel — see [Remote deploy and dashboard](#remote-deploy-and-dashboard) below.

Authenticate with a dashboard **admin** API key (`furoshiki api-keys create` or the **API Keys** page). For loopback-only binding on untrusted networks, set `FUROSHIKI_API_HOST=127.0.0.1` in `~/.furoshiki/.env` and use an SSH tunnel from other machines.

The dashboard provides live controls for:

| Page | What you can do |
|------|----------------|
| **Status** | System health, process status, heartbeat |
| **Scheduler** | View and edit scheduled tasks (reflection, backup, outreach, etc.) |
| **Models** | Configure LLM routing, model tiers, provider settings |
| **LLM budgets** | Set daily/monthly spending caps |
| **Identity & context** | Edit SOUL persona, view session context |
| **Settings** | Tune behavior: proactive outreach, conversation continuity, DND hours |
| **Plugins** | Install and manage runtime plugins |
| **API Keys** | Create bearer tokens for programmatic access |
| **Logs** | Browse real-time log streams |

---

## What it is

Most AI assistants are stateless. Furoshiki isn't. It maintains:

- **Episodic memory** — every conversation is logged, embedded in vector storage (ChromaDB), and retrievable
- **A self-model** — evolving self-understanding updated by nightly reflection, separate from the chat-facing persona
- **Needs and inner life** — internal states (connection, curiosity, rest, purpose) that decay over time and shape tone
- **Proactive voice** — Furoshiki reaches out when there is genuinely something worth saying, with DND, cooldown, and mood gates
- **Operator dashboard** — web UI for schedules, LLM routing, budgets, plugins, and system health

**Harness-agnostic.** Telegram is the primary interface. Any harness can integrate via a simple contract: write session logs, read structured context. See the [project site](https://furoshiki.ai) for integration details.

---

## Features

| | |
|---|---|
| **Persistent memory** | SQLite + ChromaDB vector store for episodic and semantic recall |
| **Scheduled reflection** | Nightly journal, morning orientation, deep weekly self-review |
| **Proactive outreach** | Gated by recency, mood, DND window, and duplicate detection |
| **Operator dashboard** | Schedules, LLM routing, budgets, plugins, identity editing, API keys |
| **Plugin system** | Runtime hooks for conversation, reflection, and scheduled tasks |
| **LLM cost controls** | Daily/monthly budget caps, per-source model routing, provider selection |
| **Repair & delegation** | Auto-healing watchdog + agentic CLI integration for proposals |
| **Model tools** | In-conversation tools for emotion adjustment, observations, and user facts |

---

## Architecture

Furoshiki runs as two processes controlled by the `furoshiki` CLI:

- **Brain** — internal task scheduler (replaces cron), manages Telegram listener and API server as child processes, auto-restarts them on failure
- **Doctor** — independent watchdog, monitors health, rotates logs, triggers repairs for recurring errors

All runtime data lives under `FUROSHIKI_DATA` (default `~/.furoshiki/`), keeping the installed package clean and portable. Use `furoshiki export` and `furoshiki import` to bundle and migrate instances between machines.

---

## Management commands

| Command | Purpose |
|---------|---------|
| `furoshiki start` / `stop` | Start or stop the Brain and Doctor processes |
| `furoshiki status` | System status and health overview |
| `furoshiki logs` | View log streams (all sources or by service) |
| `furoshiki db migrate` | Apply database schema migrations |
| `furoshiki onboard` | Interactive setup wizard |
| `furoshiki onboard --keys-only` | Update API keys only |
| `furoshiki mood` | Show emotional state and recent reflections |
| `furoshiki schedules merge-defaults` | Add missing scheduled tasks from defaults |
| `furoshiki export` / `import` | Backup or restore an instance archive |
| `furoshiki deploy` | Push repo source to a remote host over SSH (see below) |

Use `furoshiki --help` for the full command list.

---

## Development (from source)

For hacking on Furoshiki (not required if you only use `pip install furoshiki` from PyPI):

1. Install **[uv](https://docs.astral.sh/uv/getting-started/installation/)** (manages Python and the project `.venv`):

   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
   ```

2. Clone the repo and run the installer:

   ```bash
   git clone <your-repo-url> furoshiki && cd furoshiki
   ./install.sh --dev
   ```

   This runs `uv sync` from `uv.lock`, installs the package editable into `.venv`, and runs `furoshiki init` (skip init with `./install.sh --deps-only`).

3. Daily commands:

   ```bash
   source .venv/bin/activate    # optional
   furoshiki start
   uv run pytest                # tests (or: pytest after activate)
   ```

**Migrating an existing instance** from another machine: copy a `furoshiki-instance-*.tar.gz` export and run `furoshiki import <archive>` on the target — do not re-run `onboard` unless you want a fresh instance.

**Repair a broken env:** `./install.sh --repair` or `./install.sh --recreate` (removes `.venv` and re-syncs).

### Remote deploy and dashboard

Use this when you **develop on one machine** (e.g. a laptop) but **run Furoshiki on another** (e.g. a home server over SSH). Deploy pushes **source code only**; instance data (`~/.furoshiki/`) stays on the remote.

#### One-time: move the instance to the remote host

On the **source** machine (Brain stopped: `furoshiki stop`):

```bash
furoshiki export -o /tmp/furoshiki-instance.tar.gz
scp /tmp/furoshiki-instance.tar.gz you@remote.example:/tmp/
```

On the **remote** (after clone + `./install.sh --deps-only`):

```bash
furoshiki import /tmp/furoshiki-instance.tar.gz
furoshiki db migrate
furoshiki start
```

#### Ongoing: deploy code changes

1. Copy the example config (this file is **gitignored** — do not commit secrets):

   ```bash
   cp deploy.remote.env.example deploy.remote.env
   ```

2. Edit `deploy.remote.env` with your host, SSH user, and remote repo path. Example shape only:

   ```bash
   DEPLOY_HOST=192.168.1.50
   DEPLOY_USER=deploy
   DEPLOY_REPO_PATH=/home/deploy/furoshiki
   # Optional: DEPLOY_SSH_OPTS=-i ~/.ssh/id_ed25519
   # Prefer SSH keys. Password auth requires sshpass and DEPLOY_SSH_PASS or SSHPASS — keep those out of git.
   ```

3. From the repo root on your dev machine:

   ```bash
   ./scripts/deploy_remote.sh
   # or: furoshiki deploy
   ```

   This **rsyncs** the repo (excludes `.venv`, `memory/`, `.env`, `.git`), runs **`uv sync`** on the remote when `uv.lock` is present, then **`furoshiki restart brain`** so the listener and API load new code.

   | Flag | Effect |
   |------|--------|
   | `--dry-run` | Show rsync command without copying |
   | `--no-deps` | Skip `uv sync` (Python-only edits) |
   | `--restart listener` | Restart only the Telegram listener instead of full Brain cycle |

#### Dashboard on a remote host

The API defaults to **`0.0.0.0:7432`** — no extra env var is required for LAN access.

**Same network** — the API listens on `0.0.0.0:7432`, but you must **allow the port in the host firewall** (common on Ubuntu):

```bash
# on the remote host (example: ufw, LAN-only)
sudo ufw allow from 192.168.0.0/16 to any port 7432 proto tcp comment 'Furoshiki dashboard API'
```

Then open:

```text
http://<remote-host-ip>:7432/dashboard
```

Sign in with an **admin** bearer token from the remote instance (`FUROSHIKI_API_TOKEN` in that host’s `~/.furoshiki/.env`, or a key from `furoshiki api-keys create`).

**SSH tunnel** (works even when the port is not exposed on the LAN):

```bash
ssh -L 7432:127.0.0.1:7432 you@remote.example
```

Then on your dev machine open [http://localhost:7432/dashboard](http://localhost:7432/dashboard).

**Lock API to loopback** on the server (recommended on untrusted networks): in the remote `~/.furoshiki/.env`, set `FUROSHIKI_API_HOST=127.0.0.1`, restart Brain, and use the SSH tunnel above.

---

## Links

- **Company:** [Soki Creative LLC](https://soki-creative.com)
- **Project site:** [furoshiki.ai](https://furoshiki.ai) — architecture overview, operator user guide, plugin docs ([source](https://github.com/bvelasquez/furoshiki-site))
- **Marketing site repo:** [github.com/bvelasquez/furoshiki-site](https://github.com/bvelasquez/furoshiki-site) — static HTML + Firebase deploy (not part of the PyPI package)
- **Source:** [github.com/barryvelasquez/furoshiki](https://github.com/barryvelasquez/furoshiki) — repository coming soon
- **Issues:** [github.com/barryvelasquez/furoshiki/issues](https://github.com/barryvelasquez/furoshiki/issues)

---

## Releasing (maintainers)

PyPI publishes are automated on merge to `main` when `pyproject.toml` version is new. See [docs/RELEASE.md](docs/RELEASE.md) for one-time PyPI/GitHub setup.

---

## License

Elastic License 2.0. See [LICENSE](https://github.com/barryvelasquez/furoshiki/blob/main/LICENSE) and [NOTICE](https://github.com/barryvelasquez/furoshiki/blob/main/NOTICE) for details.

© 2026 [Soki Creative LLC](https://soki-creative.com). All rights reserved under the terms of the Elastic License 2.0.