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.

Repository layout

SETUP.md              clone → cited answer (start here as a user)
MODEL.md              the decision model: the act, the loss, the bar
SCOREBOARD.md         what the act scores on every pinned set (eval/score.py writes it)
PRINCIPLES.md         the standing principles (KB trust, compose don't rebuild, privacy)
ROADMAP.md            the plan (J0–J5, to the MVP)
CLAUDE.md             operating manual for an agent working in this repo
LICENSE               AGPL-3.0-or-later
bin/
  ask-live            THE entrypoint: cited answers over the live corpus, fact-verified
  mail-to-tasks       email→GTD timer entrypoint: grounded action items, auto-filed with citations
src/
  pkm/                the KB — content-addressed extraction + transforms + DuckDB catalogue
  life_agent/         the agent — retrieval/citation guard, event-sourced GTD (tasks), Telegram reach
examples/
  README.md           the sample-corpus guide + the identity-guard demo
  sample-corpus/      synthetic markdown docs (Ada Lovelace) to try before your own data
config/
  pkm.example.yaml            pkm content store + extractor versions
  data-sources.example.yaml   which folders to ingest
  pii-patterns.txt.example    private denylist for the PII guard (copy to $LIFE_AGENT_KB)
scripts/
  bootstrap-sample.sh   build the sample corpus into a throwaway sandbox
  smoke-fresh-clone.sh  CI: clone → sample → cited retrieval, no key
  ask.py                the ask-live implementation (retrieve → extract → decide → cite)
  ingest_sources.py     register + extract + chunk your declared data roots into pkm
docs/
  kb-schema.md                  the knowledge-base schema (what lives under $LIFE_AGENT_KB)
  pkm/                          pkm's SPEC and principles

Entry points

Command	What it does
bin/ask-live	Ask one question.
bin/jarvis	Telegram bot (GTD + questions), event-sourced.
bin/daily-digest	Morning brief; systemd timer with a dead-man check.
make check / make score	Tests; the scoreboard.

Contributing

• Never commit personal data. Test data is synthetic (@example.com, IDs that fail their checksum, the fictional Ada Lovelace and Charles Babbage). Arm the PII guard once per clone: git config core.hooksPath .githooks and cp config/pii-patterns.txt.example "$LIFE_AGENT_KB/pii-patterns.txt". It is fail-closed and prints path:line: kind, never the value; a reviewed false positive takes a trailing # PII-OK. Without a KB: python .githooks/pii_check.py --shapes-only.
• make check (ruff + mypy + pytest) must be green before a PR; tests that need a network or API key are marked llm and skipped by default.
• src/pkm has stricter rules (src/pkm/CLAUDE.md): amend docs/pkm/SPEC.md first, test before code, every cache operation proven idempotent by a double-run.
• Compose, don't rebuild: check whether a producer, transform or script already does it.

License

AGPL-3.0-or-later. pkm (vendored as src/pkm) is AGPL too, so the whole repository is AGPL: you may use, modify, and redistribute it, but if you run a modified version as a network service you must offer its users the corresponding source.