{
"markdown": "# NocturnusAI\n\n[](https://github.com/Auctalis/nocturnusai/actions/workflows/ci.yml)\n[](https://pypi.org/project/nocturnusai/)\n[](https://www.npmjs.com/package/nocturnusai-sdk)\n[](https://github.com/Auctalis/nocturnusai/pkgs/container/nocturnusai)\n[](LICENSE)\n[](https://nocturnus.ai/docs/mcp)\n\n> **The context engineering engine for AI agents: send only what changed.**\n\n\n\n---\n\n## Before / After\n\n```python\n# ❌ Without NocturnusAI — replay everything, every turn\nmessages = system_prompt + full_history + tool_outputs # ~1,259 tokens/turn\nresponse = llm(messages) # $13,600/mo at scale\n\n# ✅ With NocturnusAI — send only what changed\nctx = nocturnus.process_turns(raw_turns) # extract → infer → delta\nmessages = system_prompt + ctx.briefing_delta # ~221 tokens/turn\nresponse = llm(messages) # $2,400/mo. Same accuracy.\n```\n\n---\n\n## The Numbers\n\nMeasured on live APIs. 15-turn product support conversation. Real `usage.input_tokens` counts. [Run it yourself.](https://nocturnus.ai/benchmark)\n\n| | Naive replay | RAG-optimized | **NocturnusAI** |\n|---|---|---|---|\n| Tokens per turn | ~1,259 | ~800 | **~221** |\n| Cost per month (1K req/hr, Opus 4, $15/1M) | $13,600 | $12,000 | **$2,400** |\n| Latency | high | medium | **low** |\n| Truth-preserving | no | no | **yes** |\n\nClaude Opus 4: **5.7×** reduction. Gemini 2.0 Flash: **10.0×**. [Full calculations.](https://nocturnus.ai/calculations)\n\n---\n\n## Install\n\n```bash\npip install nocturnusai # Python\nnpm install nocturnusai-sdk # TypeScript\ndocker run -p 9300:9300 ghcr.io/auctalis/nocturnusai:latest # Docker\n```\n\nOr use the setup wizard:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Auctalis/nocturnusai/main/install.sh | bash\n```\n\n---\n\n## Why Developers Star This Repo\n\n- **Reproducible token reduction** — benchmark in the repo, methodology published, run it against your own workload\n- **Deterministic inference** — same query, same result, every time. No embedding drift, no cosine similarity lottery\n- **Truth maintenance** — retract a fact, all derived conclusions auto-retract. No stale context, no hallucination on operational state\n- **Plugs into existing stacks** — LangChain, LlamaIndex, CrewAI, AutoGen, MCP, Vercel AI SDK, OpenAI Agents SDK, Mastra\n- **Benchmarkable against naive replay** — numbers derived, not invented. Every claim traces to a notebook cell\n\n---\n\n## Framework Quickstarts\n\n| Framework | Integration | Link |\n|---|---|---|\n| **LangChain / LangGraph** | Drop-in `NocturnusContextProvider`, LangSmith trace pass-through | [Docs](https://nocturnus.ai/docs/integrations) |\n| **CrewAI** | Task-scoped context per agent role | [Docs](https://nocturnus.ai/docs/integrations) |\n| **AutoGen** | Context server callable by any agent | [Docs](https://nocturnus.ai/docs/integrations) |\n| **MCP** | Spec-compliant server for Claude Desktop, Cursor, Continue | [Config](https://nocturnus.ai/docs/mcp) |\n| **OpenAI Agents SDK** | Context middleware, no tool modifications | [Docs](https://nocturnus.ai/docs/integrations) |\n| **Vercel AI SDK** | Edge-compatible adapter for Next.js, Nuxt, SvelteKit | [Docs](https://nocturnus.ai/docs/integrations) |\n| **Python SDK** | `pip install nocturnusai` | [Docs](https://nocturnus.ai/docs/sdks) |\n| **TypeScript SDK** | `npm install nocturnusai-sdk` | [Docs](https://nocturnus.ai/docs/sdks) |\n\n---\n\n## How It Works\n\nThree steps. Every turn.\n\n1. **Extract** — raw conversation turns → structured facts via LLM extraction\n2. **Infer** — backward-chaining logical inference finds only the facts reachable from the agent's current goal\n3. **Return the delta** — a `briefingDelta` containing only what changed since the last turn\n\nThis is not vector search. It is not summarization. It is deterministic inference on a logic engine — [Hexastore](https://nocturnus.ai/docs/concepts) indexing, [backward chaining](https://nocturnus.ai/how-it-works), and [truth maintenance](https://nocturnus.ai/docs/concepts#truth-maintenance).\n\n---\n\n## The Working Loop\n\n> **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](#quick-start) for setup options, or use predicate syntax (e.g., `\"customer_tier(acme_corp, enterprise)\"`) which works without any LLM.\n\n### 1. First reduction: `POST /context`\n\n```bash\ncurl -X POST http://localhost:9300/context \\\n -H 'Content-Type: application/json' \\\n -H 'X-Tenant-ID: default' \\\n -d '{\n \"turns\": [\n \"user: Customer says they are enterprise and blocked on SLA credits.\",\n \"tool: CRM says account is Acme Corp with a 2M ARR contract.\",\n \"agent: Last week support promised to review SLA eligibility.\",\n \"tool: Billing note says renewal is due next month.\"\n ],\n \"maxFacts\": 12\n }'\n```\n\n### 2. Goal-driven pass: `POST /memory/context`\n\n```bash\ncurl -X POST http://localhost:9300/memory/context \\\n -H 'Content-Type: application/json' \\\n -H 'X-Tenant-ID: default' \\\n -d '{\n \"goals\": [{\"predicate\":\"eligible_for_sla\",\"args\":[\"acme_corp\"]}],\n \"maxFacts\": 12,\n \"sessionId\": \"ticket-42\"\n }'\n```\n\n### 3. Later turns: `POST /context/diff`\n\n```bash\ncurl -X POST http://localhost:9300/context/diff \\\n -H 'Content-Type: application/json' \\\n -H 'X-Tenant-ID: default' \\\n -d '{\"sessionId\": \"ticket-42\", \"maxFacts\": 12}'\n```\n\nReturns only `added` and `removed` entries between snapshots.\n\n### 4. End of thread: `POST /context/session/clear`\n\n```bash\ncurl -X POST http://localhost:9300/context/session/clear \\\n -H 'Content-Type: application/json' \\\n -H 'X-Tenant-ID: default' \\\n -d '{\"sessionId\":\"ticket-42\"}'\n```\n\n---\n\n## Choose Your Surface\n\n\nPython SDK
\n\n```python\nfrom nocturnusai import SyncNocturnusAIClient\n\nwith SyncNocturnusAIClient(\"http://localhost:9300\") as client:\n ctx = client.process_turns(\n turns=[\n \"user: Customer says they are enterprise and blocked on SLA credits.\",\n \"tool: CRM says account is Acme Corp with a 2M ARR contract.\",\n ],\n scope=\"ticket-42\",\n session_id=\"ticket-42\",\n )\n\n diff = client.diff_context(session_id=\"ticket-42\", max_facts=12)\n client.clear_context_session(\"ticket-42\")\n\n print(ctx.briefing_delta)\n```\n\n \n\n\nTypeScript SDK
\n\n```ts\nimport { NocturnusAIClient } from 'nocturnusai-sdk';\n\nconst client = new NocturnusAIClient({\n baseUrl: 'http://localhost:9300',\n tenantId: 'default',\n});\n\nconst ctx = await client.processTurns({\n turns: [\n 'user: Customer says they are enterprise and blocked on SLA credits.',\n 'tool: CRM says account is Acme Corp with a 2M ARR contract.',\n ],\n scope: 'ticket-42',\n sessionId: 'ticket-42',\n});\n\nconst diff = await client.diffContext({ sessionId: 'ticket-42', maxFacts: 12 });\nawait client.clearContextSession('ticket-42');\nconsole.log(ctx.briefingDelta);\n```\n\n \n\n\nMCP
\n\n```json\n{\n \"mcpServers\": {\n \"nocturnus\": {\n \"url\": \"http://localhost:9300/mcp/sse\",\n \"transport\": \"sse\"\n }\n }\n}\n```\n\nUse 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.\n\n \n\n---\n\n## What Lives Behind The Workflow\n\nWhen you do need backend mechanics, NocturnusAI provides them:\n\n- Deterministic fact and rule storage\n- Backward-chaining inference with proof chains\n- Truth maintenance and contradiction handling\n- Temporal facts with `ttl`, `validFrom`, and `validUntil`\n- Multi-tenancy via `X-Database` and `X-Tenant-ID`\n- MCP, REST, Python SDK, TypeScript SDK, and CLI surfaces over the same engine\n\n---\n\n## Quick Start\n\n### Docker (fastest)\n\n```bash\ndocker run -d --name nocturnusai -p 9300:9300 \\\n --restart unless-stopped \\\n -v nocturnusai-data:/data \\\n ghcr.io/auctalis/nocturnusai:latest\n```\n\n```bash\ncurl http://localhost:9300/health # Verify it's running\n```\n\n### Docker with Ollama (enables natural-language extraction)\n\n```bash\ndocker run -d --name nocturnusai -p 9300:9300 \\\n --add-host=host.docker.internal:host-gateway \\\n -e LLM_PROVIDER=ollama \\\n -e LLM_MODEL=granite3.3:8b \\\n -e LLM_BASE_URL=http://host.docker.internal:11434/v1 \\\n -e EXTRACTION_ENABLED=true \\\n ghcr.io/auctalis/nocturnusai:latest\n```\n\n### From this repo\n\n```bash\nmake up-ollama && make smoke\n```\n\n---\n\n## CLI\n\n```bash\nnocturnusai # Interactive REPL\nnocturnusai -e \"context 10\" # Salience-ranked working set\nnocturnusai -e \"compress\" # POST /memory/compress\nnocturnusai -e \"cleanup 0.05\" # POST /memory/cleanup\n```\n\n---\n\n## Documentation\n\nFull docs: **[nocturnus.ai](https://nocturnus.ai)**\n\n| | |\n|---|---|\n| [Start Here](https://nocturnus.ai/docs) | The turn-reduction workflow |\n| [Context Workflow](https://nocturnus.ai/docs/context) | Raw turns → optimize → diff → clear |\n| [API Reference](https://nocturnus.ai/docs/api) | REST endpoints and response shapes |\n| [SDKs](https://nocturnus.ai/docs/sdks) | Python and TypeScript client methods |\n| [Integrations](https://nocturnus.ai/integrations) | LangChain, CrewAI, AutoGen, MCP, and more |\n| [Benchmark](https://nocturnus.ai/benchmark) | Measured token reduction on live APIs |\n| [Calculations](https://nocturnus.ai/calculations) | Every number, derived |\n| [How It Works](https://nocturnus.ai/how-it-works) | The extraction → inference → delta pipeline |\n\n---\n\n## Docker Compose (advanced)\n\n```bash\ngit clone https://github.com/Auctalis/nocturnusai.git && cd nocturnusai\n\nmake up # Server using .env.example defaults\nmake up-ollama # + Ollama (reuses host or starts bundled)\nmake up-monitoring # + Prometheus + Grafana\nmake smoke # Verify health + context endpoint\n```\n\n## Build from Source\n\nRequires JDK 17+.\n\n```bash\n./gradlew :nocturnusai-server:run # HTTP server on :9300\n./gradlew :nocturnusai-cli:run # Interactive REPL (JVM)\n./gradlew :nocturnusai-cli:nativeCompile # Build native binary\n./gradlew test # Full test suite\n```\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Issues labelled `good first issue` are good entry points.\n\n## Security\n\nReport vulnerabilities privately via [GitHub Security Advisories](https://github.com/Auctalis/nocturnusai/security/advisories/new). See [SECURITY.md](SECURITY.md).\n\n## License\n\n[Business Source License 1.1](LICENSE) (SPDX: `BUSL-1.1`). Free for internal use — including internal production — inside your own organization. Offering NocturnusAI or substantial functionality as a product/hosted service to third parties requires a commercial license ([licensing@nocturnus.ai](mailto:licensing@nocturnus.ai)). Converts to Apache 2.0 on 2030-02-19. See [LICENSE](LICENSE) and [DISCLAIMER.md](DISCLAIMER.md).\n\n---\n\n> **LEGAL & SAFETY NOTICE**\n>\n> NocturnusAI is a deterministic reasoning engine, but **its output is only as reliable as the facts provided to it.**\n>\n> 1. **No Warranty of Truth.** \"Verified\" refers to logical consistency of inference, not accuracy of real-world claims.\n> 2. **Not for Autonomous High-Stakes Decisions.** Do not use this engine for unsupervised medical, financial, legal, or physical-safety decisions without an independent human verification step.\n> 3. **Logic Layer Only.** NocturnusAI provides information and inference; it does not execute actions.\n> 4. **No Liability.** See [DISCLAIMER.md](DISCLAIMER.md) and [LICENSE](LICENSE).\n",
"bytes": 12660,
"sha": "3e8ead3136b228bc1e72792f7edd08e2d611bda8352601dd3bb0b9bfa6b30421",
"repo_slug": "auctalis/nocturnusai",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_ai_nocturnus_logic_server_3d269717/readme"
}