docs/QUICKSTART.md

PhillNet Recall 1.2.0: quick start

Requires Python 3.10+. The memory core uses only the standard library. No pretrained model, embedding runtime, GPU, or gradient training is required. Install the wheel:

python -m pip install phillnet_recall-1.2.0-py3-none-any.whl

Or install the extracted repository with python -m pip install .. The source includes an optional C99 CPU scorer (python scripts/build_native.py on the tested Linux host). The portable wheel uses the exact Python reference path. The small checkpoint does not imply the whole application fits in 12 KB.

New vocabulary without modifying weights

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'])

The bridge is a supplied query mapping, not a discovered meaning. It is scoped, versioned, expirable, and deletable. pack_grounded includes the selected note AND its glossary dependencies, or omits the entire bundle. It never labels related notes as an inferred answer. The existing recall interface remains backward compatible; use recall_grounded explicitly for these mappings.

Combine conditions across memories

from phillnet_recall import RecallMemory, pack_query

with RecallMemory('recall.sqlite3', tenant='phillip', namespace='ops') as memory:
    for predicate, value in [('region', 'west'), ('owner', 'Mira')]:
        memory.remember(f'Beacon {predicate}: {value}', source='operator:config',
                        entity='Beacon', predicate=predicate, value=value)
    plan = {
        'where': [
            {'entity': '?service', 'predicate': 'region', 'value': 'west'},
            {'entity': '?service', 'predicate': 'owner', 'value': 'Mira'},
        ],
        'select': ['?service'],
    }
    result = memory.query(plan)
    print(result['rows'])  # [{'?service': 'Beacon'}]
    packet = pack_query(memory, result, budget=8192)

Plans are supplied by the application, not inferred from arbitrary language. Variables use exact case-sensitive NFKC-normalized values. Use opaque consistent IDs when identity matters. no_matches concerns this eligible store, not the world.

Serve one authenticated scope

python -m pip install '.[server]'
# Set PHILLNET_RECALL_API_KEY to a locally generated 32+ character secret.
python -m phillnet_recall --db data/recall.sqlite3 --tenant phillip serve --port 8000

PowerShell:

$env:PHILLNET_RECALL_API_KEY = (py -c "import secrets; print(secrets.token_urlsafe(40))")
py -m phillnet_recall --db data/recall.sqlite3 --tenant phillip serve --port 8000

The default bind is localhost. Public deployment needs TLS, ingress rate limits, authorization and persistent private storage. A process serves one configured scope. Do not grant clients the ability to choose arbitrary tenants.

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'))

Client methods map to the server's JSON API. Remote HTTP is rejected in favor of HTTPS, and redirects do not forward credentials. API and HTTP errors do not print request contents or keys.

Reproduce local checks

python -m pip install '.[test,hub]'
python scripts/build_native.py
python -m pytest -q
python scripts/reproduce.py
python scripts/evaluate_v12.py
python scripts/http_smoke_v12.py

Tests requiring native parity must build the C kernel first. Windows/macOS native builds and Docker builds were not verified in this release. Pure-Python installed wheel execution was verified separately.