Nuvlore

Nuvlore is a memory-native agent framework. The framework owns execution, memory stores own knowledge, and extensions own tools.

For the production learning architecture, Nuvlore is the deterministic LangGraph execution and workflow control plane; Memvanta is the long-term memory and learning plane. They remain separate products connected through LangGraph BaseStore and versioned Learning APIs—neither imports the other's runtime internals.

Architecture Boundary

| Layer | Owns | Does not own | | --- | --- | --- | | Framework core | Runtime execution, active workflow versions, extension loading, policy enforcement, replay/canary/promotion, trace events | Domain knowledge, company environments, learned procedures | | Memory store | Environment facts, domain knowledge, procedure candidates, workflow patch proposals | Active workflow mutation, trust/policy changes, direct tool execution | | Extension | Tool implementations, tool metadata, system API adapters | Workflow decisions, long-lived operational knowledge |

First Runtime Slice

This repository starts with a small executable slice:

• MemoryStore contract and in-memory implementation.
• JsonFileStore as a simple local adapter example.
• BootstrapRuntime that reads a bootstrap plan from memory.
• ExtensionManager that validates and registers extension tools.
• PolicyEngine that enforces memory-defined rules against extension metadata.
• ToolRuntime that invokes tools only after framework policy enforcement.
• WorkflowRegistry plus guarded immutable workflow evolution owned by Nuvlore.
• InvestigationFlow, ExecutionFlow, and MonitoringFlow as built-in flow primitives.
• TraceRecorder for audit events around bootstrap, policy decisions, and tool calls.

Nuvlore + Memvanta learning loop

GraphStateRuntime resolves node-scoped memory into checkpoint-stable MemorySnapshots. Handlers can only attribute a MemoryUse to an item in that snapshot. Every completed run produces ordered RunEvents and a deterministic OutcomeReport, then enters PostgresLearningOutbox; remote learning delivery is asynchronous and cannot turn a successful workflow into a failed one.

Configure provider: memvanta to use the remote BaseStore. Memvanta enriches recall with observed utility. Nuvlore filters provisional, expired, or repeatedly harmful procedures and uses verified utility to rerank the remaining results.

Workflow changes use a separate guarded path. WorkflowPatchCandidates are declarative JSON Patch documents bound to an immutable base version. Nuvlore requires graph validation, operation registry resolution, policy validation, historical replay, non-regressing canary evidence, and explicit approval before an atomic promotion. Rollback is also versioned and approval-gated. Memvanta may propose patches and receive dispositions, but cannot activate a workflow.

The former Nuvlore-local model extraction implementation is migration-only and is excluded from the published package. New extraction and consolidation run in Memvanta's durable LangMem pipeline.

Bootstrap Shape

The following bootstrap shape remains supported as a migration input. New production deployments keep active workflow versions in Nuvlore's control plane and use memory only for knowledge and proposals:

{
  organization: "acme",
  requiredExtensions: [
    {
      id: "airflow",
      source: "github:acme/extensions",
      tools: [
        { id: "readTaskLog", actionType: "read", handler: async () => ({ ok: true }) }
      ]
    }
  ],
  workflowProfiles: [
    {
      id: "airflow-investigation",
      flow: "investigation",
      knowledgeNamespaces: ["acme.semantic.airflow"],
      probes: [{ id: "log", tool: "airflow.readTaskLog" }]
    }
  ],
  policies: {
    global: { defaultMode: "read_only" }
  }
}

Framework validates this plan, registers extensions and workflow profiles, then enforces policy before every tool invocation.

Extension source trust is checked before any module import or handler execution. trust: "official" from memory or a loaded manifest is ignored as trust proof; trusted status must come from framework configuration, trustedExtensionSources, or a future signed registry. Source-less inline extensions are rejected by default and are only accepted when allowLocalExtensions: true is set for explicit local test fixtures.

An extension can also be supplied as a module:

{
  id: "airflow",
  module: "file:///path/to/airflow-extension.mjs",
  source: "github:acme/extensions"
}

The module must export default or manifest with the same tool manifest shape.

Minimal Usage

import { InMemoryStore, NuvloreRuntime } from "nuvlore";

const memoryStore = new InMemoryStore({
  bootstrap: { plan: {
    organization: "acme",
    requiredExtensions: [],
    workflowProfiles: [],
    policies: {}
  } }
});

const runtime = new NuvloreRuntime({ memoryStore });
await runtime.bootstrap();

Development

npm test
npm run test:unit
npm run test:integration

Management console

The Nuvlore console is the deterministic execution control plane. It shares Memvanta's visual language while keeping workflow execution, runs, releases, and learning delivery separate from Memvanta's memory UI.

Start the existing Memvanta Compose services and the host Metal model, then:

export NUVLORE_DATABASE_URL=postgresql://postgres:[email protected]:55432/memvanta
export NUVLORE_MEMVANTA_URL=http://127.0.0.1:8100
export NUVLORE_MEMVANTA_SPACE_ID=local
export NUVLORE_LLM_BASE_URL=http://127.0.0.1:18080
export NUVLORE_EMBEDDING_BASE_URL=http://127.0.0.1:18081
npm run console:seed
npm run console:dev

Open http://127.0.0.1:8200/. The console uses only production PostgreSQL and service projections; it has no fixture/preview mode. console:seed is an explicit idempotent import of bundled, validated workflow definitions.

Loopback mode uses the local Memvanta principal. Network binding requires both --allow-network and NUVLORE_API_BEARER_TOKEN with at least 32 characters; health endpoints remain public and every operational route requires the token. Put TLS and ordinary edge rate limits in front of a network deployment.