User guide

What this is for

Furoshiki keeps memory, a self-model, needs, and scheduled reflection so a language model can stay coherent between chats. Python owns routing, budgets, and storage; models own prose. Telegram is the primary chat harness today; anything else integrates through a small session contract (see below).

You will touch: the furoshiki CLI, the repair API on localhost (dashboard + automation), optional Telegram commands, and site/ + docs/ references when you need the full spec.

Install & first run

PyPI (recommended): install the published package — no git clone required. Requires Python 3.11+ and an OpenRouter API key. Optional: a Telegram bot token from @BotFather.

1. Install: pip install furoshiki (or pip3). Verify with furoshiki --help.
2. Onboard: furoshiki onboard — API keys, timezone, optional SOUL/USER templates. Use furoshiki onboard --keys-only later to rotate keys.
3. Database: furoshiki db migrate — creates SQLite + ChromaDB under ~/.furoshiki/memory/ (or $FUROSHIKI_DATA).
4. Start: furoshiki start — Brain + Doctor. Brain manages the Telegram listener and repair API as child processes.
5. Dashboard: open http://localhost:7432/dashboard while the stack is running.

Migrating an instance? furoshiki export on the source machine and furoshiki import <archive.tar.gz> on the target. Package page: pypi.org/project/furoshiki.

CLI (furoshiki)

Run furoshiki help for the live list. Most commands accept --json for agents and scripts. Routine database changes use furoshiki db migrate (not raw init_db.py).

Common groups

Repair REST API

Base URL: http://127.0.0.1:<FUROSHIKI_API_PORT>/api/v1 (default port 7432). Send header Authorization: Bearer <token> using either the admin value FUROSHIKI_API_TOKEN from .env or a scoped key from furoshiki api-keys create (read / write / admin).

Scopes (summary)

• read — GET endpoints (status, mood, logs, design query, …)
• write — read plus mutating POST/PUT that do not require full admin (nudge, delegations, some analytics saves, …)
• admin — destructive operations, service restarts, config/operator JSON, API key management, db migrate via API

Full route inventory and plugin-token rules live in scripts/api_v1_routes.py (file header). Plugin subprocesses use short-lived tokens for /api/v1/plugin/* — see Plugin HTTP API and docs/PLUGIN-API.md.

Telegram setup

1. Create a bot with BotFather; copy the token into TELEGRAM_BOT_TOKEN in .env (see .env.template).
2. Set TELEGRAM_CHAT_ID to the authorized private or group chat.
3. Start Brain (furoshiki start) so the managed listener polls Telegram.

Normal messages go through the full reply pipeline; lines starting with / are treated as commands where registered.

Telegram shortcuts

Keep this list aligned with scripts/telegram_listener.py → _telegram_commands_help_text(). In chat, send /help, /commands, or /shortcuts for the same catalog.

Context augmentations

• /list_context — list active augmentations
• /pin_context [id] — pin latest or a specific id
• /unpin_context <id> | all

Open questions

• /myquestions, /openquestions

Extensions & delegation

• /ext — extension work queue · /jobs — delegation job list
• /ext_view <id> — one row · /redispatch <job_id>
• /proposals · /apply <job_id>
• /plugins · /skills · /callables

Create delegation jobs

• /delegate_skill — self_modification (generic skill/plugin)
• /delegate_code — code_change · /delegate_research · /delegate_script · /delegate_check
• Short: /d_skill /d_code /d_research /d_script /d_check

Plugin proposal shortcuts

• /plugin_cron /plugin_post_conversation /plugin_pre_conversation /plugin_pre_reflection /plugin_callable /plugin_post_reflection
• Long form: /propose_plugin_<hook> … — hook schemas in docs/PLUGIN-SPEC.md

Services

• /restart <listener|doctor|repair-api|dashboard|reload-watch|all>

CLI parity (exact line)

• /status /health /doctor /mood /design
• /logs — listener log tail · /traces · /trace [N]

Tasks & model

• /tasks, /task add …, /task done <id>
• /model, /model <shortcut>, or natural “switch to …”

Proactive outreach

• /outreach_pause [hours] (default 4h) · /outreach_resume
• Phrases: give me a break, pause outreach, leave me alone (see listener regex)
• When you clearly resolve a topic in chat (e.g. “that project is done”), pending non-system mind_queue outreach rows on the same topic may auto-expire; compose also runs a light semantic memory pass first. Tune under Dashboard Settings → Operator → Tier 1 — Voice & proactive outreach (voice_dispatcher in memory/operator_settings.json).

Corrections

• /correct <scope> | <wrong> | <right> [| context] — scopes behavior, preference, fact

Structured corrections

Corrections record authoritative wrong→right pairs. They land in structured storage, feed prompt assembly, can be embedded for retrieval, and may consolidate into longer-term commitments over time.

Three ways to record

• Telegram: /correct behavior | … | … (pipe-separated parts)
• CLI: furoshiki correction add --scope … --wrong … --correct … [--context …]
• API: POST /api/v1/operator/correction (admin scope)

Design reference: docs/SELF-AWARENESS-DESIGN.md (operator structured corrections).

Operator dashboard

The dashboard HTML ships in the repo as scripts/dashboard/index.html and is served by the repair API on your host. It is not the same as the public marketing pages under site/. Use it for logs, emotions, extensions queue, settings (writes memory/operator_settings.json), API keys, and LLM routing UI.

Browser / URL tips: Open the UI in a normal top-level browser tab (e.g. http://127.0.0.1:7432/dashboard/). If the API was briefly down, Chrome may show an error document (chrome-error://…); retrying navigation from that embedded context can log Unsafe attempt to load URL … from frame with URL chrome-error://chromewebdata/ — use a fresh address-bar load or a new tab once furoshiki start has the repair API listening. Prefer one hostname consistently (127.0.0.1 vs localhost) so cookies and storage match. The dashboard response sets X-Frame-Options: DENY and Content-Security-Policy: frame-ancestors 'none' so it cannot be embedded in iframes (avoids fragile IDE preview frames).

• Feature flags (under Settings) includes personality_roles — situational masks after the identity shell — and optional personality_roles_semantic_tiebreak (stage 2 when strict triggers match no row; uses the same local embedder as Chroma, not the chat model).
• Self & user → Personality roles lists session-context active role; create, edit, or delete roles with structured triggers (topics, time, user-need floors, mood window, exclusive) and mask prose. Tier-1 fields under Settings adjust semantic tie-break threshold and how many recent user lines are embedded.
• Self & user → Personality evolution — monitor Furoshiki's developing personality traits from real interactions. Shows trait scores, observation counts, valence trends, auto-learned roles, and drift history. Traits mature when they have ≥2 observations, score >0.7, and positive valence trend; mature traits generate personality directives in prompts. Auto-learned roles are created from successful interactions with high quality scores. Brain schedules: aggregate_personality_traits (daily 5 UTC), learn_personality_roles (daily 5:30 UTC).
• Self & user → Topic zones — see Topic zones below.

Topic zones (thread blend)

Zones and keywords live in SQLite (topic_zones, topic_zone_keywords) and drive context_zones scoring when FUROSHIKI_CONTEXT_ZONES=1 (default): prompt assembly, conversation compass, and personality-role topic triggers all read the same ids. Use Self & user → Topic zones in the dashboard to add, disable, or delete zones and keywords (seed ships on first furoshiki db migrate when the table is empty).

Heuristic extractions may append bounded source=learned keywords when Tier-1 topic_zones.persist_learned is on — set via memory/operator_settings.json or env FUROSHIKI_TOPIC_ZONE_LEARN_PERSIST / FUROSHIKI_TOPIC_ZONE_LEARN_MAX (see .env.template). Future reflection jobs can insert source=reflection rows the same way.

Dashboard JSON (same Bearer token as the rest of the operator UI; see scripts/dashboard_routes.py): GET/POST/PUT/DELETE /dashboard/api/topic-zones, POST /dashboard/api/topic-zones/{zone_id}/keywords, DELETE /dashboard/api/topic-zone-keywords/{id} (base URL is the repair API host, e.g. http://127.0.0.1:7432). Architecture: docs/SELF-AWARENESS-DESIGN.md (context zones).

Plugins, delegation, extensions

• Plugins & extensions overview
• Plugin author how-to · docs/PLUGIN-HOW-TO.md
• Plugin HTTP API reference · docs/PLUGIN-API.md
• Delegation & skills · docs/DELEGATION-AND-SKILLS.md
• Unified pipeline: docs/EXTENSIONS-UNIFIED-PIPELINE.md

Other harnesses (not Telegram)

Any client reads session-context.json at session start and may call write_session.py at session end. See docs/INTEGRATION.md (minimal contract) and docs/AGENT-INTEGRATION.md (full agent guide).

Brain, Doctor, scheduler

• Brain — internal scheduler (memory/schedules.json) + child processes (listener, repair API, …).
• Doctor — separate watchdog (health, restarts, repair dispatch).
• Cron files in the repo are reference; live cadence is Brain schedules unless you deliberately use OS cron.

Memory & user profile

Conversations are logged and embedded; curated text and user_facts (Chroma) power retrieval and the session profile. Post-conversation jobs update durable state after a quiet window; JIT embedding can capture facts mid-session (see README.md).

• Adaptive profile (refine_user_profile.py) — Brain runs it daily at 3:30 UTC via task refine_user_profile in memory/schedules.json (shipped default in config/defaults/schedules.json). After pulling repo upgrades, run furoshiki schedules merge-defaults once so missing tasks are appended. Also runs with --force after a full post-conversation reflection; manual: furoshiki profile refresh or Telegram /profile_refresh.
• Personality evolution — Furoshiki learns personality traits from real interactions via the record_personality_observation model tool (enabled when FUROSHIKI_MODEL_TOOLS=1, default on). Observations aggregate daily into trait scores; mature traits (≥2 observations, score >0.7, positive valence) generate personality directives in prompts. Auto-learned roles are created from successful interactions. Monitor in dashboard: Self & user → Personality evolution.

Trace & design query

• furoshiki trace "…" — simulate prompt assembly for a synthetic user line (no LLM). --full prints the exact messages bodies; --final-messages prints JSON only (good for replaying the same payload in another client). On the dashboard Trace → Final messages, the <pre> blocks are authoritative; band Markdown below system is analysis-only. When personality roles are enabled, each trace includes a personality_roles object (and a Metadata row) showing whether a situational mask was applied, strict vs semantic path (strict_matched, tiebreak_*), and if nothing matched, read no_match_hint — stage 1 triggers are strict (topic + time-of-day + needs + mood).
• furoshiki design query "…" — semantic search over embedded architecture docs; design update re-embeds after doc changes.

Models & budgets

Switch chat models from Telegram (/model) or use furoshiki config models. Optional llm-routing.json merges per-call routing; tune caps via dashboard/API (/api/v1/budget) or env defaults. See docs/MODELS.md.

Emotion & needs

Emotions, Furoshiki needs, and inferred user needs drive tone and directives. Human-readable mechanics: Emotion state page and docs/EMOTION-STATE-AND-NEEDS.md.

Background loops

Scheduled work includes (among others) post-conversation reflection, question processing, inner monologue, deep reflection, and self-diagnosis. Schedules and rationale are in docs/SELF-AWARENESS-DESIGN.md.

Self-questions & open questions

Inspect and maintain the SQLite pipeline with furoshiki db questions, dedupe helpers, and Telegram /myquestions. Full flow in docs/SELF-AWARENESS-DESIGN.md.

Curiosity & patterns

furoshiki curiosity triage|list classifies the curiosity queue toward observations or follow-ups. furoshiki patterns list|detect surfaces behavioral patterns that can promote into commitments.

Analytics

furoshiki analytics report (optional --llm narrative) and furoshiki analytics alignment join mind-state and contact signals. Dashboard Emotions → Mind analytics mirrors the same data. See docs/ANALYTICS-CORRELATION.md.

API keys

Prefer scoped keys from furoshiki api-keys create for automation; reserve the admin FUROSHIKI_API_TOKEN for operator actions (restarts, destructive routes). Manage keys from the CLI or the dashboard API Keys tab.

Agent backend

furoshiki agent set claude|cursor selects which CLI backend extensions tooling prefers; furoshiki agent status shows the active choice.

Logs & repairs

Tail with furoshiki watch or furoshiki logs <service>; query via API (/api/v1/logs, /api/v1/logs/query). The dashboard Logs page includes a plugins tab for rows written via the Plugin HTTP /plugin/log path (source values like plugin:my-plugin). Loader diagnostics still land under the extensions stream (plugin_pipeline). Repair jobs surface at /api/v1/repairs and in dashboard flows.

Export & data directory

Source code (FUROSHIKI_SRC) and runtime data (FUROSHIKI_DATA) are separate. Use furoshiki export / furoshiki import to move an instance between machines (see README.md).

Dev & restarts

Clone setup uses uv: install uv, then ./install.sh --dev in the repo (uv sync + editable package). Repair: ./install.sh --repair or --recreate.

• furoshiki restart <name|all> — bounce Brain-managed services.
• furoshiki reload-watch — debounced file watch → restart (local dev).
• furoshiki boot install — Windows scheduled task helper where supported.
• HTTP restart: POST /api/v1/services/{name}/restart with admin Bearer token (repair API).