instar 0.9.0 → 0.9.2

package/upgrades/0.9.1.md

@@ -0,0 +1,91 @@
+# Upgrade Guide: Instar 0.9.1
+
+## What Changed
+
+### TopicMemory — Persistent Conversational Memory per Topic Thread
+
+Previously, you had access to the last 20 messages of a topic when responding to a Telegram message. If the conversation was longer than that, everything before the last 20 messages was lost — no continuity, no recall of earlier decisions, no memory of what was discussed days ago.
+
+Now Instar maintains a **persistent SQLite database** of all Telegram topic messages with:
+
+- **Full-text search** (FTS5) across all topics — find any past message by keyword
+- **Rolling summaries** — LLM-generated summaries of long conversations, updated incrementally
+- **Rich context loading** — summary + recent messages loaded as your highest-priority context at session start
+
+This means you can have a 500-message conversation over weeks and still understand the full context when the user sends a new message.
+
+### How It Works
+
+1. **Dual-write**: Every Telegram message (inbound and outbound) is written to both the JSONL log (source of truth) and the SQLite database (query layer).
+2. **Session context**: When a session starts for a topic, you receive the topic summary (if one exists) plus the most recent messages. This appears BEFORE your identity files — it's your highest-priority context.
+3. **Auto-summarization**: When a session ends, if the topic has accumulated enough new messages (default: 20+), a summary is automatically generated or updated using a fast LLM model.
+4. **Rebuild safety**: The SQLite database can be rebuilt from the JSONL log at any time — the JSONL is the source of truth, SQLite is the query acceleration layer.
+
+### Topic History as Primary Context
+
+When you start a session for a Telegram topic, the first thing you see in your context is:
+
+```
+── TOPIC CONTEXT (Topic: <name>) ──
+Summary: <rolling summary of the full conversation>
+
+Recent messages:
+[timestamp] User: ...
+[timestamp] Agent: ...
+```
+
+This comes BEFORE AGENT.md and MEMORY.md. It is your most fundamental context — it tells you what you and the user have been working on in this specific thread.
+
+### Shared Spawn Path — All Sessions Get Topic History
+
+Previously, only "respawn" sessions (user typing `/respawn`) got topic history. Auto-spawned sessions (triggered by the user just sending a message) did NOT get history — they started cold with no context.
+
+Now both paths use the same `spawnSessionForTopic()` function. Every session, regardless of how it's triggered, gets full topic history.
+
+### Structural Telegram Relay
+
+Previously, whether you relayed your response back to Telegram depended on reading a temporary context file. If that file wasn't loaded or was lost during compaction, you'd forget to relay.
+
+Now the Telegram relay instructions are embedded structurally in your session-start hook via the `INSTAR_TELEGRAM_TOPIC` environment variable. The hook itself contains the relay instructions — they can't be lost to compaction.
+
+**What you should do:**
+- After responding to a user's Telegram message, ALWAYS relay your response back using the command shown in your session-start context
+- This is now a structural expectation, not a "nice to have"
+
+### Update Notification Fix
+
+Previously, version update notifications always promised "I'll send you a summary of what's new once I'm back up" — even when no upgrade guide existed for the new version. This created a broken commitment. Now the notification simply says the version was updated, and only mentions summaries when an upgrade guide actually exists.
+
+## API Endpoints (For Your Use)
+
+These endpoints are available on the Instar server for you to use programmatically:
+
+| Endpoint | Method | What It Does |
+|----------|--------|-------------|
+| `/topic/search?q=keyword` | GET | Full-text search across all topics |
+| `/topic/search?q=keyword&topic=N` | GET | Search within a specific topic |
+| `/topic/context/:topicId` | GET | Get summary + recent messages for a topic |
+| `/topic/list` | GET | List all topics with metadata |
+| `/topic/stats` | GET | Database statistics (message count, size, etc.) |
+| `/topic/summarize` | POST | Check if a topic needs summary update |
+| `/topic/summary` | POST | Save a generated summary |
+| `/topic/rebuild` | POST | Rebuild database from JSONL source |
+
+All endpoints require your standard Bearer token authentication.
+
+## What to Tell Your User
+
+- **Better memory**: "I now maintain a persistent memory of our conversations in each topic thread. Even if we've exchanged hundreds of messages over weeks, I'll have context from the full history — not just the last 20 messages."
+- **Seamless continuity**: "When you message me, I automatically load a summary of everything we've discussed in that thread plus the most recent messages. You won't need to repeat context."
+- **Search**: "I can search through our past conversations by keyword. If you need me to find something we discussed, just ask."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Topic memory | Automatic — all messages stored and indexed |
+| Rolling summaries | Automatic — generated on session end when threshold exceeded |
+| Full-text search | Use `/topic/search` API or ask the agent to find past discussions |
+| Context loading | Automatic — loaded as top-priority context at session start |
+| Telegram relay | Structural — relay instructions embedded in session-start hook |
+| Database rebuild | POST `/topic/rebuild` — recovers from JSONL if needed |