# FamiliarOS Memory System

FamiliarOS has **two kinds of memory** that work together:

1. **Triggered Memory** — explicit facts you teach the Familiar using trigger phrases
2. **Chat History Memory** — the full transcript of every conversation, searchable across sessions

---

## 1. Triggered Memory (Explicit)

These are stored when you use specific phrases in your prompts. The Familiar extracts the fact and saves it permanently.

### Trigger Phrases

| Phrase | Example | What gets stored |
|--------|---------|------------------|
| `Remember that ...` | "Remember that I have two dogs" | Note: "User has two dogs." |
| `My name is ...` | "My name is Alice" | Identity: "User's name is Alice." |
| `Call me ...` | "Call me Bob" | Identity: "User's name is Bob." |
| `My favorite ... is ...` | "My favorite color is blue" | Preference: "User's favorite color is blue." |
| `I prefer ...` | "I prefer dark mode" | Preference: "User prefers dark mode." |

### How triggered memory works

- Each trigger phrase is matched with a regex on every message you send
- Extracted facts are deduplicated by normalized text
- Stored in `familiaros-memory.json` in your user data directory
- Injected into the system prompt when relevant to your current query
- You can view, edit, and delete memories in **Settings → Memory**

### Tips for best results

- Use simple, declarative sentences
- One fact per message works best
- The Familiar does **not** automatically extract facts from free-form chat — you must use trigger phrases

---

## 2. Chat History Memory (Automatic)

Every conversation is saved automatically. You can browse past conversations and the Familiar can reference them.

### What is saved

- Every message you send
- Every reply the AI gives
- System messages and error states
- Timestamps for each entry

### How chat history memory works

- Conversations are stored in `familiaros-chat-history.json`
- Conversation metadata (title, date, message count) is stored in `familiaros-chat-conversations.json`
- When building context for the AI, both triggered memories **and** relevant past conversation excerpts are searched
- This gives the Familiar "memory" across multiple chat sessions without requiring explicit triggers

### Browsing history

- Click the **History** button in the prompt window to see a list of all conversations
- Click any conversation to open it
- The **Editor** button shows the current conversation's message list

---

## File Locations

| File | Platform | Path |
|------|----------|------|
| Triggered memories | Windows | `%APPDATA%/FamiliarOS/familiaros-memory.json` |
| Triggered memories | Linux | `~/.config/FamiliarOS/familiaros-memory.json` |
| Chat history | Windows | `%APPDATA%/FamiliarOS/familiaros-chat-history.json` |
| Chat history | Linux | `~/.config/FamiliarOS/familiaros-chat-history.json` |
| Conversations | Windows | `%APPDATA%/FamiliarOS/familiaros-chat-conversations.json` |
| Conversations | Linux | `~/.config/FamiliarOS/familiaros-chat-conversations.json` |

Legacy `openpets-*.json` files are still migrated on load for compatibility,
but FamiliarOS writes the new `familiaros-*.json` filenames going forward.