Auctalis/nocturnusai

> **The context engineering engine for AI agents: send only what changed.**
---
Before / After
---
The Numbers
Measured on live APIs. 15-turn product support conversation. Real usage.input_tokens counts. Run it yourself.
| | Naive replay | RAG-optimized | **NocturnusAI** |
|---|---|---|---|
| Tokens per turn | ~1,259 | ~800 | **~221** |
| Cost per month (1K req/hr, Opus 4, $15/1M) | $13,600 | $12,000 | **$2,400** |
| Latency | high | medium | **low** |
| Truth-preserving | no | no | **yes** |
Claude Opus 4: **5.7×** reduction. Gemini 2.0 Flash: **10.0×**. Full calculations.
---
Install
Or use the setup wizard:
---
Why Developers Star This Repo
- **Reproducible token reduction** — benchmark in the repo, methodology published, run it against your own workload
- **Deterministic inference** — same query, same result, every time. No embedding drift, no cosine similarity lottery
- **Truth maintenance** — retract a fact, all derived conclusions auto-retract. No stale context, no hallucination on operational state
- **Plugs into existing stacks** — LangChain, LlamaIndex, CrewAI, AutoGen, MCP, Vercel AI SDK, OpenAI Agents SDK, Mastra
- **Benchmarkable against naive replay** — numbers derived, not invented. Every claim traces to a notebook cell
---
Framework Quickstarts
| Framework | Integration | Link |
|---|---|---|
| **LangChain / LangGraph** | Drop-in NocturnusContextProvider, LangSmith trace pass-through | Docs |
| **CrewAI** | Task-scoped context per agent role | Docs |
| **AutoGen** | Context server callable by any agent | Docs |
| **MCP** | Spec-compliant server for Claude Desktop, Cursor, Continue | Config |
| **OpenAI Agents SDK** | Context middleware, no tool modifications | Docs |
| **Vercel AI SDK** | Edge-compatible adapter for Next.js, Nuxt, SvelteKit | Docs |
| **Python SDK** | pip install nocturnusai | Docs |
| **TypeScript SDK** | npm install nocturnusai-sdk | Docs |
---
How It Works
Three steps. Every turn.
1. **Extract** — raw conversation turns → structured facts via LLM extraction
2. **Infer** — backward-chaining logical inference finds only the facts reachable from the agent's current goal
3. **Return the delta** — a briefingDelta containing only what changed since the last turn
This is not vector search. It is not summarization. It is deterministic inference on a logic engine — Hexastore indexing, backward chaining, and truth maintenance.
---
The Working Loop
> **LLM required for natural-language turns.** The examples below send raw text turns through an LLM to extract structured facts. If you start the server without an LLM provider, natural-language turns will return zero facts. See Quick Start for setup options, or use predicate syntax (e.g., "customer_tier(acme_corp, enterprise)") which works without any LLM.
1. First reduction: POST /context
2. Goal-driven pass: POST /memory/context
3. Later turns: POST /context/diff
Returns only added and removed entries between snapshots.
4. End of thread: POST /context/session/clear
---
Choose Your Surface
Python SDK
TypeScript SDK
MCP
Use the context tool each turn for a salience-ranked working set. Pair MCP with the HTTP context endpoints when you need goal-driven assembly and diffs.