Cognitum SDKs
Official SDKs for the Cognitum platform — ship against the Cognitum Seed
appliance (direct, over mDNS / USB gadget / LAN) or the Cognitum Cloud
control plane (api.cognitum.one).
One surface. Three runtimes.
接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
npx -y @cognitum-one/[email protected]Claude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
claude mcp add cognitum-one-sdk -- npx -y @cognitum-one/sdk@0.4.0在終端機中執行。
{ "mcpServers": { "cognitum-one-sdk": { "command": "npx", "args": [ "-y", "@cognitum-one/[email protected]" ] } }}claude_desktop_config.json
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
Official SDKs for the Cognitum platform — ship against the Cognitum Seed
appliance (direct, over mDNS / USB gadget / LAN) or the Cognitum Cloud
control plane (api.cognitum.one).
One surface. Three runtimes.
Official Cognitum SDK for Node.js and TypeScript
| Language | Package | Version | Install |
|---|
| Node.js / TypeScript | @cognitum-one/sdk | published 0.3.0; 0.4.0 prepared on main | npm install @cognitum-one/sdk |
| Python | cognitum-sdk (import as cognitum) | published 0.3.0; 0.4.0 prepared on main | pip install cognitum-sdk |
| Rust | cognitum-one | published 0.3.0; 0.4.0 prepared on main | cognitum-one = "0.3" |
The Python distribution name is
cognitum-sdk(the PyPI project namecognitumbelongs to an unrelated third party) but the import name is stillcognitum—pip install cognitum-sdk, thenfrom cognitum import ....
All three SDKs implement the same domain model, the same HTTP contract, and the same failover / security / observability invariants — they differ only where the host runtime makes a different idiom natural.
Package identifiers, registry versions, and per-capability maturity are also
published as a machine-readable manifest:
capabilities/sdk-release.v1.json
(validated against capabilities/sdk-release.schema.json
and cross-checked against live npm/PyPI/crates.io in CI — see
scripts/verify-release-manifest.mjs).
The version in the source manifests is not proof that a registry publish has happened. The table above names both states deliberately. Use the registry version for installs and the capability manifest for operation maturity.
import { SeedClient } from "@cognitum-one/sdk/seed";
const client = new SeedClient({
endpoints: "https://cognitum.local:8443",
tls: { insecure: true }, // dev-only; use tls.ca for production
});
const status = await client.status();
console.log(`seed ${status.deviceId}, epoch ${status.epoch}`);
const result = await client.store.query({ vector: [0.1, 0.2, /*...*/ 0.8], k: 3 });
from cognitum.seed import SeedClient, SeedTLS
client = SeedClient(
endpoints="https://cognitum.local:8443",
tls=SeedTLS(insecure=True), # dev-only
)
status = client.status()
print(f"seed {status.device_id}, epoch {status.epoch}")
result = client.store.query(vector=[0.1, 0.2, 0.8], k=3)
# async variant available as AsyncSeedClient with the same surface
use cognitum::seed::{SeedClient, SeedTls};
let client = SeedClient::builder()
.endpoint("https://cognitum.local:8443")
.tls(SeedTls::Insecure) // dev-only
.build()?;
let status = client.status().await?;
println!("seed {} epoch {}", status.device_id, status.epoch);
let result = client.store().query(StoreQuery {
vector: vec![0.1, 0.2, /*...*/ 0.8],
k: 3,
}).await?;
Full Rust usage gated behind features = ["seed"]; mesh via
features = ["seed", "mdns"].
Every SDK ships — with parity tests:
SeedClient with 1..N peers, closest-first with
session-sticky reads, failover cycles on 5xx/network errors, pins on 429,
respects an ADR-0005 60 s wall-clock budget across all peer attempts.client.mesh() observability — status / peers / swarm_status /
cluster_health wrapping the seed's mesh inspection endpoints.CallOptions — pin a specific peer, bias routing (closest/
local-first/random/any), request session/eventual consistency,
override timeout / retries per call.Degraded and failed peers Unhealthy.@cognitum-one/sdk/seed/discovery/mdns · pip install cognitum-sdk[mdns] ·
cargo --features seed,mdns), Tailscale (any tailnet peer matching
cognitum-*).tls.ca / SeedTLS(ca_pem=...) /
SeedTls::Pinned), per-peer SHA-256 cert fingerprint advertised via mDNS
fp=sha256:<hex> TXT, or dev-only insecure. Fingerprint mismatch is a
hard TlsPinError — never falls back to insecure.TrustScoreBlockedError to protect the seed's trust state. Per-peer
counter; 2xx resets.pair.create
are wrapped in a redacting SecretString type. console.log(response) /
repr(response) / format!("{:?}", response) never leaks the raw value.
Conformance tests pin the contract.Retry-After header and the seed's
retry_after_us JSON body (body wins). POST methods do not auto-retry
unless the caller opts in via idempotent: true.Additive to the Seed/Cloud surface above: bounded clients for Meta-LLM,
Meta-Proxy, HarnessaaS, and MetaHarness, plus a shared agentic contract layer
(credentials, typed errors/retry, receipts, redaction, trace context). Every
SDK exposes the same namespace shape (<pkg>/agentic, <pkg>/meta-llm, …) —
see each per-language README for exact import paths.
Maturity uses one shared vocabulary across all three SDKs and the cognitum.one developer portal:
The full detail (per-language namespaces, feature flags, governing ADRs,
known gaps) lives in
capabilities/sdk-release.v1.json.
seed/ # Phase 1 — 12 endpoints per SDK, verified live
status identity
pair.status pair.create pair.delete pair.window
witness.chain
custody.epoch
store.status store.query store.ingest
ota.config ota.checkNow
seed/mesh/ # Phase 2 — observability
mesh.status mesh.peers mesh.swarmStatus mesh.clusterHealth
seed/ (advanced) # Phase 2 — per-call knobs
client.session() # sticky peer for a call chain
client.peers() # SDK-local PeerSet snapshot
client.rediscover() # re-resolve via provider
resource.call({ peer, prefer, consistency, timeout, retries })
# every resource method
mcp/ # stdio + HTTP MCP transports
McpClient(transport=StdioTransport(...))
McpClient(transport=HttpTransport(...))
discovery/ # Phase 3 — pluggable providers
ExplicitDiscovery(urls) # default
MdnsDiscovery(service_type="_cognitum._tcp.local.")
TailscaleDiscovery(prefix="cognitum-")
Paired writes carry an X-Pairing-Token per seed (per-peer in mesh mode via
a TokenBook). Cloud calls carry X-API-Key. Each SDK resolves the key in
this order, stopping at the first hit:
apiKey / api_key / builder).COGNITUM_API_KEY env var.Pairing-token resolution is analogous (pairingToken arg, then
COGNITUM_SEED_TOKEN env, else require explicit auto_pair).
docs/adr/ddd/seed-domain.md
(bounded contexts + ubiquitous language) and the
docs/adr/README.md index.docs/adr/0002-seed-wire-protocol.md —
the HTTP contract (71 endpoints).docs/adr/0016a-...md /
0016b-...md —
the SeedClient configuration contract, single- and mesh-seed modes.docs/adr/ folder.cognitum-one/sdks/issuescognitum-one/seedSUPPORT.mdSECURITY.md — do not disclose vulnerabilities in public issuesCONTRIBUTING.mdApache-2.0. Every SDK package carries its own LICENSE file matching the root
LICENSE; the license applies identically.
{ "mcpServers": { "cognitum-one-sdk": { "command": "npx", "args": [ "-y", "@cognitum-one/[email protected]" ] } }}工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
@cognitum One/sdk 透過 stdio 在本機執行。
上次檢查時間:2026-11-17。 Official Cognitum SDK for Node.js and TypeScript