From 1f581ac0a489b0409602fd382c36293c17273b8a Mon Sep 17 00:00:00 2001 From: Elliot Chen <2340896+cyfyifanchen@users.noreply.github.com> Date: Wed, 4 Mar 2026 19:30:22 -0800 Subject: [PATCH 1/8] docs: update screenshot and live demo links in README (#114) --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a7fb924d..e35a7b58 100644 --- a/README.md +++ b/README.md @@ -121,12 +121,12 @@ See the [Live2D Character with Memory Example](https://github.com/TEN-framework/
-![Image](https://github.com/user-attachments/assets/0d306b4c-bcd7-4e9e-a244-22fa3cb7b727) +[![Image](https://github.com/user-attachments/assets/0d306b4c-bcd7-4e9e-a244-22fa3cb7b727)](https://screenshot-analysis-vercel.vercel.app/) **Computer-Use with Memory** Use computer-use to launch screenshot to do analysis all in your memory. -See the [live demo]() for more details. +See the [live demo](https://screenshot-analysis-vercel.vercel.app/) for more details. ![divider][divider-light] From 1900be40bc5087dc9873cbd9b21ea213638a5995 Mon Sep 17 00:00:00 2001 From: Elliot Chen <2340896+cyfyifanchen@users.noreply.github.com> Date: Fri, 6 Mar 2026 02:47:24 -0800 Subject: [PATCH 2/8] docs: update README with OpenClaw plugin release and image link (#116) Update the OpenClaw Long-Term Memory Plugin section to reflect its release status by removing "coming this week" label. Also fix the markdown image link syntax to properly wrap the image in a link to the agent_memory branch. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e35a7b58..8babb68b 100644 --- a/README.md +++ b/README.md @@ -96,9 +96,9 @@ Welcome to EverMemOS! Join our community to help improve the project and collabo ## Usecases -![Image](https://github.com/user-attachments/assets/0c3eb2c5-3a15-4d09-8dee-c38f96422168) +[![Image](https://github.com/user-attachments/assets/60713404-2e94-4cab-9e5f-15b36291dc6f)](https://github.com/EverMind-AI/EverMemOS/tree/agent_memory) -**OpenClaw Long-Term Memory Plugin(coming this week)** +**OpenClaw Long-Term Memory Plugin** Claw is putting the pieces of his memory together. Imagine a 24/7 agent with continuous learning memory that you can carry with you wherever you go next. From c2fdcb502d1bfd56684f06b2a692254ecfb64839 Mon Sep 17 00:00:00 2001 From: Elliot Chen <2340896+cyfyifanchen@users.noreply.github.com> Date: Fri, 6 Mar 2026 02:54:44 -0800 Subject: [PATCH 3/8] docs: update README with link to agent_memory branch (#117) --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8babb68b..46346b21 100644 --- a/README.md +++ b/README.md @@ -100,7 +100,7 @@ Welcome to EverMemOS! Join our community to help improve the project and collabo **OpenClaw Long-Term Memory Plugin** -Claw is putting the pieces of his memory together. Imagine a 24/7 agent with continuous learning memory that you can carry with you wherever you go next. +Claw is putting the pieces of his memory together. Imagine a 24/7 agent with continuous learning memory that you can carry with you wherever you go next. Check out the [agent_memory](https://github.com/EverMind-AI/EverMemOS/tree/agent_memory) branch for more details. ![divider][divider-light] From ba62be64718793e8009c8d9a01ca977569c7704b Mon Sep 17 00:00:00 2001 From: Elliot Chen <2340896+cyfyifanchen@users.noreply.github.com> Date: Fri, 6 Mar 2026 16:54:46 -0800 Subject: [PATCH 4/8] docs: update README with corrected links and plugin info (#119) Update the link for the use case image and add reference to the EverMind + OpenClaw plugin repository. The change clarifies the project structure and provides direct access to the plugin code. --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 46346b21..e8eb2400 100644 --- a/README.md +++ b/README.md @@ -96,11 +96,11 @@ Welcome to EverMemOS! Join our community to help improve the project and collabo ## Usecases -[![Image](https://github.com/user-attachments/assets/60713404-2e94-4cab-9e5f-15b36291dc6f)](https://github.com/EverMind-AI/EverMemOS/tree/agent_memory) +[![Image](https://github.com/user-attachments/assets/60713404-2e94-4cab-9e5f-15b36291dc6f)](https://github.com/user-attachments/assets/0e06da2b-0236-430f-89b4-980b8b6a855f) -**OpenClaw Long-Term Memory Plugin** +**EverMind + OpenClaw Agent Memory and Plugin** -Claw is putting the pieces of his memory together. Imagine a 24/7 agent with continuous learning memory that you can carry with you wherever you go next. Check out the [agent_memory](https://github.com/EverMind-AI/EverMemOS/tree/agent_memory) branch for more details. +Claw is putting the pieces of his memory together. Imagine a 24/7 agent with continuous learning memory that you can carry with you wherever you go next. Check out the [agent_memory](https://github.com/EverMind-AI/EverMemOS/tree/agent_memory) branch and the [plugin](https://github.com/EverMind-AI/EverMemOS/tree/agent_memory/evermemos-openclaw-plugin) for more details. ![divider][divider-light] From 004355dea98813f1b97e59581fc9b42453c2eff6 Mon Sep 17 00:00:00 2001 From: Elliot Chen <2340896+cyfyifanchen@users.noreply.github.com> Date: Fri, 6 Mar 2026 16:59:11 -0800 Subject: [PATCH 5/8] docs: update usecase banner image and fix link (#121) * docs: update README with corrected links and plugin info Update the link for the use case image and add reference to the EverMind + OpenClaw plugin repository. The change clarifies the project structure and provides direct access to the plugin code. * docs: update usecases image link to point to agent_memory branch --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e8eb2400..10cc524a 100644 --- a/README.md +++ b/README.md @@ -96,7 +96,7 @@ Welcome to EverMemOS! Join our community to help improve the project and collabo ## Usecases -[![Image](https://github.com/user-attachments/assets/60713404-2e94-4cab-9e5f-15b36291dc6f)](https://github.com/user-attachments/assets/0e06da2b-0236-430f-89b4-980b8b6a855f) +[![Image](https://github.com/user-attachments/assets/0e06da2b-0236-430f-89b4-980b8b6a855f)](https://github.com/EverMind-AI/EverMemOS/tree/agent_memory) **EverMind + OpenClaw Agent Memory and Plugin** From b9136180298c09b6bbee17d2794766a88586f12a Mon Sep 17 00:00:00 2001 From: Elliot Chen <2340896+cyfyifanchen@users.noreply.github.com> Date: Fri, 6 Mar 2026 22:20:09 -0800 Subject: [PATCH 6/8] docs: update banner GIF URL in README (#122) --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 10cc524a..eceb55f4 100644 --- a/README.md +++ b/README.md @@ -537,7 +537,7 @@ Read our [Contribution Guidelines](CONTRIBUTING.md) for code standards and Git w [divider-light]: https://github.com/user-attachments/assets/2e2bbcc6-e6d8-4227-83c6-0620fc96f761#gh-light-mode-only [divider-dark]: https://github.com/user-attachments/assets/d57fad08-4f49-4a1c-bdfc-f659a5d86150#gh-dark-mode-only -[banner-gif]: https://github.com/user-attachments/assets/3f22c9a8-a8db-4061-accf-f04c055aa01b +[banner-gif]: https://github.com/user-attachments/assets/f661bf5b-9942-4142-8310-9d4c5cc57924 [arxiv-badge]: https://img.shields.io/badge/arXiv-EverMemOS_Paper-F5C842?labelColor=gray&style=flat-square&logo=arxiv&logoColor=white From 8cb6d0197503e2f0f0f439e1208efc4d3c429bcc Mon Sep 17 00:00:00 2001 From: Elliot Chen <2340896+cyfyifanchen@users.noreply.github.com> Date: Sun, 8 Mar 2026 00:48:08 -0800 Subject: [PATCH 7/8] docs: add Chinese translation of README (#125) --- README.md | 239 +++++++++---------- README.zh.md | 648 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 770 insertions(+), 117 deletions(-) create mode 100644 README.zh.md diff --git a/README.md b/README.md index eceb55f4..49139148 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,6 @@ [![Ask DeepWiki][deepwiki-badge]][deepwiki] [![License][license-badge]][license] -

Share EverMemOS Repository

[![][share-x-shield]][share-x-link] @@ -23,33 +22,33 @@ [![][share-mastodon-shield]][share-mastodon-link] [![][share-weibo-shield]][share-weibo-link] --> - [Documentation][documentation] • [API Reference][api-docs] • [Demo][demo-section] +[![English][lang-en-badge]][lang-en-readme] +[![简体中文][lang-zh-badge]][lang-zh-readme]
-[![Image](https://github.com/user-attachments/assets/739a0939-ab1d-4659-81c4-0842466afde9)](https://luma.com/n88icl03) +[![Memory Genesis Competition 2026][competition-image]][competition-link] > [!IMPORTANT] > > ### Memory Genesis Competition 2026 -> -> Join our AI [Memory Competition](https://luma.com/n88icl03)! Build innovative applications, plugins, or infrastructure improvements powered by EverMemOS. -> +> +> Join our AI [Memory Competition][competition-link]! Build innovative applications, plugins, or infrastructure improvements powered by EverMemOS. +> > **Tracks:** > - **Agent + Memory** - Build intelligent agents with long-term, evolving memories > - **Platform Plugins** - Integrate EverMemOS with VSCode, Chrome, Slack, Notion, LangChain, and more > - **OS Infrastructure** - Optimize core functionality and performance -> -> **[Get Started with the Competition Starter Kit](docs/STARTER_KIT.md)** -> -> Join our [Discord](https://discord.gg/gYep5nQRZJ) to ask anything you want. AMA session is open to everyone and occurs biweekly. -> +> +> **[Get Started with the Competition Starter Kit][starter-kit]** +> +> Join our [Discord][discord] to ask anything you want. AMA session is open to everyone and occurs biweekly.
@@ -94,79 +93,73 @@ Welcome to EverMemOS! Join our community to help improve the project and collabo
-## Usecases +## Use Cases -[![Image](https://github.com/user-attachments/assets/0e06da2b-0236-430f-89b4-980b8b6a855f)](https://github.com/EverMind-AI/EverMemOS/tree/agent_memory) +[![EverMind + OpenClaw Agent Memory and Plugin][usecase-openclaw-image]][usecase-openclaw-link] **EverMind + OpenClaw Agent Memory and Plugin** -Claw is putting the pieces of his memory together. Imagine a 24/7 agent with continuous learning memory that you can carry with you wherever you go next. Check out the [agent_memory](https://github.com/EverMind-AI/EverMemOS/tree/agent_memory) branch and the [plugin](https://github.com/EverMind-AI/EverMemOS/tree/agent_memory/evermemos-openclaw-plugin) for more details. - +Claw is putting the pieces of his memory together. Imagine a 24/7 agent with continuous learning memory that you can carry with you wherever you go next. Check out the [agent_memory][usecase-openclaw-link] branch and the [plugin][usecase-openclaw-plugin-link] for more details. ![divider][divider-light] ![divider][divider-dark]
-[![Image](https://github.com/user-attachments/assets/a80bdab3-e5d0-43b9-9e8d-0a9605012a26)](https://github.com/TEN-framework/ten-framework/tree/main/ai_agents/agents/examples/voice-assistant-with-EverMemOS) +[![Live2D Character with Memory][usecase-live2d-image]][usecase-live2d-link] **Live2D Character with Memory** -Add long-term memory to your anime character that can talk to you in real-time powered by [TEN Framework](https://github.com/TEN-framework/ten-framework). -See the [Live2D Character with Memory Example](https://github.com/TEN-framework/ten-framework/tree/main/ai_agents/agents/examples/voice-assistant-with-EverMemOS) for more details. - +Add long-term memory to your anime character that can talk to you in real-time powered by [TEN Framework][ten-framework-link]. +See the [Live2D Character with Memory Example][usecase-live2d-link] for more details. ![divider][divider-light] ![divider][divider-dark]
-[![Image](https://github.com/user-attachments/assets/0d306b4c-bcd7-4e9e-a244-22fa3cb7b727)](https://screenshot-analysis-vercel.vercel.app/) +[![Computer-Use with Memory][usecase-computer-image]][usecase-computer-link] **Computer-Use with Memory** Use computer-use to launch screenshot to do analysis all in your memory. -See the [live demo](https://screenshot-analysis-vercel.vercel.app/) for more details. - +See the [live demo][usecase-computer-link] for more details. ![divider][divider-light] ![divider][divider-dark]
- -[![Image](https://github.com/user-attachments/assets/d1efe507-4eb7-4867-8996-457497333449)](https://github.com/EverMind-AI/evermem_got_demo) +[![Game of Thrones Memories][usecase-got-image]][usecase-got-link] **Game of Thrones Memories** -A demonstration of AI memory infrastructure through an interactive Q&A experience with "A Game of Thrones" -See the [code](https://github.com/EverMind-AI/evermem_got_demo) for more details. +A demonstration of AI memory infrastructure through an interactive Q&A experience with "A Game of Thrones". +See the [code][usecase-got-link] for more details. ![divider][divider-light] ![divider][divider-dark]
-[![Image](https://github.com/user-attachments/assets/b40b2241-b0e6-4fc9-9a35-92139f3a2d81)](https://github.com/EverMind-AI/evermem-claude-code) +[![EverMemOS Claude Code Plugin][usecase-claude-image]][usecase-claude-link] **EverMemOS Claude Code Plugin** Persistent memory for Claude Code. Automatically saves and recalls context from past coding sessions. -See the [code](https://github.com/EverMind-AI/evermem-claude-code) for more details. +See the [code][usecase-claude-link] for more details. ![divider][divider-light] ![divider][divider-dark]
-[![Image](https://github.com/user-attachments/assets/6586e647-dd5f-4f9f-9b26-66f930e8241c)](https://main.d2j21qxnymu6wl.amplifyapp.com/graph.html) +[![Visualize Memories with Graphs][usecase-graph-image]][usecase-graph-link] **Visualize Memories with Graphs** -Memory Graph view that visualizes your stored entities and how they relate, this is a pure frontend demo which hasn't been plugged with the backend yet, we are working on it. -See the [live demo](https://main.d2j21qxnymu6wl.amplifyapp.com/graph.html). - - +Memory Graph view that visualizes your stored entities and how they relate. This is a pure frontend demo which has not been plugged into the backend yet, and we are working on it. +See the [live demo][usecase-graph-link]. +![EverMemOS Overall Benchmark Results][benchmark-summary-image] + +*EverMemOS outperforms existing memory systems across all major benchmarks* -->
@@ -210,9 +199,11 @@ See the [live demo](https://main.d2j21qxnymu6wl.amplifyapp.com/graph.html). ## Quick Start ### Prerequisites + - Python 3.10+ • Docker 20.10+ • uv package manager • 4GB RAM **Verify Prerequisites:** + ```bash # Verify you have the required versions python --version # Should be 3.10+ @@ -247,7 +238,7 @@ curl http://localhost:1995/health # Expected response: {"status": "healthy", ...} ``` -✅ Server running at `http://localhost:1995` • [Full Setup Guide](docs/installation/SETUP.md) +✅ Server running at `http://localhost:1995` • [Full Setup Guide][setup-guide]
@@ -286,7 +277,7 @@ for memory_group in result.get("memories", []): print(f"Memory: {memory_group}") ``` -📖 [More Examples](docs/usage/USAGE_EXAMPLES.md) • 📚 [API Reference](docs/api_docs/memory_api.md) • 🎯 [Interactive Demos](docs/usage/DEMOS.md) +📖 [More Examples][usage-examples] • 📚 [API Reference][api-docs] • 🎯 [Interactive Demos][interactive-demos]
@@ -307,7 +298,7 @@ uv run python src/run.py uv run python src/bootstrap.py demo/simple_demo.py ``` -**Try it now**: Follow the [Demo Guide](docs/usage/DEMOS.md) for step-by-step instructions. +**Try it now**: Follow the [Demo Guide][interactive-demos] for step-by-step instructions. ### Full Demo Experience @@ -319,7 +310,7 @@ uv run python src/bootstrap.py demo/extract_memory.py uv run python src/bootstrap.py demo/chat_with_memory.py ``` -See the [Demo Guide](docs/usage/DEMOS.md) for details. +See the [Demo Guide][interactive-demos] for details.
@@ -330,10 +321,10 @@ See the [Demo Guide](docs/usage/DEMOS.md) for details. ## Advanced Techniques -- **[Group Chat Conversations](docs/advanced/GROUP_CHAT_GUIDE.md)** - Combine messages from multiple speakers -- **[Conversation Metadata Control](docs/advanced/METADATA_CONTROL.md)** - Fine-grained control over conversation context -- **[Memory Retrieval Strategies](docs/advanced/RETRIEVAL_STRATEGIES.md)** - Lightweight vs Agentic retrieval modes -- **[Batch Operations](docs/usage/BATCH_OPERATIONS.md)** - Process multiple messages efficiently +- **[Group Chat Conversations][group-chat-guide]** - Combine messages from multiple speakers +- **[Conversation Metadata Control][metadata-control-guide]** - Fine-grained control over conversation context +- **[Memory Retrieval Strategies][retrieval-strategies-guide]** - Lightweight vs Agentic retrieval modes +- **[Batch Operations][batch-operations-guide]** - Process multiple messages efficiently
@@ -350,7 +341,7 @@ See the [Demo Guide](docs/usage/DEMOS.md) for details. | [Configuration Guide][config-guide] | Environment variables and services | | [API Usage Guide][api-usage-guide] | Endpoints and data formats | | [Development Guide][dev-guide] | Architecture and best practices | -| [Memory API][api-docs] | Complete API reference | +| [Memory API][memory-api-doc] | Complete API reference | | [Demo Guide][demo-guide] | Interactive examples | | [Evaluation Guide][evaluation-guide] | Benchmark testing | @@ -367,15 +358,13 @@ EverMemOS achieves **93% overall accuracy** on the LoCoMo benchmark, outperformi ### Benchmark Results -

- EverMemOS Benchmark Results -

+![EverMemOS Benchmark Results][benchmark-image] ### Supported Benchmarks -- **[LoCoMo](https://github.com/snap-research/locomo)** - Long-context memory benchmark with single/multi-hop reasoning -- **[LongMemEval](https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned)** - Multi-session conversation evaluation -- **[PersonaMem](https://huggingface.co/datasets/bowen-upenn/PersonaMem)** - Persona-based memory evaluation +- **[LoCoMo][locomo-link]** - Long-context memory benchmark with single/multi-hop reasoning +- **[LongMemEval][longmemeval-link]** - Multi-session conversation evaluation +- **[PersonaMem][personamem-link]** - Persona-based memory evaluation ### Quick Start @@ -393,7 +382,7 @@ uv run python -m evaluation.cli --dataset locomo --system evermemos cat evaluation/results/locomo-evermemos/report.txt ``` -📊 [Full Evaluation Guide](evaluation/README.md) • 📈 [Complete Results](https://huggingface.co/datasets/EverMind-AI/EverMemOS_Eval_Results) +📊 [Full Evaluation Guide][evaluation-guide] • 📈 [Complete Results][evaluation-results-link]
@@ -404,9 +393,9 @@ cat evaluation/results/locomo-evermemos/report.txt ## GitHub Codespaces -EverMemOS supports [GitHub Codespaces](https://github.com/features/codespaces) for cloud-based development. This eliminates the need to set up Docker, manage local network configurations, or worry about environment compatibility issues. +EverMemOS supports [GitHub Codespaces][codespaces-link] for cloud-based development. This eliminates the need to set up Docker, manage local network configurations, or worry about environment compatibility issues. -[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/EverMind-AI/EverMemOS) +[![Open in GitHub Codespaces][codespaces-badge]][codespaces-project-link] ![divider][divider-light] ![divider][divider-dark] @@ -420,14 +409,14 @@ EverMemOS supports [GitHub Codespaces](https://github.com/features/codespaces) f | 8-core | ✅ Recommended | Good performance with all services | | 16-core+ | ✅ Optimal | Best for heavy development workloads | -> **Note:** If your company provides GitHub Codespaces, hardware limitations typically won't be an issue since enterprise plans often include access to larger machine types. +> **Note:** If your company provides GitHub Codespaces, hardware limitations typically will not be an issue since enterprise plans often include access to larger machine types. ### Getting Started with Codespaces 1. Click the "Open in GitHub Codespaces" button above 2. Select a **4-core or larger** machine when prompted 3. Wait for the container to build and services to start -4. Update API keys in `.env` (LLM_API_KEY, VECTORIZE_API_KEY, etc.) +4. Update API keys in `.env` (`LLM_API_KEY`, `VECTORIZE_API_KEY`, etc.) 5. Run `make run` to start the server All infrastructure services (MongoDB, Elasticsearch, Milvus, Redis) start automatically and are pre-configured to work together. @@ -457,9 +446,9 @@ EverMemOS is available on these AI-powered Q&A platforms. They can help you find
-## 🌟 Star and stay tuned with us +## 🌟 Star and stay tuned with us -![star us gif](https://github.com/user-attachments/assets/0c512570-945a-483a-9f47-8e067bd34484) +![star us gif][star-gif]
@@ -470,7 +459,7 @@ EverMemOS is available on these AI-powered Q&A platforms. They can help you find ## Contributing -We love open-source energy! Whether you’re squashing bugs, shipping features, sharpening docs, or just tossing in wild ideas, every PR moves EverMemOS forward. Browse [Issues](https://github.com/EverMind-AI/EverMemOS/issues) to find your perfect entry point—then show us what you’ve got. Let’s build the future of memory together. +We love open-source energy! Whether you are squashing bugs, shipping features, sharpening docs, or just tossing in wild ideas, every PR moves EverMemOS forward. Browse [Issues][issues-link] to find your perfect entry point, then show us what you have got. Let us build the future of memory together.
@@ -480,31 +469,28 @@ We love open-source energy! Whether you’re squashing bugs, shipping features, > > Join us in building EverMemOS better! Every contribution makes a difference, from code to documentation. Share your projects on social media to inspire others! > -> Connect with one of the EverMemOS maintainers [@elliotchen200](https://x.com/elliotchen200) on 𝕏 or [@cyfyifanchen](https://github.com/cyfyifanchen) on GitHub for project updates, discussions, and collaboration opportunities. - +> Connect with one of the EverMemOS maintainers [@elliotchen200][elliot-x-link] on 𝕏 or [@cyfyifanchen][cyfyifanchen-link] on GitHub for project updates, discussions, and collaboration opportunities. ![divider][divider-light] ![divider][divider-dark] ### Code Contributors -[![EverMemOS][contributors-image]][contributors] +[![EverMemOS Contributors][contributors-image]][contributors] ![divider][divider-light] ![divider][divider-dark] - ### Contribution Guidelines -Read our [Contribution Guidelines](CONTRIBUTING.md) for code standards and Git workflow. - +Read our [Contribution Guidelines][contributing-doc] for code standards and Git workflow. ![divider][divider-light] ![divider][divider-dark] ### License & Citation & Acknowledgments -[Apache 2.0](LICENSE) • [Citation](docs/CITATION.md) • [Acknowledgments](docs/ACKNOWLEDGMENTS.md) +[Apache 2.0][license] • [Citation][citation-doc] • [Acknowledgments][acknowledgments-doc]
@@ -514,7 +500,6 @@ Read our [Contribution Guidelines](CONTRIBUTING.md) for code standards and Git w
- [readme-top]: #readme-top [welcome]: #welcome-to-evermemos @@ -537,16 +522,22 @@ Read our [Contribution Guidelines](CONTRIBUTING.md) for code standards and Git w [divider-light]: https://github.com/user-attachments/assets/2e2bbcc6-e6d8-4227-83c6-0620fc96f761#gh-light-mode-only [divider-dark]: https://github.com/user-attachments/assets/d57fad08-4f49-4a1c-bdfc-f659a5d86150#gh-dark-mode-only + [banner-gif]: https://github.com/user-attachments/assets/f661bf5b-9942-4142-8310-9d4c5cc57924 +[competition-image]: https://github.com/user-attachments/assets/739a0939-ab1d-4659-81c4-0842466afde9 +[usecase-openclaw-image]: https://github.com/user-attachments/assets/0e06da2b-0236-430f-89b4-980b8b6a855f +[usecase-live2d-image]: https://github.com/user-attachments/assets/a80bdab3-e5d0-43b9-9e8d-0a9605012a26 +[usecase-computer-image]: https://github.com/user-attachments/assets/0d306b4c-bcd7-4e9e-a244-22fa3cb7b727 +[usecase-got-image]: https://github.com/user-attachments/assets/d1efe507-4eb7-4867-8996-457497333449 +[usecase-claude-image]: https://github.com/user-attachments/assets/b40b2241-b0e6-4fc9-9a35-92139f3a2d81 +[usecase-graph-image]: https://github.com/user-attachments/assets/6586e647-dd5f-4f9f-9b26-66f930e8241c +[overview-image]: figs/overview.png +[benchmark-image]: figs/benchmark_2.png +[benchmark-summary-image]: https://github.com/user-attachments/assets/a6ff7523-db24-40f5-96ab-aa94f41b2392 +[star-gif]: https://github.com/user-attachments/assets/0c512570-945a-483a-9f47-8e067bd34484 [arxiv-badge]: https://img.shields.io/badge/arXiv-EverMemOS_Paper-F5C842?labelColor=gray&style=flat-square&logo=arxiv&logoColor=white -[arxiv-link]: https://arxiv.org/abs/2601.02163 -[release-badge]: https://img.shields.io/github/v/release/EverMind-AI/EverMemOS?color=369eff&labelColor=gray&logo=github&style=flat-square -[release-date-badge]: https://img.shields.io/github/release-date/EverMind-AI/EverMemOS?labelColor=gray&style=flat-square -[commits-badge]: https://img.shields.io/github/commit-activity/m/EverMind-AI/EverMemOS?labelColor=gray&color=pink&style=flat-square -[issues-closed-badge]: https://img.shields.io/github/issues-search?query=repo%3AEverMind-AI%2FEverMemOS%20is%3Aclosed&label=issues%20closed&labelColor=gray&color=green&style=flat-square -[contributors-badge]: https://img.shields.io/github/contributors/EverMind-AI/EverMemOS?color=c4f042&labelColor=gray&style=flat-square [license-badge]: https://img.shields.io/badge/License-Apache%202.0-blue?labelColor=gray&labelColor=F5C842&style=flat-square @@ -562,73 +553,87 @@ Read our [Contribution Guidelines](CONTRIBUTING.md) for code standards and Git w [lang-zh-badge]: https://img.shields.io/badge/简体中文-lightgrey?style=flat-square -[discord-badge]: https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fdiscord.com%2Fapi%2Fv10%2Finvites%2FgYep5nQRZJ%3Fwith_counts%3Dtrue&query=%24.approximate_presence_count&suffix=%20online&label=Discord&color=5865F2&style=for-the-badge&logo=discord&logoColor=white [discord-members-badge]: https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fdiscord.com%2Fapi%2Fv10%2Finvites%2FgYep5nQRZJ%3Fwith_counts%3Dtrue&query=%24.approximate_member_count&suffix=%20members&label=Discord&color=404EED&style=for-the-badge&logo=discord&logoColor=white [hugging-face-badge]: https://img.shields.io/badge/Hugging_Face-EverMind-F5C842?style=flat&logo=huggingface&logoColor=white [x-badge]: https://img.shields.io/badge/X/Twitter-EverMind-000000?style=flat&logo=x&logoColor=white -[linkedin-badge]: https://img.shields.io/badge/LinkedIn-EverMind-0A66C2?style=flat&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyBmaWxsPSIjZmZmIiByb2xlPSJpbWciIHZpZXdCb3g9IjAgMCAyNCAyNCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48dGl0bGU%2BTGlua2VkSW48L3RpdGxlPjxwYXRoIGQ9Ik0yMC40NDcgMjAuNDUyaC0zLjU1NHYtNS41NjljMC0xLjMyOC0uMDI3LTMuMDM3LTEuODUyLTMuMDM3LTEuODUzIDAtMi4xMzYgMS40NDUtMi4xMzYgMi45Mzl2NS42NjdIOS4zNTFWOWgzLjQxNHYxLjU2MWguMDQ2Yy40NzctLjkgMS42MzctMS44NSAzLjM3LTEuODUgMy42MDEgMCA0LjI2NyAyLjM3IDQuMjY3IDUuNDU1djYuMjg2ek01LjMzNyA3LjQzM2MtMS4xNDQgMC0yLjA2My0uOTI2LTIuMDYzLTIuMDY1IDAtMS4xMzguOTItMi4wNjMgMi4wNjMtMi4wNjMgMS4xNCAwIDIuMDY0LjkyNSAyLjA2NCAyLjA2MyAwIDEuMTM5LS45MjUgMi4wNjUtMi4wNjQgMi4wNjV6bTEuNzgyIDEzLjAxOUgzLjU1NVY5aDMuNTY0djExLjQ1MnpNMjIuMjI1IDBIMS43NzFDLjc5MiAwIDAgLjc3NCAwIDEuNzI5djIwLjU0MkMwIDIzLjIyNy43OTIgMjQgMS43NzEgMjRoMjAuNDUxQzIzLjIgMjQgMjQgMjMuMjI3IDI0IDIyLjI3MVYxLjcyOUMyNCAuNzc0IDIzLjIgMCAyMi4yMjIgMGguMDAzeiIvPjwvc3ZnPg%3D%3D +[linkedin-badge]: https://img.shields.io/badge/LinkedIn-EverMind-0A66C2?style=flat&logo=linkedin&logoColor=white [reddit-badge]: https://img.shields.io/badge/Reddit-EverMind-FF4500?style=flat&logo=reddit&logoColor=white [wechat-badge]: https://img.shields.io/badge/WeChat-EverMind%20社区-07C160?style=for-the-badge&logo=wechat&logoColor=white [deepwiki-badge]: https://deepwiki.com/badge.svg -[readmex-badge]: https://raw.githubusercontent.com/CodePhiliaX/resource-trusteeship/main/readmex.svg + [back-to-top]: https://img.shields.io/badge/-Back_to_top-gray?style=flat-square -[star-us]: #star-us - - -[releases]: https://github.com/EverMind-AI/EverMemOS/releases -[commit-activity]: https://github.com/EverMind-AI/EverMemOS/graphs/commit-activity -[issues-closed]: https://github.com/EverMind-AI/EverMemOS/issues?q=is%3Aissue+is%3Aclosed -[contributors-image]: https://contrib.rocks/image?repo=EverMind-AI/EverMemOS -[contributors]: https://github.com/EverMind-AI/EverMemOS/graphs/contributors -[license]: https://github.com/EverMind-AI/EverMemOS/blob/main/LICENSE +[codespaces-badge]: https://github.com/codespaces/badge.svg - + +[arxiv-link]: https://arxiv.org/abs/2601.02163 [python]: https://www.python.org/ [docker]: https://www.docker.com/ [fastapi]: https://fastapi.tiangolo.com/ [mongodb]: https://www.mongodb.com/ [elasticsearch]: https://www.elastic.co/elasticsearch/ [milvus]: https://milvus.io/ - - +[license]: https://github.com/EverMind-AI/EverMemOS/blob/main/LICENSE +[documentation]: docs/ +[api-docs]: docs/api_docs/memory_api.md [lang-en-readme]: README.md -[lang-zh-readme]: README.md - - +[lang-zh-readme]: README.zh.md +[competition-link]: https://luma.com/n88icl03 +[starter-kit]: docs/STARTER_KIT.md [discord]: https://discord.gg/gYep5nQRZJ -[hugging-face]: https://huggingface.co/EverMind-AI -[x]: https://x.com/EverMindAI -[linkedin]: https://www.linkedin.com/company/ai-evermind -[reddit]: https://www.reddit.com/r/EverMindAI/ [wechat]: https://github.com/EverMind-AI/EverMemOS/discussions/67 - - [deepwiki]: https://deepwiki.com/EverMind-AI/EverMemOS -[readmex]: https://readmex.com/EverMind-AI/EverMemOS - - -[uv]: https://github.com/astral-sh/uv -[deepinfra]: https://deepinfra.com/ -[memos]: https://github.com/usememos/memos -[nemori]: https://github.com/nemori-ai/nemori - - -[documentation]: #documentation -[api-docs]: docs/api_docs/memory_api.md +[usecase-openclaw-link]: https://github.com/EverMind-AI/EverMemOS/tree/agent_memory +[usecase-openclaw-plugin-link]: https://github.com/EverMind-AI/EverMemOS/tree/agent_memory/evermemos-openclaw-plugin +[ten-framework-link]: https://github.com/TEN-framework/ten-framework +[usecase-live2d-link]: https://github.com/TEN-framework/ten-framework/tree/main/ai_agents/agents/examples/voice-assistant-with-EverMemOS +[usecase-computer-link]: https://screenshot-analysis-vercel.vercel.app/ +[usecase-got-link]: https://github.com/EverMind-AI/evermem_got_demo +[usecase-claude-link]: https://github.com/EverMind-AI/evermem-claude-code +[usecase-graph-link]: https://main.d2j21qxnymu6wl.amplifyapp.com/graph.html +[paper-link]: https://arxiv.org/abs/2601.02163 +[overview-doc]: docs/OVERVIEW.md +[architecture-doc]: docs/ARCHITECTURE.md +[full-docs]: docs/ +[changelog-doc]: docs/CHANGELOG.md +[setup-guide]: docs/installation/SETUP.md +[usage-examples]: docs/usage/USAGE_EXAMPLES.md +[interactive-demos]: docs/usage/DEMOS.md +[group-chat-guide]: docs/advanced/GROUP_CHAT_GUIDE.md +[metadata-control-guide]: docs/advanced/METADATA_CONTROL.md +[retrieval-strategies-guide]: docs/advanced/RETRIEVAL_STRATEGIES.md +[batch-operations-guide]: docs/usage/BATCH_OPERATIONS.md [getting-started]: docs/dev_docs/getting_started.md [config-guide]: docs/usage/CONFIGURATION_GUIDE.md [api-usage-guide]: docs/dev_docs/api_usage_guide.md [dev-guide]: docs/dev_docs/development_guide.md +[memory-api-doc]: docs/api_docs/memory_api.md [demo-guide]: demo/README.md [evaluation-guide]: evaluation/README.md +[locomo-link]: https://github.com/snap-research/locomo +[longmemeval-link]: https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned +[personamem-link]: https://huggingface.co/datasets/bowen-upenn/PersonaMem +[evaluation-results-link]: https://huggingface.co/datasets/EverMind-AI/EverMemOS_Eval_Results +[codespaces-link]: https://github.com/features/codespaces +[codespaces-project-link]: https://codespaces.new/EverMind-AI/EverMemOS +[issues-link]: https://github.com/EverMind-AI/EverMemOS/issues +[elliot-x-link]: https://x.com/elliotchen200 +[cyfyifanchen-link]: https://github.com/cyfyifanchen +[contributors-image]: https://contrib.rocks/image?repo=EverMind-AI/EverMemOS +[contributors]: https://github.com/EverMind-AI/EverMemOS/graphs/contributors [contributing-doc]: CONTRIBUTING.md +[citation-doc]: docs/CITATION.md +[acknowledgments-doc]: docs/ACKNOWLEDGMENTS.md +[hugging-face]: https://huggingface.co/EverMind-AI +[x]: https://x.com/EverMindAI +[linkedin]: https://www.linkedin.com/company/ai-evermind +[reddit]: https://www.reddit.com/r/EverMindAI/ - + [share-linkedin-link]: https://linkedin.com/feed/?shareActive=true&text=Check%20this%20repo%20out.%0A%0AEverMemOS%3A%20persistent%20memory%20for%20all%20agents.%0A%0AOpen%20source%20and%20ready%20to%20use.%0A%0Ahttps%3A%2F%2Fgithub.com%2FEverMind-AI%2FEverMemOS -[share-linkedin-shield]: https://img.shields.io/badge/-Share%20on%20LinkedIn-555?labelColor=555&style=flat-square&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyBmaWxsPSIjZmZmIiByb2xlPSJpbWciIHZpZXdCb3g9IjAgMCAyNCAyNCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48dGl0bGU%2BTGlua2VkSW48L3RpdGxlPjxwYXRoIGQ9Ik0yMC40NDcgMjAuNDUyaC0zLjU1NHYtNS41NjljMC0xLjMyOC0uMDI3LTMuMDM3LTEuODUyLTMuMDM3LTEuODUzIDAtMi4xMzYgMS40NDUtMi4xMzYgMi45Mzl2NS42NjdIOS4zNTFWOWgzLjQxNHYxLjU2MWguMDQ2Yy40NzctLjkgMS42MzctMS44NSAzLjM3LTEuODUgMy42MDEgMCA0LjI2NyAyLjM3IDQuMjY3IDUuNDU1djYuMjg2ek01LjMzNyA3LjQzM2MtMS4xNDQgMC0yLjA2My0uOTI2LTIuMDYzLTIuMDY1IDAtMS4xMzguOTItMi4wNjMgMi4wNjMtMi4wNjMgMS4xNCAwIDIuMDY0LjkyNSAyLjA2NCAyLjA2MyAwIDEuMTM5LS45MjUgMi4wNjUtMi4wNjQgMi4wNjV6bTEuNzgyIDEzLjAxOUgzLjU1NVY5aDMuNTY0djExLjQ1MnpNMjIuMjI1IDBIMS43NzFDLjc5MiAwIDAgLjc3NCAwIDEuNzI5djIwLjU0MkMwIDIzLjIyNy43OTIgMjQgMS43NzEgMjRoMjAuNDUxQzIzLjIgMjQgMjQgMjMuMjI3IDI0IDIyLjI3MVYxLjcyOUMyNCAuNzc0IDIzLjIgMCAyMi4yMjIgMGguMDAzeiIvPjwvc3ZnPg%3D%3D +[share-linkedin-shield]: https://img.shields.io/badge/-Share%20on%20LinkedIn-555?labelColor=555&style=flat-square&logo=linkedin&logoColor=white [share-mastodon-link]: https://mastodon.social/share?text=Check%20this%20repo%20out.%0A%0AEverMemOS%3A%20persistent%20memory%20for%20all%20agents.%0A%0AOpen%20source%20and%20ready%20to%20use.%0A%0Ahttps%3A%2F%2Fgithub.com%2FEverMind-AI%2FEverMemOS [share-mastodon-shield]: https://img.shields.io/badge/-Share%20on%20Mastodon-555?labelColor=555&logo=mastodon&logoColor=white&style=flat-square [share-reddit-link]: https://www.reddit.com/submit?title=EverMemOS%3A%20persistent%20memory%20for%20all%20agents.%20Open%20source%20and%20ready%20to%20use.&url=https%3A%2F%2Fgithub.com%2FEverMind-AI%2FEverMemOS diff --git a/README.zh.md b/README.zh.md new file mode 100644 index 00000000..7f7d3bd3 --- /dev/null +++ b/README.zh.md @@ -0,0 +1,648 @@ +
+ +![banner-gif][banner-gif] + +[![][arxiv-badge]][arxiv-link] +[![Python][python-badge]][python] +[![Docker][docker-badge]][docker] +[![FastAPI][fastapi-badge]][fastapi] +[![MongoDB][mongodb-badge]][mongodb] +[![Elasticsearch][elasticsearch-badge]][elasticsearch] +[![Milvus][milvus-badge]][milvus] +[![Ask DeepWiki][deepwiki-badge]][deepwiki] +[![License][license-badge]][license] + +

分享 EverMemOS 仓库

+ +[![][share-x-shield]][share-x-link] +[![][share-linkedin-shield]][share-linkedin-link] +[![][share-reddit-shield]][share-reddit-link] +[![][share-telegram-shield]][share-telegram-link] + + +[文档][documentation] • +[API 参考][api-docs] • +[演示][demo-section] + +[![English][lang-en-badge]][lang-en-readme] +[![简体中文][lang-zh-badge]][lang-zh-readme] + +
+ +
+ +[![Memory Genesis Competition 2026][competition-image]][competition-link] + +> [!IMPORTANT] +> +> ### Memory Genesis Competition 2026 +> +> 欢迎参加我们的 AI [记忆竞赛][competition-link]。无论你是构建创新应用、平台插件，还是改进底层基础设施，只要是基于 EverMemOS 的作品都欢迎提交。 +> +> **赛道：** +> - **Agent + Memory** - 构建具备长期、可演化记忆的智能体 +> - **Platform Plugins** - 将 EverMemOS 集成到 VSCode、Chrome、Slack、Notion、LangChain 等平台 +> - **OS Infrastructure** - 优化核心能力与系统性能 +> +> **[从竞赛 Starter Kit 开始][starter-kit]** +> +> 欢迎加入我们的 [Discord][discord] 提问交流。AMA 面向所有人开放，双周举行一次。 + +
+ + + +## 欢迎来到 EverMemOS + +欢迎来到 EverMemOS。加入我们的社区，一起改进项目，并与来自世界各地的优秀开发者协作。 + +| 社区 | 用途 | +| :--- | :--- | +| [![Discord Members][discord-members-badge]][discord] | 加入 EverMind Discord 社区，与其他用户交流 | +| [![WeChat][wechat-badge]][wechat] | 加入 EverMind 微信群，参与讨论并获取更新 | + + +
+ +## 应用场景 + +[![EverMind + OpenClaw Agent Memory and Plugin][usecase-openclaw-image]][usecase-openclaw-link] + +**EverMind + OpenClaw Agent Memory and Plugin** + +Claw 正在把自己的记忆碎片重新拼起来。想象一个 24/7 在线、拥有持续学习记忆的 Agent，无论你走到哪里，它都能跟着你继续工作。详情可查看 [agent_memory][usecase-openclaw-link] 分支和对应的 [plugin][usecase-openclaw-plugin-link]。 + +![divider][divider-light] +![divider][divider-dark] + +
+ +[![Live2D Character with Memory][usecase-live2d-image]][usecase-live2d-link] + +**Live2D Character with Memory** + +为你的二次元角色加上长期记忆，让它能够与你实时语音互动，底层由 [TEN Framework][ten-framework-link] 驱动。 +更多细节请查看 [Live2D Character with Memory Example][usecase-live2d-link]。 + +![divider][divider-light] +![divider][divider-dark] + +
+ +[![Computer-Use with Memory][usecase-computer-image]][usecase-computer-link] + +**Computer-Use with Memory** + +将 computer-use 与长期记忆结合起来，启动截图分析并把整个过程沉淀进记忆系统。 +更多细节请查看 [在线演示][usecase-computer-link]。 + +![divider][divider-light] +![divider][divider-dark] + +
+ +[![Game of Thrones Memories][usecase-got-image]][usecase-got-link] + +**Game of Thrones Memories** + +这是一个通过《冰与火之歌：权力的游戏》互动问答来展示 AI 记忆基础设施能力的示例。 +更多细节请查看 [代码][usecase-got-link]。 + +![divider][divider-light] +![divider][divider-dark] + +
+ +[![EverMemOS Claude Code Plugin][usecase-claude-image]][usecase-claude-link] + +**EverMemOS Claude Code Plugin** + +为 Claude Code 提供持久化记忆。它会自动保存并召回你过去编程会话中的上下文。 +更多细节请查看 [代码][usecase-claude-link]。 + +![divider][divider-light] +![divider][divider-dark] + +
+ +[![Visualize Memories with Graphs][usecase-graph-image]][usecase-graph-link] + +**Visualize Memories with Graphs** + +Memory Graph 视图会把你存储的实体及其关系可视化出来。这目前还是一个纯前端演示，暂时还没有接入后端，我们正在推进中。 +可查看 [在线演示][usecase-graph-link]。 + + + +
+
+ +[![][back-to-top]][readme-top] + +
+ +## 快速开始 + +### 环境要求 + +- Python 3.10+ • Docker 20.10+ • `uv` 包管理器 • 4GB RAM + +**验证环境：** + +```bash +# 验证所需版本 +python --version # 应为 3.10+ +docker --version # 应为 20.10+ +``` + +### 安装 + +```bash +# 1. 克隆仓库并进入目录 +git clone https://github.com/EverMind-AI/EverMemOS.git +cd EverMemOS + +# 2. 启动 Docker 依赖服务 +docker compose up -d + +# 3. 安装 uv 和项目依赖 +curl -LsSf https://astral.sh/uv/install.sh | sh +uv sync + +# 4. 配置 API Key +cp env.template .env +# 编辑 .env 并设置： +# - LLM_API_KEY（用于记忆提取） +# - VECTORIZE_API_KEY（用于向量化 / rerank） + +# 5. 启动服务 +uv run python src/run.py + +# 6. 验证安装 +curl http://localhost:1995/health +# 期望响应：{"status": "healthy", ...} +``` + +✅ 服务运行地址：`http://localhost:1995` • [完整安装指南][setup-guide] + +
+
+ +[![][back-to-top]][readme-top] + +
+ +## 基础使用 + +通过简单的 Python 代码即可写入并检索记忆： + +```python +import requests + +API_BASE = "http://localhost:1995/api/v1" + +# 1. 存储一条对话记忆 +requests.post(f"{API_BASE}/memories", json={ + "message_id": "msg_001", + "create_time": "2025-02-01T10:00:00+00:00", + "sender": "user_001", + "content": "I love playing soccer on weekends" +}) + +# 2. 搜索相关记忆 +response = requests.get(f"{API_BASE}/memories/search", json={ + "query": "What sports does the user like?", + "user_id": "user_001", + "memory_types": ["episodic_memory"], + "retrieve_method": "hybrid" +}) + +result = response.json().get("result", {}) +for memory_group in result.get("memories", []): + print(f"Memory: {memory_group}") +``` + +📖 [更多示例][usage-examples] • 📚 [API 参考][api-docs] • 🎯 [交互式 Demo][interactive-demos] + +
+
+ +[![][back-to-top]][readme-top] + +
+ +## Demo + +### 运行 Demo + +```bash +# 终端 1：启动 API 服务 +uv run python src/run.py + +# 终端 2：运行简单 Demo +uv run python src/bootstrap.py demo/simple_demo.py +``` + +**现在就试试**：按照 [Demo Guide][interactive-demos] 中的步骤操作即可。 + +### 完整 Demo 体验 + +```bash +# 从样例数据中提取记忆 +uv run python src/bootstrap.py demo/extract_memory.py + +# 启动带记忆的交互式聊天 +uv run python src/bootstrap.py demo/chat_with_memory.py +``` + +更多细节请查看 [Demo Guide][interactive-demos]。 + +
+
+ +[![][back-to-top]][readme-top] + +
+ +## 进阶技巧 + +- **[群聊对话][group-chat-guide]** - 组合多个说话者的消息 +- **[会话元数据控制][metadata-control-guide]** - 精细控制会话上下文 +- **[记忆检索策略][retrieval-strategies-guide]** - 轻量检索与 Agentic 检索 +- **[批量操作][batch-operations-guide]** - 高效处理多条消息 + +
+
+ +[![][back-to-top]][readme-top] + +
+ +## 文档 + +| 指南 | 说明 | +| ---- | ---- | +| [快速开始][getting-started] | 安装与配置 | +| [配置指南][config-guide] | 环境变量与服务配置 | +| [API 使用指南][api-usage-guide] | 接口与数据格式 | +| [开发指南][dev-guide] | 架构与最佳实践 | +| [Memory API][memory-api-doc] | 完整 API 参考 | +| [Demo Guide][demo-guide] | 交互式示例 | +| [评测指南][evaluation-guide] | 基准测试方法 | + +
+
+ +[![][back-to-top]][readme-top] + +
+ +## 评测与基准测试 + +EverMemOS 在 LoCoMo 基准测试上实现了 **93% 总体准确率**，表现优于可比记忆系统。 + +### 基准结果 + +![EverMemOS Benchmark Results][benchmark-image] + +### 支持的基准数据集 + +- **[LoCoMo][locomo-link]** - 面向单跳 / 多跳推理的长上下文记忆基准 +- **[LongMemEval][longmemeval-link]** - 多会话对话记忆评测 +- **[PersonaMem][personamem-link]** - 基于人格画像的记忆评测 + +### 快速开始 + +```bash +# 安装评测依赖 +uv sync --group evaluation + +# 运行 smoke test（快速验证） +uv run python -m evaluation.cli --dataset locomo --system evermemos --smoke + +# 运行完整评测 +uv run python -m evaluation.cli --dataset locomo --system evermemos + +# 查看结果 +cat evaluation/results/locomo-evermemos/report.txt +``` + +📊 [完整评测指南][evaluation-guide] • 📈 [完整结果][evaluation-results-link] + +
+
+ +[![][back-to-top]][readme-top] + +
+ +## GitHub Codespaces + +EverMemOS 支持使用 [GitHub Codespaces][codespaces-link] 进行云端开发。这意味着你不需要在本地手动配置 Docker、网络环境或兼容性问题。 + +[![Open in GitHub Codespaces][codespaces-badge]][codespaces-project-link] + +![divider][divider-light] +![divider][divider-dark] + +### 资源要求 + +| 机器规格 | 状态 | 说明 | +| -------- | ---- | ---- | +| 2-core（免费档） | ❌ 不支持 | 资源不足以运行基础设施服务 | +| 4-core | ✅ 最低可用 | 可以运行，但负载较高时可能较慢 | +| 8-core | ✅ 推荐 | 可较稳定地运行全部服务 | +| 16-core+ | ✅ 最佳 | 适合更重的开发与测试任务 | + +> **说明：** 如果你的公司提供 GitHub Codespaces，通常不会受硬件限制影响，因为企业方案往往可以使用更高规格的机器。 + +### 开始使用 Codespaces + +1. 点击上方 "Open in GitHub Codespaces" 按钮 +2. 在弹窗中选择 **4-core 及以上** 的机器规格 +3. 等待容器构建并自动启动服务 +4. 在 `.env` 中填写 API Key（`LLM_API_KEY`、`VECTORIZE_API_KEY` 等） +5. 运行 `make run` 启动服务 + +MongoDB、Elasticsearch、Milvus、Redis 等基础设施服务都会自动启动，并已预配置为可协同工作。 + +
+
+ +[![][back-to-top]][readme-top] + +
+ +## 提问与支持 + +EverMemOS 已接入以下 AI 驱动问答平台。它们可以帮助你快速、准确地获取答案，并支持从基础安装到高级实现的多语言问题查询。 + +| 服务 | 链接 | +| ---- | ---- | +| DeepWiki | [![Ask DeepWiki][deepwiki-badge]][deepwiki] | + +
+
+ +[![][back-to-top]][readme-top] + +
+ +
+ + +## 🌟 点亮 Star 并关注我们 + +![star us gif][star-gif] + +
+
+ +[![][back-to-top]][readme-top] + +
+ +## 参与贡献 + +我们热爱开源社区的活力。无论你是在修 Bug、做功能、完善文档，还是提出一些大胆的新想法，每一个 PR 都会推动 EverMemOS 往前走。欢迎查看 [Issues][issues-link] 寻找适合你的切入点，然后把你的成果提交给我们。一起构建记忆系统的未来。 + +
+ +> [!TIP] +> +> **欢迎各种形式的贡献** 🎉 +> +> 一起把 EverMemOS 做得更好。从代码到文档，每一份贡献都很重要。也欢迎你把自己的项目分享到社交平台，激发更多人的灵感。 +> +> 欢迎通过 𝕏 联系 EverMemOS 维护者 [@elliotchen200][elliot-x-link]，或通过 GitHub 联系 [@cyfyifanchen][cyfyifanchen-link]，获取项目动态、参与讨论并展开合作。 + +![divider][divider-light] +![divider][divider-dark] + +### 代码贡献者 + +[![EverMemOS Contributors][contributors-image]][contributors] + +![divider][divider-light] +![divider][divider-dark] + +### 贡献指南 + +请阅读 [Contribution Guidelines][contributing-doc] 了解代码规范与 Git 工作流。 + +![divider][divider-light] +![divider][divider-dark] + +### 许可证、引用与鸣谢 + +[Apache 2.0][license] • [Citation][citation-doc] • [Acknowledgments][acknowledgments-doc] + +
+ +
+ +[![][back-to-top]][readme-top] + +
+ + +[readme-top]: #readme-top +[welcome]: #欢迎来到-evermemos +[introduction]: #介绍 +[why-evermemos]: #为什么选择-evermemos +[quick-start]: #快速开始 +[prerequisites]: #环境要求 +[installation]: #安装 +[codespaces]: #github-codespaces +[run-demo]: #运行-demo +[full-demo-experience]: #完整-demo-体验 +[api-usage]: #api-使用 +[evaluation-section]: #评测与基准测试 +[docs-section]: #文档 +[questions-section]: #提问与支持 +[contributing]: #参与贡献 +[demo-section]: #demo + + +[divider-light]: https://github.com/user-attachments/assets/2e2bbcc6-e6d8-4227-83c6-0620fc96f761#gh-light-mode-only +[divider-dark]: https://github.com/user-attachments/assets/d57fad08-4f49-4a1c-bdfc-f659a5d86150#gh-dark-mode-only + + +[banner-gif]: https://github.com/user-attachments/assets/3f22c9a8-a8db-4061-accf-f04c055aa01b +[competition-image]: https://github.com/user-attachments/assets/739a0939-ab1d-4659-81c4-0842466afde9 +[usecase-openclaw-image]: https://github.com/user-attachments/assets/0e06da2b-0236-430f-89b4-980b8b6a855f +[usecase-live2d-image]: https://github.com/user-attachments/assets/a80bdab3-e5d0-43b9-9e8d-0a9605012a26 +[usecase-computer-image]: https://github.com/user-attachments/assets/0d306b4c-bcd7-4e9e-a244-22fa3cb7b727 +[usecase-got-image]: https://github.com/user-attachments/assets/d1efe507-4eb7-4867-8996-457497333449 +[usecase-claude-image]: https://github.com/user-attachments/assets/b40b2241-b0e6-4fc9-9a35-92139f3a2d81 +[usecase-graph-image]: https://github.com/user-attachments/assets/6586e647-dd5f-4f9f-9b26-66f930e8241c +[overview-image]: figs/overview.png +[benchmark-image]: figs/benchmark_2.png +[benchmark-summary-image]: https://github.com/user-attachments/assets/a6ff7523-db24-40f5-96ab-aa94f41b2392 +[star-gif]: https://github.com/user-attachments/assets/0c512570-945a-483a-9f47-8e067bd34484 + + +[arxiv-badge]: https://img.shields.io/badge/arXiv-EverMemOS_Paper-F5C842?labelColor=gray&style=flat-square&logo=arxiv&logoColor=white +[license-badge]: https://img.shields.io/badge/License-Apache%202.0-blue?labelColor=gray&labelColor=F5C842&style=flat-square + + +[python-badge]: https://img.shields.io/badge/Python-3.10+-blue?labelColor=gray&style=flat-square&logo=python&logoColor=white&labelColor=F5C842 +[docker-badge]: https://img.shields.io/badge/Docker-Supported-4A90E2?labelColor=gray&style=flat-square&logo=docker&logoColor=white&labelColor=F5C842 +[fastapi-badge]: https://img.shields.io/badge/FastAPI-Latest-26A69A?labelColor=gray&style=flat-square&logo=fastapi&logoColor=white&labelColor=F5C842 +[mongodb-badge]: https://img.shields.io/badge/MongoDB-7.0+-00C853?labelColor=gray&style=flat-square&logo=mongodb&logoColor=white&labelColor=F5C842 +[elasticsearch-badge]: https://img.shields.io/badge/Elasticsearch-8.x-0084FF?labelColor=gray&style=flat-square&logo=elasticsearch&logoColor=white&labelColor=F5C842 +[milvus-badge]: https://img.shields.io/badge/Milvus-2.4+-00A3E0?labelColor=gray&style=flat-square&labelColor=F5C842 + + +[lang-en-badge]: https://img.shields.io/badge/English-lightgrey?style=flat-square +[lang-zh-badge]: https://img.shields.io/badge/简体中文-lightgrey?style=flat-square + + +[discord-members-badge]: https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fdiscord.com%2Fapi%2Fv10%2Finvites%2FgYep5nQRZJ%3Fwith_counts%3Dtrue&query=%24.approximate_member_count&suffix=%20members&label=Discord&color=404EED&style=for-the-badge&logo=discord&logoColor=white +[hugging-face-badge]: https://img.shields.io/badge/Hugging_Face-EverMind-F5C842?style=flat&logo=huggingface&logoColor=white +[x-badge]: https://img.shields.io/badge/X/Twitter-EverMind-000000?style=flat&logo=x&logoColor=white +[linkedin-badge]: https://img.shields.io/badge/LinkedIn-EverMind-0A66C2?style=flat&logo=linkedin&logoColor=white +[reddit-badge]: https://img.shields.io/badge/Reddit-EverMind-FF4500?style=flat&logo=reddit&logoColor=white +[wechat-badge]: https://img.shields.io/badge/WeChat-EverMind%20社区-07C160?style=for-the-badge&logo=wechat&logoColor=white + + +[deepwiki-badge]: https://deepwiki.com/badge.svg + + +[back-to-top]: https://img.shields.io/badge/-Back_to_top-gray?style=flat-square +[codespaces-badge]: https://github.com/codespaces/badge.svg + + +[arxiv-link]: https://arxiv.org/abs/2601.02163 +[python]: https://www.python.org/ +[docker]: https://www.docker.com/ +[fastapi]: https://fastapi.tiangolo.com/ +[mongodb]: https://www.mongodb.com/ +[elasticsearch]: https://www.elastic.co/elasticsearch/ +[milvus]: https://milvus.io/ +[license]: https://github.com/EverMind-AI/EverMemOS/blob/main/LICENSE +[documentation]: docs/ +[api-docs]: docs/api_docs/memory_api.md +[lang-en-readme]: README.md +[lang-zh-readme]: README.zh.md +[competition-link]: https://luma.com/n88icl03 +[starter-kit]: docs/STARTER_KIT.md +[discord]: https://discord.gg/gYep5nQRZJ +[wechat]: https://github.com/EverMind-AI/EverMemOS/discussions/67 +[deepwiki]: https://deepwiki.com/EverMind-AI/EverMemOS +[usecase-openclaw-link]: https://github.com/EverMind-AI/EverMemOS/tree/agent_memory +[usecase-openclaw-plugin-link]: https://github.com/EverMind-AI/EverMemOS/tree/agent_memory/evermemos-openclaw-plugin +[ten-framework-link]: https://github.com/TEN-framework/ten-framework +[usecase-live2d-link]: https://github.com/TEN-framework/ten-framework/tree/main/ai_agents/agents/examples/voice-assistant-with-EverMemOS +[usecase-computer-link]: https://screenshot-analysis-vercel.vercel.app/ +[usecase-got-link]: https://github.com/EverMind-AI/evermem_got_demo +[usecase-claude-link]: https://github.com/EverMind-AI/evermem-claude-code +[usecase-graph-link]: https://main.d2j21qxnymu6wl.amplifyapp.com/graph.html +[paper-link]: https://arxiv.org/abs/2601.02163 +[overview-doc]: docs/OVERVIEW.md +[architecture-doc]: docs/ARCHITECTURE.md +[full-docs]: docs/ +[changelog-doc]: docs/CHANGELOG.md +[setup-guide]: docs/installation/SETUP.md +[usage-examples]: docs/usage/USAGE_EXAMPLES.md +[interactive-demos]: docs/usage/DEMOS.md +[group-chat-guide]: docs/advanced/GROUP_CHAT_GUIDE.md +[metadata-control-guide]: docs/advanced/METADATA_CONTROL.md +[retrieval-strategies-guide]: docs/advanced/RETRIEVAL_STRATEGIES.md +[batch-operations-guide]: docs/usage/BATCH_OPERATIONS.md +[getting-started]: docs/dev_docs/getting_started.md +[config-guide]: docs/usage/CONFIGURATION_GUIDE.md +[api-usage-guide]: docs/dev_docs/api_usage_guide.md +[dev-guide]: docs/dev_docs/development_guide.md +[memory-api-doc]: docs/api_docs/memory_api.md +[demo-guide]: demo/README.md +[evaluation-guide]: evaluation/README.md +[locomo-link]: https://github.com/snap-research/locomo +[longmemeval-link]: https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned +[personamem-link]: https://huggingface.co/datasets/bowen-upenn/PersonaMem +[evaluation-results-link]: https://huggingface.co/datasets/EverMind-AI/EverMemOS_Eval_Results +[codespaces-link]: https://github.com/features/codespaces +[codespaces-project-link]: https://codespaces.new/EverMind-AI/EverMemOS +[issues-link]: https://github.com/EverMind-AI/EverMemOS/issues +[elliot-x-link]: https://x.com/elliotchen200 +[cyfyifanchen-link]: https://github.com/cyfyifanchen +[contributors-image]: https://contrib.rocks/image?repo=EverMind-AI/EverMemOS +[contributors]: https://github.com/EverMind-AI/EverMemOS/graphs/contributors +[contributing-doc]: CONTRIBUTING.md +[citation-doc]: docs/CITATION.md +[acknowledgments-doc]: docs/ACKNOWLEDGMENTS.md +[hugging-face]: https://huggingface.co/EverMind-AI +[x]: https://x.com/EverMindAI +[linkedin]: https://www.linkedin.com/company/ai-evermind +[reddit]: https://www.reddit.com/r/EverMindAI/ + + +[share-linkedin-link]: https://linkedin.com/feed/?shareActive=true&text=Check%20this%20repo%20out.%0A%0AEverMemOS%3A%20persistent%20memory%20for%20all%20agents.%0A%0AOpen%20source%20and%20ready%20to%20use.%0A%0Ahttps%3A%2F%2Fgithub.com%2FEverMind-AI%2FEverMemOS +[share-linkedin-shield]: https://img.shields.io/badge/-Share%20on%20LinkedIn-555?labelColor=555&style=flat-square&logo=linkedin&logoColor=white +[share-mastodon-link]: https://mastodon.social/share?text=Check%20this%20repo%20out.%0A%0AEverMemOS%3A%20persistent%20memory%20for%20all%20agents.%0A%0AOpen%20source%20and%20ready%20to%20use.%0A%0Ahttps%3A%2F%2Fgithub.com%2FEverMind-AI%2FEverMemOS +[share-mastodon-shield]: https://img.shields.io/badge/-Share%20on%20Mastodon-555?labelColor=555&logo=mastodon&logoColor=white&style=flat-square +[share-reddit-link]: https://www.reddit.com/submit?title=EverMemOS%3A%20persistent%20memory%20for%20all%20agents.%20Open%20source%20and%20ready%20to%20use.&url=https%3A%2F%2Fgithub.com%2FEverMind-AI%2FEverMemOS +[share-reddit-shield]: https://img.shields.io/badge/-Share%20on%20Reddit-555?labelColor=555&logo=reddit&logoColor=white&style=flat-square +[share-telegram-link]: https://t.me/share/url?text=Check%20this%20repo%20out.%0A%0AEverMemOS%3A%20persistent%20memory%20for%20all%20agents.%0A%0AOpen%20source%20and%20ready%20to%20use.&url=https%3A%2F%2Fgithub.com%2FEverMind-AI%2FEverMemOS +[share-telegram-shield]: https://img.shields.io/badge/-Share%20on%20Telegram-555?labelColor=555&logo=telegram&logoColor=white&style=flat-square +[share-weibo-link]: https://service.weibo.com/share/share.php?sharesource=weibo&title=Check%20this%20repo%20out.%0A%0AEverMemOS%3A%20persistent%20memory%20for%20all%20agents.%0A%0AOpen%20source%20and%20ready%20to%20use.&url=https%3A%2F%2Fgithub.com%2FEverMind-AI%2FEverMemOS +[share-weibo-shield]: https://img.shields.io/badge/-Share%20on%20Weibo-555?labelColor=555&logo=sinaweibo&logoColor=white&style=flat-square +[share-whatsapp-link]: https://api.whatsapp.com/send?text=Check%20this%20repo%20out.%0A%0AEverMemOS%3A%20persistent%20memory%20for%20all%20agents.%0A%0AOpen%20source%20and%20ready%20to%20use.%0A%0Ahttps%3A%2F%2Fgithub.com%2FEverMind-AI%2FEverMemOS +[share-whatsapp-shield]: https://img.shields.io/badge/-Share%20on%20WhatsApp-555?labelColor=555&logo=whatsapp&logoColor=white&style=flat-square +[share-x-link]: https://x.com/intent/tweet?text=Check%20this%20repo%20out.%0A%0AEverMemOS%3A%20persistent%20memory%20for%20all%20agents.%0A%0AOpen%20source%20and%20ready%20to%20use.&url=https%3A%2F%2Fgithub.com%2FEverMind-AI%2FEverMemOS +[share-x-shield]: https://img.shields.io/badge/-Share%20on%20X-555?labelColor=555&logo=x&logoColor=white&style=flat-square From f19f62112a0c71f6f7e857a9a9d2ed893b97709d Mon Sep 17 00:00:00 2001 From: Spark Lab Scout Date: Wed, 18 Mar 2026 20:11:49 +0800 Subject: [PATCH 8/8] fix: replace remaining == None with is None, bare except with except Exception MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - mem_memorize.py: 3 instances of == None → is None - mem_db_operations.py: bare except → except Exception - episodic_memory_milvus_repository.py: bare except → except Exception Follows Python best practices (PEP 8) for None comparisons and exception handling. --- src/biz_layer/mem_db_operations.py | 2 +- src/biz_layer/mem_memorize.py | 6 +++--- .../search/repository/episodic_memory_milvus_repository.py | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/biz_layer/mem_db_operations.py b/src/biz_layer/mem_db_operations.py index 66519a42..03800bfd 100644 --- a/src/biz_layer/mem_db_operations.py +++ b/src/biz_layer/mem_db_operations.py @@ -143,7 +143,7 @@ def _convert_timestamp_to_time( try: dt = from_iso_format(timestamp) return to_iso_format(dt) - except: + except Exception: # If parsing fails, return string directly return timestamp else: diff --git a/src/biz_layer/mem_memorize.py b/src/biz_layer/mem_memorize.py index e951a13c..89b4902a 100644 --- a/src/biz_layer/mem_memorize.py +++ b/src/biz_layer/mem_memorize.py @@ -1290,7 +1290,7 @@ async def memorize(request: MemorizeRequest) -> int: # ===== Preprocess and get historical data ===== if request.raw_data_type == RawDataType.CONVERSATION: request = await preprocess_conv_request(request, current_time) - if request == None: + if request is None: logger.warning(f"[mem_memorize] preprocess_conv_request returned None") return 0 @@ -1326,7 +1326,7 @@ async def memorize(request: MemorizeRequest) -> int: ) logger.debug(f"[mem_memorize] Extracting MemCell took: {time.perf_counter() - memcell_start} seconds") - if memcell_result == None: + if memcell_result is None: logger.warning(f"[mem_memorize] Skipped extracting MemCell") return 0 @@ -1345,7 +1345,7 @@ async def memorize(request: MemorizeRequest) -> int: ) logger.info("=" * 80) - if memcell == None: + if memcell is None: # No boundary detected, confirm current messages to accumulation (sync_status: -1 -> 0) await conversation_data_repo.save_conversation_data( request.new_raw_data_list, request.group_id diff --git a/src/infra_layer/adapters/out/search/repository/episodic_memory_milvus_repository.py b/src/infra_layer/adapters/out/search/repository/episodic_memory_milvus_repository.py index 4aad056b..7b1e7131 100644 --- a/src/infra_layer/adapters/out/search/repository/episodic_memory_milvus_repository.py +++ b/src/infra_layer/adapters/out/search/repository/episodic_memory_milvus_repository.py @@ -124,7 +124,7 @@ async def create_and_save_episodic_memory( metadata_json = metadata try: metadata_dict = json.loads(metadata) - except: + except Exception: metadata_dict = {} # Prepare entity data