# FablePool — an open protocol for user-owned AI memory

FablePool is an open-source protocol and reference implementation for a
**user-owned personal AI memory layer**: a local-first knowledge graph in
which your own devices ingest evidence (calendar, notes, photo metadata, …),
derive claims about you with explicit **provenance and confidence**, and let
*you* inspect, correct, refute, export, synchronize, delegate, and revoke
those claims.

This is not another chatbot. It is the substrate a personal AI would need if
it were owned by the user instead of by an app vendor:

* **Append-only signed operations.** Raw evidence, derived claims,
  corrections, and (in later milestones) permissions are all signed
  operations in an append-only log.
* **Derivation graph.** Every claim links to the claims and evidence it was
  derived from, so a correction mechanically cascades to everything
  downstream.
* **Open wire format.** The whole graph exports as JSON Lines of signed
  operation envelopes that another implementation can replay.
* **Auditable.** The entire history verifies cryptographically with one
  command.

## Milestone status

| # | Milestone | Status |
|---|-----------|--------|
| 1 | Architecture, threat model, and non-goals | ✅ done |
| 2 | Wire format and signed operation log schema | ✅ done |
| 3 | Reference local node with import adapters (calendar, notes, mock photo metadata) | ✅ done |
| 4 | Derivation engine with provenance, confidence, and cascade invalidation | ✅ done |
| 5 | **Inspection and refutation interface (CLI/TUI)** | ✅ this milestone |
| 6 | Sync and capability-based delegation demo | upcoming |

## Install

Requires Python 3.10+.

```console
$ git clone <repo> && cd fablepool
$ python -m venv .venv && source .venv/bin/activate
$ pip install -e ".[dev]"        # ".[dev]" adds pytest for the test suite
```

(`pip install -e .` alone is enough to run the CLI and demo.)

There is intentionally no checked-in lockfile; `pip` resolves the flexible
constraints in `pyproject.toml` on first install. If you want reproducible
environments, generate one yourself, e.g. `pip freeze > requirements.lock`,
after a successful install.

## Quickstart

Point the CLI at a throwaway node directory and seed it with the bundled
sample dataset (a fictional person's calendar, notes, and photo metadata):

```console
$ export FABLEPOOL_NODE_DIR=/tmp/fablepool-demo
$ fablepool seed-demo
$ fablepool topics                       # what do you know about me?
$ fablepool claims --topic schedule
$ fablepool why <CLAIM_ID>               # ...and why?
$ fablepool refute <CLAIM_ID> --reason "no longer true"   # watch the cascade
$ fablepool export --out my-graph.jsonl  # take your graph with you
$ fablepool audit                        # verify the whole history
$ fablepool shell                        # or do all of it interactively
```

Every command also has a `--json` mode with a stable output contract — see
[`docs/cli-reference.md`](docs/cli-reference.md) for every command, flag,
JSON schema, and exit code.

## The canonical demo

The scripted walkthrough runs the full flow — *"what do you know about me
and why?"*, a user refutation, the downstream cascade, export, and audit —
narrating each step:

```console
$ python scripts/demo_walkthrough.py
```

A guided, human-paced version of the same flow with annotated transcripts is
in [`docs/walkthrough.md`](docs/walkthrough.md).

## Testing

```console
$ pip install -e ".[dev]"
$ pytest
```

The suite covers every interactive command (browse, drill-down, correct,
refute, shell), the export/audit contracts (wire-format line validation,
full vs. topic-subset export, audit JSON, append-only behavior across
mutations), and runs `scripts/demo_walkthrough.py` end-to-end against a
throwaway node, then re-audits the node it leaves behind. The export/audit
and walkthrough tests run the CLI as a real subprocess (`python -m
fablepool`), so they validate exactly what a user — or a second
implementation — would see.

## Repository layout

```
src/fablepool/
  wire.py        # wire-format envelopes (milestone #2)
  identity.py    # node identity & signing
  oplog.py       # append-only signed operation log
  model.py       # evidence / claim / derivation model
  store.py       # node storage
  explain.py     # derivation explanations ("why?")
  seed.py        # sample-dataset seeding
  cli.py         # one-shot CLI commands
  shell.py       # interactive REPL
  render.py      # human-readable rendering
scripts/
  demo_walkthrough.py   # scripted canonical demo
docs/
  cli-reference.md      # full CLI contract (commands, JSON, exit codes)
  walkthrough.md        # usability walkthrough of the demo flow
tests/                  # pytest suite (in-process + subprocess integration)
```

## Design guarantees (this milestone)

* Corrections and refutations are **append-only**: nothing is ever deleted,
  and the integration tests assert that exports only ever grow.
* **Determinism**: exporting an unchanged node twice is byte-identical.
* A full export's line count equals the operation count reported by
  `audit` — the export *is* the log.
* Human-readable output is free to improve; the `--json` contracts and exit
  codes documented in `docs/cli-reference.md` are stable.

## Non-goals

Carried forward from milestone #1: FablePool is not a chatbot, not a cloud
service, not an ML training pipeline, and not a DRM system. It does not try
to prevent an authorized reader from remembering what it was shown — it makes
grants narrow, explicit, auditable, and mechanically revocable. See the
milestone #1 architecture document for the full threat model and non-goals.

## License

Open source; see the license metadata in `pyproject.toml`.