diff --git a/src/memos/dream/README.md b/src/memos/dream/README.md new file mode 100644 index 000000000..3fe7dab09 --- /dev/null +++ b/src/memos/dream/README.md @@ -0,0 +1,129 @@ +# Dream Plugin + +Dream is an optional MemOS community feature, currently in beta. It explores how +an agent can reflect on recently added memories outside the foreground request +path, then consolidate them into higher-level context, insights, and diary +entries. The implementation is intentionally lightweight and extensible, and we +welcome the community to help improve the signal policy, prompts, persistence, +diary experience, and downstream integrations. + +## Status and Enablement + +Dream is disabled by default. + +With no plugin environment variables configured, MemOS loads ordinary plugins as +before, but it does not load the built-in `dream` plugin. Enable it explicitly: + +```bash +MEMOS_ENABLED_PLUGINS=dream +``` + +`MEMOS_DISABLED_PLUGINS` has the highest priority, so this keeps Dream disabled: + +```bash +MEMOS_ENABLED_PLUGINS=dream +MEMOS_DISABLED_PLUGINS=dream +``` + +## Current Capabilities + +When enabled, the built-in `CommunityDreamPlugin` provides: + +- signal capture from successful memory add operations; +- deterministic Dream metadata enrichment during fine extraction; +- scheduler-driven Dream execution through the `dream.execute` hook; +- manual cube-level triggering through `POST /dream/trigger/cube`; +- Dream diary querying through `POST /dream/diary`; +- `Context` recall merged into normal search results. + +The default pipeline is: + +1. Build or update `Context` nodes from pending memories. +2. Form Dream motives from recently added source memories. +3. Recall related `UserMemory` and `LongTermMemory` nodes. +4. Use the configured LLM to produce at most one insight per motive. +5. Generate a human-readable Dream diary entry. +6. Persist valid insight actions and diary entries to the graph database. + +If no LLM is available, Dream can still run the pipeline, but fallback reasoning +does not write new insight memories because zero-confidence actions are skipped. + +## Usage + +Enable Dream and start the API service: + +```bash +export MEMOS_ENABLED_PLUGINS=dream +make serve +``` + +Check plugin health: + +```bash +curl http://127.0.0.1:8000/dream/diary/health +``` + +Manually submit a cube-level Dream task: + +```bash +curl -X POST "http://127.0.0.1:8000/dream/trigger/cube?cube_id=&user_id=&user_name=" +``` + +Query recent Dream diary entries: + +```bash +curl -X POST http://127.0.0.1:8000/dream/diary \ + -H "Content-Type: application/json" \ + -d '{"cube_id": "", "filter": {"limit": 5}}' +``` + +Fetch one diary entry: + +```bash +curl -X POST http://127.0.0.1:8000/dream/diary \ + -H "Content-Type: application/json" \ + -d '{"cube_id": "", "filter": {"task_id": "dream_diary_xxx"}}' +``` + +## Configuration + +Plugin loading: + +- `MEMOS_ENABLED_PLUGINS=dream`: enable Dream. +- `MEMOS_DISABLED_PLUGINS=dream`: disable Dream, even if it is also enabled. + +Dream-specific options: + +- `MEMOS_DREAM_HEURISTIC_ENRICHER`: defaults to `on`. +- `MEMOS_DREAM_ENRICH_OVERWRITE`: defaults to `off`. +- `MEMOS_DREAM_CONTEXT_ENABLED`: defaults to `on`. +- `MEMOS_DREAM_CONTEXT_SUMMARY_LLM`: defaults to `on`. +- `MEMOS_DREAM_CONTEXT_BINDING_LLM`: defaults to `on`. +- `MEMOS_DREAM_CONTEXT_BINDING_MIN_GROUP_SIZE`: defaults to `2`. +- `MEMOS_DREAM_CONTEXT_BINDING_MAX_GROUP_SIZE`: defaults to `30`. +- `MEMOS_DREAM_CONTEXT_BINDING_CONFIDENCE_THRESHOLD`: defaults to `0.65`. + +## Beta Limitations + +- Signals are stored in memory and do not survive process restarts. +- The automatic trigger policy is currently a simple pending-memory threshold. +- The built-in signal source focuses on new-memory accumulation. Conflict, + feedback, frequency, and fragmentation signals are extension points. +- The diary and surfacing experience is still early. +- Write-back policies for update, merge, archive, and long-term maintenance are + available as extension directions, not complete product behavior. + +## Contributing + +Dream is designed as a community-building surface. Good places to contribute: + +- better trigger policies and signal stores; +- stronger motive formation and recall strategies; +- safer and more useful reasoning prompts; +- richer diary generation and user-facing surfacing; +- memory lifecycle and maintenance policies; +- alternative `dream` plugin implementations with higher priority. + +Projects can ship their own plugin with the same logical name (`dream`). When +multiple providers expose `dream`, the plugin manager keeps the implementation +with the highest priority. diff --git a/src/memos/dream/plugin.py b/src/memos/dream/plugin.py index fbe098df7..ef3291d53 100644 --- a/src/memos/dream/plugin.py +++ b/src/memos/dream/plugin.py @@ -46,6 +46,7 @@ class CommunityDreamPlugin(MemOSPlugin): version = "0.1.0" description = "Built-in Dream plugin" priority = 10 + enabled_by_default = False def on_load(self) -> None: self.context: dict[str, Any] = {"shared": {}, "configs": {}} diff --git a/src/memos/plugins/base.py b/src/memos/plugins/base.py index b10b7c824..24d356bbf 100644 --- a/src/memos/plugins/base.py +++ b/src/memos/plugins/base.py @@ -28,6 +28,7 @@ class MemOSPlugin: version: str = "0.0.0" description: str = "" priority: int = 0 + enabled_by_default: bool = True _app: FastAPI | None = None diff --git a/src/memos/plugins/manager.py b/src/memos/plugins/manager.py index a4478a22d..b18618098 100644 --- a/src/memos/plugins/manager.py +++ b/src/memos/plugins/manager.py @@ -39,7 +39,14 @@ def _parse_plugin_names(value: str | None) -> set[str]: @classmethod def _is_plugin_enabled(cls, plugin: MemOSPlugin) -> bool: disabled = cls._parse_plugin_names(os.getenv("MEMOS_DISABLED_PLUGINS")) - return plugin.name not in disabled + if plugin.name in disabled: + return False + + if plugin.enabled_by_default: + return True + + enabled = cls._parse_plugin_names(os.getenv("MEMOS_ENABLED_PLUGINS")) + return plugin.name in enabled @staticmethod def _select_plugin_winners( @@ -121,7 +128,7 @@ def discover(self) -> None: for plugin_name, plugin in winners.items(): if not self._is_plugin_enabled(plugin): logger.info( - "Plugin discovered but disabled: %s v%s (MEMOS_DISABLED_PLUGINS)", + "Plugin discovered but disabled: %s v%s", plugin.name, plugin.version, ) diff --git a/tests/plugins/test_plugin_component_init.py b/tests/plugins/test_plugin_component_init.py new file mode 100644 index 000000000..49a12f625 --- /dev/null +++ b/tests/plugins/test_plugin_component_init.py @@ -0,0 +1,236 @@ +from __future__ import annotations + +from collections import namedtuple + + +class TestPluginComponentInit: + def test_build_plugin_context_shapes_expected_sections(self): + from memos.plugins.component_bootstrap import build_plugin_context + + context = build_plugin_context( + graph_db="graph", + embedder="embedder", + default_cube_config="cube", + nli_client_config={"base_url": "http://nli"}, + mem_reader_config="mem_reader", + reranker_config="reranker", + feedback_reranker_config="feedback_reranker", + internet_retriever_config="internet", + ) + + assert context["shared"]["graph_db"] == "graph" + assert context["shared"]["embedder"] == "embedder" + assert context["configs"]["default_cube_config"] == "cube" + assert context["configs"]["nli_client_config"]["base_url"] == "http://nli" + assert "components" not in context + + def test_manager_calls_init_components(self): + from memos.plugins.base import MemOSPlugin + from memos.plugins.manager import PluginManager + + class DummyPlugin(MemOSPlugin): + name = "dummy" + + def on_load(self) -> None: + self.calls = 0 + + def init_components(self, context: dict) -> None: + self.calls += 1 + context["components"]["dummy"] = "ok" + + plugin = DummyPlugin() + plugin.on_load() + manager = PluginManager() + manager._plugins[plugin.name] = plugin + context = {"components": {}} + + manager.init_components(context) + + assert plugin.calls == 1 + assert context["components"]["dummy"] == "ok" + + def test_discover_is_idempotent(self, monkeypatch): + import importlib.metadata + + from memos.plugins.base import MemOSPlugin + from memos.plugins.manager import PluginManager + + EntryPoint = namedtuple("EntryPoint", ["name", "load"]) + + class DummyPlugin(MemOSPlugin): + name = "dummy" + + load_calls = {"count": 0} + + def load_plugin(): + load_calls["count"] += 1 + return DummyPlugin + + class EntryPoints(list): + def select(self, *, group): + assert group == "memos.plugins" + return self + + monkeypatch.setattr( + importlib.metadata, + "entry_points", + lambda: EntryPoints([EntryPoint(name="dummy", load=load_plugin)]), + ) + + manager = PluginManager() + manager.discover() + manager.discover() + + assert load_calls["count"] == 1 + assert list(manager.plugins) == ["dummy"] + + def test_discover_loads_plugins_by_default(self, monkeypatch): + import importlib.metadata + + from memos.plugins.base import MemOSPlugin + from memos.plugins.manager import PluginManager + + EntryPoint = namedtuple("EntryPoint", ["name", "load"]) + + class OptInPlugin(MemOSPlugin): + name = "regular" + + class EntryPoints(list): + def select(self, *, group): + assert group == "memos.plugins" + return self + + monkeypatch.delenv("MEMOS_DISABLED_PLUGINS", raising=False) + monkeypatch.setattr( + importlib.metadata, + "entry_points", + lambda: EntryPoints([EntryPoint(name="regular", load=lambda: OptInPlugin)]), + ) + + manager = PluginManager() + manager.discover() + + assert list(manager.plugins) == ["regular"] + + def test_discover_skips_plugins_disabled_by_default(self, monkeypatch): + import importlib.metadata + + from memos.plugins.base import MemOSPlugin + from memos.plugins.manager import PluginManager + + EntryPoint = namedtuple("EntryPoint", ["name", "load"]) + + class DreamLikePlugin(MemOSPlugin): + name = "dream" + enabled_by_default = False + + class EntryPoints(list): + def select(self, *, group): + assert group == "memos.plugins" + return self + + monkeypatch.delenv("MEMOS_DISABLED_PLUGINS", raising=False) + monkeypatch.delenv("MEMOS_ENABLED_PLUGINS", raising=False) + monkeypatch.setattr( + importlib.metadata, + "entry_points", + lambda: EntryPoints([EntryPoint(name="dream", load=lambda: DreamLikePlugin)]), + ) + + manager = PluginManager() + manager.discover() + + assert list(manager.plugins) == [] + + def test_discover_loads_default_disabled_plugin_when_enabled(self, monkeypatch): + import importlib.metadata + + from memos.plugins.base import MemOSPlugin + from memos.plugins.manager import PluginManager + + EntryPoint = namedtuple("EntryPoint", ["name", "load"]) + + class DreamLikePlugin(MemOSPlugin): + name = "dream" + enabled_by_default = False + + class EntryPoints(list): + def select(self, *, group): + assert group == "memos.plugins" + return self + + monkeypatch.delenv("MEMOS_DISABLED_PLUGINS", raising=False) + monkeypatch.setenv("MEMOS_ENABLED_PLUGINS", "dream") + monkeypatch.setattr( + importlib.metadata, + "entry_points", + lambda: EntryPoints([EntryPoint(name="dream", load=lambda: DreamLikePlugin)]), + ) + + manager = PluginManager() + manager.discover() + + assert list(manager.plugins) == ["dream"] + + def test_discover_skips_disabled_plugin(self, monkeypatch): + import importlib.metadata + + from memos.plugins.base import MemOSPlugin + from memos.plugins.manager import PluginManager + + EntryPoint = namedtuple("EntryPoint", ["name", "load"]) + + class DisabledPlugin(MemOSPlugin): + name = "disabled_one" + + class EntryPoints(list): + def select(self, *, group): + assert group == "memos.plugins" + return self + + monkeypatch.setenv("MEMOS_DISABLED_PLUGINS", "disabled_one") + monkeypatch.setattr( + importlib.metadata, + "entry_points", + lambda: EntryPoints([EntryPoint(name="disabled_one", load=lambda: DisabledPlugin)]), + ) + + manager = PluginManager() + manager.discover() + + assert list(manager.plugins) == [] + + def test_discover_disabled_env_overrides_enabled_env(self, monkeypatch): + import importlib.metadata + + from memos.plugins.base import MemOSPlugin + from memos.plugins.manager import PluginManager + + EntryPoint = namedtuple("EntryPoint", ["name", "load"]) + + class DreamLikePlugin(MemOSPlugin): + name = "dream" + enabled_by_default = False + + class EntryPoints(list): + def select(self, *, group): + assert group == "memos.plugins" + return self + + monkeypatch.setenv("MEMOS_DISABLED_PLUGINS", "dream") + monkeypatch.setenv("MEMOS_ENABLED_PLUGINS", "dream") + monkeypatch.setattr( + importlib.metadata, + "entry_points", + lambda: EntryPoints([EntryPoint(name="dream", load=lambda: DreamLikePlugin)]), + ) + + manager = PluginManager() + manager.discover() + + assert list(manager.plugins) == [] + + def test_builtin_dream_plugin_is_disabled_by_default(self): + from memos.dream import CommunityDreamPlugin + + assert CommunityDreamPlugin.enabled_by_default is False