Skip to main content
Glama

NocturnusAI

CI PyPI npm Docker License: BUSL-1.1 MCP

AIエージェントのためのコンテキストエンジニアリングエンジン:変更点のみを送信します。

NocturnusAI — AIエージェントのためのコンテキストエンジニアリングエンジン


Before / After

# ❌ 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.

Related MCP server: RelayPlane

数値データ

ライブAPIで測定。15ターンの製品サポート会話。実際の usage.input_tokens カウント。ご自身で実行してください。

単純なリプレイ

RAG最適化

NocturnusAI

ターンあたりのトークン数

~1,259

~800

~221

月額コスト (1K req/hr, Opus 4, $15/1M)

$13,600

$12,000

$2,400

レイテンシ

高

中

低

真実性の保持

いいえ

いいえ

はい

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

開発者がこのリポジトリにスターを付ける理由

  • 再現可能なトークン削減 — リポジトリ内のベンチマーク、公開された手法、自身のワークロードで実行可能

  • 決定論的な推論 — 同じクエリなら、毎回同じ結果。埋め込みのドリフトやコサイン類似度の運任せはありません

  • 真実性の維持 — 事実を撤回すれば、派生したすべての結論も自動的に撤回されます。古いコンテキストや運用状態に関するハルシネーションはありません

  • 既存スタックへのプラグイン — LangChain, LlamaIndex, CrewAI, AutoGen, MCP, Vercel AI SDK, OpenAI Agents SDK, Mastra

  • 単純なリプレイに対するベンチマーク可能 — 数値は導出されたものであり、捏造ではありません。すべての主張はノートブックのセルにトレース可能です


フレームワークのクイックスタート

フレームワーク

統合

リンク

LangChain / LangGraph

ドロップイン NocturnusContextProvider, LangSmithトレースパススルー

ドキュメント

CrewAI

エージェントロールごとのタスクスコープコンテキスト

ドキュメント

AutoGen

どのエージェントからも呼び出し可能なコンテキストサーバー

ドキュメント

MCP

Claude Desktop, Cursor, Continue向けの仕様準拠サーバー

設定

OpenAI Agents SDK

コンテキストミドルウェア、ツール変更不要

ドキュメント

Vercel AI SDK

Next.js, Nuxt, SvelteKit向けのEdge互換アダプター

ドキュメント

Python SDK

pip install nocturnusai

ドキュメント

TypeScript SDK

npm install nocturnusai-sdk

ドキュメント


仕組み

3つのステップ。毎ターン実行されます。

  1. 抽出 — 生の会話ターン → LLM抽出による構造化された事実

  2. 推論 — 後方連鎖論理推論により、エージェントの現在の目標から到達可能な事実のみを特定

  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}'

スナップショット間の added(追加)および removed(削除)されたエントリのみを返します。

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

毎ターン context ツールを使用して、重要度順にランク付けされたワーキングセットを取得します。目標主導型のアセンブリや差分が必要な場合は、MCPとHTTPコンテキストエンドポイントを組み合わせてください。


ワークフローの裏側

バックエンドのメカニズムが必要な場合、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

ここから開始

ターン削減ワークフロー

コンテキストワークフロー

生ターン → 最適化 → 差分 → クリア

APIリファレンス

RESTエンドポイントとレスポンス形状

SDK

PythonおよびTypeScriptクライアントメソッド

統合

LangChain, CrewAI, AutoGen, MCPなど

ベンチマーク

ライブAPIでの測定されたトークン削減量

計算式

すべての数値の導出

仕組み

抽出 → 推論 → デルタのパイプライン


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 Advisories を通じて非公開で行ってください。SECURITY.md を参照してください。

ライセンス

Business Source License 1.1 (SPDX: BUSL-1.1)。組織内での内部使用(内部本番環境を含む)は無料です。NocturnusAIまたはその実質的な機能をサードパーティ向けの製品/ホスト型サービスとして提供する場合は、商用ライセンスが必要です (licensing@nocturnus.ai)。2030年2月19日にApache 2.0に変換されます。LICENSE および DISCLAIMER.md を参照してください。


法的および安全に関する通知

NocturnusAIは決定論的な推論エンジンですが、その出力は提供された事実の信頼性に依存します。

  1. 真実性の保証なし。 「検証済み」とは推論の論理的一貫性を指すものであり、現実世界の主張の正確性を保証するものではありません。

  2. 自律的な重大な決定には不向き。 独立した人間の検証ステップなしに、医療、金融、法律、または物理的な安全に関する自律的な決定にこのエンジンを使用しないでください。

  3. ロジックレイヤーのみ。 NocturnusAIは情報と推論を提供するものであり、アクションを実行するものではありません。

  4. 免責事項。 DISCLAIMER.md および LICENSE を参照してください。

Available Tools

16 tools
aggregateA

Compute aggregations over matching facts. Supports COUNT, SUM, MIN, MAX, and AVG over a numeric argument at a specified position. Example: COUNT all score(player, ?) facts, or AVG scores at argIndex=1. Side effects: none (read-only). Auth: requires X-Tenant-ID header; FACT_READ permission when auth is enabled. Rate-limited per principal. Errors: VALIDATION_ERROR on unknown operation or missing argIndex for numeric ops.

Inputs: predicate (required), args (required), operation (required), argIndex, +1 more.

askA

Query the knowledge base using multi-step logical reasoning (backward chaining with unification). Finds all provable answers by applying rules and matching facts. Use ?-prefixed variables for unknowns; optionally returns full proof chains. Side effects: none (read-only). Auth: requires X-Tenant-ID header; FACT_READ permission when auth is enabled. Rate-limited per principal. Errors: VALIDATION_ERROR on bad args; result set bounded by INFERENCE_MAX_RESULTS (default 10,000) to prevent OOM.

Inputs: predicate (required), args (required), scope, withProof, +1 more.

bulk_assertA

Assert multiple facts in a single call for efficiency. Non-transactional: each fact is attempted independently — contradictions are reported without aborting the batch. Returns counts of successful and failed assertions. Side effects: mutates state (additive) — partial successes persist even if other facts in the batch fail. Auth: requires X-Tenant-ID header; FACT_WRITE permission when auth is enabled. Rate-limited per principal. Errors: VALIDATION_ERROR on malformed input; per-fact failures returned in the response's errors array.

Inputs: facts (required).

cleanupA

Run memory decay and eviction. Expires facts past their TTL and evicts low-salience facts when memory exceeds capacity. Call periodically in long-running agent sessions to prevent unbounded growth. Side effects: DESTRUCTIVE — permanently removes evicted and expired facts (irreversible). Auth: requires X-Tenant-ID header; FACT_WRITE permission when auth is enabled. Rate-limited per principal. Errors: VALIDATION_ERROR on bad threshold.

Inputs: threshold.

compressA

Run memory consolidation: detects repeated episodic patterns (e.g., 'user asked about X five times') and creates semantic summaries. Reduces memory footprint in long-running sessions while preserving essential knowledge. Side effects: mutates state (additive) — creates new summary facts; original facts remain intact. Auth: requires X-Tenant-ID header; FACT_WRITE permission when auth is enabled. Rate-limited per principal. Errors: VALIDATION_ERROR on bad args.

Inputs: no named parameters.

contextA

Get the most relevant knowledge for the current reasoning step, ranked by composite salience (recency × frequency × priority). Returns a token-optimized context window in 'predicate', 'natural', or 'structured' format. Pass goals for goal-driven selection, sessionId for incremental diffs across turns. Side effects: read-only for stored facts (salience access counters may update internally). Auth: requires X-Tenant-ID header; FACT_READ permission when auth is enabled. Rate-limited per principal. Errors: VALIDATION_ERROR on bad args.

Inputs: maxFacts, minSalience, predicates, scope, +6 more.

delete_scopeA

Delete a named scope and all facts within it. Use to clean up completed or abandoned hypothetical reasoning branches. Side effects: DESTRUCTIVE and IRREVERSIBLE — permanently removes all facts in the scope; cascades TMS retraction for any derived facts. Auth: requires X-Tenant-ID header; FACT_WRITE permission when auth is enabled. Rate-limited per principal. Errors: VALIDATION_ERROR if scope name is blank.

Inputs: scope (required).

forgetA

Retract a fact from the knowledge base. Inverse of 'tell'. Side effects: DESTRUCTIVE — triggers cascading retraction of any knowledge derived from this fact via the Truth Maintenance System (irreversible). Auth: requires X-Tenant-ID header; FACT_WRITE permission when auth is enabled. Rate-limited per principal. Errors: VALIDATION_ERROR on bad args (no error if the fact was not present).

Inputs: predicate (required), args (required), scope.

fork_scopeA

Fork a knowledge base scope — creates an independent copy of all facts in the source scope under a new target scope name. Use for hypothetical reasoning ('What if Alice moves to London?') without modifying the main knowledge base. Similar to git branch for knowledge. Side effects: mutates state (additive) — creates a new scope with copied facts; source scope is unchanged. Auth: requires X-Tenant-ID header; FACT_WRITE permission when auth is enabled. Rate-limited per principal. Errors: VALIDATION_ERROR if targetScope is blank or already exists.

Inputs: targetScope (required), sourceScope.

list_scopesA

List all named scopes in the knowledge base. Shows what hypothetical contexts or reasoning branches exist. The global (unscoped) partition is always present but not listed. Side effects: none (read-only). Auth: requires X-Tenant-ID header; FACT_READ permission when auth is enabled. Rate-limited per principal. Errors: none under normal operation.

Inputs: no named parameters.

merge_scopeA

Merge facts from one scope into another (default: global). Use to commit hypothetical reasoning back into the main knowledge base. Strategy controls conflict handling: SOURCE_WINS overwrites, TARGET_WINS keeps existing, KEEP_BOTH retains both, REJECT aborts on conflict. Side effects: mutates the target scope; may overwrite existing facts depending on strategy (potentially destructive under SOURCE_WINS). Auth: requires X-Tenant-ID header; FACT_WRITE permission when auth is enabled. Rate-limited per principal. Errors: VALIDATION_ERROR on unknown strategy; CONFLICT_ERROR when strategy=REJECT and conflicts are found.

Inputs: sourceScope (required), targetScope, strategy.

predicatesA

Discover the knowledge base schema. Lists all predicates currently stored with arity (argument count), fact count, and whether they have associated rules. Use this before querying to understand what knowledge is available. Side effects: none (read-only). Auth: requires X-Tenant-ID header; FACT_READ permission when auth is enabled. Rate-limited per principal. Errors: none under normal operation.

Inputs: scope.

recallA

Time-travel query: recall what was known at a specific point in time. Returns facts valid at the given timestamp, respecting temporal bounds (validFrom, validUntil, ttl). Useful for debugging agent behavior or reconstructing past state. Side effects: none (read-only). Auth: requires X-Tenant-ID header; FACT_READ permission when auth is enabled. Rate-limited per principal. Errors: VALIDATION_ERROR on bad args or missing timestamp.

Inputs: predicate (required), args (required), timestamp (required), scope.

retract_patternA

Retract all facts matching a pattern in a single call. Use ?-prefixed variables as wildcards to retract multiple facts at once. Returns the count and list of retracted facts. Side effects: DESTRUCTIVE — removes multiple facts and cascades TMS retraction for each removed fact (irreversible). Auth: requires X-Tenant-ID header; FACT_WRITE permission when auth is enabled. Rate-limited per principal. Errors: VALIDATION_ERROR on bad args.

Inputs: predicate (required), args (required), scope.

teachA

Define a logical rule for automatic reasoning. When body conditions hold, head becomes derivable via backward chaining. Use ?-prefixed variables; supports Negation-as-Failure. Example: 'If ?x is human AND NOT god(?x), THEN ?x is mortal'. Side effects: mutates state (additive) — rules remain active until explicitly removed. Auth: requires X-Tenant-ID header; RULE_WRITE permission when auth is enabled. Rate-limited per principal. Errors: VALIDATION_ERROR on malformed rules.

Inputs: head (required), body (required), scope.

tellA

Assert a fact into the knowledge base. Stores knowledge queryable via logical reasoning. Supports TTL expiration, confidence scoring, and configurable conflict resolution. Side effects: mutates state (additive) — stored facts persist until retracted or expired. Auth: requires X-Tenant-ID header for tenant isolation; FACT_WRITE permission when auth is enabled. Rate-limited per principal. Errors: VALIDATION_ERROR on bad args, CONFLICT_ERROR on contradictions when conflictStrategy=REJECT.

Inputs: predicate (required), args (required), scope, negated, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 16 tools

    Disambiguation5/5

    Each tool targets a distinct operation: tell/forget/retract_pattern for facts, teach for rules, ask/aggregate/context/recall for queries, scope management tools, and memory maintenance tools. No two tools have overlapping purposes; clear boundaries between them.

    Naming Consistency3/5

    Naming is mixed: some tools use verb_noun (bulk_assert, delete_scope), others are single verbs (ask, forget), and one is a noun (context). While each name is individually clear, the lack of a consistent pattern reduces predictability.

    Tool Count4/5

    16 tools is slightly above the typical range but justified by the complexity of the knowledge base domain (fact management, rules, queries, scopes, memory). Each tool serves a clear purpose.

    Completeness4/5

    The surface covers core CRUD for facts, queries, scopes, schema discovery, and memory management. A minor gap is the absence of a tool to list or remove defined rules, but the overall coverage is strong.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An implementation of persistent memory for Claude using a local knowledge graph, allowing the AI to remember information about users across conversations with customizable storage location.
      11
      62
      JavaScript
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables efficient AI workflow orchestration by chaining multi-step LLM operations while keeping intermediate results out of the context window, reducing token usage by 90%+ and supporting multiple AI providers.
      7
      41 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A production-ready reasoning engine that integrates Claude AI with specialized MCP tools for knowledge retrieval, schema validation, and domain-specific rubric evaluation. It enables structured RAG-based analysis across legal, health, and science domains via a RESTful API.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Provides versioned, structured memory for AI agents, allowing them to store facts, detect conflicts, and track knowledge history via a hosted SaaS platform. It enables efficient hierarchical information retrieval and semantic search while keeping token usage constant as memory scales.
      7
      20 npm
      8
      Apache 2.0