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:

1. Compress large context chunks before feeding them to an agent.
2. Retrieve relevant notes or prior generations.
3. Track lineage when you are evolving generations.
4. Keep long-lived notes in persistent memory.
5. Rank outputs with the scoring helpers.
6. Parse structured model output with StructuredOutputParser.
7. 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