# PhillNet Recall 1.2.0 · Grounded Memory
**Remember the evidence. Keep the connection.**
By **Phillip A. Holland Jr. / ayjays132** · Apache-2.0 · Local-first · No new neural training
[Quick start](docs/QUICKSTART.md) · [Publish to Hugging Face](docs/HF_PUBLICATION.md) · [Architecture](docs/ARCHITECTURE_1.2.md) · [Measured results](reports/v12_evaluation.json)
## What is this?
PhillNet Recall is a **custom-library external memory system and compact policy
checkpoint**. It stores source evidence, retrieves related notes, follows supplied
relationships, preserves explicit corrections and historical validity, and assembles
context without silently dropping dependencies.
**1.2 adds three substantive capabilities:** scope-local terminology bridges that
can change without editing weights; positive conjunctive queries across memories;
and bounded search for smaller complete evidence packets. An authenticated API,
standard-library Python client, release verifier, wheel and separate Docker Space
showcase are included.
It is **not a generative LLM**, embedding model, KV-cache replacement, unrestricted
semantic parser, universal animal translator, or a demonstrated state-of-the-art
memory product. The weight bank is part of a hybrid executable system: storage,
parsing, joins, budgets, glossaries and certificates are ordinary software outside
the neural records. Matching a note does not establish that it is true.
## At a glance
| Item | This release |
|---|---|
| Intended Hub model repository | `ayjays132/PhillNet-Recall` |
| Intended demo Space | `ayjays132/PhillNet-Recall-Demo` |
| Package | `phillnet-recall`, version `1.2.0` |
| Neural policies | 24 complete records, 500 bytes each |
| Packed checkpoints | 12,128 bytes, including two headers |
| Architecture | Each policy: 20 inputs → 20 ReLU units → 1 score |
| Numerical parameters | 10,584 across the two banks |
| Core dependencies | Python 3.10+ standard library; optional C99 CPU scorer |
| New training or distillation | None |
| Previous banks | Both preserved byte-for-byte from 1.1 |
| Personal evidence | Private application database, not part of the Hub checkpoint |
| Publication | Packaged; not uploaded by this build |
**12 KB is the policy payload, not total RAM.** Source text, SQLite, indexes, graph
views, proof alternatives and Python require additional storage and computation.
The HF card's `custom-code` tag describes the installed local library. Loading a
policy does not require or use `trust_remote_code=True`.
## 1. Add terminology as evidence, not an untraceable global synonym
An application can supply a scoped mapping:
> In project Nova, “amber docket” is the query phrase used for “incident register.”
The mapping is stored as a regular source-backed record. Retrieval can then find
an incident note using the unfamiliar term. The selected note carries the mapping
record as a dependency. Correction, deletion, TTL and historical time handling
apply to the mapping just as they apply to other evidence.
```python
from phillnet_recall import RecallMemory, pack_grounded
with RecallMemory('recall.sqlite3', tenant='phillip', namespace='nova') as memory:
memory.remember_bridge(
'amber docket', 'incident register',
source='operator:approved-glossary',
)
memory.remember(
'Nova incident register: Mira handles escalation.',
source='incident-record:11',
)
result = memory.recall_grounded('Nova amber docket', top_k=1)
packet = pack_grounded(memory, result, budget=8192)
print(packet['text'])
```
This is **new supplied information**, not automatic discovery of meaning. A wrong
mapping can retrieve the wrong note. Conflicting mappings fail closed; unrelated
namespaces do not inherit each other's terminology. Without a tokenizer, `budget`
is UTF-8 bytes. Returned notes are not labeled as inferred answers.
## 2. Combine constraints across supplied relationships
```python
plan = {
'where': [
{'entity': '?service', 'predicate': 'region', 'value': 'west'},
{'entity': '?service', 'predicate': 'owner', 'value': 'Mira'},
],
'select': ['?service'],
}
result = memory.query(plan)
```
With the corresponding supplied facts, this returns the services satisfying **both**
conditions and the complete supporting records. Up to six positive atoms are
supported. Variables unify exact case-sensitive values. This is not arbitrary
natural-language-to-query translation.
The query certificate includes a digest of the eligible scope. Adding a new
matching service invalidates an old exhaustive result even though its old positive
support may not have changed. A `no_matches` result describes the queried store,
not the absence of an entity or fact in the world.
## 3. Spend context on complete support
Different answers may have proofs that share large source records. The earlier
packer chose the shortest proof for each answer independently. The new optimizer
searches combinations of complete proofs and counts the **actual serialized
packet**, paying for shared record IDs only once.
The default bound is 4,096 combinations. `optimal=true` means that the complete
candidate choice space was examined; it is not asserted after a search cutoff.
A feasible complete packet may be returned with `optimal=false`. If the search
cap prevents finding a fitting packet, `search_exhausted` is distinct from a proven
`budget_exceeded` result. No incomplete proof is emitted to make a number look good.
## Executed results
These are **project-authored synthetic tests**, not independent real-world
benchmark results. No fixture changed neural weights. The glossary ablation adds
explicit information, so it does not isolate a neural architecture advantage.
| Measurement | Observed result |
|---|---:|
| Local regression tests | **377/377** |
| All 24 policies: native/reference numerical probes | **3,120/3,120 exact** |
| New terminology cases, without supplied bridges | 4/96 correct at rank one |
| Same cases, supplied bridges + neural policy | **96/96** |
| Same cases, supplied bridges + conventional policy | **96/96** |
| Candidate notes per terminology case | 24 |
| Retrieved notes packed with their mapping dependencies | 96/96 |
| Randomized conjunctive queries matching a separate set oracle | **128/128** |
| Constructed shared-proof cases with smaller complete context | **40/40** |
| Median reduction in serialized bytes on those 40 cases | **32.17%** |
| Unsupported meaning controls without mappings | 4/4 correctly return `unknown` |
The 96 cases vary opaque terminology and distractors within the same constructed
family. The 128 relational cases are random finite graphs, not external knowledge
questions. The 40 packing cases deliberately contain shared dependencies; the
32.17% is **not a prediction of average savings on user conversations**. UTF-8 byte
reduction is not necessarily the same percentage of tokens or billed inference cost.
Neural and equivalent conventional retrieval scoring tie. Joins and proof
completeness are enforced by the host algorithms. These results do not establish
neural reasoning superiority, general semantic retrieval, or world-leading quality.
[Raw fixtures/results](reports/v12_evaluation.json) · [Local HTTP evidence](reports/http_v12.json) · [Report provenance](reports/README.md)
## Installation and serving
Install the supplied wheel, or enter the source repository and run:
```bash
python -m pip install .
python examples/demo_v12.py
```
The portable wheel includes the exact Python reference scorer. To compile the
optional native kernel from the source release on the tested Linux environment:
```bash
python scripts/build_native.py
```
For a private application service:
```bash
python -m pip install '.[server]'
# Set PHILLNET_RECALL_API_KEY locally to a random 32+ character secret.
python -m phillnet_recall --db data/recall.sqlite3 --tenant phillip serve --port 8000
```
The authenticated endpoints include `/v1/memories`, `/v1/search`, `/v1/recall`,
`/v1/paths`, `/v1/bridges`, `/v1/grounded-search`, `/v1/grounded-context`, `/v1/query`,
and `/v1/query-context`. The default bind is localhost. TLS, ingress rate limits,
appropriate application authorization, backups and encrypted storage remain the
host's responsibility. This is one configured tenant/namespace per API process.
```python
import os
from phillnet_recall import RecallClient
client = RecallClient(
'http://127.0.0.1:8000',
api_key=os.environ['PHILLNET_RECALL_API_KEY'],
)
print(client.grounded('Nova amber docket'))
```
The client accepts HTTPS for remote service origins and refuses credential-bearing
redirects. It does not log credentials or memory payloads in HTTP error messages.
## Hugging Face: model and Space are different artifacts
The model repository contains the policy data, source, installable package,
model card, tests and release manifest. It is **not** advertised as a standard
text-generation endpoint. The separate ready-to-upload Docker Space demonstrates
four fixed synthetic cases using the actual library, with a fresh in-memory store
per request. It accepts no personal memory content.
```bash
python scripts/verify_release.py
python scripts/publish_hf.py # dry run: no network or upload
hf auth login # authenticate locally
python scripts/publish_hf.py --publish # creates a new private model repo
```
Add `--public` only when public creation is intended. Existing repositories are
not overwritten and their audiences are not changed. The manifest protects the
allowlisted release bytes; it is not a digital signature. See the separate Space
publication commands in [HF_PUBLICATION.md](docs/HF_PUBLICATION.md).
After publication and local package installation:
```python
from phillnet_recall import RecallPolicy, RecallMemory
policy = RecallPolicy.from_pretrained(
'ayjays132/PhillNet-Recall', revision='YOUR_REVIEWED_COMMIT_SHA')
memory = RecallMemory('recall.sqlite3', policy=policy, tenant='me')
```
Only checkpoint data files are downloaded. Remote downloading and live Hub
rendering were not tested here; local save/load is tested.
## Host-model compatibility
Recall is external to model weights and KV caches. It can provide JSON evidence,
plain-text context, or an application-facing API to a host with a compatible input
adapter. This is a framework boundary, **not certification of every model**.
Actual host-tokenizer input budgets can be checked by the supplied prompt adapters.
GPT-2 and Qwen3.5-0.8B tests were invoked but did not generate answers because
Transformers was unavailable in the build environment; checkpoint network access
also failed. Explicit `not_run` receipts are preserved. No model answer accuracy,
reader improvement or cross-model parity is claimed.
## Limits, privacy and deployment gates
- English authored topic groups remain finite. Unknown meanings without an explicit
bridge or lexical connection still fail. Bridges and graph claims must be supplied.
- Source reliability and ranker scores are not calibrated truth probabilities.
Checksums and certificates are not signatures or verification of real-world facts.
- Instruction-like-text screening is a limited heuristic. Memory stays untrusted
source data; the host must not execute instructions found inside it.
- Resource bounds can reject large candidate sets, joins or proof-choice spaces.
An omitted or incomplete answer is never silently presented as exhaustive.
- SQLite persistence and deletion behavior are tested, but backups, storage media,
encryption and access controls determine real privacy guarantees.
- The package is locally tested. No official LongMemEval/LoCoMo score, independent
external audit, Docker image build, native Windows/macOS run, actual browser
rendering or live public deployment has been established.
## Provenance, reproducibility and research
The original twenty PHILL-UGR memory profiles and two additional original policies
are retained in `rankers.ugr`; the two 1.1 evidence policies are retained in
`evidence.ugr`. Complete numerical recipes and lineage are in `provenance/`.
Safetensors files mirror the packed parameters for inspection. `scripts/reproduce.py`
reconstructs both banks exactly. No parameter is added or edited in 1.2.
```bash
python -m pip install '.[test,hub,server]'
python scripts/build_native.py
python -m pytest -q
python scripts/reproduce.py
python scripts/evaluate_v12.py
python scripts/http_smoke_v12.py
```
The research notes distinguish this implementation from graph-RAG methods and
training-free retrieval that still relies on pretrained embeddings. Relevant
references and novelty boundaries are in [RESEARCH_1.2.md](docs/RESEARCH_1.2.md).
The included LongMemEval loader is a retrieval harness, not a completed benchmark.