diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..baa0a719 --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,33 @@ +# Code of Conduct + +EverOS should be a welcoming place for researchers, builders, maintainers, and +first-time contributors. + +## Expected Behavior + +- Be respectful and constructive. +- Assume good intent, especially across language and culture differences. +- Give feedback on ideas and code, not on people. +- Help newcomers find the right context when they are missing it. +- Keep discussions focused on improving the project. + +## Unacceptable Behavior + +- Harassment, threats, insults, or personal attacks. +- Discriminatory language or behavior. +- Publishing private information without permission. +- Repeatedly derailing issues, pull requests, or discussions. +- Any conduct that would make the project unsafe or unwelcoming. + +## Reporting + +If you see or experience unacceptable behavior, contact the maintainers through +GitHub Discussions or the community channels linked in the README. Maintainers +may remove comments, close threads, or restrict participation when needed to +protect the community. + +## Scope + +This code of conduct applies to project spaces, including GitHub issues, pull +requests, discussions, documentation, community chats, and events connected to +EverOS. diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 00000000..d55ce87d --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,83 @@ +# Contributing to EverOS + +Thanks for helping improve EverOS. This repository brings together architecture +methods, benchmarks, and use cases for long-term memory in self-evolving agents, +so there are several useful ways to contribute. + +## Ways to Contribute + +- Improve or extend an architecture method in `methods/`. +- Add benchmark tasks, adapters, or reproducibility notes in `benchmarks/`. +- Add a memory-enabled app, demo, or integration in `use-cases/`. +- Fix documentation, examples, setup steps, or broken links. +- Report bugs with clear reproduction steps and environment details. + +## Development Setup + +Most core development happens in EverCore: + +```bash +git clone https://github.com/EverMind-AI/EverOS.git +cd EverOS/methods/EverCore + +docker compose up -d +uv sync +cp env.template .env +uv run python src/run.py +``` + +Verify the server: + +```bash +curl http://localhost:1995/health +``` + +## Common Commands + +```bash +cd methods/EverCore +make test # Run tests +make lint # Run formatting and i18n checks +uv sync --group evaluation # Install evaluation dependencies +``` + +## Pull Request Checklist + +Before opening a PR, please check: + +- The change is scoped to the relevant area: `methods/`, `benchmarks/`, or + `use-cases/`. +- Setup or behavior changes are documented. +- Tests or manual verification are included when relevant. +- No secrets, `.env` files, generated build output, or dependency folders are + committed. +- Active relative links in Markdown files resolve. + +## Use-Case Contributions + +Use cases should be easy for a new developer to inspect and run. Each use case +should include: + +- A README with what it does, how to run it, and what memory feature it shows. +- A small `.env.example` when configuration is required. +- No committed images, build output, dependency folders, or secrets. + +Images should be hosted with GitHub user attachments or another external asset +URL instead of committed to the repository. + +## Style Notes + +- Follow existing patterns before adding new abstractions. +- EverCore I/O is async; use `await`. +- EverCore is multi-tenant; keep data tenant-scoped. +- Keep prompt changes aligned across + `methods/EverCore/src/memory_layer/prompts/en/` and + `methods/EverCore/src/memory_layer/prompts/zh/` when applicable. + +## Community + +Please keep discussions respectful, constructive, and welcoming. See +`CODE_OF_CONDUCT.md` for expectations. + +By contributing, you agree that your contributions are licensed under the +Apache License 2.0. diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 00000000..81ebb7d1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,54 @@ +name: Bug report +description: Report a reproducible problem in EverOS +title: "[Bug]: " +labels: ["bug"] +body: + - type: markdown + attributes: + value: Thanks for helping improve EverOS. Clear reproduction steps make bugs much faster to fix. + - type: dropdown + id: area + attributes: + label: Area + options: + - methods/EverCore + - methods/HyperMem + - benchmarks/EverMemBench + - benchmarks/EvoAgentBench + - use-cases + - documentation + - other + validations: + required: true + - type: textarea + id: problem + attributes: + label: What happened? + description: Describe the bug and the behavior you expected. + validations: + required: true + - type: textarea + id: reproduce + attributes: + label: Steps to reproduce + placeholder: | + 1. Go to ... + 2. Run ... + 3. See ... + validations: + required: true + - type: textarea + id: environment + attributes: + label: Environment + placeholder: | + OS: + Python: + Node: + Docker: + Commit: + - type: textarea + id: logs + attributes: + label: Logs or screenshots + render: shell diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..33c52338 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: EverOS Discussions + url: https://github.com/EverMind-AI/EverOS/discussions + about: Ask questions, share ideas, and discuss roadmap topics. diff --git a/.github/ISSUE_TEMPLATE/docs.yml b/.github/ISSUE_TEMPLATE/docs.yml new file mode 100644 index 00000000..aa71fc56 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/docs.yml @@ -0,0 +1,22 @@ +name: Documentation issue +description: Report unclear, missing, or outdated documentation +title: "[Docs]: " +labels: ["documentation"] +body: + - type: input + id: page + attributes: + label: Page or file + placeholder: README.md, methods/EverCore/docs/... + validations: + required: true + - type: textarea + id: issue + attributes: + label: What should be improved? + validations: + required: true + - type: textarea + id: suggestion + attributes: + label: Suggested wording or structure diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 00000000..edb795ed --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,40 @@ +name: Feature request +description: Suggest an improvement or new capability +title: "[Feature]: " +labels: ["enhancement"] +body: + - type: dropdown + id: area + attributes: + label: Area + options: + - architecture methods + - benchmarks + - use cases + - developer experience + - documentation + - other + validations: + required: true + - type: textarea + id: problem + attributes: + label: Problem or opportunity + description: What user need, research gap, or workflow pain does this address? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: Describe the change you would like to see. + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + - type: textarea + id: context + attributes: + label: Additional context diff --git a/.github/ISSUE_TEMPLATE/use_case.yml b/.github/ISSUE_TEMPLATE/use_case.yml new file mode 100644 index 00000000..b67ae4c3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/use_case.yml @@ -0,0 +1,37 @@ +name: Use-case proposal +description: Propose an app, demo, or integration for use-cases/ +title: "[Use Case]: " +labels: ["use case"] +body: + - type: textarea + id: summary + attributes: + label: Summary + description: What does the use case demonstrate? + validations: + required: true + - type: textarea + id: memory + attributes: + label: Memory behavior + description: What should the agent remember, retrieve, or evolve over time? + validations: + required: true + - type: textarea + id: stack + attributes: + label: Stack and dependencies + description: List frameworks, services, models, or external APIs. + - type: textarea + id: run + attributes: + label: Run path + description: How should a new developer run or inspect it? + - type: checkboxes + id: checklist + attributes: + label: Contribution checklist + options: + - label: I can include a README with setup instructions. + - label: I can avoid committing secrets, generated output, dependency folders, and image files. + - label: I can include `.env.example` if configuration is needed. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 2a0c77b7..d4008706 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,80 +1,37 @@ -## Description +## Summary - + -## Type of Change +## Area - + -- [ ] Bug fix (non-breaking change that fixes an issue) -- [ ] New feature (non-breaking change that adds functionality) -- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) -- [ ] Documentation update -- [ ] Refactoring (no functional changes) -- [ ] Performance improvement -- [ ] Test improvements -- [ ] Build/CI/CD changes +- [ ] Architecture method +- [ ] Benchmark +- [ ] Use case +- [ ] Documentation +- [ ] Developer experience +- [ ] CI, build, or release -## Related Issues +## Verification - + -Fixes # -Relates to # +```text -## Changes Made - - - -- -- -- - -## Testing - - - -- [ ] Tested locally with manual verification -- [ ] Added/updated unit tests -- [ ] Added/updated integration tests -- [ ] All existing tests pass - -**Test Configuration:** -- OS: -- Python version: -- Database versions (if relevant): - -**Test Results:** -``` -# Paste relevant test output here ``` ## Checklist - - -- [ ] My code follows the project's [code style guidelines](../CONTRIBUTING.md#-code-style) -- [ ] I have performed a self-review of my code -- [ ] I have commented my code where necessary, particularly in complex areas -- [ ] I have updated the documentation accordingly -- [ ] My changes generate no new warnings or errors -- [ ] I have added tests that prove my fix is effective or that my feature works -- [ ] New and existing unit tests pass locally with my changes -- [ ] I have used [Gitmoji](https://gitmoji.dev/) in my commit messages -- [ ] Any dependent changes have been merged and published - -## Screenshots (if applicable) - - - -## Additional Notes - - - -## Breaking Changes +- [ ] I kept the change scoped to the relevant area. +- [ ] I updated docs, examples, or setup notes when behavior changed. +- [ ] I added or updated tests when the change affects behavior. +- [ ] I did not commit secrets, `.env` files, dependency folders, or generated output. +- [ ] Active relative links in Markdown files resolve. - +## Notes for Reviewers ---- + -By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license. +By submitting this pull request, I agree that my contribution is licensed under +the Apache License 2.0. diff --git a/.github/SECURITY.md b/.github/SECURITY.md new file mode 100644 index 00000000..aa122317 --- /dev/null +++ b/.github/SECURITY.md @@ -0,0 +1,33 @@ +# Security Policy + +Thank you for helping keep EverOS and its users safe. + +## Reporting a Vulnerability + +Please do not open a public GitHub issue for a security vulnerability. + +Report suspected vulnerabilities privately through one of the maintainer contact +channels listed in the README, or by opening a GitHub security advisory if that +feature is available for the repository. + +Include as much detail as you can: + +- Affected component or path. +- Steps to reproduce. +- Impact and likely severity. +- Relevant logs, requests, responses, or screenshots. +- Suggested fix, if you have one. + +## Supported Scope + +Security reports are most useful for: + +- EverCore API, storage, tenant isolation, and memory retrieval behavior. +- Authentication, authorization, or data exposure risks. +- Secret handling in examples, demos, and deployment files. +- Benchmark or use-case code that could execute untrusted input unsafely. + +## Disclosure + +Maintainers will review reports and coordinate a fix before public disclosure +when the issue is confirmed. diff --git a/.github/workflows/deploy-website.yml b/.github/workflows/deploy-website.yml index ace1b4f8..5768b1e3 100644 --- a/.github/workflows/deploy-website.yml +++ b/.github/workflows/deploy-website.yml @@ -2,7 +2,7 @@ name: Deploy Website on: push: - branches: [feat/readme-redesign] + branches: [main] paths: - 'benchmarks/EvoAgentBench/website/**' - '.github/workflows/deploy-website.yml' diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..70efe5b3 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,71 @@ +name: Docs + +on: + pull_request: + paths: + - "**/*.md" + - ".github/ISSUE_TEMPLATE/**" + - ".github/PULL_REQUEST_TEMPLATE.md" + - ".github/workflows/docs.yml" + push: + branches: [main] + paths: + - "**/*.md" + - ".github/ISSUE_TEMPLATE/**" + - ".github/PULL_REQUEST_TEMPLATE.md" + - ".github/workflows/docs.yml" + +permissions: + contents: read + +jobs: + links: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Validate active relative Markdown links + run: | + python3 - <<'PY' + from pathlib import Path + import re + import sys + + files = [ + Path("README.md"), + Path("AGENTS.md"), + Path(".github/CONTRIBUTING.md"), + Path(".github/CODE_OF_CONDUCT.md"), + Path(".github/SECURITY.md"), + ] + + missing = [] + for path in files: + if not path.exists(): + continue + text = path.read_text() + active = re.sub(r"", "", text, flags=re.S) + for raw in re.findall(r"\[[^\]]*\]\(([^)]+)\)", active): + link = raw.split("#", 1)[0] + if not link or link.startswith(("http://", "https://", "mailto:")): + continue + target = (path.parent / link).resolve() + try: + target.relative_to(Path.cwd().resolve()) + except ValueError: + missing.append((path, raw, "outside repository")) + continue + if not target.exists(): + missing.append((path, raw, "missing")) + + if missing: + for path, raw, reason in missing: + print(f"{path}: {raw} -> {reason}") + sys.exit(1) + + print("Active relative Markdown links resolve.") + PY + + - name: Validate issue template YAML + run: | + ruby -e 'require "yaml"; Dir[".github/ISSUE_TEMPLATE/*.yml"].sort.each { |p| YAML.load_file(p); puts "YAML ok: #{p}" }' diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..2707448d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,73 @@ +# AGENTS.md + +This repository is organized around the same reader journey as the top-level +README: + +1. **Use cases** show what persistent memory enables in real products and + workflows. +2. **Quick Start** gets EverCore running locally. +3. **Architecture methods** document the memory systems included in EverOS. +4. **Benchmarks** and **Evaluation** show how to measure and reproduce results. + +## Project Map + +- `methods/EverCore/` - long-term memory operating system for agents. +- `methods/HyperMem/` - hypergraph-based hierarchical memory architecture. +- `benchmarks/EverMemBench/` - memory quality evaluation. +- `benchmarks/EvoAgentBench/` - agent self-evolution evaluation. +- `use-cases/` - apps, demos, and integrations built on top of the memory layer. + +## README Guidance + +- Keep the top-level README flow smooth: overview, use cases, quick start, + architecture methods, benchmarks, evaluation, citations, community. +- Avoid repeating the three-part project framing after the overview. Later + sections should act as catalogues or action paths. +- Use repository-relative links in the README, and verify that active relative + links resolve before finishing. +- Keep commented-out README blocks out unless they are intentionally preserved + for a near-term restoration. + +## Open-Source DX Guidance + +- Keep root uncluttered. Prefer community files in `.github/`: + `.github/CONTRIBUTING.md`, `.github/CODE_OF_CONDUCT.md`, + `.github/SECURITY.md`, issue templates, and the pull request template. +- Treat `CITATION.cff` as optional. Add it only if the project wants GitHub's + "Cite this repository" affordance at the cost of one extra root file. +- Favor clear run paths, small examples, and explicit verification commands. +- Make contribution paths obvious for architecture methods, benchmarks, docs, + and use cases. +- Treat broken links, stale setup commands, missing `.env.example` files, and + unclear issue templates as developer-experience bugs. +- Keep `.github/workflows/docs.yml` lightweight and dependency-free so docs + hygiene is easy to trust. + +## Quick Commands + +```bash +cd methods/EverCore +docker compose up -d # Start infrastructure +uv sync # Install dependencies +uv run python src/run.py # Run application +make test # Run tests +make lint # Run formatting/i18n checks +uv run pyright # Type check, if pyright is installed +``` + +## Key Entry Points + +- `methods/EverCore/src/run.py` - EverCore application entry. +- `methods/EverCore/src/agentic_layer/memory_manager.py` - core memory manager. +- `methods/EverCore/src/infra_layer/adapters/input/api/` - REST API controllers. +- `methods/EverCore/docs/` - EverCore setup, usage, and architecture docs. +- `methods/EverCore/evaluation/` - EverCore evaluation runner and reports. + +## Development Notes + +- All I/O is async; use `await`. +- EverCore is multi-tenant; data must remain tenant-scoped. +- Prompts live in `methods/EverCore/src/memory_layer/prompts/` with EN/ZH + variants. +- Prefer existing repo patterns and component boundaries before adding new + abstractions. diff --git a/CLAUDE.md b/CLAUDE.md index 9b2fa45d..f74cd526 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,33 +1,77 @@ # CLAUDE.md -Refer to [AGENTS.md](methods/EverCore/AGENTS.md) for comprehensive project documentation including: -- Project architecture and structure -- Tech stack and dependencies -- Code conventions and patterns -- Key abstractions and files -- Development guidelines -- Database schema + + +This repository is organized around the same reader journey as the top-level +README: + +1. **Use cases** show what persistent memory enables in real products and + workflows. +2. **Quick Start** gets EverCore running locally. +3. **Architecture methods** document the memory systems included in EverOS. +4. **Benchmarks** and **Evaluation** show how to measure and reproduce results. + +## Project Map + +- `methods/EverCore/` - long-term memory operating system for agents. +- `methods/HyperMem/` - hypergraph-based hierarchical memory architecture. +- `benchmarks/EverMemBench/` - memory quality evaluation. +- `benchmarks/EvoAgentBench/` - agent self-evolution evaluation. +- `use-cases/` - apps, demos, and integrations built on top of the memory layer. + +## README Guidance + +- Keep the top-level README flow smooth: overview, use cases, quick start, + architecture methods, benchmarks, evaluation, citations, community. +- Avoid repeating the three-part project framing after the overview. Later + sections should act as catalogues or action paths. +- Use repository-relative links in the README, and verify that active relative + links resolve before finishing. +- Keep commented-out README blocks out unless they are intentionally preserved + for a near-term restoration. + +## Open-Source DX Guidance + +- Keep root uncluttered. Prefer community files in `.github/`: + `.github/CONTRIBUTING.md`, `.github/CODE_OF_CONDUCT.md`, + `.github/SECURITY.md`, issue templates, and the pull request template. +- Treat `CITATION.cff` as optional. Add it only if the project wants GitHub's + "Cite this repository" affordance at the cost of one extra root file. +- Favor clear run paths, small examples, and explicit verification commands. +- Make contribution paths obvious for architecture methods, benchmarks, docs, + and use cases. +- Treat broken links, stale setup commands, missing `.env.example` files, and + unclear issue templates as developer-experience bugs. +- Keep `.github/workflows/docs.yml` lightweight and dependency-free so docs + hygiene is easy to trust. ## Quick Commands ```bash cd methods/EverCore -docker-compose up -d # Start infrastructure +docker compose up -d # Start infrastructure uv sync # Install dependencies -make run # Run application -pytest # Run tests -black src/ && isort src/ # Format code -pyright # Type check +uv run python src/run.py # Run application +make test # Run tests +make lint # Run formatting/i18n checks +uv run pyright # Type check, if pyright is installed ``` ## Key Entry Points -- `methods/EverCore/src/run.py` - Application entry -- `methods/EverCore/src/agentic_layer/memory_manager.py` - Core memory manager -- `methods/EverCore/src/infra_layer/adapters/input/api/` - REST API controllers +- `methods/EverCore/src/run.py` - EverCore application entry. +- `methods/EverCore/src/agentic_layer/memory_manager.py` - core memory manager. +- `methods/EverCore/src/infra_layer/adapters/input/api/` - REST API controllers. +- `methods/EverCore/docs/` - EverCore setup, usage, and architecture docs. +- `methods/EverCore/evaluation/` - EverCore evaluation runner and reports. -## Remember +## Development Notes -- All I/O is async - use `await` -- Multi-tenant system - data is tenant-scoped -- Prompts in `methods/EverCore/src/memory_layer/prompts/` (EN/ZH) +- All I/O is async; use `await`. +- EverCore is multi-tenant; data must remain tenant-scoped. +- Prompts live in `methods/EverCore/src/memory_layer/prompts/` with EN/ZH + variants. +- Prefer existing repo patterns and component boundaries before adding new + abstractions. diff --git a/README.md b/README.md index 62fcf921..ec399917 100644 --- a/README.md +++ b/README.md @@ -3,9 +3,9 @@ ![banner-gif](https://github.com/user-attachments/assets/0bf97efd-580f-4a53-a2a2-58d6daea7290)

- - - + + + X HuggingFace @@ -26,13 +26,13 @@
- [Project Overview](#project-overview) -- [Methods](#methods) -- [Benchmarks](#benchmarks) -- [Quick Start](#quick-start) -- [Evaluation & Benchmarking](#evaluation--benchmarking) - [Use Cases](#use-cases) -- [Citation](#citation) -- [Stay Tuned](#-stay-tuned) +- [Quick Start](#quick-start) +- [Architecture Methods](#architecture-methods) +- [Benchmarks](#benchmarks) +- [Evaluation](#evaluation) +- [Citations](#citations) +- [Stay Tuned](#stay-tuned) - [Contributing](#contributing)
@@ -43,158 +43,185 @@ ## Project Overview -**EverOS** brings together long-term memory **methods**, **benchmarks**, and **use cases** for building self-evolving agents. +**EverOS** is a unified home for building, evaluating, and applying long-term memory in self-evolving agents. The repository is organized around three essential parts: + +| Part | What it gives you | Start here | +| :--- | :--- | :--- | +| **Architecture methods** | Memory systems and algorithms you can run, extend, or compare. | [methods/](methods/) | +| **Benchmarks** | Open evaluation suites for memory quality and agent self-evolution. | [benchmarks/](benchmarks/) | +| **Use cases** | Apps, demos, and integrations showing how memory changes real agent workflows. | [use-cases/](use-cases/) | -At the heart of EverOS is **EverCore** β€” a long-term memory operating system for agents. Follow the [Quick Start](#quick-start) to spin it up in a few minutes. From there, plug it into one of the **use cases** as a template and watch your agent come alive with persistent memory you can actually see and feel. When you are ready to know how good it really is, run the **benchmarks** to measure how your agent remembers, reasons, and evolves. +At the center of EverOS is **EverCore**, a long-term memory operating system for agents. If you are new to the project, scan the use cases first to see what memory enables, then follow the [Quick Start](#quick-start) to run EverCore locally. The architecture and benchmark sections below give you the deeper reference material when you are ready to compare systems or reproduce results. ``` EverOS/ -β”œβ”€β”€ benchmarks/ # Evaluation suites -β”‚ β”œβ”€β”€ EverMemBench/ # Memory quality evaluation -β”‚ └── EvoAgentBench/ # Agent self-evolution evaluation -β”œβ”€β”€ methods/ # Memory architectures -β”‚ β”œβ”€β”€ EverCore/ # Long-term memory operating system -β”‚ └── HyperMem/ # Hypergraph memory architecture -└── use-cases/ # Templates to plug the core into - β”œβ”€β”€ openher/ # OpenHer β€” AI companion with memory - β”œβ”€β”€ claude-code-plugin/ # Claude Code Plugin β€” memory-enhanced code plugin - β”œβ”€β”€ game-of-throne-demo/ # Game of Thrones Demo β€” a memory-enabled game +β”œβ”€β”€ benchmarks/ +β”‚ β”œβ”€β”€ EverMemBench/ +β”‚ └── EvoAgentBench/ +β”œβ”€β”€ methods/ +β”‚ β”œβ”€β”€ EverCore/ +β”‚ └── HyperMem/ +└── use-cases/ + β”œβ”€β”€ claude-code-plugin/ + β”œβ”€β”€ game-of-throne-demo/ + β”œβ”€β”€ openher/ β”œβ”€β”€ ... └── ... ```
-## Architecture Methods - -Methods are memory architectures you can choose from β€” production-ready implementations that give agents persistent, structured long-term memory. Pick the one that fits your use case, or compose them together. +## Use Cases -Full benchmark numbers live in the [Evaluation & Benchmarking](#evaluation--benchmarking) section and in each method's paper. +Use cases show what persistent memory makes possible in real products and workflows. Some examples are packaged in this repository; others point to external demos or integrations you can study and adapt. + + + + -
- +![banner-gif](https://github.com/user-attachments/assets/9dcb3dd4-4402-45fa-ae13-e6782f42c7ea) +#### Earth Online Memory Game -### EverCore +Earth Online is a memory-aware productivity game that turns everyday planning into a living quest log. -A self-organizing memory operating system inspired by biological imprinting. Extracts, structures, and retrieves long-term knowledge from conversations β€” enabling agents to remember, understand, and continuously evolve. + -LoCoMo **93.05%** Β· LongMemEval **83.00%** + -[Paper](https://arxiv.org/abs/2601.02163) Β· [Docs](methods/EverCore/) +![banner-gif](https://github.com/user-attachments/assets/57d8cda7-35a5-4561-b794-5520dffc917b) + +#### Multi-Agent Orchestration Platform + +Golutra presents a multi-agent workforce for engineering teams, extending the IDE model from a single assistant to coordinated agents.
- +![banner-gif](https://github.com/user-attachments/assets/e6eaf308-a874-483f-8874-6934bf95a78f) -### HyperMem +#### Mobi Companion -A hypergraph-based hierarchical memory architecture that captures high-order associations through hyperedges. Organizes memory into topic, event, and fact layers for coarse-to-fine long-term conversation retrieval. +An iOS app where users create, nurture, and live with a personalized AI companion called Mobi. -LoCoMo **92.73%** + -[Paper](https://arxiv.org/abs/2604.08256) Β· [Docs](methods/HyperMem/) +![banner-gif](https://github.com/user-attachments/assets/9aabcaa9-f97a-49d2-9109-0b5bb696ed41) + +#### AI Wearable with Memory + +A context-native AI wearable that listens to everyday life and converts conversations into memory.
+ + -
+![banner-gif](https://github.com/user-attachments/assets/df9677ec-386f-4c56-a428-08bca25c54dc) -## Benchmarks +#### OpenClaw Agent Memory -Benchmarks are designed as **open public standards**. Any memory architecture or agent framework can be evaluated under the same ruler. +A 24/7 agent workflow with continuous learning memory across sessions. - - +[Agent Memory](https://github.com/EverMind-AI/everos/tree/agent_memory) Β· [Plugin](https://github.com/EverMind-AI/everos/tree/agent_memory/everos-openclaw-plugin) + + + + - -
- +![banner-gif](https://github.com/user-attachments/assets/3a2357a1-c0c3-464a-8979-0d1cdfc9b0d4) -### EverMemBench +#### Live2D Character with Memory -Three-layer memory quality evaluation: factual recall, applied reasoning, and personalized generalization. Evaluates memory systems and LLMs under a unified standard. +Add long-term memory to a real-time Live2D character, powered by [TEN Framework](https://github.com/TEN-framework/ten-framework). -[Paper](https://arxiv.org/abs/2602.01313) Β· [Dataset](https://huggingface.co/datasets/EverMind-AI/EverMemBench-Dynamic) Β· [Docs](benchmarks/EverMemBench/) +[Code](https://github.com/TEN-framework/ten-framework/tree/main/ai_agents/agents/examples/voice-assistant-with-everos)
- +![banner-gif](https://github.com/user-attachments/assets/c36bdc04-97d3-4fe9-97d9-4b93b475595a) -### EvoAgentBench +#### Computer-Use with Memory -Agent self-evolution evaluation β€” not static snapshots, but longitudinal growth curves. Measures transfer efficiency, error avoidance, and skill-hit quality through controlled experiments with and without evolution. +Run screenshot-based analysis with computer-use and store the results in memory. -[Docs](benchmarks/EvoAgentBench/) +[Live Demo](https://screenshot-analysis-vercel.vercel.app/)
+ +[![banner-gif](https://github.com/user-attachments/assets/54a7cf8f-62c4-4fbc-9d50-b214d034e051)](use-cases/game-of-throne-demo) +#### Game of Thrones Memories -
-

+A demonstration of AI memory infrastructure through an interactive Q&A experience with *A Game of Thrones*. -[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) +[Code](use-cases/game-of-throne-demo) -
+ + + + - + ## Quick Start +Choose the path that matches your goal: + ```bash git clone https://github.com/EverMind-AI/EverOS.git cd EverOS ``` -Then navigate to the component you need: - -| | Component | Entry Point | -| :-- | :--- | :--- | -| **EverCore** | Build agents with long-term memory | [methods/EverCore/](methods/EverCore/) | -| **HyperMem** | Use the hypergraph memory architecture | [methods/HyperMem/](methods/HyperMem/) | -| **EverMemBench** | Evaluate memory system quality | [benchmarks/EverMemBench/](benchmarks/EverMemBench/) | -| **EvoAgentBench** | Measure agent self-evolution | [benchmarks/EvoAgentBench/](benchmarks/EvoAgentBench/) | +| Goal | Component | Entry Point | +| :--- | :--- | :--- | +| Build agents with long-term memory | **EverCore** | [methods/EverCore/](methods/EverCore/) | +| Explore the hypergraph memory architecture | **HyperMem** | [methods/HyperMem/](methods/HyperMem/) | +| Evaluate memory system quality | **EverMemBench** | [benchmarks/EverMemBench/](benchmarks/EverMemBench/) | +| Measure agent self-evolution | **EvoAgentBench** | [benchmarks/EvoAgentBench/](benchmarks/EvoAgentBench/) | +| Adapt an example app or integration | **Use cases** | [use-cases/](use-cases/) | > Each component has its own installation guide, dependency configuration, and usage examples. ### EverCore +The fastest way to run a memory system locally is to start with EverCore: + ```bash cd methods/EverCore @@ -219,7 +246,7 @@ curl http://localhost:1995/health # Expected response: {"status": "healthy", ...} ``` -Server runs at `http://localhost:1995` Β· [Full Setup Guide](docs/installation/SETUP.md) +Server runs at `http://localhost:1995` Β· [Full Setup Guide](methods/EverCore/docs/installation/SETUP.md) ### Basic Usage @@ -251,7 +278,7 @@ for memory_group in result.get("memories", []): print(f"Memory: {memory_group}") ``` -[More Examples](docs/usage/USAGE_EXAMPLES.md) Β· [API Reference](https://docs.evermind.ai/api-reference/introduction) Β· [Interactive Demos](docs/usage/DEMOS.md) +[More Examples](methods/EverCore/docs/usage/USAGE_EXAMPLES.md) Β· [API Reference](https://docs.evermind.ai/api-reference/introduction) Β· [Interactive Demos](methods/EverCore/docs/usage/DEMOS.md)
@@ -260,70 +287,40 @@ for memory_group in result.get("memories", []):
- + + + + + +
-## Evaluation & Benchmarking + -EverCore achieves **93% overall accuracy** on the LoCoMo benchmark, outperforming comparable memory systems. +### EverCore -### Benchmark Results +A self-organizing memory operating system inspired by biological imprinting. Extracts, structures, and retrieves long-term knowledge from conversations so agents can remember, understand, and continuously evolve. -![EverOS Benchmark Results](https://github.com/user-attachments/assets/41b656e7-6f82-41b7-891d-d6079d10dd39) +LoCoMo **93.05%** Β· LongMemEval **83.00%** -### Supported Benchmarks +[Paper](https://arxiv.org/abs/2601.02163) Β· [Docs](methods/EverCore/) -- **[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 + -### Run Evaluations + -```bash -# Install evaluation dependencies -uv sync --group evaluation +### HyperMem -# Run smoke test (quick verification) -uv run python -m evaluation.cli --dataset locomo --system everos --smoke +A hypergraph-based hierarchical memory architecture that captures high-order associations through hyperedges, with topic, event, and fact layers for coarse-to-fine conversation retrieval. -# Run full evaluation -uv run python -m evaluation.cli --dataset locomo --system everos +LoCoMo **92.73%** -# View results -cat evaluation/results/locomo-everos/report.txt -``` +[Paper](https://arxiv.org/abs/2604.08256) Β· [Docs](methods/HyperMem/) -[Full Evaluation Guide](evaluation/README.md) Β· [Complete Results](https://huggingface.co/datasets/EverMind-AI/everos_Eval_Results) +

@@ -332,153 +329,77 @@ cat evaluation/results/locomo-everos/report.txt
- -## Use Cases +These benchmarks provide shared standards for measuring memory quality and agent self-evolution across systems. - - - - - - - - - - - - -
-![banner-gif](https://github.com/user-attachments/assets/9dcb3dd4-4402-45fa-ae13-e6782f42c7ea) - -#### Earth Online Memory Game - -Earth Online is a memory-aware productivity game that turns everyday planning into a living quest log.Β  - - - - - -![banner-gif](https://github.com/user-attachments/assets/57d8cda7-35a5-4561-b794-5520dffc917b) - -#### Multi‑Agent Orchestration Platform - -Golutra is pitched as β€œbeyond the IDE,” aΒ multi-agentΒ workforce rather than a single assistant for engineering teams. - -
- -![banner-gif](https://github.com/user-attachments/assets/e6eaf308-a874-483f-8874-6934bf95a78f) - -#### Mobi Is a Companion - -An iOS app that lets users create, nurture, and live with a personalized AI β€œlifeform” companion calledΒ Mobi. - - - -![banner-gif](https://github.com/user-attachments/assets/9aabcaa9-f97a-49d2-9109-0b5bb696ed41) - -#### AI Wearable with Memory - -A context-native empathic AI wearable that listens to everyday life -and converts conversations into memory. - -
- -![banner-gif](https://github.com/user-attachments/assets/df9677ec-386f-4c56-a428-08bca25c54dc) + -#### OpenClaw Agent Memory +### EverMemBench -A 24/7 agent with continuous learning memory that you can carry with you wherever you go. +Three-layer memory quality evaluation: factual recall, applied reasoning, and personalized generalization. -[Agent Memory](https://github.com/EverMind-AI/everos/tree/agent_memory) Β· [Plugin](https://github.com/EverMind-AI/everos/tree/agent_memory/everos-openclaw-plugin) +[Paper](https://arxiv.org/abs/2602.01313) Β· [Dataset](https://huggingface.co/datasets/EverMind-AI/EverMemBench-Dynamic) Β· [Docs](benchmarks/EverMemBench/) -![banner-gif](https://github.com/user-attachments/assets/3a2357a1-c0c3-464a-8979-0d1cdfc9b0d4) + -#### Live2D Character with Memory +### EvoAgentBench -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). +Agent self-evolution evaluation through longitudinal growth curves, transfer efficiency, error avoidance, and skill-hit quality. -[Code](https://github.com/TEN-framework/ten-framework/tree/main/ai_agents/agents/examples/voice-assistant-with-everos) +[Docs](benchmarks/EvoAgentBench/)
- -![banner-gif](https://github.com/user-attachments/assets/c36bdc04-97d3-4fe9-97d9-4b93b475595a) - -#### Computer-Use with Memory - -Use computer-use to launch screenshot-based analysis, all stored in your memory. - -[Live Demo](https://screenshot-analysis-vercel.vercel.app/) +
- - +
+
-[![banner-gif](https://github.com/user-attachments/assets/54a7cf8f-62c4-4fbc-9d50-b214d034e051)](use-cases/game-of-throne-demo) +[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) -#### Game of Thrones Memories +
-A demonstration of AI memory infrastructure through an interactive Q&A experience with "A Game of Thrones". +## Evaluation -[Code](use-cases/game-of-throne-demo) +Use the evaluation runner to reproduce EverCore results or compare another memory system against the same benchmark tasks. - - - - +### Benchmark Results -[![banner-gif](https://github.com/user-attachments/assets/af37c1f6-7ba5-430c-b99d-2a7e7eac618f)](use-cases/claude-code-plugin) +![EverOS Benchmark Results](https://github.com/user-attachments/assets/41b656e7-6f82-41b7-891d-d6079d10dd39) -#### Claude Code Plugin +### Supported Benchmarks -Persistent memory for Claude Code. Automatically saves and recalls context from past coding sessions. +- **[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 -[Code](use-cases/claude-code-plugin) +### Run Evaluations - - +```bash +cd methods/EverCore -![banner-gif](https://github.com/user-attachments/assets/d521d28c-0ccd-44ff-aecc-828245e2f973) +# Install evaluation dependencies +uv sync --group evaluation -#### Memory Graph Visualization +# Run smoke test (quick verification) +uv run python -m evaluation.cli --dataset locomo --system everos --smoke -Visualize your stored entities and how they relate. Pure frontend demo β€” backend integration in progress. +# Run full evaluation +uv run python -m evaluation.cli --dataset locomo --system everos -[Live Demo](https://main.d2j21qxnymu6wl.amplifyapp.com/graph.html) +# View results +cat evaluation/results/locomo-everos/report.txt +``` - - - +[Full Evaluation Guide](methods/EverCore/evaluation/README.md) Β· [Complete Results](https://huggingface.co/datasets/EverMind-AI/everos_Eval_Results)
@@ -487,9 +408,9 @@ Visualize your stored entities and how they relate. Pure frontend demo β€” backe
-## Citation +## Citations -If EverOS helps your research, please cite: +If EverOS helps your research, please cite the relevant paper: ```bibtex @article{hu2026evermemos, @@ -521,7 +442,9 @@ If EverOS helps your research, please cite: -## 🌟 Stay Tuned +## Stay Tuned + +Star the repo or join the community links above to follow new architecture methods, benchmark releases, and memory-enabled use cases. ![star us gif](https://github.com/user-attachments/assets/0c512570-945a-483a-9f47-8e067bd34484) @@ -534,7 +457,7 @@ If EverOS helps your research, please cite: ## Contributing -We love open-source energy! Whether you are squashing bugs, shipping features, sharpening docs, or just tossing in wild ideas, every PR moves EverOS forward. Browse [Issues](https://github.com/EverMind-AI/EverOS/issues) to find your perfect entry point, then show us what you have got. Let us build the future of memory together. +Contributions are welcome across the whole repository: architecture methods, benchmark coverage, use-case examples, documentation, and bug fixes. Browse [Issues](https://github.com/EverMind-AI/EverOS/issues) to find a good entry point, then open a PR when you are ready.
@@ -542,7 +465,7 @@ We love open-source energy! Whether you are squashing bugs, shipping features, s > > **Welcome all kinds of contributions** πŸŽ‰ > -> Join us in building EverOS better! Every contribution makes a difference, from code to documentation. Share your projects on social media to inspire others! +> Help make EverOS better. Code, documentation, benchmark reports, use-case write-ups, and integration examples are all valuable. Share your projects on social media to inspire others. > > Connect with one of the EverOS maintainers [@elliotchen200](https://x.com/elliotchen200) on 𝕏 or [@cyfyifanchen](https://github.com/cyfyifanchen) on GitHub for project updates, discussions, and collaboration opportunities. @@ -558,14 +481,14 @@ We love open-source energy! Whether you are squashing bugs, shipping features, s ### Contribution Guidelines -Read our [Contribution Guidelines](methods/EverCore/CONTRIBUTING.md) for code standards and Git workflow. +Read the [Contribution Guidelines](.github/CONTRIBUTING.md) for setup, pull request expectations, and use-case submission notes. For responsible disclosure, see the [Security Policy](.github/SECURITY.md). ![divider](https://github.com/user-attachments/assets/2e2bbcc6-e6d8-4227-83c6-0620fc96f761#gh-light-mode-only) ![divider](https://github.com/user-attachments/assets/d57fad08-4f49-4a1c-bdfc-f659a5d86150#gh-dark-mode-only) -### License & Citation & Acknowledgments +### License, Conduct, and Acknowledgments -[Apache 2.0](https://github.com/EverMind-AI/EverOS/blob/main/LICENSE) β€’ [Acknowledgments](methods/EverCore/docs/ACKNOWLEDGMENTS.md) +[Apache 2.0](https://github.com/EverMind-AI/EverOS/blob/main/LICENSE) β€’ [Code of Conduct](.github/CODE_OF_CONDUCT.md) β€’ [Acknowledgments](methods/EverCore/docs/ACKNOWLEDGMENTS.md)