furoshiki 0.1.5

Self-aware AI companion system — memory, identity, contemplation, and self-model

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.

---

Installation

Prerequisites

• Python 3.11 or later — install from python.org or your system package manager
• OpenRouter API key — sign up at openrouter.ai/keys (free credits available)
• (Optional) Telegram bot token — create a bot via @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:

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

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

furoshiki db migrate

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

Start the system

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)
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 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 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 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 (manages Python and the project .venv):

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

2. Clone the repo and run the installer:

   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:

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

furoshiki export -o /tmp/furoshiki-instance.tar.gz
scp /tmp/furoshiki-instance.tar.gz [e-mail]:/tmp/

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

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

   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:

   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:

   ./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):

# 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:

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

ssh -L 7432:127.0.0.1:7432 [e-mail]

Then on your dev machine open 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
• Project site: furoshiki.ai — architecture overview, operator user guide, plugin docs (source)
• Marketing site repo: github.com/bvelasquez/furoshiki-site — static HTML + Firebase deploy (not part of the PyPI package)
• Source: github.com/barryvelasquez/furoshiki — repository coming soon
• Issues: 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 for one-time PyPI/GitHub setup.

---

License

Elastic License 2.0. See LICENSE and NOTICE for details.

© 2026 Soki Creative LLC. All rights reserved under the terms of the Elastic License 2.0.