How It Works on the Backend

This page is the machinery behind the turn-reduction workflow. If your immediate problem is "my prompt is too big," read Real Workflow first and come back here later.

Backend Pipeline & Context Optimization

The backend path from raw turns to a smaller context window is roughly:

1. Turns arrive as raw text, tool output, or already-structured facts.
2. Structure is normalized so repeated or overlapping statements can be compared.
3. Relevant state is selected via salience scoring or goal-driven optimization.
4. Contradictions are detected before the final window is returned.
5. Session snapshots are stored so later turns can use /context/diff instead of sending everything again.

# Broad first pass
POST /context

# Goal-specific pass (unified endpoint — use goals parameter)
POST /memory/context

# Later turns
POST /context/diff

# End of thread
POST /context/session/clear

How The Backend Chooses What Stays

Nocturnus uses two related selection modes:

• Salience-ranked selection for the "what is broadly most important right now?" case.
• Goal-driven selection for the "what does the next model call need to answer this specific question?" case.

Salience combines recency, frequency, and explicit priority. Goal-driven selection goes further by tracing which stored state is actually relevant to the requested goal.

Memory Lifecycle

Long-running systems do not just need retrieval. They need old context to stop accumulating forever.

• POST /memory/context returns the current salience-ranked working set.
• POST /memory/consolidate compresses repeated episodic patterns into smaller summaries.
• POST /memory/decay removes expired or low-value context.

This is how a long-running agent avoids dragging months of stale context into every new prompt.

Contradictions and Trust

Reduction is only useful if the reduced window is trustworthy. The backend checks for conflicting state and can auto-resolve contradictions before the window is returned.

That matters because smaller context is not enough by itself. Smaller and wrong is still wrong.

Session Snapshots and Diffs

When you call /memory/context with a sessionId, the backend stores a snapshot of that window. Later, /context/diff compares the new window to the old one and returns only the additions and removals.

This is the operational mechanism behind "stop paying for the same context twice."

Scopes and Multi-Tenancy

Context reduction often needs partitioning.

• Database separates environments or large knowledge domains.
• Tenant separates customers or agents.
• Scope separates threads, documents, hypotheses, or other logical slices inside a tenant.

In practice, many teams map a conversation or document to a scope so the reducer only looks at the relevant slice.

Low-Level Backend Concepts

These are the lower-level building blocks. They matter when you want deeper control, debugging, or custom reasoning behavior.

Facts

A fact is a structured statement stored in the backend. Internally it is an Atom with a predicate name, ordered arguments, truth value, optional scope, time metadata, and optional confidence.

customer_tier(acme_corp, enterprise)
current_issue(acme_corp, saml_issuer_mismatch)
NOT billing_blocked(acme_corp)

Rules

Rules define derived relationships. They are useful when you want the backend to infer higher-level state instead of storing every conclusion directly.

service_credit_applicable(?account) :-
    outage_duration_hours(?account, ?hours),
    promised_credit_threshold(?account, 4),
    exceeds(?hours, 4)

Inference

The backend supports backward chaining for question-driven proof and forward chaining for reactive derivation. This is why /memory/context with goals can work from goals instead of only from surface frequency.

Temporal State

Facts can have createdAt, validFrom, validUntil, and ttl. That lets the backend reconstruct what was true at a given moment and drop expired state automatically.

Truth Maintenance

Derived facts keep provenance. If a supporting fact is removed, dependent conclusions can be retracted automatically. That is how the backend keeps the reduced context aligned with the underlying state.

What's Next?