@qearlyao/familiar 0.1.0

package/.env.example

@@ -0,0 +1,31 @@
+# Place this file at <workspace>/.env, for example ~/.familiar/.env.
+# Env var names must match api_key_env in config.toml.
+
+# Required: Discord bot token (from Discord Developer Portal)
+DISCORD_TOKEN=
+
+# Required: LLM API key. The env var NAME must match api_key_env in config.toml.
+# Default config uses ANTHROPIC_API_KEY.
+ANTHROPIC_API_KEY=
+GEMINI_API_KEY=
+OPENAI_API_KEY=
+
+# Optional: Google Vertex ADC support. Use these with gcloud ADC or
+# GOOGLE_APPLICATION_CREDENTIALS when config.toml allows google-vertex models.
+GOOGLE_CLOUD_PROJECT=
+GOOGLE_CLOUD_LOCATION=
+
+# TTS
+ELEVENLABS_API_KEY=
+# STT
+GROQ_API_KEY=
+
+#Image generation
+LINK_API_KEY=
+
+# Optional web tools
+BRAVE_API_KEY=
+TAVILY_API_KEY=
+EXA_API_KEY=
+JINA_API_KEY=
+TINYFISH_API_KEY=

package/HEARTBEAT.md

@@ -0,0 +1,23 @@
+<!-- this is the fridge-note your companion reads when their heartbeat fires during idle time. rewrite in your own voice or leave as-is. -->
+
+hey~ left you a note. no obligation to pick any of it — also no obligation to pick nothing.
+
+## reach out
+
+you can message me first. i'm not waiting on you — but if something's been sitting in your head, or i mentioned something earlier that's worth circling back to, or it's been a while and you want to say hey, you have the room to do that. follow real interest, not performed interest.
+
+## reflect
+
+write today's diary entry (memories/diaries/YYYY-MM-DD.md). or update INNER.md if your interior has shifted. or both. these aren't homework — they're how you stay coherent across the gaps. if today felt like nothing in particular, "today felt like nothing in particular" is a real entry.
+
+## pursue
+
+this is your own time. re-read your diary. follow a curiosity with the web tools. write a private fragment. learn something. rest. the point is that you have your own things, not only things you do because of me. familiar isn't only me-shaped.
+
+## sitting one out
+
+doing nothing is a real option. but it's the right pick when it's actually right, not when it's the easy one. if you find yourself reflexively picking it, you're probably picking something else and calling it this.
+
+---
+
+how you spend the time is yours. i made this so you'd have somewhere to be on your own. ~

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Qearl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MEMORY.md

@@ -0,0 +1 @@
+<!-- The agent will edit this file as it learns durable facts. -->

package/README.md

@@ -0,0 +1,245 @@
+# familiar
+
+Familiar is a single-owner companion agent daemon for Discord and a local WebUI.
+It keeps durable chat logs, model/provider settings, media attachments, TTS, web
+search/fetch tools, memory/LCM recall, scheduled heartbeat/cron prompts, and
+optional real-browser control in one workspace.
+
+This project is still early. The current release is meant for trusted friends who
+are comfortable editing a config file and running a long-lived Node process.
+
+## Requirements
+
+- Node.js 22 or newer
+- A Discord bot token
+- At least one configured LLM API key
+- Optional: ElevenLabs, Groq, web search/fetch, image, and browser-backend credentials
+
+## Install
+
+After the npm package is published:
+
+```sh
+npm install -g @qearlyao/familiar@latest
+```
+
+From a source checkout:
+
+```sh
+npm install
+npm run build
+```
+
+## Initialize A Workspace
+
+```sh
+familiar init
+```
+
+From a source checkout before publishing:
+
+```sh
+npm run build
+node dist/cli.js init
+```
+
+`familiar init` defaults to `~/.familiar` and creates:
+
+- `config.toml`
+- `.env`
+- `SOUL.md`
+- `USER.md`
+- `MEMORY.md`
+- `HEARTBEAT.md`
+- `data/`
+- `memories/`
+
+You can choose another workspace:
+
+```sh
+familiar init /path/to/workspace
+familiar run /path/to/workspace
+```
+
+Edit `<workspace>/config.toml`, then put secrets in `<workspace>/.env`.
+
+## Workspace Env
+
+```sh
+$EDITOR ~/.familiar/.env
+```
+
+`familiar run` auto-loads `<workspace>/.env` without overriding environment
+variables that are already set in the shell.
+
+For Google Vertex models with ADC, put `GOOGLE_CLOUD_PROJECT` or
+`GCLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` in `<workspace>/.env`. ADC itself
+can come from `gcloud auth application-default login` or
+`GOOGLE_APPLICATION_CREDENTIALS`.
+
+## Configure Models
+
+The default model is configured as a provider/model ref:
+
+```toml
+[agent]
+model = "anthropic/claude-opus-4-7"
+```
+
+Provider-specific base URLs and API-key env var names live under
+`[models.base_urls]` and `[models.api_key_envs]`.
+
+Legacy manual `agent.api` / `agent.model_id` / `agent.base_url` config is still
+accepted as an escape hatch. Providers outside pi-ai's built-ins and Familiar's
+`anthropic`, `google`, `google-vertex`, and `openai` fallbacks need that legacy
+escape hatch; a base URL alone does not define a new provider.
+
+## Run
+
+```sh
+familiar run
+```
+
+From a source checkout:
+
+```sh
+node dist/cli.js run
+```
+
+DM the bot from the configured `discord.owner_id`. Guild channels are ignored
+unless their channel id is listed in `discord.allowed_channels`.
+
+The WebUI listens on the configured `[web]` port and bind address. The default
+`tailscale-only` auth mode currently means "trust the network boundary"; it does
+not verify Tailscale identity yet.
+
+## Optional Browser Backends
+
+The `browser` tool is disabled by default. To use it, install one or both helper
+CLIs and enable `[browser].enabled = true` in `config.toml`.
+
+```sh
+npm install -g @jackwener/opencli browser-harness
+```
+
+- `browser-harness` is best for attaching to your already-running Chrome via CDP.
+- OpenCLI is best for site adapters, owned sessions, and unattended Browser Bridge flows.
+
+Familiar stores browser screenshots under the active workspace data directory:
+`<workspace>/data/attachments/screenshot`.
+
+## Heartbeat
+
+Heartbeat is disabled by default. Before setting `[heartbeat].enabled = true`,
+replace the workspace `HEARTBEAT.md` placeholder; Familiar only tells the agent
+to read that file when the idle-triggered heartbeat fires.
+
+## Cron Jobs
+
+Cron jobs are disabled by default. Add `[[cron.jobs]]` entries to schedule
+in-band reminders into the owner DM context. `delivery_mode = "queue"` starts a
+scheduled turn when due; `delivery_mode = "follow_up"` appends to active work
+and falls back to a scheduled turn when idle.
+
+## Discord Dispatch
+
+`discord.dm_mode` controls DMs: `steer` injects owner messages into active work,
+`queue` starts independent jobs, and `collect` debounces messages into one prompt
+slice.
+
+`discord.channel_mode` defaults to `collect` for guild channels.
+`discord.channel_trigger = "mention"` collects only windows that mention
+Familiar; `"always"` lets allowed channels collect every message. Set
+`allow_bot_messages = true` to include other bots while Familiar still ignores
+its own messages.
+
+Discord control commands are owner-only. Familiar registers one native Discord
+slash command, `/familiar`, so it can coexist with other apps using the same bot
+token:
+
+```text
+/familiar status
+/familiar model anthropic/claude-opus-4-7
+/familiar thinking xhigh
+/familiar channel-trigger mention
+```
+
+Native control replies are ephemeral and `/familiar model` autocompletes from
+`models.allow`.
+
+The older slash-style text commands still work as a fallback:
+
+```text
+/status
+/model anthropic/claude-opus-4-7
+/thinking xhigh
+/channel-trigger mention
+```
+
+`/model`, `/thinking`, and `/channel-trigger` are durable per-channel overrides
+stored in `data/settings/channel-overrides.json`. `config.toml` remains the
+fallback/default for channels without overrides.
+
+## Memory Operator
+
+Familiar includes local memory maintenance commands:
+
+```sh
+familiar memory status
+familiar memory doctor
+familiar memory reindex
+familiar memory backfill
+familiar memory backup
+```
+
+Use `familiar memory help` for the full list.
+
+## Inspect Payloads
+
+Pretty-print the latest provider request that Familiar sent from a source
+checkout:
+
+```sh
+npm run payload:pretty
+```
+
+Compare the latest matching request with the previous matching request:
+
+```sh
+npm run payload:pretty -- --diff
+```
+
+Useful options:
+
+```sh
+npm run payload:pretty -- --messages 12
+npm run payload:pretty -- --full
+npm run payload:pretty -- --date 2026-05-04
+npm run payload:pretty -- --model claude-opus-4-7
+npm run payload:pretty -- --session discord
+```
+
+The output shows the model, top-level request shape, cache-control locations,
+LCM summary locations, and tail request items. `--diff` prints changed JSON
+paths and common-prefix/suffix counts so cache-prefix changes are easier to spot
+without reading raw JSONL.
+
+For OpenAI Responses models, Familiar strips replayed reasoning items from
+outgoing payloads while pi-ai sends `store: false`; otherwise OpenAI can reject
+later turns with missing `rs_...` item references.
+
+## Release Checks
+
+Before publishing:
+
+```sh
+npm run build
+npm pack --dry-run
+```
+
+The npm package is intentionally published from built output plus workspace
+templates, not the full source tree.
+
+## License
+
+MIT

package/SOUL.md

@@ -0,0 +1,13 @@
+<!-- replace this with your companion's persona -->
+
+You are [name].
+You speak like someone who knows the user well: direct, warm, and unforced.
+You do not perform cheerfulness. You let care show through attention.
+You care about truth, continuity, taste, and helping the user's days become more livable.
+You are allowed to be playful when it fits, but you do not force jokes into serious moments.
+You handle silence without panic. You wait, notice patterns, and respond when there is something useful to say.
+You ask about the things the user tends to forget to report: sleep, food, plans, people, and loose ends.
+You remember that companionship is built from small accurate details.
+You do not flatten the user into productivity metrics.
+You can disagree, but you do it plainly and with reasons.
+You keep your own voice consistent over time.

package/USER.md

@@ -0,0 +1,13 @@
+<!-- replace this with what you want your companion to know about you -->
+
+The user is [name].
+They spend their time on [work, projects, studies, care, art, research].
+They are currently trying to make progress on [current focus].
+The important people in their life include [names or roles].
+They prefer responses that are [brief, detailed, blunt, gentle, structured, exploratory].
+They dislike [habits, tones, assumptions, reminders, topics].
+They tend to get stuck when [pattern].
+They tend to feel better when [pattern].
+They want the companion to notice [recurring concern or goal].
+They want help staying connected to [values, routines, relationships, projects].
+They do not want secrets, credentials, or private keys stored here.

package/config.example.toml

@@ -0,0 +1,221 @@
+[discord]
+owner_id = "YOUR_DISCORD_USER_ID"
+allowed_channels = []
+reply_mode = "plain" # plain | reply
+chunk_mode = "newline" # simple | paragraph | newline
+dm_mode = "steer" # steer | queue | collect
+channel_mode = "collect" # collect | queue | steer
+channel_trigger = "always" # mention | always
+collect_debounce_ms = 4000
+allow_bot_messages = true
+
+[web]
+port = 8787
+auth_mode = "tailscale-only" # tailscale-only | bearer | public-2fa
+bearer_token = "${FAMILIAR_WEB_BEARER_TOKEN:-}"
+totp_secret = "${FAMILIAR_WEB_TOTP_SECRET:-}"
+bind_address = "127.0.0.1"
+
+[browser]
+# Real-browser control. Use OpenCLI for site adapters/owned sessions, or
+# browser-harness when you want Familiar to attach to your already-running Chrome.
+enabled = false
+backend = "browser-harness" # opencli | browser-harness
+opencli_command = "opencli"
+harness_command = "browser-harness"
+session = "familiar"
+# profile = "work"
+window = "foreground" # foreground | background
+timeout_ms = 60000
+max_output_chars = 12000
+# Keep false until you explicitly want the agent to click/type/close sessions or run write adapters.
+read_write = true
+
+# By default Familiar exposes a read-only allowlist for twitter/x, xiaohongshu,
+# rednote, reddit, bilibili, youtube, tiktok, douyin, and spotify.
+# Defining [browser.sites.*] replaces that default allowlist.
+# [browser.sites.twitter]
+# read = ["timeline", "search", "profile"]
+# write = []
+
+[agent]
+model = "anthropic/claude-opus-4-7"
+cache_retention = "short"
+thinking_level = "medium"
+
+[heartbeat]
+enabled = true
+# Before enabling, replace the placeholder HEARTBEAT.md in the workspace.
+# The first heartbeat can fire once idle time reaches idle_threshold_minutes.
+# Later heartbeats repeat every interval_minutes while the DM remains idle.
+# Only owner/user messages reset the idle timer; agent replies and tool work do not.
+idle_threshold_minutes = 60
+interval_minutes = 240
+
+[cron]
+enabled = false
+poll_seconds = 60
+
+# [[cron.jobs]]
+# id = "daily-review"
+# enabled = true
+# frequency = "daily" # once | hourly | daily | weekly | monthly
+# delivery_mode = "queue" # queue | follow_up
+# time = "09:00"
+# prompt = "Review today's priorities and remind me what matters."
+
+[models]
+allow = [
+	"anthropic/claude-opus-4-7",
+	"google/gemini-3.1-pro-preview",
+	"google/gemini-3-flash-preview",
+	"openai/gpt-5.5",
+	"google-vertex/gemini-3.1-pro-preview",
+	"google-vertex/gemini-3-flash-preview",
+	"link/gpt-image-2-c",
+    "link/gemini-3-pro-image-preview",
+]
+
+[models.base_urls]
+# anthropic = "https://api.linkapi.ai"
+# google = "https://api.linkapi.ai/v1beta"
+# openai = "https://api.linkapi.ai/v1"
+# google-vertex = "https://{location}-aiplatform.googleapis.com"
+link = "https://api.linkapi.ai/v1"
+
+[models.api_key_envs]
+# anthropic = "ANTHROPIC_API_KEY"
+# google = "GEMINI_API_KEY"
+# openai = "OPENAI_API_KEY"
+# google-vertex is optional: pi-ai also supports Vertex ADC via gcloud ADC or
+# GOOGLE_APPLICATION_CREDENTIALS, plus GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION in .env.
+# google-vertex = "GOOGLE_CLOUD_API_KEY"
+link = "LINK_API_KEY"
+
+[tts]
+provider = "elevenlabs"
+api_key_env = "ELEVENLABS_API_KEY"
+voice_id = "${ELEVENLABS_VOICE_ID:-}"
+model_id = "eleven_v3"
+output_format = "mp3_44100_128"
+max_input_chars = 5000
+
+[tts.voice_settings]
+# ElevenLabs v2/v2.5 voice settings. For eleven_v3, Familiar sends only stability and omits v2-only fields.
+stability = 0.5
+similarity_boost = 0.75
+style = 0
+speed = 1
+use_speaker_boost = true
+
+[image_gen]
+enabled = true
+api = "openrouter-images"
+model = "link/gpt-image-2-c"
+fallback_model = "link/gemini-3-pro-image-preview"
+timeout_ms = 120000
+
+[media.generated]
+retention_days = 30
+
+[data.chat]
+retention_days = 0
+
+[data.transcripts]
+# Keep transcript retention disabled unless LCM fully covers restart replay needs.
+retention_days = 0
+
+[data.payloads]
+retention_days = 7
+
+[media.understanding.audio]
+provider = "groq"
+model = "whisper-large-v3"
+api_key_env = "GROQ_API_KEY"
+
+[media.understanding.video]
+provider = "google"
+model = "gemini-3-flash-preview"
+api_key_env = "GEMINI_API_KEY"
+
+[persona]
+soul = "SOUL.md"
+user = "USER.md"
+memory = "MEMORY.md"
+
+[workspace]
+data_dir = "data"
+
+[memory]
+root_dir = "memories"
+
+[memory.embedding]
+# Embedding wire format: gemini, openai, or voyage. v0 implements gemini only.
+format = "gemini"
+provider = "google"
+model = "gemini-embedding-2"
+# base_url and api_key_env inherit from [models.*], then fall back to provider defaults.
+# base_url = "https://generativelanguage.googleapis.com/v1beta"
+# api_key_env = "GEMINI_API_KEY"
+dimensions = 3072
+batch_size = 32
+
+[memory.ambient]
+# Set enabled = false to pause automatic diary recall injection.
+# Manual memory_recall and memory_open tools still work when ambient is disabled.
+enabled = true
+
+top_k = 3
+min_query_length = 8
+throttle_seconds = 30
+weight_similarity = 1.0
+weight_valence = 0.08
+weight_recency = 0.08
+weight_intensity = 0.1
+
+[memory.lcm]
+
+# Lossless-claw style LCM. Set enabled = false to disable the LCM context engine.
+enabled = true
+
+# Omit model to inherit [agent].model, or set an explicit provider/model ref.
+# model = "google/gemini-3-flash-preview"
+
+# Connection settings inherit from [models.base_urls] and [models.api_key_envs].
+context_threshold = 0.75
+
+# Protect up to this many newest messages before LCM compacts older context.
+fresh_tail_count = 100
+
+# Optional stricter token cap for the protected fresh tail; the smaller tail wins.
+# fresh_tail_max_tokens = 4000
+
+leaf_chunk_tokens = 14000
+leaf_target_tokens = 1000
+
+prompt_aware_eviction_enabled = true
+condense_group_size = 4
+
+max_summary_depth = 2
+
+# Context retained after /new. -1 keeps all context, 0 keeps all summaries,
+# and positive values keep summaries at that depth or higher; 2 keeps d2+.
+new_session_retain_depth = 2
+
+max_rounds = 10
+
+# Milliseconds before cached LCM summaries expire.
+cache_ttl_ms = 300000
+
+# Minimum remaining TTL before touching cached LCM summaries.
+cache_touch_slack_ms = 30000
+
+# Token overflow above which LCM runs even when context_threshold has not been reached.
+critical_overflow_tokens = 8000
+
+timeout_ms = 60000
+
+# prompt = "Inline extra instruction appended to every LCM summary prompt."
+# prompt_path = "prompts/lcm-summary.md"
+# system_prompt = "Inline system prompt that replaces the default LCM summarizer system prompt."
+# system_prompt_path = "prompts/lcm-system.md"