Quickstart

Start the Server

One command. Installs Docker Compose stack, waits for healthy, and installs the native CLI binary:

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

# With an API key for LLM features (enables /extract and /synthesize in Steps 2–3):
$ curl -fsSL https://raw.githubusercontent.com/Auctalis/nocturnusai/main/install.sh | bash -s -- --key sk-ant-...

# With local Ollama (free, no API key needed — install Ollama first):
$ curl -fsSL https://raw.githubusercontent.com/Auctalis/nocturnusai/main/install.sh | bash -s -- --host-ollama

Verify it's running:

$ curl http://localhost:9300/health

{ "status": "healthy" }

Feed It Text, Ask It Questions

The fastest way to get started. Set an LLM API key — ANTHROPIC_API_KEY, OPENAI_API_KEY, or GOOGLE_API_KEY — and NocturnusAI handles fact extraction and Q&A automatically.

Extract facts from plain text:

$ curl -X POST http://localhost:9300/extract \
    -H "Content-Type: application/json" \
    -d '{
    "text": "Acme Corp is on the enterprise plan and is based in Austin. They get 24/7 SLA support.",
    "assert": true
  }'

{
  "facts": [
    { "predicate": "customer_tier", "args": ["acme_corp", "enterprise"] },
    { "predicate": "location", "args": ["acme_corp", "austin"] },
    { "predicate": "sla_tier", "args": ["acme_corp", "24_7"] }
  ],
  "asserted": true
}

Ask a natural language question — get a sourced answer:

$ curl -X POST http://localhost:9300/synthesize \
    -H "Content-Type: application/json" \
    -d '{"question": "What support level does Acme Corp get?"}'

{
  "answer": "Acme Corp gets 24/7 SLA support on their enterprise plan.",
  "derivation": [
    { "fact": "sla_tier(acme_corp, 24_7)" },
    { "fact": "customer_tier(acme_corp, enterprise)" }
  ],
  "confidence": 0.97
}

POST /context
{ "turns": ["Acme is on enterprise plan", "They have 24/7 SLA"] }

→ { "facts": [
    {"predicate":"customer_tier", "args":["acme","enterprise"], "salience":0.95},
    {"predicate":"sla_tier", "args":["acme","24_7"], "salience":0.90}
  ],
  "factsReturned": 2, "contradictions": 0
}

Connect Any Agent in 30 Seconds

NocturnusAI is an MCP server. Any MCP-compatible agent, IDE, or framework connects with a two-line config — no SDK, no API wrapper, no code changes required.

Cursor / Windsurf (.cursor/mcp.json):

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

Claude Desktop (claude_desktop_config.json):

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

Your agent immediately gets 9 tools: tell, ask, teach, forget, recall, context, compress, cleanup, predicates.

Structured Facts & Queries

Use the structured API directly — no LLM key required. Facts are stored as typed predicates, giving you deterministic pipelines without any LLM in the extraction path. These are the same endpoints the MCP tools call internally.

Store a structured fact:

$ curl -X POST http://localhost:9300/tell \
    -H "Content-Type: application/json" \
    -d '{"predicate": "customer_tier", "args": ["acme_corp", "enterprise"]}'

{ "status": "ok", "atom": "customer_tier(acme_corp, enterprise)" }

Query with a variable (the ? prefix marks unknowns):

$ curl -X POST http://localhost:9300/ask \
    -H "Content-Type: application/json" \
    -d '{"predicate": "customer_tier", "args": ["acme_corp", "?tier"]}'

{ "results": ["customer_tier(acme_corp, enterprise)"] }

LangChain Agent with Verified Knowledge

Install the Python SDK with LangChain integration:

$ pip install nocturnusai[langchain] langchain-anthropic

A complete working agent in 20 lines:

from nocturnusai import SyncNocturnusAIClient
from nocturnusai.langchain import get_nocturnusai_tools
from langchain_anthropic import ChatAnthropic
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_core.prompts import ChatPromptTemplate

# Connect to Nocturnus — get 4 LangChain tools backed by the reasoning engine
client = SyncNocturnusAIClient("http://localhost:9300")
tools = get_nocturnusai_tools(client)
# → assert, query, infer, context

llm = ChatAnthropic(model="claude-sonnet-4-6")
prompt = ChatPromptTemplate.from_messages([
    ("system", "Use your tools to store and retrieve verified facts. Never guess."),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
])
agent = create_tool_calling_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools)

result = executor.invoke({
    "input": "Remember: Acme Corp is on the enterprise plan. Now — what plan are they on?"
})
print(result["output"])

# Agent gets optimized facts from /context — 200 tokens, not 150K.
# Correct. Sourced. 750x cheaper than context stuffing.
Acme Corp is on the enterprise plan. (verified from knowledge base)