|
Download README.md from ayjays132/PhillNet_Recall: direct link, hf CLI and curl.
- Browser
- Download file 14.8 kB
-
https://huggingface.co/ayjays132/PhillNet_Recall/resolve/main/README.md
- Command line
-
hf download hf://ayjays132/PhillNet_Recall/README.md
-
curl -L -o README.md https://huggingface.co/ayjays132/PhillNet_Recall/resolve/main/README.md
14.8 kB
| language: | |
| - en | |
| license: apache-2.0 | |
| library_name: phillnet-recall | |
| tags: | |
| - phillnet | |
| - memory | |
| - retrieval | |
| - evidence | |
| - graph | |
| - ranker | |
| - training-free | |
| - local-first | |
| - safetensors | |
| - custom-code | |
| model-index: | |
| - name: PhillNet Recall 1.2.0 | |
| results: [] | |
| <div align="center"> | |
| <img src="assets/hero.png" alt="PhillNet Recall 1.2.0 — Grounded memory. Complete evidence. 24 policies and 12,128 packed bytes." width="100%"> | |
| # 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) | |
| </div> | |
| ## 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` | | |
| <img src="assets/grounded-results.png" alt="96 synthetic queries: 4 first-place hits without the supplied glossary, 96 with it, and 96 with equivalent conventional scoring. Additional information is explicitly supplied." width="100%"> | |
| 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. | |
| <details><summary><strong>Documentation map</strong></summary> | |
| | Guide | Purpose | | |
| |---|---| | |
| | [Quick start](docs/QUICKSTART.md) | Local use, glossary, structured queries and API | | |
| | [1.2 architecture](docs/ARCHITECTURE_1.2.md) | Bounds, exact semantics, optimization and certificates | | |
| | [Inherited architecture](docs/ARCHITECTURE.md) | Original path semantics and bitemporal validity | | |
| | [Migration](docs/MIGRATION_1.2.md) | Compatible database and new statuses | | |
| | [HF publication](docs/HF_PUBLICATION.md) | Verified model and Space upload paths | | |
| | [Research](docs/RESEARCH_1.2.md) | Primary sources and what they do not establish | | |
| | [Report provenance](reports/README.md) | Current evidence versus retained development reports | | |
| </details> | |
| ## License and citation | |
| Apache-2.0 for this implementation and authored policies; inherited attribution | |
| is retained in `NOTICE.md`. No third-party pretrained checkpoint is bundled. | |
| ```bibtex | |
| @software{holland2026phillnetrecall, | |
| author = {Phillip A. Holland Jr.}, | |
| title = {PhillNet Recall 1.2.0: Grounded Memory}, | |
| year = {2026}, | |
| version = {1.2.0}, | |
| note = {Scope-local terminology, positive relational queries, and complete-evidence context selection} | |
| } | |
| ``` | |