docs/product-model.md

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

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

# Exomem product model

Exomem is durable memory with sources, proof, history, and review for MCP-capable agents.

Built-in AI memory and Exomem should be complementary:

| Layer | Use it for | Do not use it for |
| --- | --- | --- |
| Built-in AI memory | Preferences, working rules, tone, routing instructions, small stable facts about how to help the user | Project history, research conclusions, legal/warranty records, source material, proof, supersession history |
| Exomem | Durable governed knowledge: sources, proof/evidence, decisions, records, compiled conclusions, review queues, and history | Ephemeral chat state or private assistant implementation preferences |

## Simple actions

Users and agents should think in verbs first. Exomem's internal page types still enforce governance, but normal prompts should not require the user to choose them.

| User action | What it means | Backed by |
| --- | --- | --- |
| Save | Keep raw material or a durable conclusion | `save_source` for raw material; `create_note` for compiled conclusions; `save_evidence` for proof |
| Adopt/import | Understand an existing vault safely before changing anything | `adopt_vault(mode="scan-only")`, then explicit copy/manifest/compile modes |
| Ask | Retrieve what the vault already knows with citations | `search_memory`, then `read_page`; `search_memory(deep=true)` for bounded context |
| Prove | Show or preserve proof for a claim, case, warranty, dispute, record, or receipt | `save_evidence`, `upload_files`, `list_review_items(queue="provenance")` |
| Review | Surface stale, unprocessed, disconnected, or contradictory areas; explicitly snooze/dismiss reviewed signals | `list_review_items`; `decide_review_item` for state changes |
| Update | Correct, edit, or supersede knowledge while preserving history | `edit_note`, `supersede_note`, `manage_memory` |
| Connect | Link related notes, entities, decisions, and sources | `manage_memory` |
| Record | Log or correct an observed event, measurement, transaction, session, or current state | `query_records`, `add_record`, `edit_record` |

## Eight governed layers

The layers name different kinds of material; they are not folders an agent should
make a user choose.

| Layer | Meaning |
| --- | --- |
| Sources | Externally received raw material, classified by an open `source_kind` and `domain`. |
| Evidence | Proof-bearing artifacts for a case, claim, compliance need, warranty, dispute, or provenance-sensitive history. |
| Notes | Compiled conclusions, decisions, research, insights, patterns, failures, experiments, and productions. |
| Entities | Stable reusable identities: people, organisations, concepts, assets, libraries, and decisions. |
| Planning | Intended future state: goals, outcomes, initiatives, priorities, horizons, commitments, and candidate work. |
| Records | Observed events and state: what happened, when, measurements, sessions, transactions, and status changes. |
| Review | The loop that compares Planning intent with Records reality and feeds explicit decisions back into Planning and Notes. |
| Imported | Adoption and migration staging, never the permanent home of live user-owned state. |

Planning and Records have distinct semantic profiles but share the structured
collection substrate. Exomem Planning owns durable intent and prioritisation.
Planning is standalone by default and may coordinate with a user-authored
workflow contract that declares companion ownership. Companion references remain
opaque and do not establish tool availability or external truth. Planning may
point to Records as observed evidence, but neither layer mirrors the other or
infers progress, completion, medical conclusions, or personal judgment.

See [Records](records.md) for the manual-first collection contract.

### Source classification is metadata; the folder is a projection

A captured source carries three independent axes. `source_kind` says what the
artifact **is**, `domain` says what it is **about**, and `projects` says which
work it serves. Kind and domain are **open vocabularies**: any slug-shaped label
is accepted and registers itself in `_Schema/source-taxonomy.yaml` on first use,
so a category nobody anticipated needs no release and no migration. `projects`
is multi-valued, because one source often serves several pieces of work.

The directory a source lands in is **derived** from the validated kind and
domain — `Sources/<Kind>/[<Domain>/]` — not the other way round. The folder tree
is a browsing projection of the metadata, never the ontology, and it is capped at
two levels. Projects deliberately never appear in the path.

There is no catch-all kind. An agent names what a source is, and a capture
without a kind is refused with the vault's known kinds and their counts. A
capture with no agent in the loop (the terminal UI, the hosted capture box, the
upload form, a legacy-vault import) is recorded as `unclassified`, and later
captures carry an advisory `source_classification_debt` suggestion that counts
those sources and the legacy `Sources/Other/` pages. Exomem never classifies or
moves anything on its own: the agent reads each source, chooses its kind, and
reclassifies it. Until then every such source stays valid, readable, and
retrievable exactly where it is.

Compiled notes use visible typed Markdown for directional note-level edges:

```markdown
## Relations
- refines [[Knowledge Base/Notes/Insights/Earlier Conclusion]]
- evidenced_by [[Knowledge Base/Sources/Articles/Original Source]]
```

Claim/finding/evidence-level edges remain semantic-block metadata. See
[semantic blocks](semantic-blocks.md) and the [Epistemic Inbox](epistemic-inbox.md).

## Existing vaults

An existing vault is not a migration problem by default. Exomem treats non-KB folders as read-only input and creates a governed `Knowledge Base/` layer beside them.

The adoption modes are explicit:

| Mode | Writes? | Purpose |
| --- | --- | --- |
| `scan-only` | No | Report structure, likely packs, governed vs read-only areas, bounded semantic-language census, and next actions |
| `save-manifest` | Yes, under `Knowledge Base/_Adoption/` only | Save the scan as a durable onboarding artifact |
| `copy-as-sources` | Yes, under `Knowledge Base/Sources/Imported/` only | Copy selected legacy text files with original path and SHA-256 provenance |
| `compile-selected` | Yes, under `Knowledge Base/Sources/Imported/` when legacy files need source copies | Copy selected legacy text files when needed, then return a reviewable compile plan; compiled notes are written later through `create_note` / `note()` |

There is no rewrite-in-place onboarding path in the normal product flow.
`scan-only` does not require initialization and never changes page bytes. Its
semantic census reports compact/rich coverage, category resolution/collisions,
malformed candidates, contract/schema debt, and relation dispositions within
explicit file/byte/example bounds. `compile-selected` is a planning step, not
auto-migration: it prepares governed sources and a note scaffold so the user or
agent can deliberately compile with `create_note` through the normal `note()`
precommit path.

Initialization and registry/index upgrades do not manufacture semantic units,
categories, relations, IDs, or review decisions. Existing compiled pages are
captured in a portable activation manifest without rewriting them.

## Sources versus evidence

A Source is raw input captured so future notes can cite it. An article, meeting transcript, pasted conversation, or research excerpt is usually a Source.

Evidence is proof-bound. A receipt saved for a warranty case, a legal letter, an insurance document, a medical record, or a screenshot preserved for a claim belongs in Evidence. Evidence does not mean "important source"; it means "used as proof for a case, claim, record, or decision."

## Compared with note graph tools

A searchable graph of Markdown notes is useful, but it is not the whole product. Exomem adds governed writes, source-to-note provenance, evidence/proof handling, explicit supersession, review queues, multimodal extraction, and one command registry that exposes the same behavior through MCP, CLI, REST, and OpenAPI.