# FamiliarOS — Our Additions (Isolated README)

This README describes only the capabilities added by our fork. It is kept separate from the upstream `README.md` so the original maintainer can review and adopt changes independently.

## New: Floating Chat Window

Double-click the desktop familiar to open an always-on-top floating chat window.

- BYOK OpenAPI-compatible chat (OpenAI, OpenRouter, Moonshot/Kimi, LiteLLM, vLLM, Azure, custom).
- Conversation history rendered as a styled list with role badges and timestamps.
- History persists across app restarts.
- Compact mode at 96px height; expanded editor/history mode at 280px.
- Prompt bar sized for 2–3 lines of text.
- Resizable corner grip; size remembered per mode.
- Enter sends, Ctrl+Enter inserts a newline, Escape closes.

## New: Local Memory

FamiliarOS now remembers things for you.

- Durable local memory store with automatic capture from chat prompts.
- Relevance-based retrieval into future system prompts.
- Memory kinds: preference, identity, fact, note.
- In-app memory viewer in Settings for search, edit, and delete.
- Also exposed through existing FamiliarOS MCP tools (`familiaros_memory_*`).

## New: Knowledge Store

Store files and add manual knowledge entries that the assistant can reference during chat.

- Upload files from Settings > Knowledge Store or store attachments directly from the floating chat window.
- Text-like files are indexed and searched by file name and extracted content.
- Relevant files are injected into the assistant's system instructions automatically.
- Combined search across stored files and FamiliarOS memories.

## New: MCP Tool Servers — Tools for Your Familiar's Chat

The **MCP Tool Servers** panel gives the built-in floating chat the ability to do real work on your local machine. It is separate from the external-agent bridge.

- Activate tools such as filesystem, terminal, web fetch, sequential thinking, Playwright, Git, GitHub, Docker, and SQLite.
- The tools run through an internal stdio MCP client in the main process.
- Once enabled, you can ask your Familiar things like *"List the files in my home directory,"* *"Summarize that PDF,"* or *"Run this test script."*
- Tools can be turned on or off individually, so you only grant the access you actually want.

## New: FamiliarOS MCP Server Panel — Your Familiar as a Tool for External Agents

The **FamiliarOS MCP Server** panel exposes your Familiar to Claude Code, Cursor, OpenCode, Codex CLI, or any other MCP-capable host.

- Command mode selector (published / bundled / local) in one place.
- Node path override and Familiar routing in one place.
- One-click **Test Server** health check.
- One-click **Copy MCP JSON** for pasting into your agent's MCP configuration.
- This is a small, controlled bridge: external agents can make your Familiar react, speak a safe bubble, or read/write memory, but they do not get unrestricted access to your desktop.

## New: MCP Toolkit Guide — A Safe Manual for the Wider MCP World

The **MCP Toolkit Guide** is a hand-picked reference surface for adopting the broader MCP ecosystem deliberately.

- It is **not** an automatic installer; it explains what popular MCP tools do, what permissions they need, and how to set them up manually.
- Each entry includes copy-paste snippets and guidance for supported hosts.
- Use it to build a persistent tool bundle or to understand a tool before you enable it.

## New: Familiar Scale

- Continuous scale slider from 0.16x to 10x in Settings.
- Window dynamically resizes so the familiar is never clipped.

## New: Virtual Familiar Status

- Bundled virtual-familiar plugin tracks hunger, energy, happiness, and affection.
- Status values live in the right-click familiar context menu (Virtual Familiar ▸ Mood, Food, Energy, Play, Bond, Level) instead of an on-familiar HUD overlay, so double-click chat stays unobstructed.
- Feed, play, familiar, and nap commands are available from the familiar context menu.

## New: Familiar Character & Base Instructions

- Give your Familiar a custom system-prompt style character in Settings.
- Toggle whether the default FamiliarOS behavior instructions are included in every chat.

## New: Custom Familiar Name

- Name your default Familiar in Settings → General.
- The chosen name appears in the tray tooltip, tray context menu, and anywhere the default Familiar is referenced.
- If no name is set, the menu falls back to the Familiar's display name or "Built-in Familiar."


## New: Text-to-Speech (Phase 2)

The familiar can now speak aloud using a configurable TTS provider.

- Settings > **Text-to-Speech** chooses between system OS voice, OpenAI TTS, ElevenLabs, Piper (local), or an OpenAI-compatible endpoint.
- Per-provider voice, model, speed, endpoint preset, and API-key storage.
- Test and Stop buttons preview the voice in Settings.
- Speech is skipped during quiet hours and uses the same safety boundaries as bubbles.
- Plugins with the `voice:speak` permission can ask the familiar to speak.

## New: Multi-Screen Awareness

The familiar now stays on the display it is currently near, rather than always snapping to the primary display.

## Installing these changes

No additional setup is required beyond the normal FamiliarOS desktop app. The new surfaces appear automatically:

- Single-click the familiar → familiar the virtual familiar.
- Double-click the familiar → floating chat.
- Right-click the familiar → Virtual Familiar status and care commands.
- Settings → OpenAPI Chat for model/credential setup.
- Settings → Text-to-Speech for voice provider and test preview.
- Settings → Memory for memory management.
- Settings → Knowledge Store for file-based knowledge.
- Integrations → MCP Tool Servers for built-in chat tool activation.
- Integrations → FamiliarOS MCP Server for external-agent bridge configuration.
- Integrations → MCP Toolkit Guide for optional persistent bundles and copy-paste snippets.