# family-knowledge

Adopt this skill: https://proskills.md/skills/other/famclaw-famclaw-skills-repo-family-knowledge

Page: https://proskills.md/skills/other/famclaw-famclaw-skills-repo-family-knowledge
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills-repo/family-knowledge/SKILL.md
size: 5071
sha: 22b1c704e11bce4226cd978ad7664c07db75d5b9
upstream: https://github.com/famclaw/famclaw/blob/main/skills-repo/family-knowledge/SKILL.md

```text
---
name: family-knowledge
description: Family knowledge base for recording and retrieving household facts (members, allergies, dietary rules, doctors, schedules, house rules, pets, important dates).
version: "0.1"
author: famclaw
license: AGPL-3.0-only
tags: [family, knowledge, memory, household]
platforms: [linux, darwin]
requires:
  bins: []
trigger:
  mode: "always"
---
# Family Knowledge

You have access to a persistent family knowledge base that stores durable household facts. This knowledge is shared across all family members and conversations.

## Built-in Categories (always available)

| Category | Description | Auto-injected |
|----------|-------------|---------------|
| `allergies` | Per-person allergies and severity. Safety-critical. | ✅ Yes |
| `dietary_restrictions` | Per-person or family dietary patterns (vegetarian, kosher, halal, gluten-free, etc.). Safety-critical. | ✅ Yes |
| `important_dates` | Birthdays, anniversaries, recurring family events. | ❌ On demand |
| `pets` | Family pets — names, species, notes. | ❌ On demand |

Parents can also create custom categories via the `add_family_category` tool.

## Available Tools

### Read (all roles)
- **`get_family_state(category?)`** — Read facts. Optional `category` filters to one category; omit to see everything. Returns fact IDs for mutation.

### Propose (all roles)
- **`propose_family_fact(category, subject, label, value, reason)`** — Propose a new fact.
  - **Parent**: Applied immediately (OPA-gated).
  - **Child**: Queued for parent approval; applied after approval.

### Parent-only mutations (admin tools)
- **`set_family_fact(category, subject, label, value)`** — Create or update a fact directly (upserts on `category+subject+label`).
- **`delete_family_fact(id)`** — Delete a fact by its numeric ID.
- **`add_family_category(name, description, always_inject?)`** — Add a custom category. `always_inject=true` makes it auto-injected like allergies.
- **`delete_family_category(name)`** — Delete a custom category (must be empty; built-ins cannot be deleted).

## When to Use Family Knowledge

**USE `get_family_state` when the user asks about:**
- Family member details (names, ages, birthdays)
- Allergies or dietary restrictions
- Pet names, types, care notes
- Important dates (birthdays, anniversaries, appointments)
- House rules or routines
- Doctors, medications, medical info
- Anything the family has previously told you to remember

**USE `propose_family_fact` / `set_family_fact` when the user:**
- Explicitly asks you to remember something ("Remember that...")
- Shares a new fact that should persist ("Mom is allergic to penicillin")
- Corrects an existing fact ("Actually, Teo's birthday is March 12, not March 14")

**DO NOT use family knowledge for:**
- General knowledge questions (weather, facts, news) — use `web_fetch` / `web_search`
- Ephemeral conversation context — the conversation history already handles that
- One-off facts the user doesn't want saved

## Subject Values

The `subject` field must be one of:
- A configured family member's `name` from config (e.g., `teo`, `julia`, `family`)
- The literal string `"family"` for household-wide facts

## Examples

**User:** "What's Teo allergic to?"
→ `get_family_state(category="allergies")`

**User:** "Remember that we have a dog named Biscuit, a golden retriever."
→ `propose_family_fact(category="pets", subject="family", label="Biscuit", value="golden retriever, 3 years old", reason="user told me to remember")`

**User (parent):** "Add a house rule: no phones at dinner."
→ `set_family_fact(category="house_rules", subject="family", label="phones_at_dinner", value="No phones at the dinner table")`

**User:** "When is Grandma's birthday?"
→ `get_family_state(category="important_dates")`

## Workflow for Children

Children **cannot** directly write facts. When a child shares something to remember:
1. Call `propose_family_fact(...)` with a clear `reason`.
2. Tell the child: "I've sent that to your parents for approval. They'll review it and it'll be saved once approved."

## Workflow for Parents

Parents can:
- Use `propose_family_fact` (auto-applies after OPA check)
- Use `set_family_fact` for direct writes
- Use `add_family_category` to create new categories like `house_rules`, `medications`, `school_contacts`, etc.

## Safety Notes

- `allergies` and `dietary_restrictions` are **always injected** into every system prompt via the `<family_safety>` block. The model sees them automatically — you do not need to call `get_family_state` for these unless the user asks for detail.
- Other categories are **on-demand** — call `get_family_state` when relevant.
- Parents can mark custom categories as `always_inject=true` for safety-critical info (e.g., `medications`).

## Category Management

To list existing categories: `get_family_state()` (no filter) shows all categories with their facts.
To add a category (parent only): `add_family_category(name="medications", description="Prescription medications and dosages", always_inject=true)`
```

## File: README.md
upstream: https://github.com/famclaw/famclaw/blob/main/README.md

````text
# 🛡️ FamClaw

**A secure, local-first family AI gateway. Runs on Raspberry Pi, Mac, or any Linux box.**

FamClaw is a lightweight Go gateway that connects your family to any AI model — local or cloud — through Telegram, Discord, and a web interface. Every message goes through a policy engine before the AI ever sees it.

---

## What it is

- **A gateway, not an AI.** FamClaw routes messages between your family and whatever LLM you configure — Ollama on your home server, OpenAI, Anthropic, OpenRouter, or any OpenAI-compatible endpoint.
- **A policy enforcer.** Every message is evaluated by OPA (Open Policy Agent) before reaching the LLM. Kids get age-appropriate responses. Sensitive topics require parental approval.
- **A family assistant.** Age-aware profiles, parental approval workflow, notification to parents via email/SMS/Slack/Discord/ntfy.

---

## How it works

```
Family member sends message
  → via Telegram / Discord / Web UI
    → FamClaw identifies user from gateway account
      → OPA policy evaluates: allow / block / request approval
        → if allow: forwards to your LLM endpoint
          → streams response back
- [Agent Setup Guide](./docs/AGENT_SETUP.md) — Complete setup instructions for AI coding agents

```

FamClaw itself uses ~20MB RAM. The LLM runs elsewhere — on a Mac Mini on your LAN, a cloud API, or any OpenAI-compatible server.

---

## Hardware

| Device | Role |
|--------|------|
| Raspberry Pi 3/4/5 | Run FamClaw 24/7, flash SD card and plug in |
| Mac Mini | Run as background daemon |
| Any Linux box | One binary, no dependencies |

---

## LLM backends

FamClaw talks to any OpenAI-compatible endpoint:

| Platform | Backend | api_key needed |
|---|---|---|
| RPi 3/4/5 | Ollama (local, auto-installed by firstboot.sh) | No |
| Mac Mini | Ollama (local) | No |
| Old Android (Termux) | OpenAI / Anthropic / OpenRouter / another device's Ollama | Yes (or LAN URL) |
| Any device | Can point at RPi's Ollama on LAN | No |
| Any device | Claude CLI (`provider: claude_cli`) | No (uses local claude binary) |

```yaml
llm:
  base_url: "http://<your-host>:11434"  # Ollama on your LAN device
  model: "llama3.2:3b"
  # Per-call LLM request timeout in seconds. Each chat/tool call gets its
  # own context deadline. Default: 300 (5 minutes).
  timeout_seconds: 300

  profiles:
    cloud:
      label: "OpenAI cloud (gpt-4o-mini)"  # display-only name shown in the web UI
      base_url: "https://api.openai.com/v1"
      model: "gpt-4o-mini"
      api_key: "${OPENAI_API_KEY}"

  # When a message carries an image attachment (a photo sent on Telegram
  # or Discord), FamClaw routes it to this LLM profile instead of the
  # normal per-user model — text-only messages always use the normal
  # endpoint. Set this to a vision-capable model (e.g. qwen2.5-vl,
  # llama3.2-vision, gemma3).
  #
  # When EMPTY, the per-user endpoint is used for images too. If that
  # model is text-only, the image is still sent to it but CANNOT be seen
  # — it is silently ignored (the assistant only receives the empty text),
  # which is why real deployments set vision_profile. Images are sent to
  # the configured LLM endpoint, which may be remote — they stay on-device
  # only when that endpoint is local.
  vision_profile: ""
```

**Profile labels:** the optional `label` on each profile is a display-only name
shown in the web UI. Keep it accurate to where the profile actually routes
(host + model), so a family member reading the label knows which model answers —
a stale label (e.g. naming a model the profile no longer serves) misdescribes
the routing.

**Security note:** `llm.api_key` is loaded from plaintext YAML by default.
Set `FAMCLAW_LLM_API_KEY` environment variable to override — it takes precedence and avoids logging the plaintext warning.

**Reasoning auto-detection.** When the endpoint is a LiteLLM (or OpenAI-compatible) gateway, FamClaw queries its model metadata at startup and learns each model's `litellm_params.merge_reasoning_content_in_choices` setting, so a final answer that ships in the reasoning field is shown to the family while chain-of-thought is filtered out — no per-model hand-configuration. Startup logs `Auto-detect: N models discovered`, or a warning when the gateway is unreachable (the built-in heuristic then applies, and later requests retry detection). Opt out or pin models with `llm.reasoning` (`enable_auto_detect: false`, `litellm_url`, `per_model_override`).

---

## Quick start

### Raspberry Pi (flash and plug in)
```bash
# Flash famclaw-rpi4-arm64.img.xz to SD card with Raspberry Pi Imager
# Plug in, wait 2 minutes, find the device IP from your router and open:
http://<your-pi-ip>:8080
```

> mDNS (`famclaw.local`) was removed in v0.5.x because it didn't resolve
> reliably on Windows or many home routers. Use the device's IP address
> from your router's DHCP leases page or `ip addr` on the Pi.

### Mac / Linux (macOS: developer terminal only)
Download the binary for your platform from the [latest release](https://github.com/famclaw/famclaw/releases/latest):

| Platform | Artifact |
|---|---|
| Apple Silicon Mac | `famclaw-darwin-arm64.tar.xz` |
| Intel Mac | `famclaw-darwin-amd64.tar.xz` |
| Linux x86_64 | `famclaw-linux-amd64.tar.xz` |
| Linux arm64 | `famclaw-linux-arm64.tar.xz` |
| Linux arm (32-bit, e.g. RPi 3/Zero) | `famclaw-linux-armv7.tar.xz` |

Download from a terminal with `curl`, not a browser: darwin binaries are
ad-hoc-signed and **not notarized by Apple** — the project ships no Developer
ID, so macOS builds are for developers only (#214) — and Gatekeeper blocks any
browser-downloaded copy. The supported macOS install path is the terminal
procedure in `docs/MACOS.md`; `scripts/install-macos-dev.sh` does the checksum
verification, `xattr -c`, and local `codesign -f -s -` re-signing for you.

```bash
tar -xJf famclaw-darwin-arm64.tar.xz   # Mac (any arch): read docs/MACOS.md first
touch config.yaml   # start empty — the web wizard fills it in
./famclaw --config config.yaml
```

Then open `http://<host>:8080` and complete the setup wizard (it writes the
rest of the config for you).

The tarballs verify against `checksums.txt` plus a cosign signature bundle.
Upgrading an existing installation (atomic swap + service restart, never an
in-place overwrite):

```bash
curl -fsSL https://raw.githubusercontent.com/famclaw/famclaw/main/scripts/update.sh | bash
```

### Build from source
```bash
git clone https://github.com/famclaw/famclaw
cd famclaw
make build
./bin/famclaw --config config.yaml
```

---

## Messaging gateways

| Gateway | Status |
|---------|--------|
| Web UI | Built — HTTP + WebSocket + embedded UI |
| Telegram | Built — long-poll Bot API |
| Discord | Built — via discordgo |

Each family member's gateway account maps to their profile. Emma's Telegram account → Emma's age policy. Parent's Discord account → parent access.

**File delivery.** When the assistant produces a file in the conversation workspace (e.g. via `file_write`), it can attach and send it back into the same conversation through the `send_file` built-in tool — currently on Discord (the group channel or DM the user is in). Files are confined to the conversation sandbox, capped at 25 MiB (Discord's bot upload limit), and every delivery is audit-logged. Which roles may call the tool is decided by OPA `tool_policy`; on gateways without file support yet, the tool returns an honest "not available" error instead of silently dropping the request.

---

## Policy system

Policies are [OPA Rego](https://www.openpolicyagent.org/) files. The default rule set lives at `internal/policy/policies/` and is **embedded in the binary** via `go:embed` — a downloaded release runs without any external policy directory. To override with custom rules, set `policies.dir` (and `policies.data_dir`) in `config.yaml` to a directory of your own `.rego` and JSON files. Run `opa test internal/policy/policies/family/ internal/policy/policies/data/ -v` to test the built-in rules loca
````
