feat: use custom storage service if found

[alex-nax]

Relates to

Addresses the need for pluggable storage backends for production deployments and fixes documentation discrepancy for session storage.

Risks

Medium

• Changes affect core storage mechanisms for state caching and session management
• Could impact existing deployments if they have custom session handling logic
• Migration path should be tested for existing in-memory sessions
• Performance characteristics may differ with custom KV store implementations

Affected areas:

• Runtime state management
• Session storage and lifecycle
• Any code relying on state caching behavior

Background

What does this PR do?

This PR introduces a pluggable Key-Value Store Service interface (IKVStoreService) that allows developers to implement custom storage backends for state caching and session management. The implementation:

1. Adds new interfaces in packages/core/src/types/store.ts:

   • IKVStore<T, M>: Generic key-value store interface with get, set, delete, entries, and optional getMetrics methods
   • IKVStoreService: Service interface for obtaining named KV stores
   • isKVStoreService: Type guard helper function

2. Integrates KV Store into runtime:

   • State cache can now use custom KV store implementations
   • Session storage can leverage external storage backends (Redis, etc.)
   • Falls back to in-memory Map-based storage when no custom service is provided

3. Fixes documentation discrepancy:

   • CRITICAL: The official documentation states that sessions use in-memory storage by default, but this was NOT actually implemented
   • This PR adds the proper fallback to in-memory storage, achieving parity with the documented behavior

What kind of change is this?

• ✅ Features (non-breaking change which adds functionality)
• ✅ Bug fixes (fixes documentation/implementation mismatch)
• ✅ Improvements (enables production scalability)

Why are we doing this? Any context or related work?

Motivation 1: Production Scalability with Replicas

In production environments, agents can throttle CPU usage when handling high loads. Running multiple replicas is a common solution, but the current in-memory-only storage causes issues:

• State is not shared across replicas
• Sessions are lost when pods restart or scale
• No persistence between deployments

With this KV Store interface, users can implement Redis, Memcached, or other distributed storage solutions to maintain state across replicas without losing data.

Motivation 2: Documentation Accuracy

The Sessions API documentation explicitly mentions in-memory storage as the default:

"In-Memory Storage" - Sessions use in-memory storage by default

However, this was never actually implemented as a proper fallback. This PR corrects this discrepancy by providing a true in-memory implementation when no custom KV store service is registered.

Documentation changes needed?

• ✅ My changes require a change to the project documentation
• Documentation should be updated to mention:
  • How to implement a custom IKVStoreService
  • Example Redis implementation for production deployments
  • Migration guide for existing deployments
  • Performance considerations for different storage backends

Testing

Where should a reviewer start?

1. Review the new interfaces in packages/core/src/types/store.ts
2. Check how the KV store is integrated in packages/core/src/runtime.ts for state caching
3. Verify session storage fallback in packages/server/src/api/messaging/sessions.ts
4. Test the default in-memory behavior without custom service
5. Validate that custom KV store services can be registered and used

Detailed testing steps

Test 1: Default In-Memory Behavior (No Custom Service)

• Start a fresh ElizaOS instance without registering a custom KV store service
• Create a session via Sessions API
• Send messages and verify state persistence
• Confirm sessions are stored in-memory (check memory usage)
• Verify session expiration and cleanup works as documented

Test 2: State Cache with Default Storage

• Start an agent with state caching enabled
• Perform actions that populate the state cache
• Verify cache entries are retrievable
• Restart the agent and confirm cache is cleared (in-memory behavior)

Test 3: Custom KV Store Service (Integration Test)

• Implement a simple custom KV store service (e.g., file-based or Redis mock)
• Register the service with the runtime
• Create sessions and verify they use the custom store
• Verify getMetrics() works if implemented
• Test entries() async generator functionality

Test 4: Production Replica Scenario (Manual)

• Deploy two agent replicas with Redis-backed KV store
• Create a session on replica 1
• Send message to session on replica 2
• Verify session state is shared correctly
• Scale down replica 1, verify replica 2 maintains sessions

Database changes

None. This PR adds an abstraction layer but does not modify database schemas.

Deploy Notes

Deployment instructions

For existing deployments: No action required. The default in-memory behavior maintains backward compatibility.

For production deployments with replicas:

1. Implement a custom IKVStoreService (e.g., Redis-backed)
2. Register the service via plugin system before agent initialization
3. Configure connection settings via environment variables
4. Monitor metrics if getMetrics() is implemented

Environment variables to consider adding:

• KV_STORE_BACKEND (e.g., "redis", "memory")
• REDIS_URL or similar connection strings for external stores
• KV_STORE_TTL for automatic expiration policies

Discord username

alexd000

[graphite-app]

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

• merge-queue - adds this PR to the back of the merge queue
• merge-queue-hotfix - for urgent hot fixes, skip the queue and merge this PR next

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}