Npm Package Installation¶

What is Hypercontext?¶

Hypercontext is a standalone SDK for building AI agents that are aware of their own context. Unlike conventional agent frameworks that operate with fixed prompts and static tool sets, Hypercontext agents:

Observe their own reasoning in real time
Rewrite their own context based on performance feedback
Archive successful strategies in an evolutionary knowledge base
Transfer learned behaviors across tasks and sessions

The framework is inspired by the Hyperagents paper's vision of meta-cognitive AI systems — agents that don't just use context, but reason about and modify their own context to improve over time.

Features¶

Self-Referential Context Loop — agents read and rewrite their own system prompts, tool descriptions, and memory at runtime
Meta-Cognitive Self-Modification — built-in reflection and context evolution based on task outcomes
Evolutionary Archive — persistent store of proven context configurations, ranked by fitness
Transfer Learning — reuse context patterns across different tasks, domains, and agent instances
Context Fission — intelligent decomposition of complex contexts into specialized sub-contexts (from ContextFission)
Zero External Dependencies — pure Python core; TypeScript SDK with minimal deps
Dual SDK — first-class Python and TypeScript/Node.js support
Framework Agnostic — works with any LLM provider (OpenAI, Anthropic, local models, etc.)
Operational Provider Recipes — practical setup guides and runnable demos for Claude, OpenAI, Ollama, OpenAI-compatible servers, and local models
Dedicated TUI — a curses-based terminal dashboard for browsing, pinning, and executing CLI commands in the shell, with --workdir support for project-root workflows
MCP Everywhere — a stdio MCP daemon for Claude Desktop, Claude Code, Codex, and other terminal or desktop agents, plus the existing HTTP server for the browser dashboard

What You Get¶

Installing hypercontext-node-sdk gives you:

the TypeScript/Node SDK
agent primitives for Node.js applications
context, lineage, archive, memory, scoring, and diff helpers
a published package that can be consumed from any Node project

The npm package is an SDK, not the Python CLI or MCP daemon. It does not ship the full Hypercontext runtime; it ships the Node.js SDK only.

Coverage At A Glance¶

Ships	Does Not Ship
TypeScript SDK, Node helpers, and SDK examples	Python CLI, TUI, stdio MCP daemon, HTTP server, browser launcher, `README.md`, or `usage.md`

Prerequisites¶

Node.js 18 or newer
npm

If you want a clean workspace, initialize a project first:

mkdir hypercontext-playground
cd hypercontext-playground
npm init -y

Install Hypercontext¶

Install the published SDK:

npm install hypercontext-node-sdk

If you are using TypeScript in a new project, install the usual tooling:

npm install -D typescript ts-node @types/node

Verify The Install¶

Create a minimal script:

import { ContextCompressor, StructuredOutputParser } from "hypercontext-node-sdk";

const compressor = new ContextCompressor();
console.log(compressor.compress("This is a longer sentence with filler words.", 0.4));

const parser = new StructuredOutputParser();
console.log(parser.parse('result: {"ok": true} and {"count": 2}'));

Run it with ts-node:

npx ts-node demo.ts

Or compile it:

npx tsc --init
npx tsc demo.ts
node demo.js

Package Configuration¶

The npm SDK does not require a .env file for the basic offline helpers. If your app uses provider-backed flows, keep your credentials in your own application environment and load them the same way you would for any Node app.

Use In Your Own Project¶

Typical imports:

import {
  ContextCompressor,
  ContextRetriever,
  ContextWindow,
  LineageTracker,
  PersistentMemory,
  FitnessEvaluator,
  TaskAgent,
  MetaAgent,
  StructuredOutputParser,
  EnhancedToolRegistry,
  LoggingMiddleware,
} from "hypercontext-node-sdk";

Typical workflow:

Compress large context chunks before feeding them to an agent.
Retrieve relevant notes or prior generations.
Track lineage when you are evolving generations.
Keep long-lived notes in persistent memory.
Rank outputs with the scoring helpers.
Parse structured model output with StructuredOutputParser.
Register and observe tools with EnhancedToolRegistry and LoggingMiddleware.

Example¶

import {
  ContextWindow,
  TaskAgent,
  StructuredOutputParser,
  EnhancedToolRegistry,
  LoggingMiddleware,
} from "hypercontext-node-sdk";

async function main() {
  const window = new ContextWindow(4096);
  window.add("Important context", 1.0, "system");

  const agent = new TaskAgent({ name: "demo", maxTokens: 1024 });
  const result = agent.forward({ query: "hello" });
  console.log(result.prediction);

  const parser = new StructuredOutputParser();
  console.log(parser.parseFirst('Answer: {"status":"ok"}'));

  const registry = new EnhancedToolRegistry();
  registry.use(new LoggingMiddleware());
  registry.registerTool(
    {
      name: "echo",
      description: "Echo a payload back",
      parameters: { type: "object" },
    },
    async (args) => args,
  );
  console.log(await registry.invoke("echo", { text: "hello" }));
}

main();

Assistant Integrations¶

If your assistant is a Node.js app, the npm SDK is the right integration path. If your assistant needs the native MCP daemon, use the Python package instead.

For practical assistant integration notes, see Integrations.

Troubleshooting¶

If the install fails:

Confirm Node.js 18+
Delete node_modules and reinstall
Make sure your package registry can reach npm
If you are working on the SDK itself, use a local development workspace for the package source and run the build/test commands from that package folder