docs/knowledge-packs.md

Rama main · réplica de lectura del repositorio original.

<!-- authority:non-specification -->

# Knowledge packs

Knowledge packs are product-level guidance for Exomem. They let a fresh user pick
useful starting domains, and they let agents route simple intentions into the
right governed layer without asking the user to understand Sources, Evidence,
Notes, Entities, or supersession first.

Packs do not create a new storage engine. They compose Exomem's product commands
and governed canonical implementation leaves. They are advisory: selecting one
does not activate a collection, create folders or templates, migrate content, or
make a schema true behind the user's back.

## Built-in packs

- `legal-warranty` - receipts, disputes, insurance, contracts, deadlines, cases, and proof.
- `creative` - references, assets, drafts, productions, taste notes, and releases.
- `technical` - projects, repositories, decisions, failures, incidents, experiments, and runbooks.
- `health-athletic` - training, symptoms, measurements, protocols, injuries, goals, and health records.
- `business` - customers, meetings, commitments, contracts, invoices, risks, and decisions.
- `personal-records` - everyday documents, purchases, travel, home, vehicles, admin records, and life logistics.

`personal-records` is the default when Exomem cannot infer a more specific pack,
which makes it suitable for fresh or empty vaults.

## Schema

Built-in packs live in `src/exomem/packs/*.json`. The runtime loads them with
`importlib.resources`, validates them strictly, and exposes the schema in
The `imports` operations report through `pack_schema`.

Each pack is a JSON object with these required fields:

| Field | Meaning |
| --- | --- |
| `id` | Stable slug. |
| `name` | Human-readable pack name. |
| `description` | Short catalog description. |
| `purpose` | What the pack is for at product level. |
| `audience` | Who should choose it. |
| `beginner_description` | Plain-language onboarding copy. |
| `agent_instructions` | Routing guidance for agents; user-facing replies should stay simple. |
| `default_note_types` | Common compiled-note types for the pack. |
| `default_entity_types` | Common entity types for the pack. |
| `default_block_types` | Common conceptual blocks such as receipt, decision, protocol, or incident. |
| `suggested_folders` | Governed KB locations the pack commonly uses; selection does not create them. |
| `suggested_workflows` | Beginner-facing workflows with `title`, `intent`, `route`, and `example`. |
| `primitives` | Durable primitives the pack commonly uses. |
| `actions` | Simple actions the pack supports. Existing packs may use legacy product verbs `save`, `adopt`, `ask`, `prove`, `review`, `update`, `connect`; new packs may also use `create_note`, `capture`, and `maintain`. |
| `examples` | User-facing prompts that should route to this pack. |
| `signals` | Structural tokens used by adoption scans to suggest the pack. |

Allowed primitives are `source`, `evidence`, `case`, `decision`, `record`,
`asset`, `production`, `entity`, `failure`, `pattern`, and `experiment`.

A pack may also carry an optional `references` field. It maps a name to a
grouped call, `{"command": "record_memory", "arguments": {"action": "query"}}`,
or to a grouped command alone, `{"command": "plan_memory"}`. When a pack has
references, `agent_instructions` and each workflow `route` cite them as
`{name}`. Each surface reads the citation in its own spelling: REST and the CLI
name the grouped command, and MCP names the tool that it lists. A reference
without arguments reads as every tool that the surface lists for the command.
Validation rejects a citation of an undefined name and a reference that some
tool shape cannot spell.

Unknown pack fields are rejected. Unknown workflow fields are also rejected. This
is intentional: a deployment should not believe a pack field is active when this
Exomem version ignores it.

## Selection manifest

Setup persists selected packs at:

```text
Knowledge Base/_Packs/selected-packs.json
```

Example:

```json
{
  "schema_version": 1,
  "selected_pack_ids": ["personal-records"],
  "source": "setup",
  "updated": "2026-07-07",
  "packs": [
    {
      "id": "personal-records",
      "name": "Personal records",
      "beginner_description": "Use this as the starter pack for everyday documents, purchases, travel, home, vehicles, and personal admin.",
      "agent_instructions": "Use this as the default when no stronger domain pack is selected...",
      "suggested_workflows": [],
      "actions": ["save", "ask", "prove", "review", "update"]
    }
  ]
}
```

Selection is guidance only. It does not create folders, migrate content, rewrite
old notes, or compile material. Setup writes the manifest only after the
`Knowledge Base/` scaffold exists.

## Adoption and setup behavior

Pack suggestions are deterministic. Exomem looks at structural signals from
`overview`: folder paths and sample file names. It does not read every note body
or ask a model to classify the vault.

The safe loop is:

1. Run `exomem setup` or `adopt_vault(mode="scan-only")`.
2. Review suggested packs or choose explicit packs for a fresh vault.
3. Persist selected packs under `Knowledge Base/_Packs/`.
4. Optionally save an adoption manifest under `Knowledge Base/_Adoption/`.
5. Copy selected legacy files as Sources when provenance matters.
6. Compile selected material later, with citations.

## Mapping to product commands

Packs do not bypass governance. They help agents choose product commands:

| Simple action | Product command |
| --- | --- |
| `capture` raw material | `save_source`; use `save_evidence` or `upload_files` for Evidence |
| `create_note` durable conclusion | `create_note`; use `supersede_note` for supersession |
| `ask` | `search_memory`, optionally `read_page` or `search_memory(deep=true)` |
| `review` | `list_review_items` |
| `connect` | `inspect_memory` with the `connections` operations |
| `adopt` | `adopt_vault(mode="scan-only")` before copy/compile modes |
| `maintain` | `inspect_memory` with `maintenance.audit` for audit and dry-run; a remote `fix`, `backfill-ids` or `reconcile` write starts as a maintenance job from a dry run's `plan_id` and a `why`; the local CLI is `exomem maintain --fix` / `--reconcile` |
| `record` observed state | `query_records`, `add_record` or `edit_record`; `records.create` on `manage_memory` |

Agents should speak in product language. The user can say "save this warranty
receipt"; the agent chooses the evidence/proof route and reports the saved path.
They can say "log this training session" or "update the car mileage"; the agent
uses `add_record` for a configured Record collection, without exposing a
storage-specific tool. Packs may recommend folders, fields, templates, views,
and review rhythms, but those recommendations never fork core behavior or make a
taxonomy mandatory. Machine-readable collection blueprints and pack activation
remain deferred.

Each pack also carries `suggested_source_kinds` and `suggested_domains`. These
are **discovery hints only** — they make plausible labels visible to an agent
that has just selected a pack. They are not a permitted set, not a second
ontology, and not a precondition for using a label: because both axes are open,
a kind or domain no pack mentions is captured and registered just the same. The
vault's `_Schema/source-taxonomy.yaml` registry stays the single authority for
what a label means and where it is filed.