life-agent

Ask anything about your own life and get an answer that cites the document each fact came from — with no hallucination. life-agent remembers your digital life, retrieves the records that bear on your question, and verifies every cited fact actually appears in its source before showing you the answer. Facts are grounded in your own documents, not a model's memory.

Use it → SETUP.md (clone to a cited answer in minutes, on a bundled synthetic corpus first — no real data, no API key to build it). Understand the design → MODEL.md · PRINCIPLES.md · ROADMAP.md · CLAUDE.md.

Quickstart

Requires uv, pandoc, and git. Try it on the bundled synthetic corpus (the fictional Ada Lovelace) before pointing it at your own data:

git clone https://github.com/gfrmin/life-agent && cd life-agent
scripts/bootstrap-sample.sh                     # builds a throwaway corpus — markdown + pandoc only, no API key

export LIFE_AGENT_KB=$PWD/examples/.sandbox/kb
export PKM_CONFIG=$PWD/examples/.sandbox/pkm.yaml
export ANTHROPIC_API_KEY=sk-ant-...             # only needed to *ask* (extraction), not to build

bin/ask-live "what is my national ID number?"   # cited answer over the corpus you just built
bin/ask-live "when does my passport expire?"

bin/ask-live is the entrypoint: it retrieves from a DuckDB catalogue (BM25, Hebrew-aware) and returns a cited span from your documents, or declines. Full walkthrough, prerequisites, and troubleshooting in SETUP.md; more sample questions and the identity-guard demo in examples/README.md.

How it fits together

your files ──┐ ingest
your email ──┴──▶  pkm — cited, searchable memory ──▶  bin/ask-live     you ask; every fact cited
                    │
                    │  grounded action items (local model, cited, auto-filed)
                    ▼
                   GTD task ledger (event-sourced) ──▶  Telegram bot    you manage tasks in plain language
                                                   ──▶  morning digest  it pushes a summary to you

You interact in exactly two places: bin/ask-live to know (questions in, cited answers out) and the Telegram bot to act (tasks). Everything else — email→tasks, the digest — runs unattended on timers. Every command, intent, and reply across these surfaces is governed by one grammar. Setting up the task half: SETUP.md, step 4.

Why the answers are trustworthy

The promise is cited, no-hallucination answers, and it is structural rather than aspirational:

• Verbatim facts are gated. Before an answer is shown, a deterministic guard (scripts/citation_guard.py) checks that every value-bearing cited fact — IDs, numbers, proper nouns — actually appears in the source it cites. Anything that doesn't is flagged ⚠ unverified, not presented as true.
• Weak retrieval abstains. If nothing in your corpus is a strong enough match, it says so instead of guessing.
• Identity is pinned. An owner profile (bin/ask-live "/tell …") is the lens for who "I" is, so a relative's or co-signer's document is never reported as yours.

Answers are grounded in pkm's content-addressed, source-cited extractions — not a compiled summary. (The "compile a wiki from everything" approach is deliberately rejected: it does not scale and it hallucinates.) What is not guaranteed: facts pkm extracted wrong upstream (e.g. OCR garble).

Use it on your own data

Your data never enters the repo. Copy config/data-sources.example.yaml to $LIFE_AGENT_KB/config/, point its roots at your folders, then migrate → ingest → extract → chunk → rebuild-index (one script: scripts/ingest_sources.py --extract --chunk). Teach it who you are with bin/ask-live "/tell My name is …". Step-by-step in SETUP.md.

What's live vs the vision

The kernel (PRINCIPLES.md): a knowledge base built from DAGs of trustworthy transformations, and a personal assistant — the life agent — making rational, utility-maximising decisions over it. Both halves exist today. The KB and its consumers: the cited read path (bin/ask-live) over pkm's catalogue, and an event-sourced GTD (life_agent.tasks, reached over Telegram) that email auto-files into with citations. And the decision half: every answer is chosen by one Bayes act (core/decide.bayes_act) over a posterior on candidates, under a stated loss — a wrong answer costs about five times what a right one earns, folded from the owner's own verdicts, and the bar to commit is derived from that rather than declared. So the assistant answers, escalates or declines, says which on every reply, and is measured on a board: SCOREBOARD.md. Status of every faculty: ROADMAP.md.

Your data stays yours

This repo contains the system, never your data. Your corpus, the eval set, and the failure log are personal — they live outside the repo, at a path you choose:

LIFE_AGENT_KB     # default: $HOME/.life-agent/kb

export LIFE_AGENT_KB=/path/to/kb and point it wherever you keep your stuff; the tooling reads from there. (Same separation pkm already uses: code in the repo, the content-addressed cache on your disk.) Nothing personal is ever committed — a PII guard in .githooks/ enforces it on every commit and push. See docs/kb-schema.md for the expected layout under $LIFE_AGENT_KB.

This is the beginning of the README. Read the rest at the original. Read the full README ↗