# Host-model integration

The memory library consumes explicit text/claim writes and emits evidence packets. It does not need to retrain or modify a host model. GPT-2, Qwen and other PhillNet generation tests have not been established here; adapters are not certifications.

## Structured multi-step recall

```python
from phillnet_recall import RecallMemory, prepare_recall_prompt

with RecallMemory("recall.sqlite3", tenant="phillip", namespace="deployment") as memory:
    memory.remember("Willow uses Beacon.", source="operator:service-map",
                    entity="Willow", predicate="uses_service", value="Beacon")
    memory.remember("Beacon is deployed in north.", source="operator:deployment",
                    entity="Beacon", predicate="deployment_region", value="north")
    result = memory.recall("Which region hosts the service used by Willow?")
    assert result["answer_values"] == ["north"]
    packet = prepare_recall_prompt(memory,
        "Which region hosts the service used by Willow?",
        max_input_units=8192, memory_units=6144)
    print(packet["prompt"])
```

For an arbitrary structured relation, call `memory.follow("X", ["relation_a", "relation_b"])`. For reverse lookup use `{"predicate":"owns","direction":"in"}`. Supply proper structured metadata; the system does not automatically extract every relationship from prose.

## Raw text and related evidence

```python
with RecallMemory("recall.sqlite3", tenant="phillip", namespace="preferences") as memory:
    memory.remember("Vegetarian food only.", source="user:explicit-preference")
    result = memory.recall("Which meal restriction should guide dinner?")
    print(result["items"][0]["text"])
    assert result["answer_values"] == []  # topic match is not an inferred answer
```

The map groups topics, not values: vegan and vegetarian are not made equivalent. Its scope is explicit English phrases. Undeclared paraphrases can still fail. Exact lexical BM25/cosine and prior neural backends remain available via `retrieve`.

## Token-aware host input

```python
packet = prepare_recall_prompt(memory, question, tokenizer=host_tokenizer,
                              max_input_units=3072, memory_units=2048)
# Feed packet["prompt"] through your existing model generation interface.
```

Reserve generation space separately from the input budget. For chat templates, apply the host's real template and check its entire encoded length; do not assume byte counts or completion-prompt counts equal chat-template token counts. The existing `prepare_messages` helper supports tokenizer-aware related-note retrieval with `backend="semantic"`. Never install raw memories as higher-priority instructions.

## Loading checkpoints

`RecallPolicy.from_pretrained(local_directory)` is locally tested. Remote use after publication accepts `"ayjays132/PhillNet-Recall"` plus an audited commit SHA. It downloads only config/bank/sensemap data and does not enable `trust_remote_code`. Save/load retains the extra evidence contract. The repo has not been published by this release process.

## Replaying official data without label leakage

Obtain the official LongMemEval cleaned non-oracle JSON separately, then run:

```bash
python scripts/evaluate_longmemeval_retrieval.py --dataset /path/longmemeval_s_cleaned.json --limit 20
```

This produces session retrieval coverage, NOT the official end-to-end language-model answer score. It preserves all conversation content in deterministic chunks and strips `has_answer`, `answer` and gold session IDs before runtime input. Evaluation uses gold session IDs only after retrieval. The default reports a 20-question prefix; use `--limit 500` for the complete published list. No live dataset was evaluated here.

## Migration

```python
legacy = ...  # existing v1 snapshot envelope
upgraded = memory.migrate_snapshot_v1(legacy)
memory.restore(upgraded)
```

This explicitly adopts the installed evidence contract. It is not an automatic import of incompatible policies or a guarantee of matching older application behavior.