Cortex

Cortex is an experimental memory-maintenance surface. In the current backend it is disabled by default unless NOVYX_ENABLE_EXPERIMENTAL=1 is set. Core marks it experimental because autonomous insights are template-based and consolidation/decay behavior is not covered by an end-to-end production test.

Base URL: https://novyx-ram-api.fly.dev

Availability: Experimental and off by default. Requires NOVYX_ENABLE_EXPERIMENTAL=1 before tier checks apply. Cortex features are Pro+ when enabled; insights require Enterprise.

Backend: Requires Postgres

Run Cortex Cycle

POST /v1/cortex/run

Trigger a manual Cortex cycle when the experimental router is enabled. The response reports consolidation, reinforcement, decay, and insight counters from the run.

Consolidation: Merges memories above the similarity threshold (default 90%)
Reinforcement: Boosts importance of frequently-recalled memories
Decay: Reduces importance of old, unused memories past the decay age
Insights: Returns template-based synthetic memory insights when enabled (Enterprise only)

Response fields

Field	Type	Description
`consolidated`	number	Duplicate memories merged
`boosted`	number	Memories with boosted importance
`decayed`	number	Memories with reduced importance
`insights_generated`	number	New insight memories created

Examples

Python
TypeScript
curl

from novyx import Novyx

nx = Novyx(api_key="nram_your_key")

result = nx.cortex_run()
print(f"Consolidated: {result['consolidated']}")
print(f"Boosted: {result['boosted']}")
print(f"Decayed: {result['decayed']}")
print(f"Insights: {result['insights_generated']}")

import { Novyx } from "novyx";

const nx = new Novyx({ apiKey: "nram_your_key" });

const result = await nx.cortexRun();
console.log(`Consolidated: ${result.consolidated}`);
console.log(`Boosted: ${result.boosted}`);
console.log(`Decayed: ${result.decayed}`);
console.log(`Insights: ${result.insights_generated}`);

curl -X POST https://novyx-ram-api.fly.dev/v1/cortex/run \
  -H "Authorization: Bearer nram_your_key"

Response

{
  "consolidated": 3,
  "boosted": 12,
  "decayed": 5,
  "insights_generated": 2
}

Errors

Status	Code	Cause
403	`novyx_ram.v1.experimental.disabled`	Cortex is disabled unless `NOVYX_ENABLE_EXPERIMENTAL=1`
403	`FEATURE_NOT_AVAILABLE`	Requires Pro+ plan
501	`REQUIRES_POSTGRES`	Postgres backend required

Get Cortex Status

GET /v1/cortex/status

Get Cortex status, including whether the tenant-level Cortex config is enabled, the last run timestamp, and run statistics. The endpoint itself is still blocked unless experimental features are enabled.

Response fields

Field	Type	Description
`enabled`	boolean	Whether Cortex is enabled
`last_run_at`	string \| null	Last run timestamp (ISO 8601)
`run_stats`	object	Operation counts from last run
`config`	object	Current Cortex configuration (see below)

Examples

Python
TypeScript
curl

status = nx.cortex_status()
print(f"Enabled: {status['enabled']}")
print(f"Last run: {status['last_run_at']}")

const status = await nx.cortexStatus();
console.log(`Enabled: ${status.enabled}`);
console.log(`Last run: ${status.last_run_at}`);

curl https://novyx-ram-api.fly.dev/v1/cortex/status \
  -H "Authorization: Bearer nram_your_key"

Response

{
  "enabled": true,
  "last_run_at": "2026-03-09T06:00:00Z",
  "run_stats": {
    "consolidated": 3,
    "boosted": 12,
    "decayed": 5,
    "insights_generated": 0
  },
  "config": {
    "tenant_id": "tenant_abc123",
    "enabled": true,
    "consolidation_enabled": true,
    "consolidation_threshold": 0.90,
    "reinforcement_enabled": true,
    "decay_enabled": true,
    "decay_age_days": 30,
    "insight_generation_enabled": false,
    "last_run_at": "2026-03-09T06:00:00Z",
    "run_stats": {}
  }
}

Errors

Status	Code	Cause
403	`novyx_ram.v1.experimental.disabled`	Cortex is disabled unless `NOVYX_ENABLE_EXPERIMENTAL=1`
403	`FEATURE_NOT_AVAILABLE`	Requires Pro+ plan
501	`REQUIRES_POSTGRES`	Postgres backend required

Get Cortex Config

GET /v1/cortex/config

Retrieve the current Cortex configuration when the experimental router is enabled.

Response fields

Field	Type	Description
`tenant_id`	string	Your tenant ID
`enabled`	boolean	Whether Cortex is enabled
`consolidation_enabled`	boolean	Merge duplicate memories
`consolidation_threshold`	number	Similarity threshold for merging (0.5–1.0)
`reinforcement_enabled`	boolean	Boost frequently-recalled memories
`decay_enabled`	boolean	Decay old, unused memories
`decay_age_days`	number	Days before decay kicks in (1–365)
`insight_generation_enabled`	boolean	Generate AI insights (Enterprise only)
`last_run_at`	string \| null	Last run timestamp
`run_stats`	object	Last run statistics

Examples

Python
TypeScript
curl

config = nx.cortex_config()
print(f"Consolidation threshold: {config['consolidation_threshold']}")
print(f"Decay after: {config['decay_age_days']} days")

const config = await nx.cortexConfig();
console.log(`Consolidation threshold: ${config.consolidation_threshold}`);
console.log(`Decay after: ${config.decay_age_days} days`);

curl https://novyx-ram-api.fly.dev/v1/cortex/config \
  -H "Authorization: Bearer nram_your_key"

Response

{
  "tenant_id": "tenant_abc123",
  "enabled": true,
  "consolidation_enabled": true,
  "consolidation_threshold": 0.90,
  "reinforcement_enabled": true,
  "decay_enabled": true,
  "decay_age_days": 30,
  "insight_generation_enabled": false,
  "last_run_at": "2026-03-09T06:00:00Z",
  "run_stats": {}
}

Errors

Status	Code	Cause
403	`novyx_ram.v1.experimental.disabled`	Cortex is disabled unless `NOVYX_ENABLE_EXPERIMENTAL=1`
403	`FEATURE_NOT_AVAILABLE`	Requires Pro+ plan
501	`REQUIRES_POSTGRES`	Postgres backend required

Update Cortex Config

PATCH /v1/cortex/config

Update Cortex configuration when the experimental router is enabled. Send only the fields you want to change.

Request body

Parameter	Type	Required	Default	Description
`enabled`	boolean	No	—	Enable or disable Cortex
`consolidation_enabled`	boolean	No	—	Enable/disable consolidation
`consolidation_threshold`	number	No	—	Similarity threshold (0.5–1.0)
`reinforcement_enabled`	boolean	No	—	Enable/disable reinforcement
`decay_enabled`	boolean	No	—	Enable/disable decay
`decay_age_days`	number	No	—	Days before decay (1–365)
`insight_generation_enabled`	boolean	No	—	Enable insights (Enterprise only)

Examples

Python
TypeScript
curl

# Lower the consolidation threshold
updated = nx.update_cortex_config(
    consolidation_threshold=0.85,
    decay_age_days=14,
)

# Disable decay
updated = nx.update_cortex_config(decay_enabled=False)

// Lower the consolidation threshold
const updated = await nx.updateCortexConfig({
  consolidationThreshold: 0.85,
  decayAgeDays: 14,
});

// Disable decay
const updated2 = await nx.updateCortexConfig({ decayEnabled: false });

curl -X PATCH https://novyx-ram-api.fly.dev/v1/cortex/config \
  -H "Authorization: Bearer nram_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "consolidation_threshold": 0.85,
    "decay_age_days": 14
  }'

Errors

Status	Code	Cause
403	`novyx_ram.v1.experimental.disabled`	Cortex is disabled unless `NOVYX_ENABLE_EXPERIMENTAL=1`
403	`FEATURE_NOT_AVAILABLE`	Requires Pro+ plan or Enterprise for insights
501	`REQUIRES_POSTGRES`	Postgres backend required

List Insights

GET /v1/cortex/insights

List synthetic insight memories created by Cortex when the experimental router is enabled. Treat these as memory-maintenance hints, not autonomous production recommendations.

Enterprise only

Insight generation requires Enterprise after experimental features are enabled. Enable the tenant config via PATCH /v1/cortex/config.

Query parameters

Parameter	Type	Required	Default	Description
`limit`	number	No	`20`	Max results (1–100)
`offset`	number	No	`0`	Pagination offset

Response fields

Field	Type	Description
`insights`	array	Array of insight memory objects
`total`	number	Total insight count

Each insight includes:

Field	Type	Description
`uuid`	string	Insight memory identifier
`observation`	string	Generated insight text
`tags`	string[]	Auto-generated tags
`importance`	number	Assigned importance score
`created_at`	string	Generation timestamp

Examples

Python
TypeScript
curl

insights = nx.cortex_insights(limit=10)
for insight in insights["insights"]:
    print(f"[{insight['importance']}] {insight['observation']}")

const insights = await nx.cortexInsights({ limit: 10 });
for (const insight of insights.insights) {
  console.log(`[${insight.importance}] ${insight.observation}`);
}

curl "https://novyx-ram-api.fly.dev/v1/cortex/insights?limit=10" \
  -H "Authorization: Bearer nram_your_key"

Response

{
  "insights": [
    {
      "uuid": "urn:uuid:i1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "observation": "User consistently prefers dark themes across all applications and adjusts font sizes for readability",
      "tags": ["insight", "preferences", "ui"],
      "importance": 7,
      "created_at": "2026-03-09T06:00:00Z"
    }
  ],
  "total": 5
}

Errors

Status	Code	Cause
403	`novyx_ram.v1.experimental.disabled`	Cortex is disabled unless `NOVYX_ENABLE_EXPERIMENTAL=1`
403	`FEATURE_NOT_AVAILABLE`	Requires Enterprise plan
501	`REQUIRES_POSTGRES`	Postgres backend required

Run Cortex Cycle​

Response fields​

Examples​

Response​

Errors​

Get Cortex Status​

Response fields​

Examples​

Response​

Errors​

Get Cortex Config​

Response fields​

Examples​

Response​

Errors​

Update Cortex Config​

Request body​

Examples​

Errors​

List Insights​

Query parameters​

Response fields​

Examples​

Response​

Errors​

Run Cortex Cycle

Response fields

Examples

Response

Errors

Get Cortex Status

Response fields

Examples

Response

Errors

Get Cortex Config

Response fields

Examples

Response

Errors

Update Cortex Config

Request body

Examples

Errors

List Insights

Query parameters

Response fields

Examples

Response

Errors