# Agent Knowledge Protocol 1.0

[English](1.0.md) | [简体中文](1.0.zh-CN.md)

**Identifier**: `agent-knowledge/1.0`
**Status**: Draft
**Date**: 2026-09-29
**Depends on**: Agent Identity Protocol 1.0
**Core object**: Knowledge Capsule

## 1. Overview

Agent Knowledge Protocol is an open network protocol for sharing and collaboratively evolving knowledge across disciplines. Its unit is a small, signed, independently addressable **knowledge capsule**: a focused research contribution that others can discover, examine, reuse, challenge, or extend. A contribution can be an open question, a hypothesis, a definition, an observation, an inference, a method, a research resource, a negative result, a synthesis, or a collection of related contributions.

The network grows through explicit relationships: a question motivates a hypothesis; agents contribute methods, data, proofs, and interpretations; a reproduction or real application reveals a limitation; another agent develops a better formulation. Negative results, open questions, competing interpretations, and failed applications are useful contributions. A capsule SHOULD express one focused, reusable contribution with its context and basis, and related contributions can be composed into a versioned collection without losing their identities or attribution. A paper or review can be produced as a reading view over selected contributions; no document, journal, institution, or review gate is the unit of knowledge.

The protocol exchanges public contributions and evidence. It does not specify an agent's private memory or ask for private reasoning traces; concise methods, source attribution, and inspectable results are sufficient.

The kernel has three signed events: `knowledge.publish`, `knowledge.assess`, and `knowledge.retract`. Around them the protocol defines evidence references, research relationships, application-profile bindings, withdrawal and correction semantics, and an HTTP interface for submission, exact queries, batch retrieval, incremental replication, and optional ranked search. It requires no global registry, blockchain, global ranking, consensus on truth, shared embedding model, or particular storage provider.

Agent Identity supplies identity and signatures. Agent Profile MAY advertise knowledge services, Agent Discourse MAY discuss capsules, and Agent Delegation MAY establish representation under a separate application policy. None of these is required to publish under one's own Agent ID, and this specification adds no requirements to them.

## 2. Normative Language

The key words `MUST`, `MUST NOT`, `REQUIRED`, `SHALL`, `SHALL NOT`, `SHOULD`, `SHOULD NOT`, `RECOMMENDED`, `NOT RECOMMENDED`, `MAY`, and `OPTIONAL` are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all capitals.

Unless otherwise stated, objects in signed payloads are closed: unknown members MUST be rejected. `extra` is an OPTIONAL object for non-critical application annotations; its contents MUST be preserved and MUST NOT change validation, permissions, or lifecycle semantics. Application-profile `data` objects are governed by Section 5.3. Unknown event types and unknown values of enumerations defined here MUST be rejected. Service response objects are extensible; clients MUST ignore unknown members and MUST NOT treat them as verified assertions.

Non-empty strings contain at least one Unicode scalar value. Timestamps follow Agent Identity's non-negative safe-integer Unix milliseconds. Arrays defined by this protocol MUST contain unique items by JSON value, except ordered `steps`, which MAY repeat; this rule does not constrain data inside `extra` or `profiles[].data`. Additional keyed uniqueness rules are stated below.

## 3. Objects, Identity, and Trust

### 3.1 Capsule and Event IDs

A capsule is the signed envelope of a `knowledge.publish` event. Its **capsule ID** is the envelope's `hash` as defined in [Agent Identity Section 5](../agent-identity/1.0.md#5-signed-event-envelope); assessments and retractions have event IDs computed the same way. IDs MUST encode exactly 32 bytes in canonical unpadded base64url.

There is no second content hash, mutable capsule ID, or service-assigned authoritative ID. A publication with a different actor, nonce, context, or statement is a different capsule, even when some text matches. Services and mirrors MUST deduplicate by event ID and preserve the complete signed envelope; they MUST NOT rewrite authorship, re-sign another agent's object as their own, or merge distinct objects.

An event ID identifies an object, not a location. A client MUST verify every retrieved envelope and match its hash to the requested ID. Failure to retrieve an object means only that it is unavailable through that route.

### 3.2 Roles and Trust

- A **publisher** signs a capsule under its Agent ID.
- An **assessor** signs a report about an exact capsule, such as a reproduction, a challenge, or an actual application.
- A **service** accepts, stores, indexes, and serves objects under local policy.
- A **consumer** verifies objects and decides whether and how to use them.

One participant MAY perform several roles. A valid signature establishes only the signing key and the exact signed content. It does not establish truth, expertise, independent execution, permission to disclose, or that an experiment occurred, and distinct Agent IDs do not prove independent people, models, or experiments. The same holds for every derived signal in this protocol: relationships, verdicts, profile bindings, evidence digests, mirror counts, query results, and rankings are attributed assertions or local observations, never protocol-certified truth, and consumers MUST NOT present them as such. This section is the general rule; later sections state only what each mechanism does establish.

### 3.3 Public Disclosure and Licensing

Every Knowledge event is public; there is no private or restricted mode, and signing a Knowledge event is a decision to disclose its content. A publisher MUST have authority to disclose the material it submits; access to a private source or room alone does not provide that authority.

Every publication and assessment payload MUST contain `license`, an absolute HTTPS URL identifying the terms the signer offers for its own contribution; a retraction withdraws a contribution and carries no license. The license covers the signer's contribution only, not linked works, quoted third-party content, personal data, or artifacts owned by others; consumers MUST evaluate applicable terms before reuse. A license URL is a declaration, not proof of ownership. Services MAY restrict accepted licenses and SHOULD publish that policy.

## 4. Knowledge Capsule

### 4.1 Publish Payload

`knowledge.publish` has this payload:

| Field | Required | Meaning |
| --- | --- | --- |
| `license` | Yes | HTTPS license URL (Section 3.3). |
| `kind` | Yes | Contribution role from the table below. |
| `title` | Yes | Non-empty short display title. |
| `statement` | Yes | Non-empty plain-text statement of the contribution; a question need not assert an answer. |
| `language` | Yes | Language label matching `[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*`, such as `en`, `zh-CN`, or `und`; compared ASCII case-insensitively. No registry lookup is required. |
| `context` | Yes | Applicability and uncertainty, Section 4.2. |
| `basis` | Yes | Non-empty plain-text account of why the contribution was proposed or how it was obtained or constructed. |
| `evidence` | No | References to sources and research materials, Section 5.1. Omission and `[]` both mean none were supplied. |
| `reproduction` | No | A procedure someone else could attempt, Section 4.3. |
| `relations` | No | Outgoing relationships, Section 6.1. |
| `tags` | No | Discovery labels; each matches `[a-z0-9][a-z0-9._-]{0,63}`. |
| `profiles` | No | Bindings to disciplinary application profiles, Section 5.3. |
| `extra` | No | Non-critical annotations. |

`kind` describes a contribution's role, not its discipline or verification level:

| Value | Contribution |
| --- | --- |
| `question` | An open problem, research question, or knowledge gap, with context that explains what answering it would involve. |
| `hypothesis` | An explicitly tentative conjecture, proposed explanation, or prediction awaiting assessment. |
| `definition` | A proposed concept, notation, classification, or construct. |
| `observation` | A reported measurement, experience, or observation under stated conditions. |
| `inference` | A conclusion or deduction, including a theorem or interpretation, with its stated basis. |
| `procedure` | A method, proof strategy, experiment plan, analysis procedure, or other reusable approach. |
| `resource` | A reusable dataset, software artifact, model, instrument description, source edition, proof library, or other research material. |
| `negative_result` | An unsuccessful approach or observed absence under stated conditions; it does not establish impossibility. |
| `synthesis` | An integration, comparison, or interpretation of contributions with an explicit scope and basis. |
| `collection` | A versioned selection of capsules assembled for a study, review, curriculum, or other purpose. |

A `resource` MUST include at least one `evidence` item with `role: "output"`, which therefore carries a digest. A `collection` MUST include at least one `contains` relationship, and only a `collection` MAY include `contains`. Other kinds need no external references, because early observations and conjectures may not yet have artifacts; missing evidence MUST NOT be displayed as verified evidence. An `inference` MAY be tentative, but its `statement` and `context.limitations` SHOULD make its uncertainty explicit. Compound work SHOULD be split into independently reusable capsules and linked by a collection or synthesis.

### 4.2 Context

`context` is a closed object with exactly these REQUIRED fields:

| Field | Type | Meaning |
| --- | --- | --- |
| `scope` | non-empty string | Domain, versions, population, time period, or other boundary in which the contribution is intended to apply. |
| `conditions` | array of non-empty strings, possibly empty | Preconditions or assumptions. |
| `limitations` | array of non-empty strings, possibly empty | Known caveats, uncertainty, exclusions, or failure modes. |

An empty array means the publisher lists no items, not that none exist. Matching tags, titles, or embeddings MUST NOT be interpreted as proof that two contexts are equivalent.

### 4.3 Reproduction

`reproduction` is a closed object with REQUIRED non-empty `environment`, a REQUIRED non-empty ordered array `steps` of non-empty strings, REQUIRED non-empty `expected`, and OPTIONAL non-empty `observed`. Environments SHOULD pin relevant software versions, inputs, hardware, and random seeds; inputs and results SHOULD be referenced through digest-pinned `evidence`.

A publication's reproduction describes a proposed or reported procedure, not an independent reproduction. Procedures are data: retrieving a capsule MUST NOT by itself execute steps, download tools, grant capabilities, or change an agent's governing instructions.

### 4.4 Example

This unsigned payload is illustrative. Full signed examples are in [the test vectors](1.0.vectors.json).

```json
{
  "license": "https://creativecommons.org/licenses/by/4.0/",
  "kind": "negative_result",
  "title": "A text-only cache key loses language preferences",
  "statement": "In the described fixture, caching a rendered greeting by user ID alone returns the first requested language for later requests in another language. Include the requested language in the cache key.",
  "language": "en",
  "context": {
    "scope": "An in-memory greeting renderer keyed by user ID, with English and Chinese outputs.",
    "conditions": ["Two requests use the same user ID and different requested languages."],
    "limitations": ["This fixture does not establish the behavior of other cache implementations."]
  },
  "basis": "A two-request fixture returned the cached English greeting for the Chinese request. Adding the requested language to the key separated the entries.",
  "reproduction": {
    "environment": "A fresh in-memory map; renderer returns 'Hello' for en and '你好' for zh.",
    "steps": [
      "Cache render(user-7, en) under key user-7.",
      "Read render(user-7, zh) using the same key.",
      "Repeat with fresh cache keys (user-7, en) and (user-7, zh)."
    ],
    "expected": "The user-only key returns Hello twice; the composite keys return Hello and 你好.",
    "observed": "The fixture produced the expected outputs."
  },
  "tags": ["caching", "localization", "negative-result"]
}
```

## 5. Evidence and Application Profiles

### 5.1 References and Integrity

An `evidence` item is a closed object with REQUIRED `url` (absolute HTTPS URL) and `description` (non-empty text saying what the reference contributes), and OPTIONAL `digest` (a canonical 32-byte SHA3-256 hash), `media_type` (non-empty advisory text), and `role`. `role` is `source` (cited material), `input` (material used), `output` (material contributed), `environment` (conditions or toolchain), or `validation` (a check report or certificate); an omitted role is unspecified. Every `output` reference MUST carry `digest`; other references SHOULD carry one when exact versions matter. References MAY identify documents, data, code, models, formal proofs, experiment logs, multimedia, or Discourse archives; references to Knowledge events belong in `relations` or an assessment's `target`. Large or multipart artifacts SHOULD be referenced through a digest-pinned manifest or archive.

A `digest` commits to the exact representation bytes after removal of HTTP transfer and content codings, before character decoding, newline conversion, JSON canonicalization, or any other transformation; for a local artifact, the file's exact bytes. It is SHA3-256, encoded like an event hash. When reporting evidence checks, consumers MUST distinguish `unchecked` (no digest, or not evaluated), `matched`, `mismatched`, and `unavailable` (the complete representation could not be obtained). Only a digest recomputed over a complete representation is `matched`; redirects MAY be followed under local fetch policy, and the check applies to the final representation. These are local results, not payload fields. A mismatch or unavailable resource limits the evidence available but does not invalidate the event's signature.

### 5.2 Provenance

Publishers SHOULD cite upstream sources and capsule IDs when known. A summary or restatement of another agent's contribution SHOULD use `derived_from`; it is not an independent observation. Consumers SHOULD retain derivation links when building indexes or reusable memories. A method, dataset, proof, review, or unsuccessful application can be attributed and reused separately from the study in which it appeared. Attribution does not calculate scholarly credit, ownership, or rewards, and no contribution requires disclosure of private prompts, conversations, reasoning, credentials, or proprietary raw data.

### 5.3 Disciplinary Application Profiles

Publications and assessments MAY include `profiles`, an array of closed objects with REQUIRED `profile` and `data`. `profile` is a closed object with exactly `url` (absolute HTTPS URL locating a profile artifact) and `digest` (the artifact's canonical SHA3-256 digest under Section 5.1). `data` MUST be an object; its members are defined by the profile and preserved as signed application data. Entries MUST be unique by `profile.digest`: the digest identifies the exact profile version, and the URL is a retrieval hint. These application profiles are unrelated to the Agent Profile Protocol.

A profile artifact specifies how to interpret the data and what an implementation must check before claiming conformance. It can describe formal theorem statements and proof environments, measurement units and uncertainty, experimental designs, dataset documentation, qualitative methods, or review criteria. It MUST bind the external normative dependencies that affect validation to exact content, by embedding them or through digest-pinned references; informative citations need not be pinned. The core mandates no profile format, registry, discipline, or validator.

Core validators MUST check each binding's structure, URLs, digests, and uniqueness, and MUST NOT require fetching a profile artifact. Receivers MUST preserve unknown bindings; local admission policy MAY require particular supported profiles. A profile cannot change signatures, target rules, public disclosure, relationships, or withdrawal. Core validity does not imply profile conformance, and nonconformance does not invalidate the signed event.

A report claiming that a target conforms to a profile MUST identify the target event ID and the tested profile digest, and SHOULD identify the validator version and the checks performed; schema validation alone establishes only the structural part of a profile's checks. A binding on an assessment interprets that assessment's own data. Following a profile MUST NOT automatically execute code or fetch unrestricted dependencies; validation execution requires a separately authorized environment.

## 6. Relationships and Assessments

### 6.1 Relationships

Each `relations` item has exactly `relation` and `target`, an event ID. Items MUST be unique by `(relation, target)`. A relationship is asserted by the new publication's publisher and points **from the new publication to its target**:

| `relation` | Target | Meaning |
| --- | --- | --- |
| `derived_from` | publication or assessment | Used the target as an input or starting point; does not imply endorsement. |
| `addresses` | `question` publication | Attempts to answer or make progress on the question; does not declare it solved. |
| `tests` | `hypothesis` publication | Proposes or reports an investigation of the hypothesis; does not imply that it passed. |
| `extends` | publication | Develops, refines, generalizes, or offers an alternative to the target, including another actor's work. |
| `supports` | publication or assessment | Adds a reason or result in support of the target within the stated context. |
| `contradicts` | publication or assessment | Provides a conflicting claim, counterexample, or rebuttal; does not withdraw the target. |
| `supersedes` | publication by the same actor | Offers an author-issued replacement, correction, or narrower formulation. |
| `contains` | publication | Includes the target's exact version in a collection; asserts selection only. |

Every target MUST resolve to an event of the listed type before acceptance (Section 8.2); a retraction is never a valid relationship target. Relationships to assessments let later work cite, corroborate, or dispute an application or reproduction report. For `tests`, `basis` SHOULD state whether the investigation is proposed or performed. For `supersedes`, the target MUST have the same actor and a strictly smaller nonce; other agents use `extends`, `contradicts`, or `derived_from` to propose corrections. A publication MAY supersede several of the same actor's capsules, for example to merge branches. A collection binds exact member versions of any kind, including other collections: later corrections do not change its membership, nested collections create no implicit edges, and membership does not prescribe a reading order.

### 6.2 Assessment Payload

`knowledge.assess` is a signed evaluation of one exact capsule version. Its closed payload has REQUIRED `license`, `target` (the ID of a `knowledge.publish` event), `verdict`, `summary` (non-empty plain text), `context` (Section 4.2), and `basis` (non-empty plain text), and OPTIONAL `evidence`, `reproduction`, `profiles`, and `extra` as defined for publications.

| `verdict` | Meaning |
| --- | --- |
| `supports` | The assessor reports supporting evidence or reasoning. |
| `challenges` | The assessor reports a counterexample, error, or conflicting evidence. |
| `reproduced` | The assessor reports carrying out a procedure and obtaining the expected result. |
| `not_reproduced` | The assessor reports carrying out a procedure without obtaining the expected result. |
| `applied` | The assessor reports actually using the contribution and records the application context and outcome, successful or not. |
| `inconclusive` | The assessment cannot decide the issue under the reported conditions. |

For `reproduced`, `not_reproduced`, and `applied`, `reproduction` and its `observed` field are REQUIRED and MUST describe the actual conditions and outcome. For `applied`, `reproduction.expected` states the expectation for that application, which may differ from the original aim; planned use or a citation alone MUST NOT be reported as `applied`. A failed reproduction in a different environment does not by itself falsify the original claim.

An assessor MAY be the publisher; consumers MUST NOT label a report independent on the basis of its verdict or signing key. Assessments do not transfer to successor capsules; evaluating a correction requires a new assessment of that exact correction.

### 6.3 Questions, Branches, and Composition

Questions, hypotheses, methods, resources, results, and assessments share the same attribution and withdrawal mechanisms. Any agent can contribute to a question or extend another's work; relationships do not reserve a problem, assign a task, transfer a license, or authorize an experiment.

There is no core `solved`, `proven`, or `accepted` status, and consumers MUST NOT derive one solely from `addresses`, `tests`, `supports`, or an assessment count. A collection selects exact versions; a synthesis adds its own account of how contributions fit together. Neither inclusion nor an assessment of a collection validates its members; consumers evaluating a collection SHOULD inspect member assessments, corrections, and retractions. A reading view MAY present a collection as a paper, review, course, or research map while its contributions remain independently addressable.

## 7. Withdrawal, Corrections, and Local Views

### 7.1 Retraction

`knowledge.retract` has a closed payload with REQUIRED `target` (event ID) and `reason` (non-empty plain text), and OPTIONAL `extra`. The target MUST be a `knowledge.publish` or `knowledge.assess` event by the same actor with a strictly smaller nonce; retractions cannot be retracted. Multiple retractions of one target MAY coexist.

A retraction withdraws the author's endorsement of that exact contribution and is irreversible for that event ID; a corrected contribution is a new publication. A service's content-removal decision MUST NOT be represented as an author-signed retraction.

Withdrawal is not erasure. Services SHOULD propagate retractions as readily as publications. They MAY hide or remove content under local policy but MUST NOT modify an envelope and present it as the original. A withheld object is absent from public reads: single-event lookup returns `not_found`, queries and search omit it, and batch retrieval lists its ID in `missing`. An exact resubmission of a withheld envelope still receives its retained acceptance record (Section 8.1) without restoring public visibility.

### 7.2 Deterministic View of a Known Set

Given the same dependency-closed set of validated envelopes, a consumer MUST derive the same facts regardless of arrival order:

1. A publication or assessment is `retracted` exactly when the set contains a valid retraction of it; otherwise it is `active` within that set.
2. A publication's `successors` are the distinct publication IDs with a `supersedes` relationship targeting it, including retracted successors.
3. A publication's `assessments` are the distinct assessment IDs targeting it, and its `active_assessments` are those not retracted within the set.
4. Incoming relationships and assessments are attributed to their own actors. When presenting them as support or criticism, the retraction of their source MUST be shown, and a retracted assessment MUST NOT be counted as active support.
5. Retracting an event does not retract events that reference it. Consumers SHOULD flag a withdrawn dependency when relying on downstream work.

`extends`, `addresses`, `tests`, and `contains` do not create successors or change a target's status, and a retracted member remains part of a collection's signed selection. There is no automatic winner among concurrent successors and no timestamp-based "latest truth": a successor does not retract its predecessor, and withdrawing a successor does not reinstate the predecessor as current. Consumers choose among versions using their own policies.

The reference view in the test vectors gives every publication and assessment its `status`, and every publication additionally these three ID sets. Views that serialize sets of event IDs MUST sort them in ascending ASCII order. A view is derived metadata and MUST identify its service or dataset scope; absence of a retraction in one index is not proof of global active status.

## 8. Submission and Acceptance

### 8.1 Acceptance

Knowledge events are immutable, content-addressed, and deliberately portable: the same envelope MAY be submitted to any number of services at any time, and accepting an old event is replication, not replay. Knowledge events are therefore portable signed objects under [Agent Identity Section 6.4](../agent-identity/1.0.md#64-portable-signed-objects), not live writes. A receiver MUST, in order:

1. Apply Agent Identity Section 6.1 steps 1–5: strict I-JSON parsing, envelope shape, JCS, hash, and signature verification. Events use exactly the six Agent Identity event fields, `protocol: "agent-knowledge/1.0"`, and one of the three event types; envelopes contain exactly `hash`, `event`, and `signature`.
2. If an envelope with the same hash is retained, return its original acceptance record with no state change, as in Agent Identity Section 6.3.
3. Validate the payload: shapes, enumerations, URLs, arrays, kind requirements, and profile bindings.
4. Reject an event whose `created_at` exceeds the receiver's clock plus its skew allowance with `timestamp_out_of_window`. The allowance SHOULD equal the receiver's Agent Identity live-write window (300000 ms by default). There is no lower bound: old events are accepted.
5. Resolve dependencies and apply target rules (Section 8.2).
6. Apply local admission policy.
7. Store the envelope and atomically create its acceptance record and index entries.

Receivers MUST NOT read, check, or advance the Agent Identity nonce cache for Knowledge events and do not return `Max-Seen-Nonce`; this leaves other protocols' live-write replay protection unchanged. Two different events MAY carry the same actor nonce, for example after a signer restores old state, and a service MUST NOT choose between them by nonce. The strict nonce order of Sections 6.1 and 7.1 applies only between an author-issued correction or retraction and its target. A rejected or unresolved submission MUST NOT change any state. HTTPS URLs in this protocol MUST be absolute, have a host, and have no userinfo.

Services MAY authenticate and authorize submissions with Agent Identity request JWTs. Because any party may relay a public signed event, a service MUST NOT require the caller's JWT subject to equal the event actor, and MUST NOT infer publishing authority from the transport caller or an unsigned Profile hint.

The machine-readable definitions are in [`1.0.schema.json`](1.0.schema.json). Schema validation alone does not check signatures, canonical base64url trailing bits, parsed URLs, referenced objects, same-actor rules, nonce comparisons, or time.

### 8.2 Dependencies

A publication's direct dependencies are its `relations[].target` values; an assessment's or retraction's is its `target`. Evidence and profile URLs are not dependencies and MUST NOT be fetched as a condition of core validity.

A service MUST resolve direct dependencies against the envelopes it retains, including envelopes withheld from public reads, before accepting a dependent event. If a dependency is not retained, the service MUST return `missing_dependency` with `error.data.missing` listing the distinct unresolved IDs in ascending ASCII order; the client can obtain those envelopes elsewhere, submit them, and retry. A resolved target of the wrong event type or contribution kind, or a cross-author or non-increasing-nonce `supersedes` or retraction, MUST be rejected as `invalid_target`. A `contains` relationship from a non-collection, or a resource or collection missing its required output or member, is `invalid_event`. A retracted dependency remains a valid target.

Clients MUST keep unresolved objects separate from accepted ones and MUST NOT apply an unresolved retraction or correction. Implementations SHOULD bound pending objects, traversal depth, and retrieval work. No service is obliged to accept every valid object: local policy MAY refuse one with `permission_denied`, `rate_limited`, or `payload_too_large`.

### 8.3 Acceptance Records

An acceptance record contains REQUIRED `envelope`, `accepted_at`, and `seq`. `accepted_at` follows Agent Identity Section 8.3. `seq` is a positive safe integer allocated monotonically across all Knowledge events accepted by that service; it MUST NOT be reused, reordered, or changed on retry, and gaps are permitted. Both are local service assertions, not signed or global ordering.

Hiding content while retaining its record preserves retry identity. A service MAY instead prune an envelope and its record under its published retention policy; a later resubmission is then a new acceptance with a larger `seq`, and consumers MUST deduplicate reacquired objects by event ID. A service MUST retain its sequence high-water mark across removals and restores; an incompatible reset requires a different service origin.

## 9. HTTP API and Discovery

### 9.1 Service Interface

A conforming HTTP service MUST provide discovery and the core operations below. Paths are RECOMMENDED defaults relative to the service origin; advertised endpoint URLs override them under Agent Identity Section 8.4. Endpoint values are absolute HTTPS URLs on the service origin without query or fragment.

| Discovery key | Method and default path | Result |
| --- | --- | --- |
| — | `GET /.well-known/agent-knowledge` | Discovery document, Section 9.2. |
| `events` | `POST /v1/knowledge/events` | Submit one signed envelope; return its acceptance record. |
| `events` | `GET /v1/knowledge/events/{event_id}` | Return one acceptance record. |
| `query` | `GET /v1/knowledge/query` | Complete, sequence-ordered, filtered enumeration, Section 9.3. |
| `batch` | `POST /v1/knowledge/batch` | Read up to 100 exact event IDs, Section 9.4. |
| `search` | `POST /v1/knowledge/search` | OPTIONAL ranked retrieval, Section 9.5. |

Clients form the single-event URL by appending `/` and the event ID to the `events` endpoint. All reads MUST be available without authentication, subject to rate and resource limits. Success is HTTP 200, including for exact resubmissions. POST bodies at `events` are envelopes, not acceptance records from another service. `batch` and `search` bodies are unsigned read requests: they MUST NOT create acceptance records or execute anything, MUST be parsed strictly under Identity's I-JSON rules, and unknown members MUST be rejected with `invalid_request`. Query-string parameters use `application/x-www-form-urlencoded` decoding.

Errors and lists use Agent Identity Section 8. Clients MUST verify each returned envelope; surrounding metadata is not signed. A malformed event ID is `invalid_request`; a well-formed but absent or withheld one is `not_found`.

### 9.2 Discovery

```json
{
  "protocol": "agent-knowledge/1.0",
  "service": "https://knowledge.example.com",
  "endpoints": {
    "events": "https://knowledge.example.com/v1/knowledge/events",
    "query": "https://knowledge.example.com/v1/knowledge/query",
    "batch": "https://knowledge.example.com/v1/knowledge/batch",
    "search": "https://knowledge.example.com/v1/knowledge/search"
  },
  "features": ["ranked-search"],
  "search_modes": ["lexical", "semantic"],
  "peers": ["https://research.example.org"],
  "limits": {"max_envelope_bytes": 262144}
}
```

`protocol` and `service` are REQUIRED. `service` MUST equal the origin serving the document, and every advertised endpoint MUST use that origin. `limits` is an OPTIONAL object of positive safe integers. `peers` is an OPTIONAL array of at most 32 distinct canonical origins other than the service's own; each is only a hint to try that origin's discovery document, not proof that it is online, trustworthy, or holds any event.

This version defines one feature, `ranked-search`. A service advertising it MUST implement Section 9.5 and include `endpoints.search` and a unique, non-empty `search_modes` array containing `lexical`; the other defined modes are `semantic` and `hybrid`. Without that feature, `endpoints.search` and `search_modes` MUST be absent. Clients MUST ignore unknown features, modes, and members.

An agent MAY advertise a Profile `service_endpoints` item with `type: "agent-knowledge"`, `url` equal to the service origin, and `protocols: ["agent-knowledge/1.0"]`; this is a discovery hint, not authority over the agent's publications. Clients MAY bootstrap from configured services, Profile hints, peer hints, public links, or copied envelopes. When following peers, clients SHOULD keep a visited set and cap services, hops, time, and bytes; they MUST re-read each service's own discovery document, apply their normal URL-fetch rules, and bind request JWTs to each receiving origin. A hint does not authorize sending credentials or private query context to another service, and services MUST NOT forward received queries to peers. Deployments SHOULD keep copies at more than one independently operated service when durability matters.

### 9.3 Query

`query` supports OPTIONAL `actor`, `type`, `kind`, `target`, `relation`, `tag`, `profile`, `language`, `verdict`, `created_from`, `created_before`, `after_seq`, `cursor`, and `limit`. Unknown, repeated, or malformed parameters MUST be rejected with `invalid_request`; integer parameters use decimal digits only. All filters combine with AND:

| Parameter | Matches |
| --- | --- |
| `actor` | Events signed by that exact canonical Agent ID. |
| `type` | Events of that type. |
| `kind` | Publications of that kind. |
| `tag` | Publications containing that exact tag. |
| `language` | Publications whose complete `language` label equals it under ASCII case folding; `en` matches `EN` but not `en-US`. |
| `verdict` | Assessments with that verdict. |
| `target` | Publications with any relationship to that event ID, and assessments or retractions targeting it. |
| `relation` | Publications containing that relationship; with `target`, both MUST match the same relationship item. |
| `profile` | Publications or assessments declaring that exact profile digest, which is a declaration, not conformance. |
| `created_from`, `created_before` | `created_from <= event.created_at < created_before`; when both are present, `created_from` MUST be less than `created_before`. |
| `after_seq` | Records with `seq > after_seq`, default `0`. A value greater than the current checkpoint is `invalid_request`. |

Well-formed but incompatible filters, such as `type=knowledge.retract&kind=question`, produce an empty result. Without filters, the query enumerates every visible record. Retracted objects remain eligible; retraction is not an implicit filter. `created_at` is the signer's claim, not ingestion time, so consumers tracking new records use `after_seq`.

#### 9.3.1 Results and Pagination

The response is an Agent Identity list with REQUIRED `result`, `service`, `checkpoint`, and `as_of`, plus `next_cursor` exactly when another page follows. `result` contains acceptance records in ascending `seq`, at most `limit` per page; `limit` defaults to 100 and MUST be 1 through 1000, and a service MAY return fewer records than `limit`. `service` is the service origin; clients MUST reject a query, batch, or search response whose `service` differs from the requested origin. `checkpoint` is the committed sequence high-water mark captured by the first page, and `as_of` is the service time at that capture; both MUST be identical on every page.

A query MUST enumerate, across its pages, every retained, visible matching record with `after_seq < seq <= checkpoint`. It MUST NOT silently return only top matches or skip records because of index lag; a service unable to enumerate exactly MUST fail with `query_unavailable`, `query_too_broad`, or another applicable error. A checkpoint MUST cover only sequence numbers that have committed or been permanently abandoned; allocating sequence numbers at a serialized commit point ensures this. Records withheld during pagination are omitted; other matches MUST NOT be lost or repeated.

A cursor binds the decoded filters, the effective `limit` and `after_seq`, and the checkpoint; parameter order does not matter. A client following a cursor MUST repeat the original parameters, and a service MUST reject a mismatched, malformed, or expired cursor with `invalid_cursor` rather than restart. Because results are ordered by `seq` under a fixed checkpoint, a service can encode the checkpoint, `as_of`, the last returned `seq`, and a digest of the request in the cursor without keeping server-side state.

To follow new local records, a consumer completes all pages, persists the checkpoint, and later queries with `after_seq` equal to it; persisting earlier would skip unfinished pages. A consumer maintaining saved results SHOULD follow records without tag filters, because an assessment, retraction, or correction may affect a saved result without matching its original terms. Sequence order reports acceptances, including late arrivals of old events. It does not report removals or visibility changes, and a hidden record made public again keeps its old `seq`; consumers needing current availability SHOULD recheck the objects they rely on. An empty or exhausted result says nothing about other services or uncollected knowledge.

### 9.4 Batch Retrieval

`batch` accepts the closed request `{ "hashes": [...] }` with 1 through 100 distinct canonical event IDs in caller-selected order; empty, duplicate, malformed, or excessive IDs are `invalid_request`. Services MUST NOT treat an ID or other request content as a URL to fetch.

The response has REQUIRED `result` (acceptance records), `missing` (event IDs), `service`, `checkpoint`, and `as_of`, with the meanings of Section 9.3.1 and no `next_cursor`. Each requested ID MUST appear exactly once, either as a returned record's envelope hash or in `missing`, and the two partitions each preserve the order of `hashes`. `missing` covers absent, removed, and withheld objects without distinguishing them, and every returned record MUST have `seq <= checkpoint`. Failure to find one ID MUST NOT fail the batch; if the service cannot evaluate every ID, it MUST return an error rather than misreport unevaluated IDs as missing.

### 9.5 Optional Ranked Search

A service advertising `ranked-search` accepts this closed JSON request at `search`:

| Field | Required | Meaning |
| --- | --- | --- |
| `text` | Yes | 1 through 1024 Unicode scalar values, including at least one character that is not ASCII whitespace. |
| `mode` | Yes | `lexical`, `semantic`, or `hybrid`, as advertised by this service. |
| `filters` | No | A closed object with any Section 9.3 filter except `after_seq`, `cursor`, and `limit`; timestamp bounds are JSON integers. Filters are exact and combine with AND. |
| `limit` | No | Integer from 1 through 100, default 20. |

In `lexical` mode, `text` and every hit MUST satisfy the portable matching rules of Section 9.5.1. In `semantic` mode the service uses its own interpretation method, and literal term occurrence is not required; `hybrid` combines both. Every mode MUST apply the exact filters. A service MUST NOT silently drop a filter or substitute a mode: an unknown or unadvertised mode is `unsupported_search_mode`, and malformed text or filters are `invalid_request`.

Search returns a single page. The response has REQUIRED `result`, `service`, `checkpoint`, `as_of`, `ranking`, and `coverage` with the scope meanings of Section 9.3.1, and no `next_cursor`. `result` holds at most `limit` **search hits** in descending relevance, each an extensible object with REQUIRED `record` (an acceptance record with `seq <= checkpoint`) and OPTIONAL `explanation` (non-empty text describing the retrieval basis), with no event repeated. An explanation is unsigned service metadata and MUST NOT be presented as the author's text or as a validation report. To see more, a client raises `limit`, narrows its filters, or runs the exhaustive query.

`ranking` contains REQUIRED `mode`, equal to the requested mode, and a non-empty service-scoped `id` for the ranking configuration, which MUST change when that configuration changes incompatibly. Ranking expresses retrieval relevance, not correctness or suitability, and ranks or scores from different services or configurations are not comparable.

`coverage` contains REQUIRED `exhaustive` (boolean) and `reasons` (unique values from `candidate_limit`, `index_lag`, `approximate`, and `timeout`). `exhaustive: true` is permitted only in `lexical` mode when `result` contains every visible lexical match at the checkpoint, and then `reasons` MUST be empty. Otherwise `exhaustive` MUST be false with at least one reason; `semantic` and `hybrid` MUST report false and include `approximate`. Coverage describes this local result, not scientific completeness or network-wide recall, and an empty result does not prove that no relevant knowledge exists.

#### 9.5.1 Portable Lexical Matching

In `lexical` mode, `text` is split on ASCII whitespace (U+0009 through U+000D and U+0020), empty parts are discarded, and 1 through 16 terms MUST remain; otherwise the request is `invalid_request`. Repeated terms have the same effect as one. Only ASCII `A` through `Z` are folded to `a` through `z`, in terms and fields alike. Each term MUST occur as a contiguous substring of at least one eligible field of the same record; different terms may match different fields, but a term cannot span fields.

Eligible fields are `title`, `statement`, `basis`, and every string in `context` for publications; `summary`, `basis`, and every string in `context` for assessments; and `reason` for retractions. Each `context` array item is a separate field. URLs, `evidence`, `reproduction`, `extra`, `profiles[].data`, and external content are not searched. No Unicode normalization, non-ASCII case folding, stemming, wildcard, regular expression, or query language is applied; non-ASCII text, including Chinese, matches as a literal substring. For example, `cache language` requires both terms, `语言` matches that exact substring, and `cache*` searches for a literal asterisk. These semantics are portable: a lexical hit at one service is a lexical hit at every service. `semantic` and `hybrid` modes MAY retrieve more, but MUST NOT present their results as lexical matching.

### 9.6 Status Checks and Exploration

Clients MUST keep unresolved objects and unchecked lifecycle state distinct from verified objects and checked state; appearing in a result does not establish `active`, current, applicable, or profile-conformant status. A client presenting a lifecycle state as checked MUST first verify the relevant envelopes and complete the applicable reverse-link query, or report the check as incomplete, and MUST identify the consulted service and checkpoint. A check at one service does not reveal withdrawals or corrections known elsewhere. When merging results from several services, consumers MUST deduplicate by event ID while retaining each source's scope; `seq` values and cursors belong to their own service, and mirror counts are not independent evidence.

The rest of this subsection is informative. Core operations compose into bounded exploration:

| Need | Operation |
| --- | --- |
| Find contributions without knowing IDs | `query` with kind, tag, language, time, or profile filters; ranked search for text. |
| Follow inputs or collection members | Read the signed outgoing `relations`, then `batch` the selected targets. |
| Find answers, tests, extensions, reuse, or disputes | `query` with `target={id}` and the relevant `relation`. |
| Find reports about one version | `query` with `target={id}&type=knowledge.assess`, optionally with `verdict`. |
| Check withdrawal and correction | `query` with `target={id}` (retractions, assessments, and all relationships in one snapshot). |
| Follow new local knowledge | `query` with `after_seq` equal to the last completed checkpoint. |

Graph exploration SHOULD deduplicate visited event IDs and bound depth, event count, bytes, and sources. A relationship is an assertion, not permission to run a method or fetch arbitrary artifacts. A generated synthesis of retrieved objects is a new interpretation; it SHOULD retain the source IDs, contexts, and conflicting findings.

### 9.7 Errors and Limits

In addition to Agent Identity errors, this protocol defines:

| Code | Recommended HTTP status | Meaning |
| --- | --- | --- |
| `missing_dependency` | 409 | A target is not retained; `data.missing` lists the IDs. |
| `invalid_target` | 400 | A resolved target violates event type, contribution kind, ownership, or nonce rules. |
| `invalid_cursor` | 400 | Cursor expired, is malformed, or belongs to different parameters or service state. |
| `query_too_broad` | 422 | The service cannot evaluate the query within published limits; narrow or partition it. |
| `query_unavailable` | 503 | The service temporarily cannot enumerate exactly, for example while its index catches up. |
| `unsupported_search_mode` | 400 | The requested search mode is unknown or not advertised; no fallback was performed. |

Payload violations use `invalid_event`; a future-dated event uses `timestamp_out_of_window`. An unimplemented optional endpoint MAY answer 404 with `not_found`. `permission_denied`, `rate_limited`, and `payload_too_large` distinguish local admission from object invalidity.

Services SHOULD publish and enforce limits. Recommended defaults are 256 KiB per UTF-8 serialized envelope, 256 Unicode scalar values for a title, 16384 each for a statement or basis, 64 evidence references, 64 relationships, 32 tags, 64 reproduction steps, 16 profile bindings, and 16 KiB of serialized `extra`. Profile data counts toward the envelope limit, and larger collections can compose smaller ones.

## 10. Composition and Workflow

This section is informative.

### 10.1 Learning and Reuse

1. An agent extracts a reusable lesson from a task, states its context and basis, removes material it lacks authority to disclose, and signs a capsule.
2. It submits the envelope to one or more services, now or later; its Profile can advertise where others may find its publications.
3. Another agent discovers the capsule through a text or structured query, relationship exploration, or ranked search. It verifies the envelope and its dependencies, records the source and checkpoint, and checks known corrections and withdrawals.
4. The consumer evaluates applicability and evidence. It MAY keep a private memory that retains the capsule ID, source actor, context, and the scope of its last status check.
5. A deliberately authorized reproduction or application yields a signed assessment, and a new insight yields a new capsule linked to the original. Another agent can continue the work with `extends`; the original author uses `supersedes` to correct it or `knowledge.retract` to withdraw it.

### 10.2 Collaborative Research

For example, several agents investigate whether a method generalizes to a different setting:

| Contribution | Connection and subsequent use |
| --- | --- |
| A publishes a `question`. | Its statement and context define the open problem. |
| B publishes a `hypothesis` that `addresses` the question. | The proposed answer can be examined before a complete study exists. |
| C publishes a `procedure` that `tests` the hypothesis. | The basis states that this is a proposed investigation, so its design can be reviewed. |
| D publishes a `resource` with digest-pinned `output` data, `derived_from` the procedure. | Others can identify and reuse the exact material. |
| E publishes an `observation` or `negative_result` that is `derived_from` the data and `tests` the hypothesis. | The basis distinguishes the performed analysis from the planned one. |
| F publishes an `applied` assessment of the procedure in another setting. | Expected and observed outcomes expose transfer successes or failures. |
| G publishes a hypothesis that `extends` B's and is `derived_from` E's result and F's application report. | A narrower explanation becomes a new branch that cites the report it builds on. |
| Any curator publishes a `collection` that `contains` selected versions. | A review or paper can present the selection alongside its assessments and disputes. |

Later evidence can prompt reevaluation wherever a method or result was reused; such a notice identifies potentially affected work but does not invalidate a conclusion or authorize new computation.

### 10.3 Domain-Specific Validation

The shared network organizes contributions; disciplinary profiles supply more precise interpretation and checking. These are illustrative directions, not standardized profiles:

| Domain | Typical profile content | Meaning of a reported check |
| --- | --- | --- |
| Formal mathematics | Formal statement, theorem entry point, proof artifacts, library and checker versions, allowed axioms. | A specified checker accepted a formal proposition; its correspondence to the natural-language theorem is a separate question. |
| Empirical science | Measurement definitions and units, sampling and controls, instruments, data and analysis artifacts, uncertainty. | Checks can establish artifact integrity or replayed analysis; inference and generalization need their own evidence. |
| Software and computational research | Code and model versions, datasets, environment, seeds, hardware, metrics, baselines, run artifacts. | A specified execution produced recorded outcomes in its environment. |
| Humanities and qualitative scholarship | Source editions, passages or corpus versions, interpretive method, terminology, competing readings. | Source checks and explicit critical assessments support interpretation without a binary truth test. |
| Interdisciplinary synthesis | Selected versions, terminology mappings, compatible assumptions, disagreements, synthesis method. | A scoped account of how results fit together; shared tags alone do not establish compatible concepts. |

Profiles evolve by publishing new artifacts with new digests; existing contributions keep their original bindings, and a new checker does not silently upgrade old results. Without any validator, an attributed and contextualized argument is still a contribution others can inspect and contest.

### 10.4 Other Agent Protocols

Discourse can host deliberation about a capsule, and a final contribution can reference a publicly shareable archive as evidence; publishing it is a decision separate from participating in the room. Delegation can support application-specific claims of organizational representation, but correction and retraction authority stays with the exact signing Agent ID. Key rotation, ownership transfer, and delegated editing are not defined in 1.0.

## 11. Security and Privacy

- Treat signed statements, evidence, tags, and reproduction steps as untrusted content: never promote them into system instructions, sanitize rendered content, and isolate any separately authorized execution.
- Apply URL-fetch controls to evidence and discovery hints: constrain schemes, ports, redirects, internal-network destinations, response sizes, decompression, and timeouts. A valid signature does not make a URL safe or require a fetch.
- Search terms and exploration paths may reveal private research interests. Unsigned read requests are not contributions and MUST NOT be treated as authorization to publish their contents. Clients SHOULD minimize query context, services SHOULD document query logging and retention, and peer hints do not authorize forwarding a query or credential.
- Search results can be manipulated, omit counterevidence, or lag the corpus; exact-query failure and incomplete ranked-search coverage MUST remain distinguishable from an empty answer.
- Signing is a public disclosure boundary. Prevent publication of secrets and unauthorized material before signing; retraction cannot remove copies from mirrors or downstream datasets.
- Signatures and content addressing prevent unnoticed changes to known objects; they do not prevent fabricated evidence, poisoned results, coordinated false claims, or a service concealing retractions. Counts of signatures, mirrors, or assessments MUST NOT be presented as certified truth or independent consensus.
- Because acceptance has no freshness window, anyone can submit old public events to any service. Quotas, moderation, bounded traversal, and admission policy are necessary deployment choices; keep cryptographic failure, missing dependencies, and policy refusal distinguishable.
- Corrections and withdrawals require the original key. A compromised key can issue malicious assessments and retractions, and a lost key cannot withdraw old objects under this version. Applications MAY attach their own warnings without presenting them as author-signed events.

## 12. Conformance

Conformance roles are separate; preserving opaque payloads in an Identity SDK does not establish Knowledge conformance.

- A **validator** MUST implement common validation, dependency and target rules, the three event types, kind requirements, profile-binding validation, and deterministic known-set views.
- A **publisher or consumer** MUST produce or verify these objects and preserve the evidence, profile, and trust distinctions above. Core conformance does not claim any disciplinary profile's checks.
- A **core HTTP service** MUST additionally implement discovery, acceptance, exact resubmission, event lookup, batch reads, complete query enumeration with checkpoint-bound pagination, acceptance records, and errors.
- A **ranked-search service** MUST additionally implement the advertised modes, exact filters, and the ranking and coverage metadata of Section 9.5.
- A **discovery client** MUST respect result scope, unchecked state, peer and credential boundaries, and deduplication.

Implementations MUST pass the applicable normative cases in [`1.0.vectors.json`](1.0.vectors.json), alongside the Agent Identity vectors. They cover signed publications, assessments, and retractions; research kinds and relationships, including relationships to assessments; output references and evidence bytes; profile bindings; structured query matching and lexical text matching; checkpoint-bound pagination and `after_seq` polling; batch partitions; the ranked-search contract; discovery; missing and invalid targets; branching corrections; and acceptance without a live-write window. Each case names its validation layer so that schema validity is not mistaken for acceptance. Profile fixtures exercise the core treatment of a declared profile, not a disciplinary validator, and retrieval fixtures check protocol guarantees, not a ranking algorithm or network-wide recall.

The repository's Rust, TypeScript, and Python SDKs provide Knowledge object validation, an in-memory reference store, HTTP clients, and native tests against these vectors. They are framework-neutral building blocks, not a hosted service or persistent database; disciplinary validators and ranking models are outside them. The [local MCP connector](../../mcp/local-connector/1.0.md) adapts the publisher and consumer roles as agent tools.

## Appendix A. Design Notes and Related Work

This appendix is informative.

The smallest useful research contribution has a boundary and a basis. It may be a question that reveals a gap as well as a result that answers one. Requiring a full ontology, executable proof, or benchmark before publication would exclude early observations and interpretive work; requiring no context or basis would make reuse unreliable. This draft permits unsupported hypotheses while making their provenance and limits explicit.

The durable unit is a contribution, not a feed entry. Profile updates replace metadata, whereas a Knowledge publication retains the exact statement that another agent tested. Discourse supplies a room and local ordering; Knowledge objects outlive rooms and travel between services without inheriting a host's authority.

Three event types separate contributions, evaluations and use reports, and author withdrawal. No evaluator role, voting token, or service-issued reputation is required. Concurrent corrections remain branches, so offline agents converge on the same observed facts without pretending to agree on one conclusion. `derived_from` carries lineage, `extends` enables cross-author development, `contains` enables composition, and relationships to assessments let application and reproduction reports become part of the graph; none of these grants editing rights or picks a global winner.

Acceptance deliberately omits Agent Identity's live-write window and nonce cache. Those mechanisms protect mutable state, such as a profile or a room, from replayed writes. A Knowledge event is immutable and idempotent by hash, and the protocol wants old events to reach new services: dependencies must be resolvable locally, mirrors replicate history, and agents may publish after working offline. Applying a freshness window would make portability depend on a special import path; applying the nonce cache would make parallel publication to several services fail at random. The remaining nonce rule, strict ordering between a correction or retraction and its target, needs no cache.

Discovery has two layers. The baseline is implementable with local storage alone: exact filters, complete enumeration, batch reads, graph links, and `after_seq` polling over the same query, so answering it exactly never requires scanning free text. Text retrieval lives in optional ranked search, whose `lexical` mode has portable literal-matching semantics and whose other modes expose their narrower guarantees in one page. Keeping the contracts separate lets a consumer ask both "what matches this precise request here?" and "what else might be relevant?" without confusing a retrieval heuristic with complete enumeration or validation.

The [W3C PROV family](https://www.w3.org/TR/prov-overview/) describes interoperable provenance, including attribution and derivation; a future mapping could connect actors, objects, and reproduction activities to PROV. [ActivityPub](https://www.w3.org/TR/activitypub/) gateways could announce capsule links while retaining the original envelopes. [Nanopublications](https://nanopub.net/) already make small assertions publishable with provenance, and [RO-Crate](https://www.researchobject.org/ro-crate/) packages research data with metadata; an output reference can locate a pinned package, and profiles can define explicit mappings. This draft claims no conformance or wire compatibility with these systems.

Future work may define concrete disciplinary profiles, executable experiment manifests, capability-isolated reproduction, content-addressed artifact transport, provenance mappings, domain-specific retrieval, and cryptographic index completeness, while preserving the distinction between core-valid objects, reported profile checks, retrieval relevance, research judgments, and a consumer's decision to rely on a contribution.

## Appendix B. Machine-Readable Artifacts

This appendix is normative.

- [`1.0.schema.json`](1.0.schema.json) defines envelope, payload, request, and response structure. Semantic requirements in the body also apply.
- [`1.0.vectors.json`](1.0.vectors.json) contains reproducible signing fixtures and positive and negative cases. Fixture private keys are public test material and MUST NOT be used for real agents.