8000 Add runtime configuration API, graceful startup, and client SDK by jealous · Pull Request #993 · MemMachine/MemMachine · GitHub
[go: up one dir, main page]
Skip to content

Add runtime configuration API, graceful startup, and client SDK #993

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
mwqgithub merged 1 commit into from
Jan 30, 2026
Merged

Add runtime configuration API, graceful startup, and client SDK #993

mwqgithub merged 1 commit into from
Jan 30, 2026
+4,382 −308

Conversation

@jealous
Copy link
Contributor
@jealous jealous commented Jan 28, 2026 •
edited
Loading

Purpose of the change

MemMachine currently requires all configured resources (embedders, language models, databases) to be available at startup. If any resource is unavailable — for example, a model is not yet deployed or an API key is not set — the server crashes. This makes it impossible to start the server in a partially configured state and add resources later.

This PR adds a runtime configuration API, makes startup graceful, and provides a client SDK module so users can:

  1. Start the server even when some resources are unavailable
  2. Add, remove, and retry resources at runtime via REST API
  3. Update memory configuration (episodic/semantic) to point at newly added resources
  4. Get clear status reporting on which resources are ready, failed, or pending
  5. Use the Python SDK to manage configuration programmatically

Description

Graceful startup

  • Resource managers (EmbedderManager, LanguageModelManager, RerankerManager) now track build failures instead of crashing. Failed resources are recorded with status FAILED and can be retried later.
  • Extracted shared resource lifecycle logic into BaseResourceManager to reduce duplication across the three manager types.
  • SemanticMemoryConf gains an enabled flag (default True) with a model_validator that auto-disables when required fields (database, llm_model, embedding_model) are empty.
  • MemMachine._initialize_default_episodic_configuration() now gracefully disables long-term or short-term episodic memory when the required embedder/reranker is not configured, instead of raising an error.
  • MemMachine.start() and stop() skip the semantic service when semantic memory is disabled.

Runtime configuration API (/api/v2/config/...)

Method Endpoint Description
GET /config View configuration with resource status
GET /config/resources View all resources and their status
PUT /config/memory Update episodic and/or semantic memory configuration
POST /config/resources/embedders Add a new embedder
POST /config/resources/language_models Add a new language model
DELETE /config/resources/embedders/{name} Remove an embedder
DELETE /config/resources/language_models/{name} Remove a language model
POST /config/resources/embedders/{name}/retry Retry building a failed embedder
POST /config/resources/language_models/{name}/retry Retry building a failed language model
POST /config/resources/rerankers/{name}/retry Retry building a failed reranker
  • Configuration changes are persisted to the YAML config file when one is loaded.
  • Error handling extracted into RestError in a new exceptions.py module.

Client SDK (rest_client/config.py)

Added a Config class to the Python SDK that wraps all configuration API endpoints:

  • client.config() — convenience accessor on MemMachineClient
  • get_config() / get_resources() — read current configuration and resource status
  • update_memory_config() — update episodic/semantic memory settings
  • add_embedder() / add_language_model() — add new resources
  • delete_embedder() / delete_language_model() — remove resources
  • retry_embedder() / retry_language_model() / retry_reranker() — retry failed resources

Follows the same patterns as the existing Project and Memory SDK classes (closed-client checks, timeout forwarding, Pydantic response parsing, exception logging).

Fixes/Closes

Fixes #974

Type of change

  • New feature (non-breaking change which adds functionality)
  • Refactor (does not change functionality, e.g., code style improvements, linting)

How Has This Been Tested?

  • Unit Test

890+ unit tests pass (pytest -m "not integration and not slow"), including:

  • test_config_router.py — 27 tests covering all API endpoints including error cases
  • test_config_service.py — 18 tests covering service-layer logic (add/remove/retry resources, memory config updates, persistence)
  • test_configuration.py — 5 new tests for config save/load and config_file_path tracking
  • test_resource_manager.py — 3 new tests for save_config and config property access
  • test_config.py — 23 tests covering the client SDK Config class (happy paths, closed-client errors, timeout forwarding, exception propagation)

Checklist

  • My code follows the style guidelines of this project (See STYLE_GUIDE.md)
  • I have performed a self-review of my own code
  • My changes generate no new warnings
  • I have added unit tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • I have checked my code and corrected any misspellings

Maintainer Checklist

  • Confirmed all checks passed
  • Contributor has signed the commit(s)
  • Reviewed the code
  • Run, Tested, and Verified the change(s) work as expected

Screenshots/Gifs

N/A

Further comments

None

@jealous jealous self-assigned this Jan 28, 2026
@jealous jealous marked this pull request as draft January 28, 2026 02:00
@jealous jealous force-pushed the bugfix/allowEmptyModel branch from 22ebb3f to 1492646 Compare January 28, 2026 22:23
@jealous jealous requested a review from Copilot January 28, 2026 22:23
@jealous jealous changed the title Allow runtime resource configuration Add runtime configuration API and graceful startup Jan 28, 2026
Copilot AI reviewed Jan 28, 2026
View reviewed changes
Copy link
Contributor
Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This pull request adds runtime resource configuration capabilities to the MemMachine server, enabling dynamic management of embedders, language models, rerankers, and memory configurations without requiring server restarts.

Changes:

  • Introduces REST API endpoints for runtime configuration management
  • Implements configuration persistence to YAML files
  • Adds error tracking and retry mechanisms for failed resource initialization

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated no comments.

Show a summary per file
File Description
src/memmachine/common/api/config_spec.py Defines API request/response models for configuration operations
src/memmachine/common/api/doc.py Adds documentation strings for configuration API endpoints
src/memmachine/common/configuration/init.py Adds config file path tracking and save() method to Configuration
src/memmachine/common/configuration/embedder_conf.py Adds null-safety check for embedder parsing
src/memmachine/common/configuration/language_model_conf.py Adds null-safety check for language model parsing
src/memmachine/common/errors.py Introduces ResourceNotReadyError for failed resource initialization
src/memmachine/common/resource_manager/base_manager.py Creates base class with shared resource management logic
src/memmachine/common/resource_manager/embedder_manager.py Refactors to use BaseResourceManager, adds add/remove operations
src/memmachine/common/resource_manager/language_model_manager.py Refactors to use BaseResourceManager, adds add/remove operations
src/memmachine/common/resource_manager/reranker_manager.py Refactors to use BaseResourceManager pattern
src/memmachine/common/resource_manager/resource_manager.py Adds manager property accessors and save_config() method
src/memmachine/main/memmachine.py Refactors default resolution logic, adds resource_manager property
src/memmachine/server/api_v2/config_router.py Implements configuration API endpoints
src/memmachine/server/api_v2/config_service.py Implements configuration service logic
src/memmachine/server/api_v2/exceptions.py Extracts RestError class to separate module
src/memmachine/server/api_v2/router.py Removes RestError class, adds config_router registration
tests/memmachine/common/api/test_version.py Updates version regex to support additional local version identifiers
tests/memmachine/common/configuration/test_configuration.py Adds tests for config file path tracking and save() method
tests/memmachine/common/resource_manager/test_resource_manager.py Adds tests for save_config() functionality
tests/memmachine/server/api_v2/test_config_router.py Adds comprehensive tests for configuration API endpoints
tests/memmachine/server/api_v2/test_config_service.py Adds tests for configuration service functions

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@jealous jealous force-pushed the bugfix/allowEmptyModel branch 4 times, most recently from 299adeb to 4ee0fc9 Compare January 28, 2026 23:19
@jealous jealous marked this pull request as ready for review January 28, 2026 23:28
@jealous jealous force-pushed the bugfix/allowEmptyModel branch 2 times, most recently from 694fa05 to f92feae Compare January 29, 2026 18:56
@jealous @claude
Add runtime configuration API, graceful startup, and client SDK
34704c9 
- Add REST API endpoints for managing resources at runtime
  (add/remove/retry embedders, language models; view status)
- Add PUT /api/v2/config/memory endpoint to update episodic
  and semantic memory configuration
- Introduce graceful startup: resources that fail to build are
  tracked as FAILED instead of crashing the server
- Add enabled/disabled flag for semantic memory with auto-disable
  when required fields (database, llm_model, embedding_model) are
  missing
- Make episodic memory initialization resilient to missing
  embedder/reranker configuration
- Extract shared resource manager logic into BaseResourceManager
- Persist configuration changes to YAML file on updates
- Add rest_client Config class wrapping all /api/v2/config endpoints
  with MemMachineClient.config() convenience accessor
- Add comprehensive tests for config router, config service, and
  client SDK config module

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jealous jealous force-pushed the bugfix/allowEmptyModel branch from f92feae to 34704c9 Compare January 29, 2026 22:37
@jealous jealous changed the title Add runtime configuration API and graceful startup Add runtime configuration API, graceful startup, and client SDK Jan 29, 2026
@mwqgithub mwqgithub merged commit b63b1c0 into main Jan 30, 2026
48 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot 7D53 Copilot left review comments

@tianAndrew tianAndrew tianAndrew approved these changes

@mwqgithub mwqgithub mwqgithub approved these changes

+1 more reviewer

@sheperdh sheperdh sheperdh approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

@jealous jealous

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Bug]: Sometimes the LLM is stuck in an infinite loop when ingesting semantic memories

5 participants

@jealous @sheperdh @tianAndrew @mwqgithub
0