{"owner":"MemTensor","repo":"MemOS","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","CLAUDE.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\n> Single source of truth for the project across AI runtimes. Claude Code, Codex, Cursor, Copilot, etc. all defer to this file.\n> Runtime-specific adaptation belongs in each runtime's own file (Claude reads `CLAUDE.md`); do not mix it in here.\n\n## Project Overview\n\n**MemOS / MemoryOS**: a memory operating system for LLM agents. Python library plus a FastAPI service, providing multiple memory types (textual / tree / preference / skill / KV cache / LoRA parametric) plus scheduling, version management, and vector & graph storage.\n\n- **Repository**: https://github.com/MemTensor/MemOS\n- **Documentation**: https://memos-docs.openmem.net/home/overview/\n- **PyPI**: https://pypi.org/project/MemoryOS/\n- **License**: Apache-2.0\n- **Top-level package**: `src/memos/`. Distribution name `MemoryOS`; import name `memos`.\n- **CLI**: `memos` (entry `memos.cli:main`)\n- **API service**: `memos.api.start_api:app`\n\n## Repository Layout\n\n| Path | Purpose |\n|------|---------|\n| `src/memos/mem_os/` | `MOS` / `MOSCore` — top-level Memory OS entry |\n| `src/memos/mem_cube/` | `GeneralMemCube` — memory container aggregating multiple memory types |\n| `src/memos/memories/` | Memory implementations: `textual/`, `activation/`, `parametric/` |\n| `src/memos/mem_scheduler/` | Memory scheduler + monitors + ORM + task scheduling |\n| `src/memos/mem_user/` | User / multi-tenant management (MySQL / Redis backends) |\n| `src/memos/mem_chat/` `mem_reader/` `mem_agent/` `mem_feedback/` `multi_mem_cube/` | Chat sessions, ingest pipeline, agent integration, feedback channel, multi-cube routing |\n| `src/memos/llms/` `embedders/` `vec_dbs/` `graph_dbs/` `chunkers/` `parsers/` `reranker/` | Provider implementations (`base.py` + `factory.py` + each backend) |\n| `src/memos/api/` | FastAPI service (routers / handlers / middleware / MCP server) |\n| `src/memos/configs/` | All pydantic configuration classes (one-to-one with the modules above) |\n| `src/memos/context/` | Cross-thread context (trace_id / user / env) |\n| `tests/` | pytest cases, subdirectories mirror `src/memos/` |\n| `apps/` | Independent sub-projects, each with its own README; not part of the main Harness flow |\n| `extensions/` | Official plugin examples |\n| `docker/` `docs/` `evaluation/` `scripts/` | Deployment, documentation, evaluation, helper scripts |\n| `.claude/agents/`, `.codex/agents/` | Project-recommended AI sub-agent definitions |\n\n## Command Cheatsheet\n\n- Install: `make install` (= `poetry install --extras all --with dev --with test` + pre-commit + push hook)\n- Start API: `make serve`\n- Export OpenAPI: `make openapi` (writes to `docs/openapi.json`)\n- Run full tests: `make test`\n- Run a single test: `poetry run pytest tests/<path>/test_xxx.py -q`\n- Lint + format: `make format`\n- Full pre-commit: `make pre_commit`\n- Build: `poetry build` (publishing is automated by `python-release.yml` on GitHub release)\n\n## Core API\n\n### Python top-level entries (`from memos import ...`)\n\n| Symbol | Purpose | Source |\n|--------|---------|--------|\n| `MOS` | Memory OS top-level entry (inherits `MOSCore`) | `memos.mem_os.main` |\n| `GeneralMemCube` | General memory container | `memos.mem_cube.general` |\n| `MOSConfig` / `GeneralMemCubeConfig` | Primary configs | `memos.configs.mem_os` / `memos.configs.mem_cube` |\n| `GeneralScheduler` / `SchedulerFactory` / `SchedulerConfigFactory` | Scheduler and factories | `memos.mem_scheduler.*` |\n\nCommon `MOS` methods: `MOS.simple()` (auto-configure from env), `register_mem_cube(cube)`, `add(...)`, `search(...)`, `chat(...)`, `create_user(...)` / `list_users()`.\n\n### API entry\n\n- ASGI app: `memos.api.start_api:app`\n- Routers: `src/memos/api/routers/` (`admin_router`, `product_router`, `server_router`)\n- OpenAPI contract: `docs/openapi.json` (must run `make openapi` after touching the API)\n\n## Import Patterns\n\n| Use | Import |\n|-----|--------|\n| Top-level entries | `from memos import MOS, GeneralMemCube, MOSConfig` |\n| Config classes | `from memos.configs.<submodule> import <Config>` |\n| Any provider factory | `from memos.<category>.factory import <Category>Factory` |\n| Logger | `from memos.log import get_logger`; `logger = get_logger(__name__)` |\n| Context (trace) | `from memos.context.context import get_current_trace_id, get_current_user_name` |\n| Exceptions | `from memos.exceptions import <semantic Exception>` |\n\n## Provider Matrix\n\nEvery provider follows the same three-piece pattern: `base.py` abstract class + `factory.py` registry + `configs/<category>.py` config. The authoritative list of registered backends is the factory's `backend_to_class`; the snapshot below is provided for quick reference:\n\n| Category | Base class | Factory | Registered backends |\n|----------|-----------|---------|---------------------|\n| LLM | `BaseLLM` | `LLMFactory` | `openai` / `openai_new` / `azure` / `ollama` / `huggingface` / `huggingface_singleton` / `vllm` / `qwen` / `deepseek` |\n| Embedder | `BaseEmbedder` | `EmbedderFactory` | `ollama` / `sentence_transformer` / `ark` / `universal_api` |\n| Vector DB | `BaseVecDB` | `VecDBFactory` | `qdrant` / `milvus` |\n| Graph DB | `BaseGraphDB` | `GraphStoreFactory` | `neo4j` / `neo4j_community` / `nebular` / `polardb` / `postgres` |\n| Chunker | `BaseChunker` | `ChunkerFactory` | `sentence` / `markdown` / `simple` / `charactertext` |\n| Parser | `BaseParser` | `ParserFactory` | `markitdown` |\n| Reranker | `BaseReranker` | `RerankerFactory` | `cosine_local` / `http_bge` / `http_bge_strategy` / `concat` / `noop` |\n| Memory | `BaseMemory` (+ `BaseTextMemory` / `BaseActMemory` / `BaseParaMemory`) | `MemoryFactory` | `naive_text` / `general_text` / `tree_text` / `simple_tree_text` / `pref_text` / `simple_pref_text` / `kv_cache` / `vllm_kv_cache` / `lora` |\n| Scheduler | `BaseScheduler` | `SchedulerFactory` | `general` / `optimized` |\n\n## Adding a New Provider\n\nMirror any existing provider in the same category:\n\n1. Implement `src/memos/<category>/<backend>.py`, inheriting the `base.py` abstract class and matching the signatures of existing providers.\n2. Add a pydantic config in `src/memos/configs/<category>.py` and register it in `<Category>ConfigFactory.backend_to_class`.\n3. Register the implementation in `<Category>Factory.backend_to_class` in `src/memos/<category>/factory.py`.\n4. Third-party dependencies **must** go into an optional extras group in `pyproject.toml` (`tree-mem` / `mem-scheduler` / `mem-user` / `mem-reader` / `pref-mem` / `skill-mem`) and be added to `all`; guard the import with try/except ImportError and raise a clear \"install extras X\" message on failure.\n5. Add tests under `tests/<category>/test_<backend>.py`; external HTTP / model loading must be mocked.\n\n## Behavior Boundaries\n\n### Always do\n\n- Write a failing test first (TDD), placed under `tests/<corresponding module>/test_*.py`.\n- Before claiming a task is done, run verification commands and paste the real output (at minimum `make format` plus the relevant pytest run).\n- Keep changes within the directories the current task authorizes; cross-module edits need to be called out and approved first.\n- Use `memos.log.get_logger(__name__)` for logging; route trace info through `memos.context.context` — do not `print`.\n- Optional third-party dependencies (neo4j / redis / pika / pymilvus / markitdown, etc.) must be guarded with try/except ImportError and declared in the matching extras group.\n- After touching `src/memos/api/`, run `make openapi` to refresh `docs/openapi.json`.\n\n### Ask first\n\n- Modifying `pyproject.toml` dependencies or the Python version constraint.\n- Touching public routes, request/response models, or the OpenAPI contract under `src/memos/api/`.\n- Changing DB schema, migrations, `mem_user` tables, or `graph_dbs` graph models.\n- Deleting files or doing wide-scope renames of public APIs (`memos.*` top-level symbols).\n- Editing `Makefile`, `.pre-commit-config.yaml`, `pyproject.toml [tool.*]`, or `.github/workflows/`.\n\n### Never do (IMPORTANT)\n\n- **Never** commit `.env`, `private/`, `.private-paths`, `tmp/`, `*.log`, secrets, tokens, or model credentials.\n- Do not log or include real API keys, raw user data, or vector contents in tests/fixtures.\n- Do not skip `pre-commit` or push with `--no-verify` (the `scripts/check-public-push.sh` pre-push hook is enforced).\n- Do not claim tests pass without real pytest output as evidence.\n- Do not add third-party dependencies to core `dependencies` — they must go into optional extras.\n- Do not run wide-scope `rm -rf` outside `src/`; do not `git push --force` or `git reset --hard origin/*`.\n\n## Code Style\n\n- Format and lint with Ruff (configured in `pyproject.toml [tool.ruff]`); `make format` must pass before commit.\n- Type annotations are required on public functions, API schemas, and config classes; implicit `Optional` is not allowed (enforced via pre-commit).\n- All configs and API schemas use Pydantic v2.\n- Logging: `logger.info(\"... %s\", x)` form — do not pre-format with f-strings before passing to the logger.\n- Exceptions: library code raises semantic exceptions from `memos.exceptions`, never bare `Exception` / `RuntimeError`; the API layer translates them to HTTP errors in `memos.api.exceptions`.\n- File naming: source `snake_case.py`, tests `test_<module>.py`.\n\n## Change → Test Mapping\n\n- Edit `src/memos/<module>/`: at minimum run `pytest tests/<corresponding module>/ -q`; run `make test` once more before merging.\n- Edit `src/memos/api/`: run `tests/api/` and `make openapi` to confirm the OpenAPI spec did not change unexpectedly.\n- Edit `pyproject.toml` dependencies: `poetry lock --no-update`, then `make test`.\n- Edit `Makefile` / pre-commit / Ruff config: run `make pre_commit` locally over the whole tree.\n\n## Git Conventions\n\n- Commits: Conventional Commits (`feat:` / `fix:` / `chore:` / `refactor:` / `docs:`), subject line ≤ 72 chars.\n- Branches: `feat/<slug>` / `fix/<slug>` / `dev-YYYYMMDD-v<version>`.\n- `main` is protected — all changes go through PRs; never force-push to `main`; do not skip git hooks.\n- Do not commit paths listed in `.private-paths`.\n- The PR template lives at `.github/PULL_REQUEST_TEMPLATE.md` — its checklist must be fully ticked.\n","CLAUDE.md":"# CLAUDE.md\n\n## Claude Code Entry\n\nProject facts live in `AGENTS.md`. This file only covers Claude Code runtime adaptation.\n\n## Sub-agents\n\nFive project-recommended sub-agents live under `.claude/agents/*.md`. Claude Code loads them automatically; the main agent should dispatch by task boundary:\n\n| Agent | Permissions | When to use |\n|-------|-------------|-------------|\n| `explorer` | Read-only | Locate code, trace call chains, gather evidence |\n| `design-reviewer` | Read-only | Review design docs (architecture / interface / performance / security / requirement coverage) |\n| `code-reviewer` | Read-only | Review diffs and return APPROVE or CHANGES_REQUESTED |\n| `backend-dev` | Read-write | Implement backend / library code under `src/memos/` (TDD) |\n| `integration-tester` | Read-write | Author and run integration / end-to-end cases under `tests/` |\n\nThe main repo has no frontend stack, so no `frontend-dev` is provided; TypeScript sub-projects under `apps/` use their own AI configuration.\n\n## Project knowledge\n\nBefore starting a task, run `ls docs/`. `docs/openapi.json` is the source of truth for the API contract; after touching `src/memos/api/`, run `make openapi` to regenerate it.\n"},"files":{"AGENTS.md":"# AGENTS.md\n\n> Single source of truth for the project across AI runtimes. Claude Code, Codex, Cursor, Copilot, etc. all defer to this file.\n> Runtime-specific adaptation belongs in each runtime's own file (Claude reads `CLAUDE.md`); do not mix it in here.\n\n## Project Overview\n\n**MemOS / MemoryOS**: a memory operating system for LLM agents. Python library plus a FastAPI service, providing multiple memory types (textual / tree / preference / skill / KV cache / LoRA parametric) plus scheduling, version management, and vector & graph storage.\n\n- **Repository**: https://github.com/MemTensor/MemOS\n- **Documentation**: https://memos-docs.openmem.net/home/overview/\n- **PyPI**: https://pypi.org/project/MemoryOS/\n- **License**: Apache-2.0\n- **Top-level package**: `src/memos/`. Distribution name `MemoryOS`; import name `memos`.\n- **CLI**: `memos` (entry `memos.cli:main`)\n- **API service**: `memos.api.start_api:app`\n\n## Repository Layout\n\n| Path | Purpose |\n|------|---------|\n| `src/memos/mem_os/` | `MOS` / `MOSCore` — top-level Memory OS entry |\n| `src/memos/mem_cube/` | `GeneralMemCube` — memory container aggregating multiple memory types |\n| `src/memos/memories/` | Memory implementations: `textual/`, `activation/`, `parametric/` |\n| `src/memos/mem_scheduler/` | Memory scheduler + monitors + ORM + task scheduling |\n| `src/memos/mem_user/` | User / multi-tenant management (MySQL / Redis backends) |\n| `src/memos/mem_chat/` `mem_reader/` `mem_agent/` `mem_feedback/` `multi_mem_cube/` | Chat sessions, ingest pipeline, agent integration, feedback channel, multi-cube routing |\n| `src/memos/llms/` `embedders/` `vec_dbs/` `graph_dbs/` `chunkers/` `parsers/` `reranker/` | Provider implementations (`base.py` + `factory.py` + each backend) |\n| `src/memos/api/` | FastAPI service (routers / handlers / middleware / MCP server) |\n| `src/memos/configs/` | All pydantic configuration classes (one-to-one with the modules above) |\n| `src/memos/context/` | Cross-thread context (trace_id / user / env) |\n| `tests/` | pytest cases, subdirectories mirror `src/memos/` |\n| `apps/` | Independent sub-projects, each with its own README; not part of the main Harness flow |\n| `extensions/` | Official plugin examples |\n| `docker/` `docs/` `evaluation/` `scripts/` | Deployment, documentation, evaluation, helper scripts |\n| `.claude/agents/`, `.codex/agents/` | Project-recommended AI sub-agent definitions |\n\n## Command Cheatsheet\n\n- Install: `make install` (= `poetry install --extras all --with dev --with test` + pre-commit + push hook)\n- Start API: `make serve`\n- Export OpenAPI: `make openapi` (writes to `docs/openapi.json`)\n- Run full tests: `make test`\n- Run a single test: `poetry run pytest tests/<path>/test_xxx.py -q`\n- Lint + format: `make format`\n- Full pre-commit: `make pre_commit`\n- Build: `poetry build` (publishing is automated by `python-release.yml` on GitHub release)\n\n## Core API\n\n### Python top-level entries (`from memos import ...`)\n\n| Symbol | Purpose | Source |\n|--------|---------|--------|\n| `MOS` | Memory OS top-level entry (inherits `MOSCore`) | `memos.mem_os.main` |\n| `GeneralMemCube` | General memory container | `memos.mem_cube.general` |\n| `MOSConfig` / `GeneralMemCubeConfig` | Primary configs | `memos.configs.mem_os` / `memos.configs.mem_cube` |\n| `GeneralScheduler` / `SchedulerFactory` / `SchedulerConfigFactory` | Scheduler and factories | `memos.mem_scheduler.*` |\n\nCommon `MOS` methods: `MOS.simple()` (auto-configure from env), `register_mem_cube(cube)`, `add(...)`, `search(...)`, `chat(...)`, `create_user(...)` / `list_users()`.\n\n### API entry\n\n- ASGI app: `memos.api.start_api:app`\n- Routers: `src/memos/api/routers/` (`admin_router`, `product_router`, `server_router`)\n- OpenAPI contract: `docs/openapi.json` (must run `make openapi` after touching the API)\n\n## Import Patterns\n\n| Use | Import |\n|-----|--------|\n| Top-level entries | `from memos import MOS, GeneralMemCube, MOSConfig` |\n| Config classes | `from memos.configs.<submodule> import <Config>` |\n| Any provider factory | `from memos.<category>.factory import <Category>Factory` |\n| Logger | `from memos.log import get_logger`; `logger = get_logger(__name__)` |\n| Context (trace) | `from memos.context.context import get_current_trace_id, get_current_user_name` |\n| Exceptions | `from memos.exceptions import <semantic Exception>` |\n\n## Provider Matrix\n\nEvery provider follows the same three-piece pattern: `base.py` abstract class + `factory.py` registry + `configs/<category>.py` config. The authoritative list of registered backends is the factory's `backend_to_class`; the snapshot below is provided for quick reference:\n\n| Category | Base class | Factory | Registered backends |\n|----------|-----------|---------|---------------------|\n| LLM | `BaseLLM` | `LLMFactory` | `openai` / `openai_new` / `azure` / `ollama` / `huggingface` / `huggingface_singleton` / `vllm` / `qwen` / `deepseek` |\n| Embedder | `BaseEmbedder` | `EmbedderFactory` | `ollama` / `sentence_transformer` / `ark` / `universal_api` |\n| Vector DB | `BaseVecDB` | `VecDBFactory` | `qdrant` / `milvus` |\n| Graph DB | `BaseGraphDB` | `GraphStoreFactory` | `neo4j` / `neo4j_community` / `nebular` / `polardb` / `postgres` |\n| Chunker | `BaseChunker` | `ChunkerFactory` | `sentence` / `markdown` / `simple` / `charactertext` |\n| Parser | `BaseParser` | `ParserFactory` | `markitdown` |\n| Reranker | `BaseReranker` | `RerankerFactory` | `cosine_local` / `http_bge` / `http_bge_strategy` / `concat` / `noop` |\n| Memory | `BaseMemory` (+ `BaseTextMemory` / `BaseActMemory` / `BaseParaMemory`) | `MemoryFactory` | `naive_text` / `general_text` / `tree_text` / `simple_tree_text` / `pref_text` / `simple_pref_text` / `kv_cache` / `vllm_kv_cache` / `lora` |\n| Scheduler | `BaseScheduler` | `SchedulerFactory` | `general` / `optimized` |\n\n## Adding a New Provider\n\nMirror any existing provider in the same category:\n\n1. Implement `src/memos/<category>/<backend>.py`, inheriting the `base.py` abstract class and matching the signatures of existing providers.\n2. Add a pydantic config in `src/memos/configs/<category>.py` and register it in `<Category>ConfigFactory.backend_to_class`.\n3. Register the implementation in `<Category>Factory.backend_to_class` in `src/memos/<category>/factory.py`.\n4. Third-party dependencies **must** go into an optional extras group in `pyproject.toml` (`tree-mem` / `mem-scheduler` / `mem-user` / `mem-reader` / `pref-mem` / `skill-mem`) and be added to `all`; guard the import with try/except ImportError and raise a clear \"install extras X\" message on failure.\n5. Add tests under `tests/<category>/test_<backend>.py`; external HTTP / model loading must be mocked.\n\n## Behavior Boundaries\n\n### Always do\n\n- Write a failing test first (TDD), placed under `tests/<corresponding module>/test_*.py`.\n- Before claiming a task is done, run verification commands and paste the real output (at minimum `make format` plus the relevant pytest run).\n- Keep changes within the directories the current task authorizes; cross-module edits need to be called out and approved first.\n- Use `memos.log.get_logger(__name__)` for logging; route trace info through `memos.context.context` — do not `print`.\n- Optional third-party dependencies (neo4j / redis / pika / pymilvus / markitdown, etc.) must be guarded with try/except ImportError and declared in the matching extras group.\n- After touching `src/memos/api/`, run `make openapi` to refresh `docs/openapi.json`.\n\n### Ask first\n\n- Modifying `pyproject.toml` dependencies or the Python version constraint.\n- Touching public routes, request/response models, or the OpenAPI contract under `src/memos/api/`.\n- Changing DB schema, migrations, `mem_user` tables, or `graph_dbs` graph models.\n- Deleting files or doing wide-scope renames of public APIs (`memos.*` top-level symbols).\n- Editing `Makefile`, `.pre-commit-config.yaml`, `pyproject.toml [tool.*]`, or `.github/workflows/`.\n\n### Never do (IMPORTANT)\n\n- **Never** commit `.env`, `private/`, `.private-paths`, `tmp/`, `*.log`, secrets, tokens, or model credentials.\n- Do not log or include real API keys, raw user data, or vector contents in tests/fixtures.\n- Do not skip `pre-commit` or push with `--no-verify` (the `scripts/check-public-push.sh` pre-push hook is enforced).\n- Do not claim tests pass without real pytest output as evidence.\n- Do not add third-party dependencies to core `dependencies` — they must go into optional extras.\n- Do not run wide-scope `rm -rf` outside `src/`; do not `git push --force` or `git reset --hard origin/*`.\n\n## Code Style\n\n- Format and lint with Ruff (configured in `pyproject.toml [tool.ruff]`); `make format` must pass before commit.\n- Type annotations are required on public functions, API schemas, and config classes; implicit `Optional` is not allowed (enforced via pre-commit).\n- All configs and API schemas use Pydantic v2.\n- Logging: `logger.info(\"... %s\", x)` form — do not pre-format with f-strings before passing to the logger.\n- Exceptions: library code raises semantic exceptions from `memos.exceptions`, never bare `Exception` / `RuntimeError`; the API layer translates them to HTTP errors in `memos.api.exceptions`.\n- File naming: source `snake_case.py`, tests `test_<module>.py`.\n\n## Change → Test Mapping\n\n- Edit `src/memos/<module>/`: at minimum run `pytest tests/<corresponding module>/ -q`; run `make test` once more before merging.\n- Edit `src/memos/api/`: run `tests/api/` and `make openapi` to confirm the OpenAPI spec did not change unexpectedly.\n- Edit `pyproject.toml` dependencies: `poetry lock --no-update`, then `make test`.\n- Edit `Makefile` / pre-commit / Ruff config: run `make pre_commit` locally over the whole tree.\n\n## Git Conventions\n\n- Commits: Conventional Commits (`feat:` / `fix:` / `chore:` / `refactor:` / `docs:`), subject line ≤ 72 chars.\n- Branches: `feat/<slug>` / `fix/<slug>` / `dev-YYYYMMDD-v<version>`.\n- `main` is protected — all changes go through PRs; never force-push to `main`; do not skip git hooks.\n- Do not commit paths listed in `.private-paths`.\n- The PR template lives at `.github/PULL_REQUEST_TEMPLATE.md` — its checklist must be fully ticked.\n","CLAUDE.md":"# CLAUDE.md\n\n## Claude Code Entry\n\nProject facts live in `AGENTS.md`. This file only covers Claude Code runtime adaptation.\n\n## Sub-agents\n\nFive project-recommended sub-agents live under `.claude/agents/*.md`. Claude Code loads them automatically; the main agent should dispatch by task boundary:\n\n| Agent | Permissions | When to use |\n|-------|-------------|-------------|\n| `explorer` | Read-only | Locate code, trace call chains, gather evidence |\n| `design-reviewer` | Read-only | Review design docs (architecture / interface / performance / security / requirement coverage) |\n| `code-reviewer` | Read-only | Review diffs and return APPROVE or CHANGES_REQUESTED |\n| `backend-dev` | Read-write | Implement backend / library code under `src/memos/` (TDD) |\n| `integration-tester` | Read-write | Author and run integration / end-to-end cases under `tests/` |\n\nThe main repo has no frontend stack, so no `frontend-dev` is provided; TypeScript sub-projects under `apps/` use their own AI configuration.\n\n## Project knowledge\n\nBefore starting a task, run `ls docs/`. `docs/openapi.json` is the source of truth for the API contract; after touching `src/memos/api/`, run `make openapi` to regenerate it.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\n> Single source of truth for the project across AI runtimes. Claude Code, Codex, Cursor, Copilot, etc. all defer to this file.\n> Runtime-specific adaptation belongs in each runtime's own file (Claude reads `CLAUDE.md`); do not mix it in here.\n\n## Project Overview\n\n**MemOS / MemoryOS**: a memory operating system for LLM agents. Python library plus a FastAPI service, providing multiple memory types (textual / tree / preference / skill / KV cache / LoRA parametric) plus scheduling, version management, and vector & graph storage.\n\n- **Repository**: https://github.com/MemTensor/MemOS\n- **Documentation**: https://memos-docs.openmem.net/home/overview/\n- **PyPI**: https://pypi.org/project/MemoryOS/\n- **License**: Apache-2.0\n- **Top-level package**: `src/memos/`. Distribution name `MemoryOS`; import name `memos`.\n- **CLI**: `memos` (entry `memos.cli:main`)\n- **API service**: `memos.api.start_api:app`\n\n## Repository Layout\n\n| Path | Purpose |\n|------|---------|\n| `src/memos/mem_os/` | `MOS` / `MOSCore` — top-level Memory OS entry |\n| `src/memos/mem_cube/` | `GeneralMemCube` — memory container aggregating multiple memory types |\n| `src/memos/memories/` | Memory implementations: `textual/`, `activation/`, `parametric/` |\n| `src/memos/mem_scheduler/` | Memory scheduler + monitors + ORM + task scheduling |\n| `src/memos/mem_user/` | User / multi-tenant management (MySQL / Redis backends) |\n| `src/memos/mem_chat/` `mem_reader/` `mem_agent/` `mem_feedback/` `multi_mem_cube/` | Chat sessions, ingest pipeline, agent integration, feedback channel, multi-cube routing |\n| `src/memos/llms/` `embedders/` `vec_dbs/` `graph_dbs/` `chunkers/` `parsers/` `reranker/` | Provider implementations (`base.py` + `factory.py` + each backend) |\n| `src/memos/api/` | FastAPI service (routers / handlers / middleware / MCP server) |\n| `src/memos/configs/` | All pydantic configuration classes (one-to-one with the modules above) |\n| `src/memos/context/` | Cross-thread context (trace_id / user / env) |\n| `tests/` | pytest cases, subdirectories mirror `src/memos/` |\n| `apps/` | Independent sub-projects, each with its own README; not part of the main Harness flow |\n| `extensions/` | Official plugin examples |\n| `docker/` `docs/` `evaluation/` `scripts/` | Deployment, documentation, evaluation, helper scripts |\n| `.claude/agents/`, `.codex/agents/` | Project-recommended AI sub-agent definitions |\n\n## Command Cheatsheet\n\n- Install: `make install` (= `poetry install --extras all --with dev --with test` + pre-commit + push hook)\n- Start API: `make serve`\n- Export OpenAPI: `make openapi` (writes to `docs/openapi.json`)\n- Run full tests: `make test`\n- Run a single test: `poetry run pytest tests/<path>/test_xxx.py -q`\n- Lint + format: `make format`\n- Full pre-commit: `make pre_commit`\n- Build: `poetry build` (publishing is automated by `python-release.yml` on GitHub release)\n\n## Core API\n\n### Python top-level entries (`from memos import ...`)\n\n| Symbol | Purpose | Source |\n|--------|---------|--------|\n| `MOS` | Memory OS top-level entry (inherits `MOSCore`) | `memos.mem_os.main` |\n| `GeneralMemCube` | General memory container | `memos.mem_cube.general` |\n| `MOSConfig` / `GeneralMemCubeConfig` | Primary configs | `memos.configs.mem_os` / `memos.configs.mem_cube` |\n| `GeneralScheduler` / `SchedulerFactory` / `SchedulerConfigFactory` | Scheduler and factories | `memos.mem_scheduler.*` |\n\nCommon `MOS` methods: `MOS.simple()` (auto-configure from env), `register_mem_cube(cube)`, `add(...)`, `search(...)`, `chat(...)`, `create_user(...)` / `list_users()`.\n\n### API entry\n\n- ASGI app: `memos.api.start_api:app`\n- Routers: `src/memos/api/routers/` (`admin_router`, `product_router`, `server_router`)\n- OpenAPI contract: `docs/openapi.json` (must run `make openapi` after touching the API)\n\n## Import Patterns\n\n| Use | Import |\n|-----|--------|\n| Top-level entries | `from memos import MOS, GeneralMemCube, MOSConfig` |\n| Config classes | `from memos.configs.<submodule> import <Config>` |\n| Any provider factory | `from memos.<category>.factory import <Category>Factory` |\n| Logger | `from memos.log import get_logger`; `logger = get_logger(__name__)` |\n| Context (trace) | `from memos.context.context import get_current_trace_id, get_current_user_name` |\n| Exceptions | `from memos.exceptions import <semantic Exception>` |\n\n## Provider Matrix\n\nEvery provider follows the same three-piece pattern: `base.py` abstract class + `factory.py` registry + `configs/<category>.py` config. The authoritative list of registered backends is the factory's `backend_to_class`; the snapshot below is provided for quick reference:\n\n| Category | Base class | Factory | Registered backends |\n|----------|-----------|---------|---------------------|\n| LLM | `BaseLLM` | `LLMFactory` | `openai` / `openai_new` / `azure` / `ollama` / `huggingface` / `huggingface_singleton` / `vllm` / `qwen` / `deepseek` |\n| Embedder | `BaseEmbedder` | `EmbedderFactory` | `ollama` / `sentence_transformer` / `ark` / `universal_api` |\n| Vector DB | `BaseVecDB` | `VecDBFactory` | `qdrant` / `milvus` |\n| Graph DB | `BaseGraphDB` | `GraphStoreFactory` | `neo4j` / `neo4j_community` / `nebular` / `polardb` / `postgres` |\n| Chunker | `BaseChunker` | `ChunkerFactory` | `sentence` / `markdown` / `simple` / `charactertext` |\n| Parser | `BaseParser` | `ParserFactory` | `markitdown` |\n| Reranker | `BaseReranker` | `RerankerFactory` | `cosine_local` / `http_bge` / `http_bge_strategy` / `concat` / `noop` |\n| Memory | `BaseMemory` (+ `BaseTextMemory` / `BaseActMemory` / `BaseParaMemory`) | `MemoryFactory` | `naive_text` / `general_text` / `tree_text` / `simple_tree_text` / `pref_text` / `simple_pref_text` / `kv_cache` / `vllm_kv_cache` / `lora` |\n| Scheduler | `BaseScheduler` | `SchedulerFactory` | `general` / `optimized` |\n\n## Adding a New Provider\n\nMirror any existing provider in the same category:\n\n1. Implement `src/memos/<category>/<backend>.py`, inheriting the `base.py` abstract class and matching the signatures of existing providers.\n2. Add a pydantic config in `src/memos/configs/<category>.py` and register it in `<Category>ConfigFactory.backend_to_class`.\n3. Register the implementation in `<Category>Factory.backend_to_class` in `src/memos/<category>/factory.py`.\n4. Third-party dependencies **must** go into an optional extras group in `pyproject.toml` (`tree-mem` / `mem-scheduler` / `mem-user` / `mem-reader` / `pref-mem` / `skill-mem`) and be added to `all`; guard the import with try/except ImportError and raise a clear \"install extras X\" message on failure.\n5. Add tests under `tests/<category>/test_<backend>.py`; external HTTP / model loading must be mocked.\n\n## Behavior Boundaries\n\n### Always do\n\n- Write a failing test first (TDD), placed under `tests/<corresponding module>/test_*.py`.\n- Before claiming a task is done, run verification commands and paste the real output (at minimum `make format` plus the relevant pytest run).\n- Keep changes within the directories the current task authorizes; cross-module edits need to be called out and approved first.\n- Use `memos.log.get_logger(__name__)` for logging; route trace info through `memos.context.context` — do not `print`.\n- Optional third-party dependencies (neo4j / redis / pika / pymilvus / markitdown, etc.) must be guarded with try/except ImportError and declared in the matching extras group.\n- After touching `src/memos/api/`, run `make openapi` to refresh `docs/openapi.json`.\n\n### Ask first\n\n- Modifying `pyproject.toml` dependencies or the Python version constraint.\n- Touching public routes, request/response models, or the OpenAPI contract under `src/memos/api/`.\n- Changing DB schema, migrations, `mem_user` tables, or `graph_dbs` graph models.\n- Deleting files or doing wide-scope renames of public APIs (`memos.*` top-level symbols).\n- Editing `Makefile`, `.pre-commit-config.yaml`, `pyproject.toml [tool.*]`, or `.github/workflows/`.\n\n### Never do (IMPORTANT)\n\n- **Never** commit `.env`, `private/`, `.private-paths`, `tmp/`, `*.log`, secrets, tokens, or model credentials.\n- Do not log or include real API keys, raw user data, or vector contents in tests/fixtures.\n- Do not skip `pre-commit` or push with `--no-verify` (the `scripts/check-public-push.sh` pre-push hook is enforced).\n- Do not claim tests pass without real pytest output as evidence.\n- Do not add third-party dependencies to core `dependencies` — they must go into optional extras.\n- Do not run wide-scope `rm -rf` outside `src/`; do not `git push --force` or `git reset --hard origin/*`.\n\n## Code Style\n\n- Format and lint with Ruff (configured in `pyproject.toml [tool.ruff]`); `make format` must pass before commit.\n- Type annotations are required on public functions, API schemas, and config classes; implicit `Optional` is not allowed (enforced via pre-commit).\n- All configs and API schemas use Pydantic v2.\n- Logging: `logger.info(\"... %s\", x)` form — do not pre-format with f-strings before passing to the logger.\n- Exceptions: library code raises semantic exceptions from `memos.exceptions`, never bare `Exception` / `RuntimeError`; the API layer translates them to HTTP errors in `memos.api.exceptions`.\n- File naming: source `snake_case.py`, tests `test_<module>.py`.\n\n## Change → Test Mapping\n\n- Edit `src/memos/<module>/`: at minimum run `pytest tests/<corresponding module>/ -q`; run `make test` once more before merging.\n- Edit `src/memos/api/`: run `tests/api/` and `make openapi` to confirm the OpenAPI spec did not change unexpectedly.\n- Edit `pyproject.toml` dependencies: `poetry lock --no-update`, then `make test`.\n- Edit `Makefile` / pre-commit / Ruff config: run `make pre_commit` locally over the whole tree.\n\n## Git Conventions\n\n- Commits: Conventional Commits (`feat:` / `fix:` / `chore:` / `refactor:` / `docs:`), subject line ≤ 72 chars.\n- Branches: `feat/<slug>` / `fix/<slug>` / `dev-YYYYMMDD-v<version>`.\n- `main` is protected — all changes go through PRs; never force-push to `main`; do not skip git hooks.\n- Do not commit paths listed in `.private-paths`.\n- The PR template lives at `.github/PULL_REQUEST_TEMPLATE.md` — its checklist must be fully ticked.\n","category":"root","tokens":2535},{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md\n\n## Claude Code Entry\n\nProject facts live in `AGENTS.md`. This file only covers Claude Code runtime adaptation.\n\n## Sub-agents\n\nFive project-recommended sub-agents live under `.claude/agents/*.md`. Claude Code loads them automatically; the main agent should dispatch by task boundary:\n\n| Agent | Permissions | When to use |\n|-------|-------------|-------------|\n| `explorer` | Read-only | Locate code, trace call chains, gather evidence |\n| `design-reviewer` | Read-only | Review design docs (architecture / interface / performance / security / requirement coverage) |\n| `code-reviewer` | Read-only | Review diffs and return APPROVE or CHANGES_REQUESTED |\n| `backend-dev` | Read-write | Implement backend / library code under `src/memos/` (TDD) |\n| `integration-tester` | Read-write | Author and run integration / end-to-end cases under `tests/` |\n\nThe main repo has no frontend stack, so no `frontend-dev` is provided; TypeScript sub-projects under `apps/` use their own AI configuration.\n\n## Project knowledge\n\nBefore starting a task, run `ls docs/`. `docs/openapi.json` is the source of truth for the API contract; after touching `src/memos/api/`, run `make openapi` to regenerate it.\n","category":"root","tokens":300}]}