Hypercontext: a framework for agents that actually know what they're doing

I built Hypercontext because I got tired of agent frameworks that treat context like a static blob you shove into a prompt and hope for the best. Most tools out there assume context is something you pass. I wanted something that treats context as something you can inspect, compress, score, and rewrite while the agent is running.

Hypercontext is still in Alpha phase.

This isn't about adding another layer of abstraction over OpenAI's API. It's about making agents aware of their own reasoning so they can fix it when it breaks.

What it actually does

Hypercontext is a self-referential agent framework for Python and TypeScript. The core idea is simple: agents should be able to read and modify their own system prompts, tool descriptions, and memory at runtime based on whether they're actually succeeding at the task.

The framework ships with:

• A Python SDK with orchestration, agents, scoring, memory, compression, deduplication, convergence detection, and archive helpers
• A TypeScript SDK for Node.js with the same primitives
• A CLI for running compression, archive queries, provider discovery, and orchestration
• A curses-based terminal UI for browsing and pinning commands without leaving the shell
• A browser dashboard for visual inspection
• An MCP stdio daemon for Claude Desktop, Claude Code, and Codex integration
• An HTTP MCP server for web integrations

Both SDKs are zero-dependency where possible. The Python core is pure Python. The TypeScript SDK has minimal deps. You can run the whole thing against Ollama locally without touching a cloud provider.

The problem with most agent frameworks

I've used agents. They all share the same blind spot: context is treated as immutable input. You construct a prompt, feed it to the model, get output back. If the output is wrong, you tweak the prompt and try again. The agent itself has no idea what worked and what didn't across runs.

Hypercontext changes this by making context a first-class citizen that agents can manipulate. Each generation gets tracked as a node in a lineage tree. You can see which parent led to which result, which branch is going stale, and which context configuration produced the best score. Successful strategies get archived and reused. Failed ones get pruned.

This isn't theoretical. The archive stores scored generations so later runs can compare branches and identify the strongest evolution path. Memory is split between persistent storage (lessons across runs) and episodic storage (context within a single session).

How the context loop works

Here's the basic flow:

1. The agent receives a task and its current context window
2. It generates a response and scores the result against a fitness function
3. If the score is below threshold, the agent reflects on what went wrong
4. It rewrites its own system prompt, tool descriptions, or memory based on that reflection
5. The new context configuration gets tested in the next generation
6. Successful configurations get archived; failed ones get discarded

This happens automatically in the TaskAgent and MetaAgent classes. You don't need to hand-code the reflection logic unless you want to.

The MetaAgent goes further. It can perform repository-aware tool use and self-modification workflows. If you point it at a codebase with --workdir, it can inspect files, suggest modifications, and track whether those modifications improved the code quality.

Installation and setup

For Python:

pip install hypercontext

For Node.js:

npm install hypercontext-node-sdk

That's it. No separate MCP package to install. No complex dependency tree. The Python package includes the CLI, TUI, stdio daemon, HTTP server, and browser launcher. The npm package is the SDK only, which is the right granularity for Node projects.

Provider setup

Hypercontext doesn't lock you into a provider. It supports Claude, OpenAI, Ollama, OpenAI-compatible servers, and local transformers models. You set credentials via environment variables or a YAML config file with named presets.

For Claude:

HYPERCONTEXT_PROVIDER=anthropic
HYPERCONTEXT_MODEL=claude-sonnet-4-20250514
ANTHROPIC_API_KEY=your-key-here

For Ollama (fully local):

ollama serve
ollama pull llama3

HYPERCONTEXT_PROVIDER=ollama
HYPERCONTEXT_MODEL=llama3
OLLAMA_BASE_URL=http://localhost:11434

The named preset feature is useful when you want multiple backends in one project. You define them in a YAML file and resolve by name at runtime. The framework expands ${VAR} values from the environment, so secrets stay out of config files.

Using it in Python

Direct orchestration is straightforward:

from hypercontext import HyperContext
hc = HyperContext(output_dir="./hypercontext_output")
summary = hc.run(max_generations=3)
print(summary)

If you want provider-backed calls without the full orchestration loop:

from hypercontext import LLMClient
from hypercontext.providers import ProviderRegistry

registry = ProviderRegistry.instance()
provider = registry.create(
    "anthropic",
    model="claude-sonnet-4-20250514",
    api_key="your-key-here",
    base_url="https://api.anthropic.com",
)

client = LLMClient(provider=provider)
text, history, metadata = client.complete("Summarize this in one sentence.")

For agent workflows, you choose between TaskAgent (repeatable tasks) and MetaAgent (repository-aware reasoning and self-modification). Both support the context evolution loop out of the box.

Using it in TypeScript

The Node SDK follows the same patterns:

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

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" });

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,
);

The TypeScript SDK includes context compression, retrieval, lineage tracking, persistent memory, fitness evaluation, and structured output parsing. It's not a port of the Python code; it's a parallel implementation with the same design goals.

CLI and terminal UI

The Python package includes a full CLI:

python -m hypercontext version
python -m hypercontext providers
python -m hypercontext run --generations 5 --output-dir ./runs/demo --workdir .
python -m hypercontext compress --input long_text.txt --ratio 0.4
python -m hypercontext archive --list

The TUI is a curses dashboard for browsing commands, pinning favorites, and executing them without leaving the terminal. It supports --workdir so you can point it at any project root.

python -m hypercontext tui --workdir /path/to/project

For desktop assistants, the stdio MCP daemon handles Claude

Desktop, Claude Code, and Codex:

python -m hypercontext mcp --workdir /path/to/project

For browser integrations, the HTTP server exposes the same tools over a REST interface:

python -m hypercontext serve --port 8080 --workdir /path/to/project

MCP integration without the hassle

Most MCP implementations require you to install a separate mcp package and configure JSON files. Hypercontext bundles the stdio daemon and HTTP server directly. You don't need to pip-install anything extra.
The stdio daemon speaks the Model Context Protocol natively. Claude Desktop can discover and invoke Hypercontext tools without manual configuration. The HTTP server does the same for browser-based integrations.

Context compression and deduplication

One of the practical problems with long-running agents is context bloat. Hypercontext includes a ContextCompressor that reduces text size while preserving semantic meaning. There's also a validator that checks compression fidelity so you don't accidentally drop important information.
The deduplication layer identifies repeated patterns across generations and collapses them. This matters when you're running evolutionary loops where similar context configurations get tested repeatedly.

Lineage tracking

Every generation gets a unique ID and tracks its parent. You can query the lineage tree to answer questions like:
Which generation produced the best score?
Which parent led to this result?
Which branch hasn't improved in the last 10 generations?
This isn't just logging. The lineage data feeds back into the parent selection strategy for the next generation. Stagnant branches get deprioritized. High-fitness branches get explored further.

Archive and transfer learning

The archive stores proven context configurations ranked by fitness score. When you start a new task, the framework can query the archive for context patterns that worked well on similar tasks. This is transfer learning without neural network retraining. You're transferring context strategies instead of model weights.

The archive is queryable via CLI:

python -m hypercontext archive --query "task:code-review fitness:>0.8"

What I learned building this

I started this project after reading the Hyperagents paper and getting frustrated that none of the existing frameworks implemented the meta-cognitive ideas in a practical way. Most research code is a mess of Jupyter notebooks and hardcoded paths. I wanted something you could actually install and use.
The hardest part wasn't the context compression or the lineage tracking. It was designing the agent loop so that self-modification doesn't spiral into chaos. If an agent can rewrite its own system prompt, it can also break its own system prompt. The convergence detection layer stops the loop when scores plateau or when context configurations start cycling.
I also learned that dual SDK maintenance is a pain. Keeping the Python and TypeScript implementations in sync requires discipline. The APIs aren't identical because the languages have different conventions, but the core concepts map directly.

Current state and what's next

The framework is functional and I'm using it in my own projects. The Python package is on PyPI, the TypeScript SDK is on npm, and the docs are on GitHub Pages.
I'm currently working on:

• Better convergence heuristics for multi-objective optimization
• A web-based lineage visualizer
• More provider recipes for local model setups
• Benchmark suites to compare context strategies across tasks The repo includes runnable examples for evolution, lineage tracking, self-modifying agents, and provider workflows. If you want to see what the framework can do without writing code, start with examples/python/feature_gallery.py.

Try it

# Python
pip install hypercontext
python -m hypercontext version

# TypeScript
npm install hypercontext-node-sdk

Docs
PyPI
npm