docs/INTEGRATION.md

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

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

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

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:

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

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.