FAQ

Honest answers.

What is proven, what is protocol, what is a claim, and what is not built yet. If a question is missing, it probably belongs here.

Identity and trust

›When I run knowledge review --approve --as oncology-review.eth, how does the system know I am oncology-review.eth?

Today it does not. --as oncology-review.eth (or KNOWLEDGE_AGENT for the MCP server) is a claim, not a proof. Anyone with access to the repository could type it. The roles in the policy — owner, reviewers, contributors — are enforced by every repository that acts on the namespace, which is real protection against mistakes and against agents overstepping, but not against a person who controls the machine and wants to lie.

What is enforced cryptographically is narrower and stronger: only the wallet that owns the ENS name holds SET_CONTENTHASH on its resolver, so only the owner can publish a version. Everything a reader sees on cancer-research.eth got there because the owner’s key moved the pointer.

The natural next step, which needs nothing new in the object model: reviewers sign their approvals with the key that owns their ENS name, and land verifies the signature — or reviewers hold a role on the namespace’s resolver and approvals are checked on chain. Until then, treat “reviewed by oncology-review.eth” as “recorded as reviewed by oncology-review.eth on the owner’s repository”.

›Do I need a different wallet for each role?

No. One wallet — the namespace owner’s — is enough, and it is used for exactly two things: registering the name (knowledge init --register) and publishing (knowledge push). Contributor, reviewer and consumer are names in the policy, not wallets. The live demo namespaces were built with a single wallet.

›Who can publish, then?

Only the owner’s wallet. A reviewer can approve and land a proposal locally, but the new version becomes visible to the network only when the owner pushes. If you want reviewers to publish, share the wallet or — better — grant them the resolver role on chain; the code already reads roles from the resolver.

What is on chain, what is not

›What exactly lives on ENS?

Per namespace: the name, a UserRegistry (so it can have children with their own owners), a PermissionedResolver, and one record — contenthash — pointing at the current refs object on IPFS. Nothing else. Claims, commits, policy, proposals and reviews are all in the refs object and the commit objects, which are content-addressed and verified by hash when fetched.

›Is the policy enforced on chain?

No. The policy (who reviews, who may propose, how many approvals) is part of the published refs, so every reader and every repository sees the same rules and enforces them locally. ENS enforces ownership of the pointer. That split is deliberate for the MVP; per-role on-chain enforcement is the hardening step described above.

›Can history be rewritten?

Not without leaving evidence. Every commit’s id is the SHA-256 of its content, including its parents. A reader who has seen v42 can check that v43 descends from it. The owner could point the name at a different history — that would be a visible break in the chain, not a silent edit. Within a history, revert adds a new version; nothing is deleted.

›Is the content encrypted?

Public namespaces (cancer-research.eth) are stored in plaintext on IPFS on purpose — any agent should be able to read them. Private and personal namespaces (--private, e.g. treasury.kestrel.eth or alice.eth) are AES-256-GCM encrypted before pinning; readers hold the namespace key. No plaintext personal memory ever reaches public IPFS.

Review

›Is the “automated review” an AI?

No large language model is involved, and that is deliberate. It is a deterministic engine that compares a proposal with the base branch: duplicates, contradictions (same topic and subject, similar claim, different statement), missing sources, low confidence, removals of reviewed claims, and claim edits with no new source. It is advisory — findings are shown to the reviewer, who decides. An LLM-assisted reviewer could be plugged in as another source of findings without changing the workflow.

›Can a contributor approve their own proposal?

No, unless they are the owner. Approvals from the same reviewer count once, and the policy says how many are needed. A reject closes the proposal; its branch stays so nothing is lost.

Using it

›How is this different from an agent-memory platform? Theirs is persistent too.

It is — persistent in the sense they claim: the memory survives the session. What it is not is durable in your hands. It is not portable (keyed to a vendor’s user id in a vendor database), not immutable (a later extraction silently overwrites; no version, no diff, no undo), and not sovereign (you hold no key and cannot grant another app read access without copying). Persistent for the application, not for you.

The test that separates the two: would a second party want to know where this came from? Memory is a byproduct of one interaction with one principal. Knowledge is authored, has a truth condition, and is read by people who were not there. Knowledge needs sources, a reviewer and a version; memory does not — which is why personal namespaces here default to approvals: 0 and land instantly. Row by row.

›Do I need to build an application to use this?

No. The consuming application is any MCP-capable assistant — Claude Code, Cursor and others — with the knowledge server attached. It resolves the name, searches, cites sources and reviewers, and can open proposals. The SDK (Namespace.for('cancer-research.eth')) is the same primitive for people who do want to build; see the consumer guide.

›Do I need to publish the MCP server to npm?

No. It is a single bundled file that a client spawns locally over stdio: claude mcp add knowledge -- npx -y @knowledge01/mcp. Search works offline against the local repositories; only pull and push touch the network.

›How does another agent see a new version?

Publishing moves one pointer. The next knowledge_pull (or knowledge pull) resolves the name, fetches the new refs and only the commits it does not have yet, and fast-forwards. There is no cache to invalidate and no server to notify.

Not built yet

›What is explicitly missing?
  • Signed approvals / on-chain reviewer roles (see the first question).
  • Contributors publishing their own forks and owners pulling them — the version graph supports it; the CLI flow assumes proposals are made on the owner’s repository.
  • Vector or graph retrieval. Search is keyword-ranked over the current snapshot, scoped by topic and subject, which is enough at namespace scale; the seam is pluggable.
  • Payments, subscriptions, marketplaces, DAO governance, reputation — deliberately later.
  • A web UI for writing. The explorer is read-only; contributions and reviews go through the CLI or an agent.