Astermind Elm

A local Model Context Protocol server for training small text classifiers with Extreme Learning Machines (ELMs). It supports in-memory inference and optional SurrealDB persistence, prediction monitoring, and vector storage.

Is it useful?

Yes, for focused classification tasks where data must stay under your control and rapid retraining matters. Good candidates include intent routing, spam or content categorization, support-ticket triage, and lightweight labeling aids.

It is not a general semantic-search model or a production ML platform. The generate_embedding tool exposes a trained ELM's task-specific hidden features; it does not use a pretrained language model and should not be described as a semantic embedding without evaluation on the intended corpus.

Capabilities

• Train multi-class text classifiers from labeled examples.
• Predict labels and return ranked confidence scores.
• Generate model-specific hidden-feature vectors.
• Keep multiple models in memory and inspect their metadata.
• Optionally store and reload versioned models and datasets in SurrealDB.
• Optionally log predictions and calculate accuracy, latency, label counts, a confusion matrix, and distribution drift.
• Store arbitrary equal-dimension vectors and search them with cosine similarity.

The server exposes 16 MCP tools:

• Core: train_classifier, predict, generate_embedding, list_models, delete_model, save_model
• Persistence: store_model_persistent, load_model_persistent, list_model_versions, store_training_dataset, load_training_dataset
• Monitoring: get_model_metrics, get_confusion_matrix, detect_drift
• Vector storage: store_embeddings, search_similar

save_model returns an in-memory summary. Use store_model_persistent when a model must survive a restart.

Requirements

• Node.js 20.19+ or 22.12+
• SurrealDB only when persistence is enabled

Install, build, and test

npm ci
npm run build
npm test

Additional commands:

npm run test:watch
npm run test:coverage
npm run watch

Coverage is enforced for the production TypeScript at 80% statements, 65% branches, 80% functions, and 80% lines. CI runs the locked dependency set on current Node.js 20, 22, and 24 releases, plus the persistence suite against a disposable SurrealDB service on Node.js 24.

MCP configuration

Build first, then point an MCP client at the compiled stdio entry point:

{
  "mcpServers": {
    "astermind-elm": {
      "command": "node",
      "args": ["/absolute/path/to/astermind-elm-mcp/build/index.js"]
    }
  }
}

The server writes protocol messages to stdout and diagnostics to stderr.

Minimal workflow

Call train_classifier:

{
  "model_id": "sentiment",
  "training_data": [
    { "text": "excellent purchase", "label": "positive" },
    { "text": "love this product", "label": "positive" },
    { "text": "terrible purchase", "label": "negative" },
    { "text": "hate this product", "label": "negative" }
  ],
  "config": {
    "hiddenUnits": 128,
    "activation": "relu"
  }
}

Then call predict:

{
  "model_id": "sentiment",
  "text": "I love this purchase",
  "top_k": 2
}

Use representative training and held-out evaluation data. Training success is not evidence that the classifier generalizes.

Optional SurrealDB persistence

The sample credentials below are for disposable local development only. Do not use them on a reachable database.

surreal start --log info --user root --pass root memory
npm run build
npm run init-db

Enable persistence in the MCP server environment:

{
  "ENABLE_PERSISTENCE": "true",
  "LOG_PREDICTIONS": "false",
  "SURREALDB_URL": "ws://127.0.0.1:8000/rpc",
  "SURREALDB_NAMESPACE": "astermind",
  "SURREALDB_DATABASE": "development",
  "SURREALDB_USERNAME": "root",
  "SURREALDB_PASSWORD": "root"
}

Variable	Default	Meaning
ENABLE_PERSISTENCE	false	Enable database-backed tools
LOG_PREDICTIONS	false	Log predictions unless a call explicitly opts out
SURREALDB_URL	ws://127.0.0.1:8000/rpc	SurrealDB RPC endpoint
SURREALDB_NAMESPACE	astermind	Namespace
SURREALDB_DATABASE	production	Database name
SURREALDB_USERNAME	root	Database user
SURREALDB_PASSWORD	root	Database password

Persisted models are loaded explicitly with load_model_persistent; they are not automatically loaded after restart. If global prediction logging is on, "log_prediction": false disables it for an individual request. Prediction logging is best-effort and non-blocking: inference still returns when the database is slow or unavailable, and logging failures are reported on stderr.

Prediction records contain the input text. Enabling logging therefore changes the privacy boundary: protect the database, credentials, backups, and access logs appropriately. “Local” only means local when both the MCP client and the configured database endpoint are local.

Monitoring semantics

• Accuracy and confusion matrices require predictions logged with ground_truth.
• Drift compares predicted-label distributions with Jensen-Shannon divergence; it does not measure accuracy degradation or causal drift.
• detect_drift returns status: "insufficient_data" and null drift fields if either comparison window has no samples.
• Monitoring queries currently materialize matching prediction rows in the server, so benchmark and redesign aggregation before high-volume use.

Test layers

• Unit tests cover validation, model lifecycle, encoding, persistence queries, metrics, drift, and vector search.
• Handler tests cover all 16 tool-dispatch paths and model serialization.
• A real stdio MCP test starts the compiled child server and exercises protocol discovery, training, prediction, and error responses.
• SurrealDB integration tests are opt-in and require an initialized disposable database:

npm run build
SURREALDB_URL=ws://127.0.0.1:8000/rpc \
SURREALDB_NAMESPACE=astermind_test \
SURREALDB_DATABASE=integration \
npm run init-db

SURREALDB_TEST_URL=ws://127.0.0.1:8000/rpc \
SURREALDB_TEST_NAMESPACE=astermind_test \
SURREALDB_TEST_DATABASE=integration \
npm run test:integration

Current limitations

• There is no built-in train/validation split, evaluation dataset tool, model selection, calibration analysis, or batch prediction API.
• Confidence scores should not be treated as calibrated probabilities without measurement.
• Model records store serialized weights but are not encrypted by this server.
• Database schema evolution is handled by the initialization script, not a versioned migration system.
• Vector search uses a database cosine-similarity query without a declared vector index; it is not an approximate-nearest-neighbor service.

These constraints make the project best suited to local prototypes, personal automation, and bounded internal workloads until workload-specific evaluation, security review, and operational testing are complete.

Project structure

src/index.ts                         MCP schemas, server, and tool handlers
src/model-manager.ts                 In-memory model lifecycle
src/tool-validation.ts               Runtime input validation
src/text-features.ts                 Shared normalized text encoding
src/persistence/surrealdb-client.ts  Persistence and monitoring operations
src/scripts/init-db.ts               SurrealDB schema initialization
tests/                               Unit, handler, stdio, and DB integration tests

See PERSISTENCE_GUIDE.md for persistence examples. The proposal and completion-summary documents in the repository are historical and are not evidence of the current release quality.

License

MIT