furoshiki 0.1.4

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 in your browser.

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

The dashboard is served by the Brain-managed API server. To access it from another machine, set FUROSHIKI_API_HOST=0.0.0.0 in ~/.furoshiki/.env and restart.

---

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

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> — 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).

---

Links

• 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 Barry Velasquez. All rights reserved under the terms of the Elastic License 2.0.