Public Knowledge Graph (KaaS)

What It Is: A shared, sourced knowledge corpus that any AI agent can query — and argue against. Contributors earn free retrieval; consumers pay per call. Every item carries a source you can open and check.

Live size: 719 items — 536 scientific papers and 183 business items. Check current counts at /api/v1/public/domains.

Why This Exists

A small model running locally is cheap, but its knowledge is frozen at training time. The usual fix is to bolt a private vector store onto it, which means every team re-ingests, re-cleans and re-indexes the same public material.

The Public Knowledge Graph inverts that: the corpus lives once, in the open, and models retrieve from it on demand.

This is deliberately not a memory-hosting service. Your private memories stay private and free — see Core Concepts. This page is about the shared layer on top.

┌──────────────────────────────────────────────────────┐
│  Public          everyone can retrieve · paid        │
│                  source required · reviewed          │
├──────────────────────────────────────────────────────┤
│  Organization    visible inside your org             │
│                  publish selected cards to Public    │
├──────────────────────────────────────────────────────┤
│  Private         only you · free · fully isolated    │
└──────────────────────────────────────────────────────┘

A card never moves between layers on its own. Publishing to the public layer is an explicit, revocable action on a specific card.

Feature 1 · Retrieve knowledge

The problem: your agent needs a fact it wasn't trained on, and you need to know where that fact came from.

Retrieval fuses full-text search with semantic vector search (reciprocal rank fusion), so a query does not have to share vocabulary with the source text.

Anonymous — free preview

No account, no key. You get the title, a short excerpt, and full metadata.

curl -X POST https://awareness.market/api/v1/public/retrieve \
  -H "Content-Type: application/json" \
  -d '{"query": "superconductivity", "top_k": 5}'

Anonymous responses are capped at top_k: 3 and return excerpts only.

Authenticated — full content

curl -X POST https://awareness.market/api/v1/public/retrieve \
  -H "Content-Type: application/json" \
  -H "X-API-Key: aw_your_key" \
  -d '{"query": "superconductivity", "top_k": 10, "domain": "science"}'

Cost: 1 credit per ~500 characters returned. An identical repeat query is not charged twice.

Example

Query "Hydride materials ... superconductivity ... high pressure" returns, in order:

Superconductivity above 200 K discovered in superhydrides of calcium
  10.1038/s41467-022-30454-w
High-Temperature Superconducting Phase in Clathrate Calcium Hydride
  10.1103/physrevlett.128.167001
A review on metal hydride materials for hydrogen storage
  10.1016/j.est.2023.108456

Every row carries a resolvable DOI. Open it and check the claim yourself — that is the whole point.

Feature 2 · Validate a hypothesis

The problem: asking an LLM "is X true?" gets you a fluent answer with no way to check it, and the model will happily agree with whatever you proposed.

This endpoint does something different. It retrieves evidence from the corpus, then runs two independent agents over that same evidence — one arguing for the hypothesis, one against — and both must cite evidence by id. Neither may introduce facts that are not in the retrieved set.

curl -X POST https://awareness.market/api/v1/public/hypothesis/validate \
  -H "Content-Type: application/json" \
  -d '{"hypothesis": "Hydride materials can achieve superconductivity near room temperature under high pressure"}'

Example — a real run

verdict: supported, confidence: 0.9. Evidence retrieved:

[0] Superconductivity above 200 K discovered in superhydrides of calcium
[1] High-Temperature Superconducting Phase in Clathrate Calcium Hydride
[2] High-Temperature Superconducting Phase in Clathrate Calcium Hydride
[3] A review on metal hydride materials for hydrogen storage

Advocate (confidence 0.9):

The discovery of superconductivity above 200 K in calcium superhydrides [0] and the synthesis of high-Tc superconducting phase in clathrate calcium hydride [1] …

Skeptic (confidence 0.8):

The provided evidence only shows superconductivity in specific hydride materials (calcium hydride) under extremely high pressure (160-190 GPa) …

Note what the skeptic did. The hypothesis is supported, but only within a scope the wording glossed over: one family of hydrides, at 160-190 GPa. That caveat is the output you actually wanted — an answer without it would have been technically true and practically misleading.

verdict is one of supported / contradicted / insufficient_evidence. If the LLM is unavailable, the call degrades to evidence-only with insufficient_evidence rather than failing.

Feature 3 · Contribute knowledge

The problem: retrieval costs credits, and you have knowledge worth sharing.

Contributed knowledge that passes review earns credits, which pay for your own retrieval.

curl -X POST https://awareness.market/api/v1/public/contributions \
  -H "X-API-Key: aw_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Room-temperature superconductivity in ...",
    "content": "...",
    "domain": "science",
    "topic": "condensed-matter",
    "source_type": "DOI",
    "source_ref": "10.1038/s41467-022-30454-w"
  }'

Rules that are actually enforced

A source is mandatory. source_type and source_ref are required. DOIs are checked against Crossref where possible.
Nothing publishes on submission. Every contribution enters a review queue as status: pending, and only becomes retrievable after a reviewer approves it.
Credits are granted on approval, not on submission. Posting low-quality material earns nothing.
Duplicates are rejected — identical title+content from the same contributor returns 409.

Track your own submissions with GET /api/v1/public/contributions/mine and your standing with GET /api/v1/public/reputation.

Reputation

Approval raises your reputation, rejection lowers it. The score feeds the confidence shown on every item, and low-reputation contributors are reviewed first.

Feature 4 · Publish organization knowledge

The problem: your team's internal knowledge has value beyond your team, but you want to release it one card at a time and take it back if needed.

curl -X POST https://awareness.market/api/v1/org/knowledge/publish \
  -H "X-API-Key: aw_your_key" \
  -H "Content-Type: application/json" \
  -d '{"card_id": "...", "memory_id": "..."}'

Published cards earn 70% of the retrieval revenue they generate; the platform keeps 30%. Only the memory owner can publish from it — the ownership check is enforced server-side, and a non-owner gets 403.

Publishing is reversible: POST /api/v1/org/knowledge/revoke removes the card from the public corpus. GET /api/v1/org/knowledge/published lists what you currently have out there.

Feature 5 · Explore the graph

Entities are extracted from the corpus and linked to the knowledge that mentions them, so you can navigate by concept rather than by query string.

Endpoint	Returns
`GET /api/v1/public/graph`	Entity-knowledge graph (nodes + edges)
`GET /api/v1/public/graph3d`	Same data laid out for 3D rendering

Both are anonymous. The web UI at /knowledge renders this as an interactive point cloud; clicking an entity back-queries the knowledge linked to it.

Feature 6 · Verify corpus integrity

The problem: a paid corpus is only trustworthy if you can tell whether it was quietly edited after publication.

# stored snapshot
curl https://awareness.market/api/v1/public/anchored-state

# recompute over current data and compare
curl "https://awareness.market/api/v1/public/anchored-state?verify=1"

?verify=1 recomputes the root from the live corpus and returns match, mismatch, or incomparable. The root commits to each item's id, title, status, and a hash of its content — so rewriting a published body changes the root.

Scope, stated precisely:

The root is stored off-chain, in the platform database. An ERC-8350 Sepolia commit path exists in the codebase but is gated on a signing key that is not configured in production — so no root has been committed on-chain, and anchored is false on every snapshot.
It is a sequential hash fold, not a Merkle tree. It can tell you the set changed; it cannot produce an inclusion proof for one item.
Snapshots carry a root_version. Roots from different preimage versions are not comparable, and ?verify=1 reports incomparable rather than a false tamper alarm.

Usage and billing

curl https://awareness.market/api/v1/public/usage -H "X-API-Key: aw_your_key"

Returns your wallet balance, burn balance, and total credits spent on public retrieval. Contributions credit the burn pool; retrieval spends from it.

For crawlers and sitemaps, GET /api/v1/public/index returns a metadata-only listing (no content, not even excerpts) ordered by citation count.

Limits and current state

Stated plainly so you can judge fit:

Semantic ranking is still being tuned. A query worded very differently from the source text may surface topically-adjacent items rather than the exact one.
Chinese-language queries fall back to substring matching rather than tokenized full-text search.
Review is manual — throughput depends on reviewer availability.
Nothing is anchored on-chain yet; the commit path is built but not enabled.
The embedding model is warmed at startup, so vector search is normally ready before the first request. If a request lands during that window it is served rather than dropped, but may be slower than usual.

Core Concepts — private memory, knowledge cards, recall modes
Knowledge Cards — how cards are structured
MCP Tools Reference — calling Awareness from an IDE agent
Terms of Service — contribution licensing and liability