| # 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. |
|
|
