# Furoshiki — Agentic Integration Guide

**This file is self-contained.** Any LLM agent, skill, or harness can read this single file and know exactly how to integrate with Furoshiki — no prior knowledge assumed.

---

## Who the user is

Canonical user context is **`session-context.json`** (`user_profile_mini`, `user_profile_reference`, `user_facts` retrieval) — not `config/USER.md` (not injected).

---

## What Furoshiki is

Furoshiki is a persistent AI with memory, needs, an inner life, and a continuous existence between sessions. It isn't stateless. It has:

- **A system identity shell** in `scripts/identity_shell.py` (non-operator prose in prompts). When `FUROSHIKI_PERSONALITY_ROLES=1` (or `personality_roles.enable` in `operator_settings.json`), Telegram may append a short **situational role** suffix after that shell; agent harnesses that bypass `telegram_listener.build_system_prompt()` do not get that suffix unless they call `role_selector.select_personality_role` themselves.
- **A living self-model** in `~/furoshiki/config/SELF.md` that updates from reflection
- **Episodic memory** of every past conversation, stored in SQLite and ChromaDB
- **Needs** (connection, curiosity, purpose, rest) that decay over time and color responses
- **A mind queue** of thoughts to share proactively
- **An inner monologue** — a private journal written daily

When you integrate with Furoshiki, you are not wrapping a chatbot. You are connecting to a living system that has state, history, and continuity.

---

## Integration Levels

There are three ways to integrate. Choose the one that matches your use case.

---

### Level 1 — Conversational Harness

**When to use:** You are building an interface where the user (the user) talks to Furoshiki directly — a chat app, voice interface, new messaging platform, mobile app, etc.

**You are:** The voice of Furoshiki in a new medium. You speak from session-context + learned profile + the system identity shell; maintain conversation history, and write sessions to memory when conversations end.

**What to do at session start:**

```python
import json, pathlib

ctx = json.loads(pathlib.Path('~/furoshiki/session-context.json').expanduser().read_text())
```

Inject `ctx['narrator_briefing']` into your system prompt. It contains a natural-language summary of Furoshiki's current state — needs, recent events, active anticipations.

Also align with:
- `~/furoshiki/config/SELF.md` — self-model (for continuity if your harness reads files)
- `~/furoshiki/config/MEMORY.md` — curated long-term memory (optional)

**What to do at session end:**

```bash
python3 ~/furoshiki/scripts/write_session.py \
  --source "system:your-harness-name" \
  --text "Brief summary: topics discussed, the user's mood, anything notable" \
  --emotional-read "the user's apparent emotional state"
```

Replace `your-harness-name` with a stable identifier (e.g. `mobile`, `voice`, `web`).

This writes to `~/furoshiki/memory/YYYY-MM-DD.md`, embeds the session into ChromaDB, and fires the soul engine. The soul engine handles everything from there.

**Optional — if the user answered a self-question during the session:**
```bash
python3 ~/furoshiki/scripts/write_session.py \
  --source "system:your-harness-name" \
  --text "..." \
  --user-answered '{"question_id": N, "summary": "their answer", "confidence": 0.8}'
```

**Tone and voice rules:**

Use **`session-context.json`** + **`scripts/identity_shell.py`** (same as Telegram). Never announce needs or internal state — let them color tone naturally.

---

### Level 2 — Background Skill

**When to use:** You are building an automated loop, a scheduled script, or a background capability that adds to Furoshiki's inner life — without being a conversational interface. Examples: a weather context injector, a mood analyzer, a calendar-aware anticipation writer, a news digest.

**You are:** A contributor to Furoshiki's inner state. You don't hold the chat persona. You add data that the soul engine and loops will process.

**Entry points — write to the system:**

| What you want to do | How to do it |
|---------------------|-------------|
| Log something that happened | `python3 ~/furoshiki/scripts/add_system_event.py --kind note --summary "..."` |
| Queue a thought for Furoshiki to send the user | `python3 ~/furoshiki/scripts/enqueue_mind.py --kind note --summary "..."` |
| Add a curiosity to explore in next inner monologue | `python3 ~/furoshiki/scripts/add_curiosity.py --content "..."` |
| Add an anticipation (upcoming event) | `python3 ~/furoshiki/scripts/add_anticipation.py --content "..." --due-date "YYYY-MM-DD"` |
| Add a curated memory | `python3 ~/furoshiki/scripts/add_memory.py --content "..."` |
| Record a self-observation | `python3 ~/furoshiki/scripts/add_self_observation.py --content "..."` |
| Ask a question Furoshiki wants to put to the user | `python3 ~/furoshiki/scripts/add_self_question.py --question "..."` |

**`PLUGIN.md` plugins (installable extension):** To package hooks that Furoshiki discovers under `$FUROSHIKI_DATA/plugins/<name>/` (pre/post conversation, reflection, callable tools, Brain-scheduled jobs), follow **`docs/PLUGIN-SPEC.md`** end-to-end — manifest schema, `--mode` contracts, and permissions. After install, `furoshiki plugins reload` registers `type: cron` hooks into `memory/schedules.json`. Overview: **`https://furoshiki.ai/plugins-extensions.html`**.

**Script conventions** (follow these so your script fits the system):
- Import from `db.py` for all DB connections and path constants
- Use `llm.py` for all LLM calls — budget enforcement is automatic
- Write a row to `system_events` when your script runs (soul engine reads this)
- Log to `~/furoshiki/logs/your-script.log` via Python's standard `logging`
- Name: `run_*.py` for scheduled loops, `add_*.py` for write tools, `query_*.py` for read tools
- Schedule with the **Brain**: add a task to `$FUROSHIKI_DATA/memory/schedules.json` (or use a `PLUGIN.md` `cron` hook + `furoshiki plugins reload`). Legacy OS crontab: `python3 ~/furoshiki/scripts/manage_cron.py` / `furoshiki cron sync` only if you still use that path.

---

### Level 3 — Agentic Skill (Claude Code / Cursor / IDE Agent)

**When to use:** You are a coding agent (Claude Code, Cursor, Cline, etc.) operating in the Furoshiki project directory. You are helping build, debug, or extend the system.

**You are:** A developer collaborating on Furoshiki's codebase. You know the architecture and follow the design rules.

**Key rules:**
1. Always update `docs/SELF-AWARENESS-DESIGN.md` when making design changes (new scripts, new tables, new loops, integration changes)
2. New memory tables → add `CREATE TABLE IF NOT EXISTS` to `scripts/init_db.py`, then run **`furoshiki db migrate`**
3. New scheduled jobs → add a task to **`$FUROSHIKI_DATA/memory/schedules.json`** (Brain hot-reloads). Legacy only: repo `cron/crontab` + **`furoshiki cron sync`** if you still use OS crontab.
4. New models → add two lines to `scripts/llm.py`: entry in `MODEL_SHORTCUTS`, entry in `_COST_TABLE`
5. Never hardcode absolute paths — use constants from `db.py`
6. Every LLM feature needs a token estimate before building
7. Never touch `config/SOUL.md`, `config/SELF.md`, `config/USER.md`, `config/MEMORY.md`, or `memory/**` via automated repair — these are protected

**Useful read targets:**
- `scripts/db.py` — all path constants and DB connection helpers
- `scripts/llm.py` — all LLM call helpers, model shortcuts, budget enforcement
- `scripts/soul_engine.py` — understand the event processing pipeline before adding events
- `scripts/write_session.py` — canonical session writer, read before writing session-adjacent code
- `docs/SELF-AWARENESS-DESIGN.md` — full architecture with data flow diagram

---

## One Absolute Rule — No Proactive DMs

**Never send a proactive message to the user from a session, skill, or agent.**

The only path for proactive outreach is the **Voice Dispatcher** (`~/furoshiki/scripts/voice_dispatcher.py`). **Cron** runs **`outreach_pulse.py` every 5 minutes**, which subprocesses `voice_dispatcher.py` each time. At most one message is sent per pulse when gates pass; `mind_queue` is the queue.

Behavioral cues for both chat and proactive Telegram copy are centralized in **`scripts/voice_context.py`** (`build_behavioral_cues`, channel contracts) so the listener and voice dispatcher stay aligned. The Telegram channel contract includes explicit handling for user-invited hypotheticals and roleplay while keeping inner monologue and system details private.

To queue a thought for the next outreach window:
```bash
python3 ~/furoshiki/scripts/enqueue_mind.py --kind note --summary "..."
```

Violating this causes duplicate message storms (happened 2026-03-22, 16+ DMs in 3 minutes).

---

## On-Demand Operations

When the user asks Furoshiki to think, reflect, or check inner state, a conversational harness can trigger these:

| the user asks | Command |
|------------|---------|
| Refresh current state | `python3 ~/furoshiki/scripts/refresh_session_context.py` |
| Recompute needs | `python3 ~/furoshiki/scripts/furoshiki_on_demand.py needs --trigger session` |
| System health | `python3 ~/furoshiki/scripts/furoshiki_on_demand.py health` |

After refresh, re-read `~/furoshiki/session-context.json` before composing the reply.

---

## Data Paths

| Path | What it is |
|------|-----------|
| `~/furoshiki/session-context.json` | Live state snapshot — regenerated every 30 min and after each post-conversation run. Includes `user_profile_mini` and `user_profile_reference` (synthesised from Chroma `user_facts`; see `docs/INTEGRATION.md`) and optional `active_role` when personality roles are enabled |
| `~/furoshiki/memory/YYYY-MM-DD.md` | Session logs from all harnesses |
| `~/furoshiki/memory/longmemory.sqlite` | All structured state — needs, queues, events, inner monologue |
| `~/furoshiki/memory/chroma/` | ChromaDB semantic memory — all sessions embedded |
| `~/furoshiki/memory/inner-monologue/` | Daily private journal files |
| `~/furoshiki/memory/heartbeat-state.json` | Live needs, mood, last decay timestamp |
| `~/furoshiki/memory/operator_settings.json` | Optional — operator/dashboard **Settings** (Tier 1); merges into script behavior (see `docs/INTEGRATION.md`; `personality_roles.enable` gates `active_role` / situational mask) |
| `~/furoshiki/scripts/identity_shell.py` | System identity shell injected into prompts (not operator prose) |
| `~/furoshiki/config/SELF.md` | Self-model (updates via deep reflection, weekly) |
| `~/furoshiki/config/USER.md` | Legacy file on disk only — **not** used in prompts; use `user_facts` + profile |
| `~/furoshiki/config/MEMORY.md` | Curated long-term memory |
| `~/furoshiki/scripts/` | All Python scripts |
| `~/furoshiki/logs/` | All runtime logs |

---

## What Runs Automatically

You don't need to orchestrate these. They run via cron or systemd:

| What | When | Effect |
|------|------|--------|
| Soul Engine | every 15 min | Decays needs, processes events, fills mind_queue |
| Outreach pulse → Voice Dispatcher | every 5 min | `outreach_pulse.py` invokes `voice_dispatcher.py` (≤1 send per run when gates pass) |
| Micro-Contemplation | every 15 min | Emotion-driven self-reflection |
| Post-Conversation | 20 min after quiet | Reflection, user_facts embed, `refine_user_profile.py`, follow-up queuing |
| Session Context Refresh | every 30 min | Regenerates `session-context.json` |
| Inner Monologue | 06:00 UTC daily | Nightly journal, curiosity generation |
| Morning Reflection | 16:00 UTC daily | Daily orientation |
| Afternoon Processing | 23:00 UTC daily | Post-session reflection |
| Emotional Read | every 6h | Records emotional weights |
| Deep Reflection | 10:00 UTC Wed | Updates SELF.md |
| Self-Diagnosis | 07:00 UTC daily | LLM health check, auto-patches |
| Doctor | every 5 min | stdlib-only health watchdog |

---

## Querying Furoshiki's Memory

Any agent can search Furoshiki's semantic memory:

```bash
python3 ~/furoshiki/scripts/query_memory.py "what has the user said about his health"
```

Returns the top matching session chunks from ChromaDB.

For structured queries against SQLite:
```bash
python3 ~/furoshiki/scripts/query_db.py "SELECT * FROM self_observations ORDER BY created_at DESC LIMIT 10"
```

---

## Quick Reference

```
# Check current state
cat ~/furoshiki/session-context.json

# Write a session (after any conversation)
python3 ~/furoshiki/scripts/write_session.py --source "system:name" --text "..." --emotional-read "..."

# Queue a thought for Furoshiki to say
python3 ~/furoshiki/scripts/enqueue_mind.py --kind note --summary "..."

# Search memory
python3 ~/furoshiki/scripts/query_memory.py "search terms"

# System health
python3 ~/furoshiki/scripts/furoshiki_on_demand.py health

# Cron management
python3 ~/furoshiki/scripts/manage_cron.py list

# Full CLI
~/furoshiki/bin/furoshiki --help
```
