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