npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@godspeedai/cognate-cognitive-api

v0.11.0

Published

Dependency-free CognitiveIndex contract, retrieval pipeline, indexing projection, and conformance kit (spec §14–16).

Readme

@godspeedai/cognate-cognitive-api

The retrieval contract for Cognate applications: a CognitiveIndex interface, the standard recall pipeline, an event-driven indexing projection, and a conformance kit for index implementations. It defines no vector database and no embedding model — implementations and embedders plug in.

When to use this package: you are building or consuming semantic recall ("find me documents like this query") and want one interface that works over any index backend, with tenant/scope filtering and authorization built into the pipeline rather than bolted on. Pick an implementation such as @godspeedai/cognate-cognitive-memory, @godspeedai/cognate-cognitive-ruvector, or @godspeedai/cognate-cognitive-rvf.

Installation

bun add @godspeedai/cognate-cognitive-api

Requires Bun >= 1.4.0. The SDK ships Bun-native TypeScript source, so add @types/bun and @types/node as dev dependencies when typechecking your project.

Quick start: recall

import { createRecall } from "@godspeedai/cognate-cognitive-api";
import { createMemoryIndex, hashingEmbedder } from "@godspeedai/cognate-cognitive-memory";

const recall = createRecall({
  index: createMemoryIndex({ dimension: 256 }),
  embedder: hashingEmbedder(256),
  resolver: {
    // Fetch authoritative content for an entry's source, with your own authorization.
    async resolve(sourceRef, actor, tenant) {
      return { kind: "ok", value: { text: "Refunds are approved by a manager." } };
    },
  },
});

const result = await recall.recall({
  text: "who approves refunds?",
  actor: { id: "alice", kind: "user" },
  tenant: "tenant-a",
  scopeIds: [],
  k: 5,
});

if (result.status === "ok") {
  for (const item of result.items) console.log(item.sourceRef, item.score);
} else {
  // "degraded": the index or embedder was unavailable; continue without cognition
  console.warn(result.reason);
}

The pipeline: embed the query, ask the index for candidates (with tenant/scope pre-filtering), re-check each candidate's provenance against the query's tenant and scopes, then fetch authoritative content through your SourceResolver. Sources that come back denied or missing are dropped silently — recall never discloses that a result existed. Results never exceed k. If the index or embedder throws, recall degrades to { status: "degraded", items: [] } unless the query sets required: true, in which case it throws CognitionUnavailableError.

Keeping an index fed: the indexer projection

cognitiveIndexer is a projection that turns durable events into index entries. You provide a deterministic extract function per event; the projection embeds the extracted documents and upserts them (idempotent by entry id, so replay is safe). When an event's payload is erased, its derived entries are removed — even across restarts.

import { cognitiveIndexer } from "@godspeedai/cognate-cognitive-api";

const indexer = cognitiveIndexer({
  name: "my-cognition",
  version: "1",
  index,               // a CognitiveIndex
  embedder,            // an Embedder
  extract: (event) =>
    event.eventType === "doc.created"
      ? [{ id: `doc:${event.eventId}`, sourceType: "event", sourceRef: `event:${event.eventId}`,
           tenant: event.tenant, scopeId: event.scopeId, semanticRef: null, eventRef: event.eventId,
           traceRef: null, metadata: {}, relationships: [], validFrom: event.occurredAt, validTo: null,
           text: String((event.payload as { title?: string }).title ?? "") }]
      : [],
});

Run it with a projection runner (the reference runtime accepts it via its projections option), or drive it yourself with @godspeedai/cognate-projections.

Conformance kit for index implementations

The @godspeedai/cognate-cognitive-api/conformance subpath exports cognitiveIndexConformance(name, make) — the behavior suite (nearest-first ordering, idempotent upserts, provenance preservation, tenant isolation, scope restriction, dimension checks) and an entry() fixture helper. Every index implementation in the Cognate family passes it unchanged; run it against your own implementation before trusting one.

Limitations

  • This package ships no index and no embedder — quality depends entirely on your choices.
  • Index candidates are never authoritative; only what your SourceResolver returns is.
  • Recall drops denied or missing sources without signaling which ones, by design.

Related packages

License

Apache-2.0