PKS

PKS stands for Phenomenological Knowledge Store. In Nova, phenomenological means that stored knowledge starts from observable website situations: what agents and users can recognize, and which verified guidance belongs to those situations.

PKS is Nova’s curated long-term memory for website behavior. It stores recurring website situations, the signals that identify them, and the actions that have proven useful.

PKS can grow automatically while agents work. Nova can notice repeated safe actions, recurring blockers, and clear semantic patterns, then prepare learning candidates that still need evidence, review, or promotion before they become active guidance.

Agents use PKS when the same obstacle appears more than once: a consent banner, a login wall, a fragile navigation pattern, a modal, or a platform-specific page structure. Nova can recognize familiar patterns instead of treating every visit as a blank page.

PKS does not replace observation. A stored hint is useful only when it still matches the current page and when the user’s safety settings allow the action.

In short

• PKS stores website knowledge, not general world knowledge.
• Nova can automatically prepare PKS candidates from repeated safe actions and clear website patterns.
• Entries connect recognition signals with guidance, playbooks, verification, and health information.
• Knowledge becomes active only after enough evidence confirms that it is useful.
• Nova can read PKS for advice, but stale or risky entries must be reviewed before they guide actions.
• PKS belongs to Nova’s learning area together with observations, promotion, and ETM task memory.

What PKS stores

1. Website context PKS groups knowledge by website or scope, so advice can stay tied to the surface where it was learned.
2. Phenomena A phenomenon is a recurring visible situation, such as a consent banner, modal, login wall, paywall, layout shift, or native browser dialog.
3. Recognition signals Signals describe how Nova can recognize the situation again: visible text, stable page structure, vendor markers, layout behavior, or interaction evidence.
4. Automatic candidates When the same safe interaction or semantic situation repeats, Nova can prepare a PKS candidate without requiring the agent to write every entry by hand.
5. Playbooks and hints A playbook describes a careful action sequence and a verification step. A hint can also stay passive when it should only guide interpretation.
6. Health Health information records whether a pattern still works, whether it failed recently, and whether it should be treated as stale.

When this matters

PKS belongs to repeated website work: mapping an unfamiliar platform, preparing a reliable automation, handling recurring blockers, or helping an agent understand why the same website keeps behaving in a certain way. It is especially valuable on sites where small UI changes can break brittle selectors or where the right action depends on context.

Knowledge model for agents

For an agent, the PKS model answers three questions: where does this knowledge apply, how can the current page prove it still matches, and what should the agent do after using or rejecting the guidance?

Scope and route

Tells the agent which website area the guidance belongs to. The agent should not transfer a route-specific hint to an unrelated page just because the domain is the same.

Phenomenon

Names the visible situation the agent is dealing with, such as a consent banner, login wall, modal, paywall, layout shift, or native dialog.

Fingerprint

Lists the signals the current page must still show before stored guidance can be trusted: selectors, text, layout, vendor markers, or interaction evidence.

Advice

Summarizes what the agent should consider next. Advice is guidance, not permission; current perception and safety boundaries still decide.

Playbook

Describes the action sequence and verification check. A playbook is only useful when the agent can confirm that the same phenomenon is currently present.

Learning level

Shows whether knowledge is still a candidate, a shadow entry, or active guidance. Non-active entries are learning material, not normal runtime instructions.

Health and repair

Shows whether the guidance has worked, failed, gone stale, or needs patching, revalidation, telemetry, or deprecation.

How agents use PKS information

For agents, PKS is not just a memory entry. It is a structured information surface in the tool response: requested detail, effective detail, known patterns, advice, health warnings, semantic learning prompts, and repair cues all tell the agent how cautiously to proceed.

1. Request the right detail An agent can ask for no PKS payload, a compact summary, or full detail. The response also shows the effective mode, so the agent knows whether it received fresh guidance, a smaller unchanged marker, or no PKS data for this turn.
2. Read the page context PKS information is tied to scope, route, locale, auth state, trust, and health. The agent should check whether the current page context matches the stored guidance before using any selector or playbook.
3. Treat advice as guidance Hints, advice items, suggestions, and opinions help the agent choose a next step. They do not override current perception. If the visible page and stored PKS disagree, the current page wins.
4. Resolve higher-priority prompts first When Nova emits a semantic learning prompt, that prompt can suppress lower-priority advice in the same response. The agent should resolve or defer that learning question before continuing with routine selector guidance.
5. Verify before acting A matching PKS entry tells the agent what might work. Before action, the agent should confirm visible signals, check safety boundaries, and avoid using PKS to hide sensitive account, payment, credential, or destructive flows.
6. Report the outcome After using a known phenomenon, the agent reports success, failure, or not applicable. That telemetry is what turns a useful hint into measurable health instead of folklore.
7. Follow repair cues Health warnings, fragile selector warnings, drift advice, and learning repair queues tell the agent when stored guidance needs patching, revalidation, or retirement before the same action is repeated.
8. Example If a consent hint appears for the current route, the agent confirms the banner is still visible, applies the safest matching response, checks that the banner is gone, and reports the result. If the banner is different, the agent re-perceives and updates or ignores the stale guidance.

When PKS knowledge applies

This is the operational layer in plain language. A PKS hint should guide an agent only when the current page still matches the stored phenomenon and the entry is mature enough for runtime use.

Warnings and failure conditions

These are hard warning conditions where Nova should stop treating PKS guidance as routine. Other promotion decisions are evidence gates; they should not be documented as numeric thresholds unless the system exposes a real threshold.

Agent interpretation example

The example shows how an agent should read PKS as structured guidance, not as an instruction to act blindly.

Request

{
  "tool": "nova.perceive",
  "arguments": {
    "targetId": "active",
    "mode": "summary",
    "pksInclude": "summary"
  }
}

Relevant response fields

{
  "structuredContent": {
    "pksIncludeRequested": "summary",
    "pksInclude": "summary",
    "pks": {
      "payload": {
        "scope": "example.com",
        "routeSegment": "_root",
        "hints": [
          {
            "id": "consent_dismiss",
            "type": "consent_cmp",
            "policy": "reject_preferred",
            "verified": true,
            "hasWarning": false
          }
        ],
        "advice": ["All 1 phenomena healthy."]
      }
    }
  }
}

Agent interpretation

{
  "treatAs": "candidate guidance",
  "beforeAction": "confirm that the visible consent signals still match",
  "afterAction": "call nova.telemetry_report with scope, phenomenonId, and outcome='success' only if the banner is gone",
  "onMismatch": "trust current perception, not the stored hint"
}

MCP contract

This is the deterministic layer below the concept. It describes the PKS fields that agents and integrators should treat as contract signals rather than prose.

Execution rule: No PKS field may trigger action without current-page confirmation.