logic-server

NocturnusAI

AI Agent 的上下文工程引擎：只发送发生变化的内容。

前后对比

# ❌ Without NocturnusAI — replay everything, every turn
messages = system_prompt + full_history + tool_outputs   # ~1,259 tokens/turn
response = llm(messages)                                 # $13,600/mo at scale

# ✅ With NocturnusAI — send only what changed
ctx = nocturnus.process_turns(raw_turns)                 # extract → infer → delta
messages = system_prompt + ctx.briefing_delta             # ~221 tokens/turn
response = llm(messages)                                 # $2,400/mo. Same accuracy.

数据表现

在实际 API 上测得。15 轮产品支持对话。真实的 usage.input_tokens 计数。亲自运行。

Claude Opus 4：减少 5.7×。Gemini 2.0 Flash：减少 10.0×。完整计算过程。

安装

pip install nocturnusai          # Python
npm install nocturnusai-sdk      # TypeScript
docker run -p 9300:9300 ghcr.io/auctalis/nocturnusai:latest  # Docker

或者使用设置向导：

curl -fsSL https://raw.githubusercontent.com/Auctalis/nocturnusai/main/install.sh | bash

开发者为何给此仓库点星

• 可复现的 Token 减少效果 — 仓库中提供基准测试，已公开方法，可使用你自己的工作负载运行测试
• 确定性推理 — 相同查询，每次得到相同结果。没有嵌入漂移，也不靠余弦相似度碰运气
• 事实维护 — 撤回一项事实，所有派生结论都会自动撤回。没有过时上下文，不会对运行状态产生幻觉
• 可接入现有技术栈 — LangChain、LlamaIndex、CrewAI、AutoGen、MCP、Vercel AI SDK、OpenAI Agents SDK、Mastra
• 可与朴素重放进行基准对比 — 数据经过推导，而非捏造。每一项声明都能追溯到 Notebook 单元格

框架快速入门

工作原理

每轮都分为三个步骤。

1. 提取 — 将原始对话轮次通过 LLM 提取为结构化事实
2. 推断 — 通过反向链推理，只查找从 Agent 当前目标可达的事实
3. 返回增量 — 返回仅包含自上一轮以来变化内容的 briefingDelta

这不是向量搜索，也不是摘要，而是在逻辑引擎上进行确定性推理 — 使用 Hexastore 索引、反向链推理 和 真值维护。

工作循环

自然语言轮次需要 LLM。 以下示例会将原始文本轮次发送给 LLM，以提取结构化事实。如果启动服务时未配置 LLM 提供商，自然语言轮次将返回零条事实。设置选项请参阅快速入门，也可以使用无需 LLM 即可运行的谓词语法（例如，"customer_tier(acme_corp, enterprise)"）。

1. 首次精简：POST /context

curl -X POST http://localhost:9300/context \
  -H 'Content-Type: application/json' \
  -H 'X-Tenant-ID: default' \
  -d '{
    "turns": [
      "user: Customer says they are enterprise and blocked on SLA credits.",
      "tool: CRM says account is Acme Corp with a 2M ARR contract.",
      "agent: Last week support promised to review SLA eligibility.",
      "tool: Billing note says renewal is due next month."
    ],
    "maxFacts": 12
  }'

2. 目标驱动处理：POST /memory/context

curl -X POST http://localhost:9300/memory/context \
  -H 'Content-Type: application/json' \
  -H 'X-Tenant-ID: default' \
  -d '{
    "goals": [{"predicate":"eligible_for_sla","args":["acme_corp"]}],
    "maxFacts": 12,
    "sessionId": "ticket-42"
  }'

3. 后续轮次：POST /context/diff

curl -X POST http://localhost:9300/context/diff \
  -H 'Content-Type: application/json' \
  -H 'X-Tenant-ID: default' \
  -d '{"sessionId": "ticket-42", "maxFacts": 12}'

仅返回快照之间新增和移除的条目。

4. 线程结束时：POST /context/session/clear

curl -X POST http://localhost:9300/context/session/clear \
  -H 'Content-Type: application/json' \
  -H 'X-Tenant-ID: default' \
  -d '{"sessionId":"ticket-42"}'

选择使用方式

from nocturnusai import SyncNocturnusAIClient

with SyncNocturnusAIClient("http://localhost:9300") as client:
    ctx = client.process_turns(
        turns=[
            "user: Customer says they are enterprise and blocked on SLA credits.",
            "tool: CRM says account is Acme Corp with a 2M ARR contract.",
        ],
        scope="ticket-42",
        session_id="ticket-42",
    )

    diff = client.diff_context(session_id="ticket-42", max_facts=12)
    client.clear_context_session("ticket-42")

    print(ctx.briefing_delta)

import { NocturnusAIClient } from 'nocturnusai-sdk';

const client = new NocturnusAIClient({
  baseUrl: 'http://localhost:9300',
  tenantId: 'default',
});

const ctx = await client.processTurns({
  turns: [
    'user: Customer says they are enterprise and blocked on SLA credits.',
    'tool: CRM says account is Acme Corp with a 2M ARR contract.',
  ],
  scope: 'ticket-42',
  sessionId: 'ticket-42',
});

const diff = await client.diffContext({ sessionId: 'ticket-42', maxFacts: 12 });
await client.clearContextSession('ticket-42');
console.log(ctx.briefingDelta);

{
  "mcpServers": {
    "nocturnus": {
      "url": "http://localhost:9300/mcp/sse",
      "transport": "sse"
    }
  }
}

工作流背后的功能

需要了解后端机制时，NocturnusAI 可提供以下功能：

• 确定性事实和规则存储
• 支持证明链的反向链推理
• 真值维护与矛盾处理
• 带有 ttl、validFrom 和 validUntil 的时间事实
• 通过 X-Database 和 X-Tenant-ID 实现多租户
• 基于同一引擎提供 MCP、REST、Python SDK、TypeScript SDK 和 CLI 接口

快速入门

Docker（最快）

docker run -d --name nocturnusai -p 9300:9300 \
  --restart unless-stopped \
  -v nocturnusai-data:/data \
  ghcr.io/auctalis/nocturnusai:latest

curl http://localhost:9300/health   # Verify it's running

使用 Ollama 的 Docker（启用自然语言提取）

docker run -d --name nocturnusai -p 9300:9300 \
  --add-host=host.docker.internal:host-gateway \
  -e LLM_PROVIDER=ollama \
  -e LLM_MODEL=granite3.3:8b \
  -e LLM_BASE_URL=http://host.docker.internal:11434/v1 \
  -e EXTRACTION_ENABLED=true \
  ghcr.io/auctalis/nocturnusai:latest

从此代码仓库启动

make up-ollama && make smoke

CLI

nocturnusai                                # Interactive REPL
nocturnusai -e "context 10"               # Salience-ranked working set
nocturnusai -e "compress"                 # POST /memory/compress
nocturnusai -e "cleanup 0.05"             # POST /memory/cleanup

文档

完整文档：nocturnus.ai

Docker Compose（高级）

git clone https://github.com/Auctalis/nocturnusai.git && cd nocturnusai

make up                                        # Server using .env.example defaults
make up-ollama                                 # + Ollama (reuses host or starts bundled)
make up-monitoring                             # + Prometheus + Grafana
make smoke                                     # Verify health + context endpoint

从源代码构建

需要 JDK 17+。

./gradlew :nocturnusai-server:run              # HTTP server on :9300
./gradlew :nocturnusai-cli:run                 # Interactive REPL (JVM)
./gradlew :nocturnusai-cli:nativeCompile       # Build native binary
./gradlew test                                 # Full test suite

参与贡献

请参阅 CONTRIBUTING.md。标记为 good first issue 的问题适合作为入门任务。

安全

请通过 GitHub 安全公告私下报告漏洞。请参阅 SECURITY.md。

许可证

Business Source License 1.1（SPDX：BUSL-1.1）。可在贵组织内部免费使用，包括内部生产环境。若要将 NocturnusAI 或其大部分功能作为产品／托管服务提供给第三方，则需要商业许可证（[email protected]）。该许可证将于 2030-02-19 转为 Apache 2.0。请参阅 LICENSE 和 DISCLAIMER.md。

法律与安全声明

NocturnusAI 是一个确定性推理引擎，但其输出的可靠性仅取决于提供给它的事实。

1. 不保证内容属实。“已验证”指推理在逻辑上保持一致，并不代表现实世界主张准确无误。
2. **不得用于自主处理高风险决策。**未经独立的人工核验，不得将此引擎用于无人监督的医疗、金融、法律或人身安全决策。
3. **仅提供逻辑层。**NocturnusAI 提供信息和推理，不会执行操作。
4. **不承担责任。**请参阅 DISCLAIMER.md 和 LICENSE。