From d0bd101b6d30ea75b72a1cd84b4a79e8b06af63b Mon Sep 17 00:00:00 2001
From: sairin1202 <952141617@qq.com>
Date: Fri, 5 Jun 2026 17:51:38 +0800
Subject: [PATCH 1/3] fix(core): harden memory workflows
---
.github/ISSUE_TEMPLATE/bug_report.yml | 1 +
.github/ISSUE_TEMPLATE/config.yml | 10 +-
.github/PULL_REQUEST_TEMPLATE.md | 61 ++--
.github/dependabot.yml | 47 +++
.github/workflows/build.yml | 17 +-
.github/workflows/codeql.yml | 44 +++
.github/workflows/release-please.yml | 33 +-
.pre-commit-config.yaml | 5 +
.python-version | 2 +-
CODE_OF_CONDUCT.md | 31 ++
CONTRIBUTING.md | 14 +-
Cargo.toml | 4 +-
Makefile | 22 +-
SECURITY.md | 58 ++++
SUPPORT.md | 39 +++
docs/HACKATHON_ISSUE_DRAFT.md | 2 +-
docs/integrations/grok.md | 22 +-
docs/langgraph_integration.md | 25 +-
docs/providers/grok.md | 32 +-
docs/sealos_use_case.md | 74 +++--
docs/sqlite.md | 39 ++-
docs/tutorials/getting_started.md | 19 +-
examples/example_1_conversation_memory.py | 30 +-
examples/example_2_skill_extraction.py | 61 ++--
examples/example_3_multimodal_memory.py | 30 +-
examples/example_4_openrouter_memory.py | 23 +-
examples/example_5_with_lazyllm_client.py | 61 ++--
examples/getting_started_robust.py | 16 +-
examples/langgraph_demo.py | 26 +-
examples/proactive/memory/__init__.py | 1 +
examples/proactive/memory/claude_sdk.py | 32 ++
examples/proactive/memory/config.py | 2 +-
examples/proactive/memory/local/common.py | 2 +-
examples/proactive/memory/local/tools.py | 5 +-
examples/proactive/memory/platform/common.py | 30 ++
.../proactive/memory/platform/memorize.py | 31 +-
examples/proactive/memory/platform/tools.py | 37 +--
examples/proactive/proactive.py | 20 +-
examples/resources/docs/doc1.txt | 27 +-
examples/sealos_support_agent.py | 64 ++--
examples/test_nebius_provider.py | 32 +-
readme/README_en.md | 76 +++--
readme/README_es.md | 72 +++--
readme/README_fr.md | 72 +++--
readme/README_ja.md | 72 +++--
readme/README_ko.md | 72 +++--
readme/README_zh.md | 72 +++--
src/memu/app/crud.py | 113 +++++--
src/memu/app/memorize.py | 43 ++-
src/memu/app/patch.py | 69 ++++-
src/memu/app/retrieve.py | 168 ++++++++---
src/memu/app/scope.py | 136 +++++++++
src/memu/app/service.py | 11 +-
src/memu/app/settings.py | 78 +++--
src/memu/client/openai_wrapper.py | 105 +++++--
.../repositories/category_item_repo.py | 12 +-
.../database/inmemory/repositories/filter.py | 5 +-
.../repositories/memory_category_repo.py | 3 +-
.../inmemory/repositories/memory_item_repo.py | 7 +-
.../inmemory/repositories/resource_repo.py | 3 +-
src/memu/database/inmemory/vector.py | 6 +
src/memu/database/models.py | 26 +-
src/memu/database/postgres/models.py | 7 +-
src/memu/database/postgres/optional.py | 14 +
.../database/postgres/repositories/base.py | 7 +-
.../repositories/category_item_repo.py | 25 ++
.../repositories/memory_category_repo.py | 6 +-
.../postgres/repositories/memory_item_repo.py | 20 +-
.../postgres/repositories/resource_repo.py | 14 +-
src/memu/database/postgres/schema.py | 6 +-
.../database/repositories/category_item.py | 2 +
src/memu/database/repositories/memory_item.py | 2 +-
src/memu/database/sqlite/models.py | 2 +-
src/memu/database/sqlite/repositories/base.py | 7 +-
.../sqlite/repositories/category_item_repo.py | 77 +++--
.../sqlite/repositories/memory_item_repo.py | 4 +-
src/memu/database/sqlite/schema.py | 1 +
src/memu/embedding/http_client.py | 3 +-
src/memu/integrations/langgraph.py | 78 +++--
src/memu/llm/lazyllm_client.py | 45 ++-
src/memu/llm/openai_sdk.py | 11 +-
src/memu/llm/wrapper.py | 125 ++++++--
src/memu/utils/dedupe.py | 79 +++++
src/memu/utils/filtering.py | 58 ++++
src/memu/utils/retrieve.py | 37 +++
src/memu/utils/serialization.py | 14 +
src/memu/utils/tool.py | 2 +-
src/memu/workflow/pipeline.py | 16 +-
tests/test_client_wrapper.py | 201 +++++++++++++
tests/test_crud_contracts.py | 231 ++++++++++++++
tests/test_inmemory.py | 112 ++++---
tests/test_langgraph_optional.py | 56 ++++
tests/test_lazyllm.py | 105 ++++---
tests/test_lazyllm_optional.py | 21 ++
tests/test_llm_observability.py | 54 ++++
tests/test_memorize_dedupe.py | 68 +++++
tests/test_openrouter.py | 195 ++++++------
tests/test_postgres.py | 51 +++-
tests/test_postgres_repository_source.py | 63 ++++
tests/test_retrieve_method.py | 181 +++++++++++
tests/test_salience.py | 27 ++
tests/test_scope_filters.py | 284 ++++++++++++++++++
tests/test_serialization.py | 213 +++++++++++++
tests/test_settings.py | 163 ++++++++++
tests/test_sqlite.py | 116 ++++---
tests/test_workflow_contracts.py | 100 ++++++
106 files changed, 4219 insertions(+), 1036 deletions(-)
create mode 100644 .github/dependabot.yml
create mode 100644 .github/workflows/codeql.yml
create mode 100644 CODE_OF_CONDUCT.md
create mode 100644 SECURITY.md
create mode 100644 SUPPORT.md
create mode 100644 examples/proactive/memory/__init__.py
create mode 100644 examples/proactive/memory/claude_sdk.py
create mode 100644 examples/proactive/memory/platform/common.py
create mode 100644 src/memu/app/scope.py
create mode 100644 src/memu/database/postgres/optional.py
create mode 100644 src/memu/utils/dedupe.py
create mode 100644 src/memu/utils/filtering.py
create mode 100644 src/memu/utils/retrieve.py
create mode 100644 src/memu/utils/serialization.py
create mode 100644 tests/test_crud_contracts.py
create mode 100644 tests/test_langgraph_optional.py
create mode 100644 tests/test_lazyllm_optional.py
create mode 100644 tests/test_llm_observability.py
create mode 100644 tests/test_memorize_dedupe.py
create mode 100644 tests/test_postgres_repository_source.py
create mode 100644 tests/test_retrieve_method.py
create mode 100644 tests/test_scope_filters.py
create mode 100644 tests/test_serialization.py
create mode 100644 tests/test_settings.py
create mode 100644 tests/test_workflow_contracts.py
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index 096c80ff..eec4a35e 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -7,6 +7,7 @@ body:
attributes:
value: |
Thanks for taking the time to report a bug in memU! Please fill in the following details.
+ If this report involves a vulnerability, leaked credential, private user data, or authentication bypass, do not open a public issue. Follow the Security Policy instead: https://github.com/NevaMind-AI/MemU/security/policy
- type: textarea
id: description
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index 6a94220c..3f23dfc9 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -1,8 +1,14 @@
blank_issues_enabled: false
contact_links:
- name: GitHub Discussions
- url: https://github.com/NevaMind-AI/memU/discussions
+ url: https://github.com/NevaMind-AI/MemU/discussions
about: For questions and general discussions about memU
+ - name: Security Reports
+ url: https://github.com/NevaMind-AI/MemU/security/policy
+ about: Please report suspected vulnerabilities privately
- name: Documentation
- url: https://github.com/NevaMind-AI/memU/blob/main/README.md
+ url: https://github.com/NevaMind-AI/MemU/blob/main/README.md
about: Check out the memU documentation
+ - name: Community Chat
+ url: https://discord.com/invite/hQZntfGsbJ
+ about: Join the memU Discord community
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 0467b332..ee78e9e6 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,44 +1,41 @@
-## 📝 Pull Request Summary
+## Summary
-Please provide a short summary explaining the purpose of this PR.
+Describe what this pull request changes and why it matters.
----
-
-## ✅ What does this PR do?
-- Clearly describe the change introduced.
-- Mention the motivation or problem it solves.
-
----
-
-## 🤔 Why is this change needed?
-- Explain the context or user impact.
-- Link any relevant issue or discussion.
-
----
-
-## 🔍 Type of Change
-Please check what applies:
+## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
-- [ ] Refactor / cleanup
-- [ ] Other (please explain)
+- [ ] Refactor or cleanup
+- [ ] CI, build, or release change
+- [ ] Test-only change
----
+## Validation
-## ✅ PR Quality Checklist
+- [ ] `make check`
+- [ ] `make test`
+- [ ] `make docs-build`
+- [ ] Focused tests or manual verification listed below
-- [ ] PR title follows the conventional format (feat:, fix:, docs:)
-- [ ] Changes are limited in scope and easy to review
-- [ ] Documentation updated where applicable
-- [ ] No breaking changes (or clearly documented)
-- [ ] Related issues or discussions linked
+Validation notes:
+
+```text
+Paste commands, relevant output, or explain why a check was not run.
+```
----
+## Review Notes
-## 📌 Optional
+- Public API impact:
+- Storage/backend impact:
+- Security or privacy impact:
+- Breaking changes or migration steps:
-- [ ] Screenshots or examples added (if applicable)
-- [ ] Edge cases considered
-- [ ] Follow-up tasks mentioned
+## Checklist
+
+- [ ] PR title uses a supported conventional prefix (`feat`, `fix`, `docs`, `test`, `refactor`, `perf`, `style`, `ci`, `build`, `chore`, `revert`)
+- [ ] Changes are limited in scope and easy to review
+- [ ] Tests cover new behavior or regression risk
+- [ ] Documentation, examples, or ADRs are updated when behavior changes
+- [ ] No secrets, credentials, or private user data are included
+- [ ] Related issues or discussions are linked
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 00000000..3e94deb6
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,47 @@
+version: 2
+updates:
+ - package-ecosystem: "uv"
+ directory: "/"
+ schedule:
+ interval: "weekly"
+ day: "monday"
+ time: "09:00"
+ timezone: "Etc/UTC"
+ open-pull-requests-limit: 5
+ commit-message:
+ prefix: "chore(deps)"
+ prefix-development: "chore(deps-dev)"
+ include: "scope"
+ labels:
+ - "dependencies"
+ - "python"
+
+ - package-ecosystem: "cargo"
+ directory: "/"
+ schedule:
+ interval: "weekly"
+ day: "monday"
+ time: "09:15"
+ timezone: "Etc/UTC"
+ open-pull-requests-limit: 5
+ commit-message:
+ prefix: "chore(deps)"
+ include: "scope"
+ labels:
+ - "dependencies"
+ - "rust"
+
+ - package-ecosystem: "github-actions"
+ directory: "/"
+ schedule:
+ interval: "weekly"
+ day: "monday"
+ time: "09:30"
+ timezone: "Etc/UTC"
+ open-pull-requests-limit: 5
+ commit-message:
+ prefix: "ci(deps)"
+ include: "scope"
+ labels:
+ - "dependencies"
+ - "ci"
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 7218e5f2..e96190b8 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -2,13 +2,15 @@ name: build
on: [push, pull_request]
+permissions:
+ contents: read
+
jobs:
build:
runs-on: ubuntu-latest
- if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.event.pull_request.base.repo.full_name
strategy:
matrix:
- python-version: ["3.13"]
+ python-version: ["3.12", "3.13"]
steps:
- uses: actions/checkout@v6
@@ -24,12 +26,13 @@ jobs:
run: uv python install ${{ matrix.python-version }}
- name: Sync dependencies
- run: |
- uv sync --frozen
- uv run pre-commit install
+ run: uv sync --frozen
- name: Run style checks
- run: uv run make check
+ run: make check
- name: Run tests
- run: uv run make test
+ run: make test
+
+ - name: Build docs
+ run: make docs-build
diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
new file mode 100644
index 00000000..d4340403
--- /dev/null
+++ b/.github/workflows/codeql.yml
@@ -0,0 +1,44 @@
+name: codeql
+
+on:
+ push:
+ branches:
+ - main
+ pull_request:
+ branches:
+ - main
+ schedule:
+ - cron: "37 3 * * 1"
+
+permissions:
+ actions: read
+ contents: read
+ security-events: write
+
+jobs:
+ analyze:
+ name: Analyze (${{ matrix.language }})
+ runs-on: ubuntu-latest
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - language: python
+ build-mode: none
+ - language: rust
+ build-mode: none
+
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v6
+
+ - name: Initialize CodeQL
+ uses: github/codeql-action/init@v4
+ with:
+ languages: ${{ matrix.language }}
+ build-mode: ${{ matrix.build-mode }}
+
+ - name: Perform CodeQL analysis
+ uses: github/codeql-action/analyze@v4
+ with:
+ category: "/language:${{ matrix.language }}"
diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml
index efaa9e1f..4d59976c 100644
--- a/.github/workflows/release-please.yml
+++ b/.github/workflows/release-please.yml
@@ -4,15 +4,21 @@ on:
- main
permissions:
- contents: write
- issues: write
- pull-requests: write
+ contents: read
+
+concurrency:
+ group: release-please-${{ github.ref }}
+ cancel-in-progress: false
name: release-please
jobs:
release-please:
runs-on: ubuntu-latest
+ permissions:
+ contents: write
+ issues: write
+ pull-requests: write
outputs:
releases_created: ${{ steps.release.outputs.releases_created }}
tag_name: ${{ steps.release.outputs.tag_name }}
@@ -36,27 +42,27 @@ jobs:
label: linux-x86_64
target: x86_64-unknown-linux-gnu
extra-args: "--compatibility manylinux_2_39"
- python-version: "3.13"
+ python-version: "3.12"
- os: ubuntu-latest
label: linux-aarch64
target: aarch64-unknown-linux-gnu
extra-args: "--compatibility manylinux_2_39"
- python-version: "3.13"
+ python-version: "3.12"
- os: macos-15-intel
label: macos-x86_64
target: ""
extra-args: ""
- python-version: "3.13"
+ python-version: "3.12"
- os: macos-latest
label: macos-aarch64
target: ""
extra-args: ""
- python-version: "3.13"
+ python-version: "3.12"
- os: windows-latest
label: windows-x86_64
target: ""
extra-args: ""
- python-version: "3.13"
+ python-version: "3.12"
steps:
- uses: actions/checkout@v6
@@ -85,7 +91,7 @@ jobs:
CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER: aarch64-linux-gnu-gcc
- name: Upload wheel artifact
- uses: actions/upload-artifact@v6
+ uses: actions/upload-artifact@v7
with:
name: wheels-${{ matrix.label }}
path: dist/*.whl
@@ -102,7 +108,7 @@ jobs:
- name: Install uv
uses: astral-sh/setup-uv@v7
with:
- python-version: "3.13"
+ python-version: "3.12"
- name: Setup Rust
uses: dtolnay/rust-toolchain@stable
@@ -114,7 +120,7 @@ jobs:
run: uvx maturin sdist --out dist
- name: Upload sdist artifact
- uses: actions/upload-artifact@v6
+ uses: actions/upload-artifact@v7
with:
name: sdist
path: dist/*.tar.gz
@@ -130,18 +136,19 @@ jobs:
if: ${{ needs.release-please.outputs.releases_created == 'true' && needs.release-please.outputs.tag_name != '' }}
environment: pypi
permissions:
+ actions: read
id-token: write
contents: write
steps:
- name: Download wheel artifacts
- uses: actions/download-artifact@v7
+ uses: actions/download-artifact@v8
with:
pattern: wheels-*
merge-multiple: true
path: dist
- name: Download sdist artifact
- uses: actions/download-artifact@v7
+ uses: actions/download-artifact@v8
with:
name: sdist
path: dist
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index b7dffddb..1f17a214 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -9,7 +9,12 @@ repos:
- id: check-json
- id: pretty-format-json
args: [--autofix, --no-sort-keys]
+ - id: check-added-large-files
+ args: [--maxkb=1024]
+ - id: detect-private-key
- id: end-of-file-fixer
+ - id: mixed-line-ending
+ args: [--fix=lf]
- id: trailing-whitespace
- repo: https://github.com/astral-sh/ruff-pre-commit
diff --git a/.python-version b/.python-version
index 24ee5b1b..e4fba218 100644
--- a/.python-version
+++ b/.python-version
@@ -1 +1 @@
-3.13
+3.12
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 00000000..e5e34be8
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,31 @@
+# Code of Conduct
+
+## Our Pledge
+
+We want MemU to be a welcoming, useful, and technically serious open source project. We expect everyone who participates in the project to treat other contributors, users, and maintainers with respect.
+
+## Expected Behavior
+
+- Be kind, patient, and constructive.
+- Assume good intent while still being clear about technical risks.
+- Keep discussions focused on the work, the project, and the people affected by decisions.
+- Welcome newcomers and help them find the right issue, document, or maintainer.
+- Respect privacy, security boundaries, and confidential reports.
+
+## Unacceptable Behavior
+
+- Harassment, intimidation, threats, or personal attacks.
+- Demeaning language related to identity, background, experience level, or technical choices.
+- Publishing private information without explicit permission.
+- Repeatedly derailing discussions after maintainers ask to refocus.
+- Any behavior that makes the project unsafe or hostile for others.
+
+## Reporting
+
+Please report conduct concerns privately by emailing [contact@nevamind.ai](mailto:contact@nevamind.ai). Include enough context for maintainers to understand what happened, such as links, screenshots, dates, and the people involved.
+
+Maintainers will review reports as promptly and fairly as possible. Retaliation against anyone who reports a concern or participates in a review is not acceptable.
+
+## Enforcement
+
+Maintainers may take action to protect the project community, including warnings, comment deletion, temporary restrictions, or removal from project spaces. Enforcement decisions should be proportionate, documented internally, and focused on restoring a healthy collaboration environment.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 99041ea2..4d3d21c7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -18,7 +18,7 @@ We welcome all types of contributions:
## 🚀 Quick Start for Contributors
### Prerequisites
-- Python 3.13+
+- Python 3.12+
- Git
- [uv](https://github.com/astral-sh/uv) (Python package manager)
- A code editor (VS Code recommended)
@@ -47,6 +47,8 @@ make test
make install # Create virtual environment and install dependencies with uv
make test # Run tests with pytest and coverage
make check # Run all checks (lock file, pre-commit, mypy, deptry)
+make docs # Preview the documentation site locally
+make docs-build # Build documentation in strict mode
```
## 🔧 Development Guidelines
@@ -76,7 +78,7 @@ uv run python -m pytest
uv run python -m pytest --cov --cov-config=pyproject.toml --cov-report=html
# Run specific test file
-uv run python -m pytest tests/rust_entry_test.py
+uv run python -m pytest tests/test_inmemory.py
# Run tests with specific marker
uv run python -m pytest -m "not slow"
@@ -120,9 +122,9 @@ For feature requests, please describe:
3. **Test your changes**
```bash
+ make check
make test
- make lint
- make coverage
+ make docs-build
```
4. **Submit pull request**
@@ -201,6 +203,7 @@ We're currently focusing on:
**Reporting Security Issues:**
- **DO NOT** create public issues for security vulnerabilities
+- Follow the [Security Policy](SECURITY.md)
- Email security issues privately to [contact@nevamind.ai](mailto:contact@nevamind.ai)
- Include detailed reproduction steps and impact assessment
- We'll acknowledge receipt within 24 hours
@@ -224,9 +227,10 @@ By contributing to MemU, you agree that:
| Channel | Best For |
|---------|----------|
-| 💬 [Discord](https://discord.gg/memu) | Real-time chat, quick questions |
+| 💬 [Discord](https://discord.com/invite/hQZntfGsbJ) | Real-time chat, quick questions |
| 🗣️ [GitHub Discussions](https://github.com/NevaMind-AI/MemU/discussions) | Feature discussions, Q&A |
| 🐛 [GitHub Issues](https://github.com/NevaMind-AI/MemU/issues) | Bug reports, feature requests |
+| 🔒 [Security Policy](SECURITY.md) | Private vulnerability reporting |
| 📧 [Email](mailto:contact@nevamind.ai) | Private inquiries |
## 🎉 Recognition
diff --git a/Cargo.toml b/Cargo.toml
index 49494051..c7fbeb0b 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -10,5 +10,5 @@ crate-type = ["cdylib"]
[dependencies]
# "extension-module" tells pyo3 we want to build an extension module (skips linking against libpython.so)
-# "abi3-py313" tells pyo3 (and maturin) to build using the stable ABI with minimum Python version 3.13
-pyo3 = { version = "0.27.1", features = ["extension-module", "abi3-py313"] }
+# "abi3-py312" tells pyo3 (and maturin) to build using the stable ABI with minimum Python version 3.12
+pyo3 = { version = "0.27.1", features = ["extension-module", "abi3-py312"] }
diff --git a/Makefile b/Makefile
index 6f516bc1..1c0ef8bd 100644
--- a/Makefile
+++ b/Makefile
@@ -1,22 +1,32 @@
.PHONY: install
install:
- @echo "🚀 Creating virtual environment using uv"
+ @echo "[install] Creating virtual environment using uv"
@uv sync
@uv run pre-commit install
.PHONY: check
check:
- @echo "🚀 Checking lock file consistency with 'pyproject.toml'"
+ @echo "[check] Checking lock file consistency with 'pyproject.toml'"
@uv lock --locked
- @echo "🚀 Linting code: Running pre-commit"
+ @echo "[check] Linting code: Running pre-commit"
@uv run pre-commit run -a
- @echo "🚀 Static type checking: Running mypy"
+ @echo "[check] Static type checking: Running mypy"
@uv run mypy
- @echo "🚀 Checking for obsolete dependencies: Running deptry"
+ @echo "[check] Checking for obsolete dependencies: Running deptry"
@uv run deptry src
.PHONY: test
test:
- @echo "🚀 Testing code: Running pytest"
+ @echo "[test] Running pytest"
@uv run python -m pytest --cov --cov-config=pyproject.toml --cov-report=xml
+
+.PHONY: docs
+docs:
+ @echo "[docs] Serving documentation with MkDocs"
+ @uv run mkdocs serve
+
+.PHONY: docs-build
+docs-build:
+ @echo "[docs] Building documentation with MkDocs"
+ @uv run mkdocs build --strict
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 00000000..44bec949
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,58 @@
+# Security Policy
+
+memU handles user-provided content, memory records, embeddings, local files, and
+provider credentials. Please report security concerns privately so maintainers
+can investigate before details become public.
+
+## Supported Versions
+
+Security fixes are prioritized for:
+
+- the latest released `memu-py` version
+- the `main` branch when a fix has not been released yet
+
+Older releases may receive fixes when the issue is severe and the patch can be
+backported safely.
+
+## Reporting a Vulnerability
+
+Do not open a public GitHub issue for suspected vulnerabilities.
+
+Email reports to [contact@nevamind.ai](mailto:contact@nevamind.ai) with:
+
+- affected version or commit
+- operating system and deployment mode
+- reproduction steps or proof of concept
+- expected impact
+- whether credentials, files, memory data, or external providers are involved
+
+We aim to acknowledge reports within 2 business days and will share status
+updates as we investigate. If a vulnerability is confirmed, maintainers will
+coordinate a fix, release guidance, and public disclosure timing with the
+reporter when possible.
+
+## Scope
+
+Useful reports include issues such as:
+
+- unauthorized access to memory data across scopes or users
+- unsafe handling of API keys, environment variables, or provider credentials
+- path traversal, unintended file reads, or writes outside configured roots
+- integration authentication or authorization bypasses
+- injection paths that can alter persistent memory without review
+
+Out-of-scope reports include social engineering, spam, denial-of-service without
+a concrete vulnerability, and findings that require access to accounts or
+systems you do not own or have permission to test.
+
+## Automated Scanning
+
+Pull requests and the `main` branch are scanned with CodeQL for Python and Rust.
+These checks complement code review and responsible disclosure; they do not
+replace private reporting for suspected vulnerabilities.
+
+## Safe Harbor
+
+Good-faith research that avoids privacy violations, data destruction, service
+disruption, and unauthorized access is welcome. Stop testing and contact us
+privately if you encounter sensitive data or credentials.
diff --git a/SUPPORT.md b/SUPPORT.md
new file mode 100644
index 00000000..4cc02091
--- /dev/null
+++ b/SUPPORT.md
@@ -0,0 +1,39 @@
+# Support
+
+Thanks for using memU. This page helps route questions and reports to the right
+place.
+
+## Questions and Discussions
+
+Use [GitHub Discussions](https://github.com/NevaMind-AI/MemU/discussions) for:
+
+- usage questions
+- architecture discussions
+- integration ideas
+- provider or storage configuration questions
+
+For quick community chat, join the
+[Discord community](https://discord.com/invite/hQZntfGsbJ).
+
+## Bugs and Feature Requests
+
+Use [GitHub Issues](https://github.com/NevaMind-AI/MemU/issues) for:
+
+- reproducible bugs
+- feature requests
+- documentation problems
+- integration regressions
+
+Please include the memU version, Python version, operating system, storage
+backend, LLM provider, and a small reproduction when possible.
+
+## Security Reports
+
+Do not report security vulnerabilities in public issues. Follow the
+[Security Policy](SECURITY.md) and email
+[contact@nevamind.ai](mailto:contact@nevamind.ai).
+
+## Private Inquiries
+
+For private questions, partnership discussions, or enterprise deployment
+inquiries, email [contact@nevamind.ai](mailto:contact@nevamind.ai).
diff --git a/docs/HACKATHON_ISSUE_DRAFT.md b/docs/HACKATHON_ISSUE_DRAFT.md
index 7951c4be..0aaa0775 100644
--- a/docs/HACKATHON_ISSUE_DRAFT.md
+++ b/docs/HACKATHON_ISSUE_DRAFT.md
@@ -11,7 +11,7 @@
This PR enhances MemU's memory type system to support specialized memory structures with type-specific metadata and introduces Tool Memory for agent self-improvement.
-**Current State:** MemU has a `memory_type` field with 5 types (profile, event, knowledge, behavior, skill) and uses different LLM prompts to extract each type. However, after extraction, all memories share the same storage schema - just `summary` and `embedding`. There's no type-specific metadata, no type-aware retrieval, and no way for agents to learn from their tool usage.
+**Current State:** MemU has a `memory_type` field with 6 supported types (profile, event, knowledge, behavior, skill, tool) and uses different LLM prompts to extract each type. Tool memories can store tool-specific metadata and execution history, while other memories continue to share the common `summary` and `embedding` storage shape.
**Enhancement:** Extend the memory system to support:
- Type-specific metadata fields (e.g., `when_to_use` for smarter retrieval)
diff --git a/docs/integrations/grok.md b/docs/integrations/grok.md
index db501833..380eee42 100644
--- a/docs/integrations/grok.md
+++ b/docs/integrations/grok.md
@@ -30,18 +30,18 @@ To use Grok as your LLM provider, switch the `provider` setting to `grok`. This
### Python Example
```python
-from memu.app.settings import LLMConfig
-
-# Configure MemU to use Grok
-config = LLMConfig(
- provider="grok",
- # The default API key env var is XAI_API_KEY
- # The default model is grok-2-latest
+from memu import MemoryService
+
+# Configure MemU to use Grok through the default LLM profile.
+service = MemoryService(
+ llm_profiles={
+ "default": {
+ "provider": "grok",
+ # Defaults: api_key="XAI_API_KEY", base_url="https://api.x.ai/v1",
+ # chat_model="grok-2-latest"
+ }
+ }
)
-
-print(f"Using provider: {config.provider}")
-print(f"Base URL: {config.base_url}")
-print(f"Chat Model: {config.chat_model}")
```
## Models Supported
diff --git a/docs/langgraph_integration.md b/docs/langgraph_integration.md
index 005851e0..e3a4298c 100644
--- a/docs/langgraph_integration.md
+++ b/docs/langgraph_integration.md
@@ -15,9 +15,18 @@ These tools are fully typed and compatible with LangGraph's `prebuilt.ToolNode`
To use this integration, you need to install the optional dependencies:
```bash
-uv add langgraph langchain-core
+pip install "memu-py[langgraph]"
```
+If you manage dependencies with uv in an application project:
+
+```bash
+uv add "memu-py[langgraph]"
+```
+
+When working from a source checkout, install the direct integration dependencies
+with `uv sync --extra langgraph`.
+
## Quick Start
Here is a complete example of how to initialize the MemU memory service and bind it to a LangGraph agent.
@@ -25,11 +34,11 @@ Here is a complete example of how to initialize the MemU memory service and bind
```python
import asyncio
import os
-from memu.app.service import MemoryService
+from memu import MemoryService
from memu.integrations.langgraph import MemULangGraphTools
# Ensure you have your configuration set (e.g., env vars for DB connection)
-# os.environ["MEMU_DATABASE_URL"] = "..."
+# os.environ["MEMU_DATABASE_DSN"] = "..."
async def main():
# 1. Initialize MemoryService
@@ -83,15 +92,21 @@ class MemULangGraphTools(memory_service: MemoryService)
Returns a tool named `save_memory`.
- **Inputs**: `content` (str), `user_id` (str), `metadata` (dict, optional).
- **Description**: Save a piece of information, conversation snippet, or memory for a user.
+- **Scope rule**: `user_id` is authoritative. A `metadata["user_id"]` value cannot override it.
#### `search_memory_tool() -> StructuredTool`
Returns a tool named `search_memory`.
-- **Inputs**: `query` (str), `user_id` (str), `limit` (int, default=5), `metadata_filter` (dict, optional), `min_relevance_score` (float, default=0.0).
+- **Inputs**: `query` (str), `user_id` (str), `limit` (int, default=5),
+ `metadata_filter` (dict, optional), `min_relevance_score` (float, default=0.0).
- **Description**: Search for relevant memories or information for a user based on a query.
+- **Bounds**: `query` and `user_id` must be non-empty, `limit` must be at least 1,
+ and `min_relevance_score` must be between 0.0 and 1.0.
+- **Scope rule**: `user_id` is authoritative. A `metadata_filter["user_id"]` value cannot override it.
## Troubleshooting
### Import Errors
If you see an `ImportError` regarding `langchain_core` or `langgraph`:
-1. Ensure you have installed the extras: `uv add langgraph langchain-core` (or `pip install langgraph langchain-core`).
+1. Ensure you have installed the extra: `pip install "memu-py[langgraph]"` or `uv add "memu-py[langgraph]"`.
+ From a source checkout, run `uv sync --extra langgraph`.
2. Verify your virtual environment is active.
diff --git a/docs/providers/grok.md b/docs/providers/grok.md
index 702eb1e5..d7e600ed 100644
--- a/docs/providers/grok.md
+++ b/docs/providers/grok.md
@@ -19,7 +19,7 @@ The integration is designed to work out-of-the-box with minimal configuration.
Set the following environment variable in your `.env` file or system environment:
```bash
-GROK_API_KEY=xai-YOUR_API_KEY_HERE
+XAI_API_KEY=xai-YOUR_API_KEY_HERE
```
### Defaults
@@ -36,31 +36,37 @@ You can enable the Grok provider by setting the `provider` field to `"grok"` in
### Using Python Configuration
```python
-from memu.app.settings import LLMConfig
-from memu.app.service import MemoryService
-
-# Configure the LLM provider to use Grok
-llm_config = LLMConfig(provider="grok")
+from memu import MemoryService
# Initialize the service
-service = MemoryService(llm_config=llm_config)
-print(f"Service initialized with model: {llm_config.chat_model}")
-# Output: Service initialized with model: grok-2-latest
+service = MemoryService(
+ llm_profiles={
+ "default": {
+ "provider": "grok",
+ # Defaults: api_key="XAI_API_KEY", base_url="https://api.x.ai/v1",
+ # chat_model="grok-2-latest"
+ }
+ }
+)
```
## Troubleshooting
### Connection Issues
If you are unable to connect to the xAI API:
-1. Verify that your `GROK_API_KEY` is set correctly and has not expired.
+1. Verify that your `XAI_API_KEY` is set correctly and has not expired.
2. Ensure that the `base_url` is resolving to `https://api.x.ai/v1`. If you have manual overrides in your settings, they might be conflicting with the default.
### Model Availability
If you receive a `404` or "Model not found" error, xAI may have updated their model names. You can override the model manually in the config if needed:
```python
-config = LLMConfig(
- provider="grok",
- chat_model="grok-beta" # Example override
+service = MemoryService(
+ llm_profiles={
+ "default": {
+ "provider": "grok",
+ "chat_model": "grok-beta", # Example override
+ }
+ }
)
```
diff --git a/docs/sealos_use_case.md b/docs/sealos_use_case.md
index 5ef9edbd..3e1a5512 100644
--- a/docs/sealos_use_case.md
+++ b/docs/sealos_use_case.md
@@ -1,54 +1,66 @@
-# 🛡️ Context-Aware Support Agent (Sealos Edition)
+# Context-Aware Support Agent (Sealos Edition)
## Overview
-This use case demonstrates how **MemU** enables a support agent to remember user history across sessions, deployed on a **Sealos Devbox** environment.
-Unlike a standard web app, this demo focuses on the **backend memory orchestration**. It runs as a **CLI (Command Line Interface)** tool to transparently show the internal memory logs, retrieval process, and state persistence without the abstraction layer of a UI.
+This use case demonstrates how memU helps a support agent remember user history
+across sessions in a Sealos Devbox-style environment.
-## 🚀 Quick Start
+Unlike a standard web app, this demo focuses on backend memory orchestration. It
+runs as a CLI tool so reviewers can see the ingestion, retrieval, and response
+flow directly in the terminal.
+
+## Quick Start
### Prerequisites
-- Sealos Devbox Environment
-- Python 3.13+
-- MemU Library (installed via `make install`)
-### How to Run the Demo
-Since this is a backend demonstration, you will run the agent directly in the terminal to observe the memory cycle.
+- Sealos Devbox environment or a local Python shell
+- Python 3.12+
+- memU installed with `pip install memu-py`, or a source checkout
+
+When running from a source checkout, the script adds the local `src/` directory
+to `sys.path` before importing memU, so this command works without building a
+wheel first:
```bash
uv run python examples/sealos_support_agent.py
```
-## 📸 Live Demo Output (Proof of Concept)
+If memU or its runtime dependencies are not importable, the demo falls back to a
+deterministic offline simulation so the flow remains reviewable.
-Below is the actual output captured from the Sealos terminal. This serves as verification of the "Demonstration Quality" requirement.
+## Live Demo Output
```plaintext
-🚀 Starting Sealos Support Agent Demo (Offline Mode)
+[START] Starting Sealos Support Agent Demo (Offline Mode)
+===================================================
-📝 --- Phase 1: Ingesting Conversation History ---
-👤 Captain: "I'm getting a 502 Bad Gateway error on port 3000."
-🤖 Agent: (Memorizing this interaction...)
-✅ Memory stored! extracted 2 items.
- - [profile] Captain reported a 502 Bad Gateway error on port 3000.
+[OK] Environment Check: MemU Library detected.
+[OK] Runtime: Sealos Devbox (Python 3.12+)
-🔍 --- Phase 2: Retrieval on New Interaction ---
-👤 Captain: "Hello"
-🤖 Agent: (Searching memory for context...)
+[PHASE 1] Ingesting Conversation History
+Captain: "I'm getting a 502 Bad Gateway error on port 3000."
+Agent: (Processing input through Memory Pipeline...)
+[OK] Memory stored! extracted 2 items:
+ - [issue] 502 Bad Gateway error
+ - [context] port 3000 configuration
-💡 Retrieved Context:
- Found Memory: Captain reported a 502 Bad Gateway error on port 3000.
+[PHASE 2] Retrieval on New Interaction (New Session)
+Captain: "Hello, any updates?"
+Agent: (Searching vector store for user 'Captain'...)
-💬 --- Phase 3: Agent Response ---
-🤖 Agent: "Welcome back, Captain. I see you had a 502 error on port 3000 recently. Is that resolved?"
+[CONTEXT] Retrieved Context:
+ Found Memory (Score: 0.98): User reported 502 error on port 3000
+ Found Memory (Score: 0.95): User was frustrated with timeout
-✨ Demo Completed Successfully
-```
+[PHASE 3] Agent Response
+Agent: "Welcome back, Captain. Regarding the 502 Bad Gateway error on port 3000 you reported earlier - have you tried checking the firewall logs?"
-## 💡 Code Highlights & Justification
-
-- **CLI vs Web**: We chose a CLI implementation to provide clear visibility into the memory ingestion and retrieval logs, which are often hidden in web implementations.
+[DONE] Demo Completed Successfully
+===================================================
+```
-- **MockLLM**: Includes a MockLLM class to ensure the demo is 100% reproducible by reviewers without needing external API keys.
+## Code Highlights
-- **Sealos Native**: Optimized to run within the ephemeral Sealos Devbox container lifecycle.
+- CLI-first: keeps the memory flow visible without a web UI.
+- Offline-safe: reviewers can run the demo even before configuring API keys.
+- Source-checkout friendly: local `src/` is used before installed packages.
diff --git a/docs/sqlite.md b/docs/sqlite.md
index 176b7ad2..d3dbe1c7 100644
--- a/docs/sqlite.md
+++ b/docs/sqlite.md
@@ -11,12 +11,16 @@ MemU supports SQLite as a lightweight, file-based database backend for memory st
### Basic Configuration
+Set `OPENAI_API_KEY` in your environment before running these examples. The
+`api_key` value below is the environment variable name that memU resolves at
+runtime, not a literal secret to paste into source code.
+
```python
-from memu.app import MemoryService
+from memu import MemoryService
# Using default SQLite file (memu.db in current directory)
service = MemoryService(
- llm_profiles={"default": {"api_key": "your-api-key"}},
+ llm_profiles={"default": {"api_key": "OPENAI_API_KEY"}},
database_config={
"metadata_store": {
"provider": "sqlite",
@@ -26,7 +30,7 @@ service = MemoryService(
# Or specify a custom database path
service = MemoryService(
- llm_profiles={"default": {"api_key": "your-api-key"}},
+ llm_profiles={"default": {"api_key": "OPENAI_API_KEY"}},
database_config={
"metadata_store": {
"provider": "sqlite",
@@ -42,7 +46,7 @@ For testing or temporary storage, you can use an in-memory SQLite database:
```python
service = MemoryService(
- llm_profiles={"default": {"api_key": "your-api-key"}},
+ llm_profiles={"default": {"api_key": "OPENAI_API_KEY"}},
database_config={
"metadata_store": {
"provider": "sqlite",
@@ -73,7 +77,7 @@ SQLite doesn't have native vector support like PostgreSQL's pgvector. MemU uses
```python
service = MemoryService(
- llm_profiles={"default": {"api_key": "your-api-key"}},
+ llm_profiles={"default": {"api_key": "OPENAI_API_KEY"}},
database_config={
"metadata_store": {
"provider": "sqlite",
@@ -114,13 +118,23 @@ shutil.copy("memu.db", "memu_backup.db")
### Import from SQLite to PostgreSQL
-To migrate data from SQLite to PostgreSQL:
+To migrate data from SQLite to PostgreSQL, install the optional PostgreSQL
+dependencies first:
+
+```bash
+pip install "memu-py[postgres]"
+# From a source checkout:
+uv sync --extra postgres
+```
+
+Then connect both backends with explicit DSNs. This migration snippet intentionally uses
+low-level repository builders so it can copy existing rows backend-to-backend; normal application code should continue to use `MemoryService(database_config=...)`.
```python
import json
from memu.database.sqlite import build_sqlite_database
from memu.database.postgres import build_postgres_database
-from memu.app.settings import DatabaseConfig
+from memu import DatabaseConfig
from pydantic import BaseModel
class UserScope(BaseModel):
@@ -135,7 +149,10 @@ sqlite_db.load_existing()
# Connect to PostgreSQL
postgres_config = DatabaseConfig(
- metadata_store={"provider": "postgres", "dsn": "postgresql://..."}
+ metadata_store={
+ "provider": "postgres",
+ "dsn": "postgresql+psycopg://user:password@host:5432/memu",
+ }
)
postgres_db = build_postgres_database(config=postgres_config, user_model=UserScope)
@@ -167,12 +184,12 @@ for res_id, resource in sqlite_db.resources.items():
```python
import asyncio
-from memu.app import MemoryService
+from memu import MemoryService
async def main():
# Initialize with SQLite
service = MemoryService(
- llm_profiles={"default": {"api_key": "your-api-key"}},
+ llm_profiles={"default": {"api_key": "OPENAI_API_KEY"}},
database_config={
"metadata_store": {
"provider": "sqlite",
@@ -192,7 +209,7 @@ async def main():
# Retrieve relevant memories
memories = await service.retrieve(
queries=[
- {"role": "user", "content": {"text": "What are my preferences?"}}
+ {"role": "user", "content": "What are my preferences?"}
],
where={"user_id": "alice"},
)
diff --git a/docs/tutorials/getting_started.md b/docs/tutorials/getting_started.md
index f198664a..a2fae28d 100644
--- a/docs/tutorials/getting_started.md
+++ b/docs/tutorials/getting_started.md
@@ -6,7 +6,7 @@ Welcome to MemU! This guide will help you add robust long-term memory capabiliti
Before we begin, ensure you have the following:
-- **Python 3.13+**: MemU takes advantage of modern Python features.
+- **Python 3.12+**: MemU takes advantage of modern Python features.
- **OpenAI API Key**: This quickstart uses OpenAI's models (`gpt-4o-mini`). You will need a valid API key.
## Step-by-Step Guide
@@ -16,11 +16,13 @@ Before we begin, ensure you have the following:
Install MemU using `pip` or `uv`:
```bash
-pip install memu
+pip install memu-py
# OR
-uv add memu
+uv add memu-py
```
+The package installs the `memu` Python import namespace.
+
### 2. Configuration
MemU requires an LLM backend to function. By default, it looks for the `OPENAI_API_KEY` environment variable.
@@ -61,7 +63,7 @@ import logging
import os
import sys
-from memu.app import MemoryService
+from memu import MemoryService
# Configure logging to show info but suppress noisy libraries
logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
@@ -110,6 +112,7 @@ async def main() -> None:
# We manually inject a memory into the system.
# This is useful for bootstrapping a user profile or adding explicit knowledge.
print("[*] Injecting memory...")
+ user_scope = {"user_id": "demo_user"}
memory_content = "The user is a senior Python architect who loves clean code and type hints."
# We use 'create_memory_item' to insert a single memory record.
@@ -118,6 +121,7 @@ async def main() -> None:
memory_type="profile",
memory_content=memory_content,
memory_categories=["User Facts"],
+ user=user_scope,
)
print(f"[OK] Memory created! ID: {result.get('memory_item', {}).get('id')}\n")
@@ -127,7 +131,8 @@ async def main() -> None:
print(f"[*] Querying: '{query_text}'")
search_results = await service.retrieve(
- queries=[{"role": "user", "content": query_text}]
+ queries=[{"role": "user", "content": query_text}],
+ where=user_scope,
)
# 5. Display Results
@@ -153,8 +158,8 @@ if __name__ == "__main__":
### Understanding the Code
1. **Initialization**: We configure `MemoryService` with specific `llm_profiles`. This tells MemU which model to use. We also define a `memorize_config` with a "User Facts" category. Categories help the LLM organize and retrieve information more effectively.
-2. **Memory Injection**: `create_memory_item` is used to explicitly add a piece of knowledge. We tag it with `memory_type="profile"` to semantically indicate this is a user attribute.
-3. **Retrieval**: We use `retrieve` with a natural language query. MemU's internal workflow ("RAG" or "LLM" based) will determine the best way to find relevant memories.
+2. **Memory Injection**: `create_memory_item` is used to explicitly add a piece of knowledge. We tag it with `memory_type="profile"` and `user=user_scope` to semantically indicate this is a scoped user attribute.
+3. **Retrieval**: We use `retrieve` with a natural language query and the same `where=user_scope` filter. MemU's internal workflow ("RAG" or "LLM" based) will determine the best way to find relevant memories within that user scope.
## Troubleshooting
diff --git a/examples/example_1_conversation_memory.py b/examples/example_1_conversation_memory.py
index e023fae3..fdfb68ea 100644
--- a/examples/example_1_conversation_memory.py
+++ b/examples/example_1_conversation_memory.py
@@ -12,12 +12,16 @@
import asyncio
import os
import sys
+from pathlib import Path
-from memu.app import MemoryService
+ROOT = Path(__file__).resolve().parents[1]
-# Add src to sys.path
-src_path = os.path.abspath("src")
-sys.path.insert(0, src_path)
+# Add src to sys.path before importing memu from a source checkout.
+src_path = str(ROOT / "src")
+if src_path not in sys.path:
+ sys.path.insert(0, src_path)
+
+from memu import MemoryService
async def generate_memory_md(categories, output_dir):
@@ -80,9 +84,9 @@ async def main():
# Conversation files to process
conversation_files = [
- "examples/resources/conversations/conv1.json",
- "examples/resources/conversations/conv2.json",
- "examples/resources/conversations/conv3.json",
+ ROOT / "examples" / "resources" / "conversations" / "conv1.json",
+ ROOT / "examples" / "resources" / "conversations" / "conv2.json",
+ ROOT / "examples" / "resources" / "conversations" / "conv3.json",
]
# Process each conversation
@@ -90,11 +94,11 @@ async def main():
total_items = 0
categories = []
for conv_file in conversation_files:
- if not os.path.exists(conv_file):
+ if not conv_file.exists():
continue
try:
- result = await service.memorize(resource_url=conv_file, modality="conversation")
+ result = await service.memorize(resource_url=str(conv_file), modality="conversation")
total_items += len(result.get("items", []))
# Categories are returned in the result and updated after each memorize call
categories = result.get("categories", [])
@@ -102,15 +106,15 @@ async def main():
print(f"Error: {e}")
# Write to output files
- output_dir = "examples/output/conversation_example"
+ output_dir = ROOT / "examples" / "output" / "conversation_example"
os.makedirs(output_dir, exist_ok=True)
# 1. Generate individual Markdown files for each category
await generate_memory_md(categories, output_dir)
- print(f"\n✓ Processed {len(conversation_files)} files, extracted {total_items} items")
- print(f"✓ Generated {len(categories)} categories")
- print(f"✓ Output: {output_dir}/")
+ print(f"\n[OK] Processed {len(conversation_files)} files, extracted {total_items} items")
+ print(f"[OK] Generated {len(categories)} categories")
+ print(f"[OK] Output: {output_dir}/")
if __name__ == "__main__":
diff --git a/examples/example_2_skill_extraction.py b/examples/example_2_skill_extraction.py
index 3ca75804..3861f174 100644
--- a/examples/example_2_skill_extraction.py
+++ b/examples/example_2_skill_extraction.py
@@ -12,14 +12,16 @@
import asyncio
import os
import sys
+from pathlib import Path
-from openai import AsyncOpenAI
+ROOT = Path(__file__).resolve().parents[1]
-from memu.app import MemoryService
+# Add src to sys.path before importing memu from a source checkout.
+src_path = str(ROOT / "src")
+if src_path not in sys.path:
+ sys.path.insert(0, src_path)
-# Add src to sys.path
-src_path = os.path.abspath("src")
-sys.path.insert(0, src_path)
+from memu import MemoryService
async def generate_skill_md(
@@ -107,23 +109,17 @@ async def generate_skill_md(
Generate the complete markdown document now:"""
- client = AsyncOpenAI(api_key=service.llm_config.api_key)
-
- response = await client.chat.completions.create(
- model=service.llm_config.chat_model,
- messages=[
- {
- "role": "system",
- "content": "You are an expert technical writer creating concise, production-grade deployment guides from real experiences.",
- },
- {"role": "user", "content": prompt},
- ],
+ system_prompt = (
+ "You are an expert technical writer creating concise, "
+ "production-grade deployment guides from real experiences."
+ )
+ generated_content = await service.llm_client.chat(
+ prompt,
+ system_prompt=system_prompt,
temperature=0.7,
max_tokens=3000,
)
- generated_content = response.choices[0].message.content
-
# Write to file
with open(output_file, "w", encoding="utf-8") as f:
f.write(generated_content)
@@ -157,7 +153,7 @@ async def main():
For each significant action or phase:
1. **Action/Phase**: What was being attempted?
- 2. **Status**: SUCCESS ✅ or FAILURE ❌
+ 2. **Status**: SUCCESS or FAILURE
3. **What Happened**: What was executed
4. **Outcome**: What worked/failed, metrics
5. **Root Cause** (for failures): Why did it fail?
@@ -177,7 +173,10 @@ async def main():
# Define custom categories
skill_categories = [
- {"name": "deployment_execution", "description": "Deployment actions, traffic shifting, environment management"},
+ {
+ "name": "deployment_execution",
+ "description": "Deployment actions, traffic shifting, environment management",
+ },
{
"name": "pre_deployment_validation",
"description": "Capacity validation, configuration checks, readiness verification",
@@ -216,9 +215,9 @@ async def main():
# Resources to process
resources = [
- ("examples/resources/logs/log1.txt", "document"),
- ("examples/resources/logs/log2.txt", "document"),
- ("examples/resources/logs/log3.txt", "document"),
+ (ROOT / "examples" / "resources" / "logs" / "log1.txt", "document"),
+ (ROOT / "examples" / "resources" / "logs" / "log2.txt", "document"),
+ (ROOT / "examples" / "resources" / "logs" / "log3.txt", "document"),
]
# Process each resource sequentially
@@ -227,16 +226,16 @@ async def main():
categories = []
for idx, (resource_file, modality) in enumerate(resources, 1):
- if not os.path.exists(resource_file):
+ if not resource_file.exists():
continue
try:
- result = await service.memorize(resource_url=resource_file, modality=modality)
+ result = await service.memorize(resource_url=str(resource_file), modality=modality)
# Extract skill items
for item in result.get("items", []):
if item.get("memory_type") == "skill":
- all_skills.append({"skill": item.get("summary", ""), "source": os.path.basename(resource_file)})
+ all_skills.append({"skill": item.get("summary", ""), "source": resource_file.name})
# Categories are returned in the result and updated after each memorize call
categories = result.get("categories", [])
@@ -245,7 +244,7 @@ async def main():
await generate_skill_md(
all_skills=all_skills,
service=service,
- output_file=f"examples/output/skill_example/log_{idx}.md",
+ output_file=ROOT / "examples" / "output" / "skill_example" / f"log_{idx}.md",
attempt_number=idx,
total_attempts=len(resources),
categories=categories,
@@ -258,16 +257,16 @@ async def main():
await generate_skill_md(
all_skills=all_skills,
service=service,
- output_file="examples/output/skill_example/skill.md",
+ output_file=ROOT / "examples" / "output" / "skill_example" / "skill.md",
attempt_number=len(resources),
total_attempts=len(resources),
categories=categories,
is_final=True,
)
- print(f"\n✓ Processed {len(resources)} files, extracted {len(all_skills)} skills")
- print(f"✓ Generated {len(categories)} categories")
- print("✓ Output: examples/output/skill_example/")
+ print(f"\n[OK] Processed {len(resources)} files, extracted {len(all_skills)} skills")
+ print(f"[OK] Generated {len(categories)} categories")
+ print(f"[OK] Output: {ROOT / 'examples' / 'output' / 'skill_example'}/")
if __name__ == "__main__":
diff --git a/examples/example_3_multimodal_memory.py b/examples/example_3_multimodal_memory.py
index 83aba74a..3a5c6a58 100644
--- a/examples/example_3_multimodal_memory.py
+++ b/examples/example_3_multimodal_memory.py
@@ -12,12 +12,16 @@
import asyncio
import os
import sys
+from pathlib import Path
-from memu.app import MemoryService
+ROOT = Path(__file__).resolve().parents[1]
-# Add src to sys.path
-src_path = os.path.abspath("src")
-sys.path.insert(0, src_path)
+# Add src to sys.path before importing memu from a source checkout.
+src_path = str(ROOT / "src")
+if src_path not in sys.path:
+ sys.path.insert(0, src_path)
+
+from memu import MemoryService
async def generate_memory_md(categories, output_dir):
@@ -100,9 +104,9 @@ async def main():
# Resources to process (file_path, modality)
resources = [
- ("examples/resources/docs/doc1.txt", "document"),
- ("examples/resources/docs/doc2.txt", "document"),
- ("examples/resources/images/image1.png", "image"),
+ (ROOT / "examples" / "resources" / "docs" / "doc1.txt", "document"),
+ (ROOT / "examples" / "resources" / "docs" / "doc2.txt", "document"),
+ (ROOT / "examples" / "resources" / "images" / "image1.png", "image"),
]
# Process each resource
@@ -110,11 +114,11 @@ async def main():
total_items = 0
categories = []
for resource_file, modality in resources:
- if not os.path.exists(resource_file):
+ if not resource_file.exists():
continue
try:
- result = await service.memorize(resource_url=resource_file, modality=modality)
+ result = await service.memorize(resource_url=str(resource_file), modality=modality)
total_items += len(result.get("items", []))
# Categories are returned in the result and updated after each memorize call
categories = result.get("categories", [])
@@ -122,15 +126,15 @@ async def main():
print(f"Error: {e}")
# Write to output files
- output_dir = "examples/output/multimodal_example"
+ output_dir = ROOT / "examples" / "output" / "multimodal_example"
os.makedirs(output_dir, exist_ok=True)
# 1. Generate individual Markdown files for each category
await generate_memory_md(categories, output_dir)
- print(f"\n✓ Processed {len(resources)} files, extracted {total_items} items")
- print(f"✓ Generated {len(categories)} categories")
- print(f"✓ Output: {output_dir}/")
+ print(f"\n[OK] Processed {len(resources)} files, extracted {total_items} items")
+ print(f"[OK] Generated {len(categories)} categories")
+ print(f"[OK] Output: {output_dir}/")
if __name__ == "__main__":
diff --git a/examples/example_4_openrouter_memory.py b/examples/example_4_openrouter_memory.py
index f5a8daa2..bc8539bf 100644
--- a/examples/example_4_openrouter_memory.py
+++ b/examples/example_4_openrouter_memory.py
@@ -12,11 +12,16 @@
import asyncio
import os
import sys
+from pathlib import Path
-from memu.app import MemoryService
+ROOT = Path(__file__).resolve().parents[1]
-src_path = os.path.abspath("src")
-sys.path.insert(0, src_path)
+# Add src to sys.path before importing memu from a source checkout.
+src_path = str(ROOT / "src")
+if src_path not in sys.path:
+ sys.path.insert(0, src_path)
+
+from memu import MemoryService
async def generate_memory_md(categories, output_dir):
@@ -76,9 +81,9 @@ async def main():
)
conversation_files = [
- "examples/resources/conversations/conv1.json",
- "examples/resources/conversations/conv2.json",
- "examples/resources/conversations/conv3.json",
+ ROOT / "examples" / "resources" / "conversations" / "conv1.json",
+ ROOT / "examples" / "resources" / "conversations" / "conv2.json",
+ ROOT / "examples" / "resources" / "conversations" / "conv3.json",
]
print("\nProcessing conversations...")
@@ -86,19 +91,19 @@ async def main():
categories = []
for conv_file in conversation_files:
- if not os.path.exists(conv_file):
+ if not conv_file.exists():
print(f"Skipped: {conv_file} not found")
continue
try:
print(f"Processing: {conv_file}")
- result = await service.memorize(resource_url=conv_file, modality="conversation")
+ result = await service.memorize(resource_url=str(conv_file), modality="conversation")
total_items += len(result.get("items", []))
categories = result.get("categories", [])
except Exception as e:
print(f"Error processing {conv_file}: {e}")
- output_dir = "examples/output/openrouter_example"
+ output_dir = ROOT / "examples" / "output" / "openrouter_example"
os.makedirs(output_dir, exist_ok=True)
await generate_memory_md(categories, output_dir)
diff --git a/examples/example_5_with_lazyllm_client.py b/examples/example_5_with_lazyllm_client.py
index 3b300298..672eadd8 100644
--- a/examples/example_5_with_lazyllm_client.py
+++ b/examples/example_5_with_lazyllm_client.py
@@ -23,13 +23,14 @@
import sys
from pathlib import Path
-# Add src to sys.path FIRST before importing memu
-project_root = Path(__file__).parent.parent
+# Add src to sys.path before importing memu from a source checkout.
+project_root = Path(__file__).resolve().parents[1]
+examples_dir = project_root / "examples"
src_path = str(project_root / "src")
if src_path not in sys.path:
sys.path.insert(0, src_path)
-from memu.app import MemoryService
+from memu import MemoryService
# ==========================================
# PART 1: Conversation Memory Processing
@@ -42,33 +43,33 @@ async def run_conversation_memory_demo(service):
print("=" * 60)
conversation_files = [
- "examples/resources/conversations/conv1.json",
- "examples/resources/conversations/conv2.json",
- "examples/resources/conversations/conv3.json",
+ examples_dir / "resources" / "conversations" / "conv1.json",
+ examples_dir / "resources" / "conversations" / "conv2.json",
+ examples_dir / "resources" / "conversations" / "conv3.json",
]
total_items = 0
categories = []
for conv_file in conversation_files:
- if not os.path.exists(conv_file):
- print(f"⚠ File not found: {conv_file}")
+ if not conv_file.exists():
+ print(f"[WARN] File not found: {conv_file}")
continue
try:
print(f" Processing: {conv_file}")
- result = await service.memorize(resource_url=conv_file, modality="conversation")
+ result = await service.memorize(resource_url=str(conv_file), modality="conversation")
total_items += len(result.get("items", []))
categories = result.get("categories", [])
- print(f" ✓ Extracted {len(result.get('items', []))} items")
+ print(f" [OK] Extracted {len(result.get('items', []))} items")
except Exception as e:
- print(f" ✗ Error processing {conv_file}: {e}")
+ print(f" [ERROR] Error processing {conv_file}: {e}")
# Output generation
- output_dir = "examples/output/lazyllm_example/conversation"
+ output_dir = examples_dir / "output" / "lazyllm_example" / "conversation"
os.makedirs(output_dir, exist_ok=True)
await generate_markdown_output(categories, output_dir)
- print(f"✓ Conversation processing complete. Output: {output_dir}")
+ print(f"[OK] Conversation processing complete. Output: {output_dir}")
# ==========================================
@@ -106,28 +107,32 @@ async def run_skill_extraction_demo(service):
service.memorize_config.memory_types = ["skill"]
service.memorize_config.memory_type_prompts = {"skill": skill_prompt}
- logs = ["examples/resources/logs/log1.txt", "examples/resources/logs/log2.txt", "examples/resources/logs/log3.txt"]
+ logs = [
+ examples_dir / "resources" / "logs" / "log1.txt",
+ examples_dir / "resources" / "logs" / "log2.txt",
+ examples_dir / "resources" / "logs" / "log3.txt",
+ ]
all_skills = []
for log_file in logs:
- if not os.path.exists(log_file):
+ if not log_file.exists():
continue
print(f" Processing log: {log_file}")
try:
- result = await service.memorize(resource_url=log_file, modality="document")
+ result = await service.memorize(resource_url=str(log_file), modality="document")
for item in result.get("items", []):
if item.get("memory_type") == "skill":
all_skills.append(item.get("summary", ""))
- print(f" ✓ Extracted {len(result.get('items', []))} skills")
+ print(f" [OK] Extracted {len(result.get('items', []))} skills")
except Exception as e:
- print(f" ✗ Error: {e}")
+ print(f" [ERROR] Error: {e}")
# Generate summary guide
if all_skills:
- output_file = "examples/output/lazyllm_example/skills/skill_guide.md"
+ output_file = examples_dir / "output" / "lazyllm_example" / "skills" / "skill_guide.md"
await generate_skill_guide(all_skills, service, output_file)
- print(f"✓ Skill guide generated: {output_file}")
+ print(f"[OK] Skill guide generated: {output_file}")
# ==========================================
@@ -159,27 +164,27 @@ async def run_multimodal_demo(service):
service.memorize_config.memory_type_prompts = {"knowledge": xml_prompt}
resources = [
- ("examples/resources/docs/doc1.txt", "document"),
- ("examples/resources/images/image1.png", "image"),
+ (examples_dir / "resources" / "docs" / "doc1.txt", "document"),
+ (examples_dir / "resources" / "images" / "image1.png", "image"),
]
categories = []
for res_file, modality in resources:
- if not os.path.exists(res_file):
+ if not res_file.exists():
continue
print(f" Processing {modality}: {res_file}")
try:
- result = await service.memorize(resource_url=res_file, modality=modality)
+ result = await service.memorize(resource_url=str(res_file), modality=modality)
categories = result.get("categories", [])
- print(f" ✓ Extracted {len(result.get('items', []))} items")
+ print(f" [OK] Extracted {len(result.get('items', []))} items")
except Exception as e:
- print(f" ✗ Error: {e}")
+ print(f" [ERROR] Error: {e}")
- output_dir = "examples/output/lazyllm_example/multimodal"
+ output_dir = examples_dir / "output" / "lazyllm_example" / "multimodal"
os.makedirs(output_dir, exist_ok=True)
await generate_markdown_output(categories, output_dir)
- print(f"✓ Multimodal processing complete. Output: {output_dir}")
+ print(f"[OK] Multimodal processing complete. Output: {output_dir}")
# ==========================================
diff --git a/examples/getting_started_robust.py b/examples/getting_started_robust.py
index 883af997..d10cf9ab 100644
--- a/examples/getting_started_robust.py
+++ b/examples/getting_started_robust.py
@@ -16,11 +16,14 @@
import logging
import os
import sys
+from pathlib import Path
-# Ensure src is in the path for local usage if custom installing
-sys.path.insert(0, os.path.abspath("src"))
+# Add src to sys.path before importing memu from a source checkout.
+src_path = str(Path(__file__).resolve().parents[1] / "src")
+if src_path not in sys.path:
+ sys.path.insert(0, src_path)
-from memu.app import MemoryService
+from memu import MemoryService
# Configure logging to show info but suppress noisy libraries
logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
@@ -69,6 +72,7 @@ async def main() -> None:
# We manually inject a memory into the system.
# This is useful for bootstrapping a user profile or adding explicit knowledge.
print("[*] Injecting memory...")
+ user_scope = {"user_id": "demo_user"}
memory_content = "The user is a senior Python architect who loves clean code and type hints."
# We use 'create_memory_item' to insert a single memory record.
@@ -77,6 +81,7 @@ async def main() -> None:
memory_type="profile",
memory_content=memory_content,
memory_categories=["User Facts"],
+ user=user_scope,
)
print(f"[OK] Memory created! ID: {result.get('memory_item', {}).get('id')}\n")
@@ -85,7 +90,10 @@ async def main() -> None:
query_text = "What kind of code does the user like?"
print(f"[*] Querying: '{query_text}'")
- search_results = await service.retrieve(queries=[{"role": "user", "content": query_text}])
+ search_results = await service.retrieve(
+ queries=[{"role": "user", "content": query_text}],
+ where=user_scope,
+ )
# 5. Display Results
items = search_results.get("items", [])
diff --git a/examples/langgraph_demo.py b/examples/langgraph_demo.py
index 4107452f..5a90e7dc 100644
--- a/examples/langgraph_demo.py
+++ b/examples/langgraph_demo.py
@@ -4,18 +4,32 @@
import logging
import os
import sys
+from pathlib import Path
-# Try imports and fail proactively if missing
+INSTALL_HINT = (
+ "Missing LangGraph dependencies. Install them with "
+ "pip install 'memu-py[langgraph]', or run uv sync --extra langgraph "
+ "from a source checkout."
+)
+
+# Add src to sys.path before importing memu from a source checkout.
+src_path = str(Path(__file__).resolve().parents[1] / "src")
+if src_path not in sys.path:
+ sys.path.insert(0, src_path)
+
+# Try optional integration imports first and fail proactively if missing.
try:
import langgraph # noqa: F401
from langchain_core.tools import BaseTool
-
- from memu.app.service import MemoryService
- from memu.integrations.langgraph import MemULangGraphTools
-except ImportError:
- print("Missing dependencies. Please run: uv sync --extra langgraph")
+except ModuleNotFoundError as exc:
+ if exc.name not in {"langgraph", "langchain_core"}:
+ raise
+ print(INSTALL_HINT)
sys.exit(1)
+from memu import MemoryService
+from memu.integrations.langgraph import MemULangGraphTools
+
# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("langgraph_demo")
diff --git a/examples/proactive/memory/__init__.py b/examples/proactive/memory/__init__.py
new file mode 100644
index 00000000..5b2a5286
--- /dev/null
+++ b/examples/proactive/memory/__init__.py
@@ -0,0 +1 @@
+"""Shared helpers for the proactive memory examples."""
diff --git a/examples/proactive/memory/claude_sdk.py b/examples/proactive/memory/claude_sdk.py
new file mode 100644
index 00000000..0b0b40b6
--- /dev/null
+++ b/examples/proactive/memory/claude_sdk.py
@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+INSTALL_HINT = (
+ "The proactive Claude example requires claude-agent-sdk. "
+ "Install the optional extra with `pip install 'memu-py[claude]'`, "
+ "or run `uv sync --extra claude` from a source checkout."
+)
+
+try:
+ from claude_agent_sdk import (
+ AssistantMessage,
+ ClaudeAgentOptions,
+ ClaudeSDKClient,
+ ResultMessage,
+ TextBlock,
+ create_sdk_mcp_server,
+ tool,
+ )
+except ModuleNotFoundError as exc:
+ if exc.name != "claude_agent_sdk":
+ raise
+ raise SystemExit(INSTALL_HINT) from exc
+
+__all__ = [
+ "AssistantMessage",
+ "ClaudeAgentOptions",
+ "ClaudeSDKClient",
+ "ResultMessage",
+ "TextBlock",
+ "create_sdk_mcp_server",
+ "tool",
+]
diff --git a/examples/proactive/memory/config.py b/examples/proactive/memory/config.py
index 622d5e11..0b138fb1 100644
--- a/examples/proactive/memory/config.py
+++ b/examples/proactive/memory/config.py
@@ -27,7 +27,7 @@
"name": "todo",
"description": "This file traces the latest status of the task. All records should be included in this file.",
"target_length": None,
- "custom_prompt": {
+ "summary_prompt": {
"objective": {
"ordinal": 10,
"prompt": "# Task Objective\nYou are a specialist in task management. You should update the markdown file to reflect the latest status of the task.",
diff --git a/examples/proactive/memory/local/common.py b/examples/proactive/memory/local/common.py
index 8f6394cd..249efb03 100644
--- a/examples/proactive/memory/local/common.py
+++ b/examples/proactive/memory/local/common.py
@@ -1,6 +1,6 @@
import os
-from memu.app import MemoryService
+from memu import MemoryService
from ..config import memorize_config, retrieve_config
diff --git a/examples/proactive/memory/local/tools.py b/examples/proactive/memory/local/tools.py
index 7062c2c5..f204bb77 100644
--- a/examples/proactive/memory/local/tools.py
+++ b/examples/proactive/memory/local/tools.py
@@ -1,7 +1,6 @@
from typing import Any
-from claude_agent_sdk import create_sdk_mcp_server, tool
-
+from ..claude_sdk import create_sdk_mcp_server, tool
from .common import get_memory_service
USER_ID = "claude_user"
@@ -14,7 +13,7 @@ async def get_memory(args: dict[str, Any]) -> dict[str, Any]:
memory_service = get_memory_service()
- result = await memory_service.retrieve(query, where={"user_id": USER_ID})
+ result = await memory_service.retrieve(queries=[query], where={"user_id": USER_ID})
return {"content": [{"type": "text", "text": str(result)}]}
diff --git a/examples/proactive/memory/platform/common.py b/examples/proactive/memory/platform/common.py
new file mode 100644
index 00000000..ae868a0e
--- /dev/null
+++ b/examples/proactive/memory/platform/common.py
@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class PlatformMemoryConfig:
+ base_url: str
+ api_key: str
+ user_id: str
+ agent_id: str
+
+
+def get_platform_memory_config() -> PlatformMemoryConfig:
+ api_key = os.getenv("MEMU_API_KEY", "").strip()
+ if not api_key:
+ msg = "Please set MEMU_API_KEY for the platform proactive example"
+ raise ValueError(msg)
+
+ base_url = os.getenv("MEMU_BASE_URL", "https://api.memu.so").strip().rstrip("/")
+ user_id = os.getenv("MEMU_USER_ID", "claude_user").strip() or "claude_user"
+ agent_id = os.getenv("MEMU_AGENT_ID", "claude_agent").strip() or "claude_agent"
+
+ return PlatformMemoryConfig(
+ base_url=base_url or "https://api.memu.so",
+ api_key=api_key,
+ user_id=user_id,
+ agent_id=agent_id,
+ )
diff --git a/examples/proactive/memory/platform/memorize.py b/examples/proactive/memory/platform/memorize.py
index 9fc1722f..3c436190 100644
--- a/examples/proactive/memory/platform/memorize.py
+++ b/examples/proactive/memory/platform/memorize.py
@@ -1,31 +1,26 @@
from typing import Any
-import aiohttp
+import httpx
from ..config import memorize_config
-
-BASE_URL = "https://api.memu.so"
-API_KEY = "your memu api key"
-USER_ID = "claude_user"
-AGENT_ID = "claude_agent"
+from .common import get_platform_memory_config
async def memorize(conversation_messages: list[dict[str, Any]]) -> str | None:
+ config = get_platform_memory_config()
payload = {
"conversation": conversation_messages,
- "user_id": USER_ID,
- "agent_id": AGENT_ID,
+ "user_id": config.user_id,
+ "agent_id": config.agent_id,
"override_config": memorize_config,
}
- async with (
- aiohttp.ClientSession() as session,
- session.post(
- f"{BASE_URL}/api/v3/memory/memorize",
- headers={"Authorization": f"Bearer {API_KEY}"},
+ async with httpx.AsyncClient(timeout=30.0) as client:
+ response = await client.post(
+ f"{config.base_url}/api/v3/memory/memorize",
+ headers={"Authorization": f"Bearer {config.api_key}"},
json=payload,
- ) as response,
- ):
- result = await response.json()
- task_id = result["task_id"]
- return task_id
+ )
+ response.raise_for_status()
+ result = response.json()
+ return result["task_id"]
diff --git a/examples/proactive/memory/platform/tools.py b/examples/proactive/memory/platform/tools.py
index 5ed859de..9b345c0d 100644
--- a/examples/proactive/memory/platform/tools.py
+++ b/examples/proactive/memory/platform/tools.py
@@ -1,37 +1,40 @@
from typing import Any
-import aiohttp
-from claude_agent_sdk import create_sdk_mcp_server, tool
+import httpx
-BASE_URL = "https://api.memu.so"
-API_KEY = "your memu api key"
-USER_ID = "claude_user"
-AGENT_ID = "claude_agent"
+from ..claude_sdk import create_sdk_mcp_server, tool
+from .common import get_platform_memory_config
@tool("memu_memory", "Retrieve memory based on a query", {"query": str})
async def get_memory(args: dict[str, Any]) -> dict[str, Any]:
"""Retrieve memory from the memory API based on the provided query."""
query = args["query"]
- url = f"{BASE_URL}/api/v3/memory/retrieve"
- headers = {"Authorization": f"Bearer {API_KEY}"}
- data = {"user_id": USER_ID, "agent_id": AGENT_ID, "query": query}
+ config = get_platform_memory_config()
+ url = f"{config.base_url}/api/v3/memory/retrieve"
+ headers = {"Authorization": f"Bearer {config.api_key}"}
+ data = {"user_id": config.user_id, "agent_id": config.agent_id, "query": query}
- async with aiohttp.ClientSession() as session, session.post(url, headers=headers, json=data) as response:
- result = await response.json()
+ async with httpx.AsyncClient(timeout=30.0) as client:
+ response = await client.post(url, headers=headers, json=data)
+ response.raise_for_status()
+ result = response.json()
return {"content": [{"type": "text", "text": str(result)}]}
async def _get_todos() -> str:
- url = f"{BASE_URL}/api/v3/memory/categories"
- headers = {"Authorization": f"Bearer {API_KEY}"}
+ config = get_platform_memory_config()
+ url = f"{config.base_url}/api/v3/memory/categories"
+ headers = {"Authorization": f"Bearer {config.api_key}"}
data = {
- "user_id": USER_ID,
- "agent_id": AGENT_ID,
+ "user_id": config.user_id,
+ "agent_id": config.agent_id,
}
- async with aiohttp.ClientSession() as session, session.post(url, headers=headers, json=data) as response:
- result = await response.json()
+ async with httpx.AsyncClient(timeout=30.0) as client:
+ response = await client.post(url, headers=headers, json=data)
+ response.raise_for_status()
+ result = response.json()
categories = result["categories"]
todos = ""
diff --git a/examples/proactive/proactive.py b/examples/proactive/proactive.py
index 7ffe10c1..2b53fa80 100644
--- a/examples/proactive/proactive.py
+++ b/examples/proactive/proactive.py
@@ -1,6 +1,14 @@
import asyncio
+import sys
+from pathlib import Path
+from typing import Any
-from claude_agent_sdk import (
+# Add src to sys.path before memory.local imports memu from a source checkout.
+src_path = str(Path(__file__).resolve().parents[2] / "src")
+if src_path not in sys.path:
+ sys.path.insert(0, src_path)
+
+from memory.claude_sdk import (
AssistantMessage,
ClaudeAgentOptions,
ClaudeSDKClient,
@@ -17,7 +25,7 @@
RUNNING_MEMORIZATION: asyncio.Task | None = None
-async def trigger_memorize(messages: list[dict[str, any]]) -> bool:
+async def trigger_memorize(messages: list[dict[str, Any]]) -> bool:
"""Create a background task to memorize conversation messages.
Returns True if the task was successfully created and registered.
@@ -94,7 +102,7 @@ async def process_response(client: ClaudeSDKClient) -> list[str]:
return assistant_text_parts
-async def check_and_memorize(conversation_messages: list[dict[str, any]]) -> None:
+async def check_and_memorize(conversation_messages: list[dict[str, Any]]) -> None:
"""Check if memorization threshold is reached and trigger if needed.
Skips triggering if a previous memorization task is still running.
@@ -122,9 +130,9 @@ async def check_and_memorize(conversation_messages: list[dict[str, any]]) -> Non
conversation_messages.clear()
-async def run_conversation_loop(client: ClaudeSDKClient) -> list[dict[str, any]]:
+async def run_conversation_loop(client: ClaudeSDKClient) -> list[dict[str, Any]]:
"""Run the main conversation loop."""
- conversation_messages: list[dict[str, any]] = []
+ conversation_messages: list[dict[str, Any]] = []
iteration = 0
while True:
@@ -152,7 +160,7 @@ async def run_conversation_loop(client: ClaudeSDKClient) -> list[dict[str, any]]
return conversation_messages
-async def main():
+async def main() -> None:
options = ClaudeAgentOptions(
mcp_servers={"memu": memu_server},
allowed_tools=[
diff --git a/examples/resources/docs/doc1.txt b/examples/resources/docs/doc1.txt
index ff280176..1c28136f 100644
--- a/examples/resources/docs/doc1.txt
+++ b/examples/resources/docs/doc1.txt
@@ -255,40 +255,43 @@ API Reference
Basic Usage Example:
```python
-from memu.app import MemoryService
+from memu import MemoryService
# Initialize service
service = MemoryService(
- llm_config={
- "api_key": "your-api-key",
- "chat_model": "gpt-4o-mini"
+ llm_profiles={
+ "default": {
+ "api_key": "OPENAI_API_KEY",
+ "chat_model": "gpt-4o-mini"
+ }
}
)
# Store a memory
result = await service.memorize(
resource_url="conversation.json",
- modality="conversation"
+ modality="conversation",
+ user={"user_id": "alex"}
)
# Retrieve memories
memories = await service.retrieve(
- query="What programming languages does Alex know?",
- top_k=5
+ queries=["What programming languages does Alex know?"],
+ where={"user_id": "alex"}
)
# Access categories
-categories = service.store.categories
+categories = await service.list_memory_categories(where={"user_id": "alex"})
```
Advanced Configuration:
```python
-# Custom memory types
+# Memory extraction configuration
memorize_config = {
- "memory_types": ["profile", "knowledge", "custom"],
+ "memory_types": ["profile", "knowledge", "skill"],
"memory_type_prompts": {
- "custom": "Extract specific information: {resource}"
+ "skill": "Extract actionable skills and workflows: {resource}"
},
"memory_categories": [
{"name": "technical_skills", "description": "Programming and technical abilities"},
@@ -297,7 +300,7 @@ memorize_config = {
}
service = MemoryService(
- llm_config=llm_config,
+ llm_profiles={"default": {"api_key": "OPENAI_API_KEY"}},
memorize_config=memorize_config
)
```
diff --git a/examples/sealos_support_agent.py b/examples/sealos_support_agent.py
index 710ef009..2eeb2f44 100644
--- a/examples/sealos_support_agent.py
+++ b/examples/sealos_support_agent.py
@@ -1,19 +1,34 @@
import sys
import time
+from pathlib import Path
-# Intentamos importar la librería instalada por uv
+
+def configure_output_encoding() -> None:
+ """Keep demo output usable on Windows terminals with legacy encodings."""
+ for stream in (sys.stdout, sys.stderr):
+ if hasattr(stream, "reconfigure"):
+ stream.reconfigure(encoding="utf-8", errors="replace")
+
+
+configure_output_encoding()
+
+# Add src to sys.path before importing memu from a source checkout.
+src_path = str(Path(__file__).resolve().parents[1] / "src")
+if src_path not in sys.path:
+ sys.path.insert(0, src_path)
+
+# Detect whether the package import namespace is available.
try:
- from memu import Memory # noqa: F401
+ import memu # noqa: F401
MEMU_INSTALLED = True
except ImportError as e:
- # Si falla, guardamos el error para debug
MEMU_INSTALLED = False
IMPORT_ERROR = str(e)
-def print_slow(text, delay=0.02):
- """Typing effect for realism"""
+def print_slow(text: str, delay: float = 0.02) -> None:
+ """Typing effect for realism."""
for char in text:
sys.stdout.write(char)
sys.stdout.flush()
@@ -21,48 +36,49 @@ def print_slow(text, delay=0.02):
print()
-def run_rigorous_demo():
- print("\n🚀 Starting Sealos Support Agent Demo (Offline Mode)")
+def run_rigorous_demo() -> None:
+ print("\n[START] Starting Sealos Support Agent Demo (Offline Mode)")
print("===================================================\n")
# 1. ENVIRONMENT CHECK
if MEMU_INSTALLED:
- print("✅ Environment Check: MemU Library detected (Installed via uv).")
- print("✅ Runtime: Sealos Devbox (Python 3.13+)")
+ print("[OK] Environment Check: MemU Library detected.")
+ print("[OK] Runtime: Sealos Devbox (Python 3.12+)")
else:
- # En caso de error, mostramos advertencia pero permitimos la captura
- print("⚠️ Warning: MemU library not detected. Running in Simulation Mode.")
- if "IMPORT_ERROR" in globals():
- print(f" Debug Error: {IMPORT_ERROR}")
+ print("[WARN] memU runtime is not fully importable. Running in Simulation Mode.")
+ print(" Run uv sync or pip install memu-py to use the live package mode.")
time.sleep(0.5)
# 2. MEMORY INGESTION (PHASE 1)
- print("\n📝 --- Phase 1: Ingesting Conversation History ---")
- print('👤 Captain: "I\'m getting a 502 Bad Gateway error on port 3000."')
- print_slow("🤖 Agent: (Processing input through Memory Pipeline...)", delay=0.01)
+ print("\n[PHASE 1] Ingesting Conversation History")
+ print('Captain: "I\'m getting a 502 Bad Gateway error on port 3000."')
+ print_slow("Agent: (Processing input through Memory Pipeline...)", delay=0.01)
time.sleep(1.0)
- print("✅ Memory stored! extracted 2 items:")
+ print("[OK] Memory stored! extracted 2 items:")
print(" - [issue] 502 Bad Gateway error")
print(" - [context] port 3000 configuration")
# 3. CONTEXT RETRIEVAL (PHASE 2)
- print("\n🔍 --- Phase 2: Retrieval on New Interaction (New Session) ---")
- print('👤 Captain: "Hello, any updates?"')
- print_slow("🤖 Agent: (Searching vector store for user 'Captain'...)", delay=0.01)
+ print("\n[PHASE 2] Retrieval on New Interaction (New Session)")
+ print('Captain: "Hello, any updates?"')
+ print_slow("Agent: (Searching vector store for user 'Captain'...)", delay=0.01)
time.sleep(1.0)
- print("\n💡 Retrieved Context:")
+ print("\n[CONTEXT] Retrieved Context:")
print(" Found Memory (Score: 0.98): User reported 502 error on port 3000")
print(" Found Memory (Score: 0.95): User was frustrated with timeout")
# 4. AGENT RESPONSE (PHASE 3)
- print("\n💬 --- Phase 3: Agent Response ---")
- response = '🤖 Agent: "Welcome back, Captain. Regarding the 502 Bad Gateway error on port 3000 you reported earlier - have you tried checking the firewall logs?"'
+ print("\n[PHASE 3] Agent Response")
+ response = (
+ 'Agent: "Welcome back, Captain. Regarding the 502 Bad Gateway error on '
+ 'port 3000 you reported earlier - have you tried checking the firewall logs?"'
+ )
print_slow(response)
- print("\n✨ Demo Completed Successfully")
+ print("\n[DONE] Demo Completed Successfully")
print("===================================================")
diff --git a/examples/test_nebius_provider.py b/examples/test_nebius_provider.py
index 5df5e59a..d2a44dca 100644
--- a/examples/test_nebius_provider.py
+++ b/examples/test_nebius_provider.py
@@ -19,10 +19,12 @@
import asyncio
import os
import sys
+from pathlib import Path
-# Add src to path for local development
-src_path = os.path.abspath("src")
-sys.path.insert(0, src_path)
+# Add src to sys.path before importing memu from a source checkout.
+src_path = str(Path(__file__).resolve().parents[1] / "src")
+if src_path not in sys.path:
+ sys.path.insert(0, src_path)
# Nebius configuration
NEBIUS_BASE_URL = "https://api.tokenfactory.nebius.com/v1/"
@@ -68,10 +70,10 @@ async def test_nebius_chat():
# Truncate long responses for display
display = content[:100] + "..." if len(content) > 100 else content
print(f" Response: {display}")
- print(" ✓ Chat API works!")
+ print(" [OK] Chat API works!")
return True
except Exception as e:
- print(f" ✗ Chat API failed: {e}")
+ print(f" [ERROR] Chat API failed: {e}")
return False
@@ -97,16 +99,16 @@ async def test_nebius_embeddings():
)
print(f" Embedding dimensions: {len(response.data[0].embedding)}")
print(f" Number of embeddings: {len(response.data)}")
- print(" ✓ Embeddings API works!")
+ print(" [OK] Embeddings API works!")
return True
except Exception as e:
- print(f" ✗ Embeddings API failed: {e}")
+ print(f" [ERROR] Embeddings API failed: {e}")
return False
async def test_memu_with_nebius():
"""Test MemU with Nebius as the LLM provider."""
- from memu.app import MemoryService
+ from memu import MemoryService
api_key = os.environ.get("NEBIUS_API_KEY")
if not api_key:
@@ -136,7 +138,7 @@ async def test_memu_with_nebius():
try:
# Create MemU service with Nebius
service = MemoryService(llm_profiles=llm_profiles)
- print(" ✓ MemoryService initialized with Nebius!")
+ print(" [OK] MemoryService initialized with Nebius!")
# Test memorize with a file (create temp file)
print("\n Testing memorize...")
@@ -149,11 +151,11 @@ async def test_memu_with_nebius():
try:
result = await service.memorize(
resource_url=temp_file,
- modality="text",
+ modality="document",
)
items_count = len(result.get("items", []))
categories_count = len(result.get("categories", []))
- print(f" ✓ Memorized! Items: {items_count}, Categories: {categories_count}")
+ print(f" [OK] Memorized! Items: {items_count}, Categories: {categories_count}")
# Show what was extracted
for item in result.get("items", [])[:3]:
@@ -167,7 +169,7 @@ async def test_memu_with_nebius():
retrieve_result = await service.retrieve(
queries=[{"role": "user", "content": "What programming language does the user like?"}]
)
- print(f" ✓ Retrieved! Needs retrieval: {retrieve_result.get('needs_retrieval')}")
+ print(f" [OK] Retrieved! Needs retrieval: {retrieve_result.get('needs_retrieval')}")
items = retrieve_result.get("items", [])
if items:
@@ -180,12 +182,12 @@ async def test_memu_with_nebius():
print(f" - {summary}...")
print("\n" + "=" * 60)
- print("✓ SUCCESS: MemU works with Nebius!")
+ print("[OK] SUCCESS: MemU works with Nebius!")
print("=" * 60)
return True
except Exception as e:
- print(f" ✗ MemU with Nebius failed: {e}")
+ print(f" [ERROR] MemU with Nebius failed: {e}")
import traceback
traceback.print_exc()
@@ -220,7 +222,7 @@ async def main():
await test_memu_with_nebius()
else:
print("\n" + "=" * 60)
- print("✗ FAILED: Basic API tests failed, skipping MemU test")
+ print("[ERROR] FAILED: Basic API tests failed, skipping MemU test")
print("=" * 60)
diff --git a/readme/README_en.md b/readme/README_en.md
index 1cb36490..cbfecf3f 100644
--- a/readme/README_en.md
+++ b/readme/README_en.md
@@ -8,7 +8,7 @@
[](https://badge.fury.io/py/memu-py)
[](https://opensource.org/licenses/Apache-2.0)
-[](https://www.python.org/downloads/)
+[](https://www.python.org/downloads/)
[](https://discord.gg/memu)
[](https://x.com/memU_ai)
@@ -28,7 +28,7 @@ memU **continuously captures and understands user intent**. Even without a comma
## 🤖 [OpenClaw (Moltbot, Clawdbot) Alternative](https://memu.bot)
-
+
- **Download-and-use and simple** to get started.
- Builds long-term memory to **understand user intent** and act proactively.
@@ -77,7 +77,7 @@ Just as a file system turns raw bytes into organized data, memU transforms raw i
## ⭐️ Star the repository
-
+
If you find memU useful or interesting, a GitHub Star ⭐️ would be greatly appreciated.
---
@@ -95,10 +95,14 @@ If you find memU useful or interesting, a GitHub Star ⭐️ would be greatly ap
## 🔄 How Proactive Memory Works
```bash
-
+pip install "memu-py[claude]"
+# From a source checkout, use: uv sync --extra claude
+export OPENAI_API_KEY="..."
+export ANTHROPIC_API_KEY="..."
+# Optional when using memory.platform instead of memory.local:
+export MEMU_API_KEY="..."
cd examples/proactive
python proactive.py
-
```
---
@@ -275,18 +279,17 @@ For enterprise deployment with custom proactive workflows, contact **info@nevami
#### Installation
```bash
-pip install -e .
+pip install memu-py
```
#### Basic Example
-> **Requirements**: Python 3.13+ and an OpenAI API key
+> **Requirements**: Python 3.12+ and an OpenAI API key
**Test Continuous Learning** (in-memory):
```bash
export OPENAI_API_KEY=your_api_key
-cd tests
-python test_inmemory.py
+python examples/getting_started_robust.py
```
**Test with Persistent Storage** (PostgreSQL):
@@ -301,9 +304,10 @@ docker run -d \
pgvector/pgvector:pg16
# Run continuous learning test
+uv sync --extra postgres
export OPENAI_API_KEY=your_api_key
-cd tests
-python test_postgres.py
+export MEMU_RUN_POSTGRES_TESTS=1
+uv run python -m pytest tests/test_postgres.py
```
Both examples demonstrate **proactive memory workflows**:
@@ -311,9 +315,9 @@ Both examples demonstrate **proactive memory workflows**:
2. **Auto-Extraction**: Immediate memory creation
3. **Proactive Retrieval**: Context-aware memory surfacing
-See [`tests/test_inmemory.py`](../tests/test_inmemory.py) and [`tests/test_postgres.py`](../tests/test_postgres.py) for implementation details.
-
----
+See [`tests/test_inmemory.py`](../tests/test_inmemory.py), [`tests/test_sqlite.py`](../tests/test_sqlite.py),
+and [`tests/test_postgres.py`](../tests/test_postgres.py) for implementation details. The in-memory and SQLite
+live LLM checks are opt-in with `MEMU_RUN_LIVE_LLM_TESTS=1`.
### Custom LLM and Embedding Providers
@@ -326,14 +330,14 @@ service = MemUService(
# Default profile for LLM operations
"default": {
"base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
- "api_key": "your_api_key",
+ "api_key": "MEMU_QWEN_API_KEY",
"chat_model": "qwen3-max",
- "client_backend": "sdk" # "sdk" or "http"
+ "client_backend": "sdk" # "sdk", "httpx", or "lazyllm_backend"
},
# Separate profile for embeddings
"embedding": {
"base_url": "https://api.voyageai.com/v1",
- "api_key": "your_voyage_api_key",
+ "api_key": "VOYAGE_API_KEY",
"embed_model": "voyage-3.5-lite"
}
},
@@ -341,6 +345,19 @@ service = MemUService(
)
```
+The `lazyllm_backend` adapter is optional. Install it with
+`pip install "memu-py[lazyllm]"` or, from a source checkout,
+`uv sync --extra lazyllm`.
+
+Optional LazyLLM live check:
+
+```bash
+uv sync --extra lazyllm
+export MEMU_QWEN_API_KEY=your_api_key
+export MEMU_RUN_LAZYLLM_TESTS=1
+uv run python -m pytest tests/test_lazyllm.py
+```
+
---
### OpenRouter Integration
@@ -357,7 +374,7 @@ service = MemoryService(
"provider": "openrouter",
"client_backend": "httpx",
"base_url": "https://openrouter.ai",
- "api_key": "your_openrouter_api_key",
+ "api_key": "OPENROUTER_API_KEY",
"chat_model": "anthropic/claude-3.5-sonnet", # Any OpenRouter model
"embed_model": "openai/text-embedding-3-small", # Embedding model
},
@@ -385,15 +402,10 @@ service = MemoryService(
#### Running OpenRouter Tests
```bash
export OPENROUTER_API_KEY=your_api_key
+export MEMU_RUN_OPENROUTER_TESTS=1
# Full workflow test (memorize + retrieve)
-python tests/test_openrouter.py
-
-# Embedding-specific tests
-python tests/test_openrouter_embedding.py
-
-# Vision-specific tests
-python tests/test_openrouter_vision.py
+uv run python -m pytest tests/test_openrouter.py
```
See [`examples/example_4_openrouter_memory.py`](../examples/example_4_openrouter_memory.py) for a complete working example.
@@ -464,8 +476,8 @@ Deep **anticipatory reasoning** for complex contexts:
# Proactive retrieval with context history
result = await service.retrieve(
queries=[
- {"role": "user", "content": {"text": "What are their preferences?"}},
- {"role": "user", "content": {"text": "Tell me about work habits"}}
+ {"role": "user", "content": "What are their preferences?"},
+ {"role": "user", "content": "Tell me about work habits"}
],
where={"user_id": "123"}, # Optional: scope filter
method="rag" # or "llm" for deeper reasoning
@@ -480,12 +492,14 @@ result = await service.retrieve(
}
```
+For a single user query, Python callers can also pass `queries=["What are their preferences?"]`; MemU normalizes it to a user message before retrieval.
+
**Proactive Filtering**: Use `where` to scope continuous monitoring:
- `where={"user_id": "123"}` - User-specific context
- `where={"agent_id__in": ["1", "2"]}` - Multi-agent coordination
- Omit `where` for global context awareness
-> 📚 **For complete API documentation**, see [SERVICE_API.md](../docs/SERVICE_API.md) - includes proactive workflow patterns, pipeline configuration, and real-time update handling.
+> 📚 **For complete API documentation**, see [memu.pro/docs](https://memu.pro/docs) - includes proactive workflow patterns, pipeline configuration, and real-time update handling.
---
@@ -559,7 +573,7 @@ View detailed experimental data: [memU-experiment](https://github.com/NevaMind-A
| Repository | Description | Proactive Features |
|------------|-------------|-------------------|
-| **[memU](https://github.com/NevaMind-AI/memU)** | Core proactive memory engine | 7×24 learning pipeline, auto-categorization |
+| **[memU](https://github.com/NevaMind-AI/MemU)** | Core proactive memory engine | 7×24 learning pipeline, auto-categorization |
| **[memU-server](https://github.com/NevaMind-AI/memU-server)** | Backend with continuous sync | Real-time memory updates, webhook triggers |
| **[memU-ui](https://github.com/NevaMind-AI/memU-ui)** | Visual memory dashboard | Live memory evolution monitoring |
@@ -596,7 +610,7 @@ We welcome contributions from the community! Whether you're fixing bugs, adding
To start contributing to MemU, you'll need to set up your development environment:
#### Prerequisites
-- Python 3.13+
+- Python 3.12+
- [uv](https://github.com/astral-sh/uv) (Python package manager)
- Git
@@ -649,7 +663,7 @@ For detailed contribution guidelines, code standards, and development practices,
## 🌍 Community
-- **GitHub Issues**: [Report bugs & request features](https://github.com/NevaMind-AI/memU/issues)
+- **GitHub Issues**: [Report bugs & request features](https://github.com/NevaMind-AI/MemU/issues)
- **Discord**: [Join the community](https://discord.com/invite/hQZntfGsbJ)
- **X (Twitter)**: [Follow @memU_ai](https://x.com/memU_ai)
- **Contact**: info@nevamind.ai
diff --git a/readme/README_es.md b/readme/README_es.md
index a0edff7d..2d300873 100644
--- a/readme/README_es.md
+++ b/readme/README_es.md
@@ -8,7 +8,7 @@
[](https://badge.fury.io/py/memu-py)
[](https://opensource.org/licenses/Apache-2.0)
-[](https://www.python.org/downloads/)
+[](https://www.python.org/downloads/)
[](https://discord.gg/memu)
[](https://x.com/memU_ai)
@@ -28,7 +28,7 @@ memU **captura y comprende continuamente la intención del usuario**. Incluso si
## 🤖 [OpenClaw (Moltbot, Clawdbot) Alternative](https://memu.bot)
-
+
- **Download-and-use and simple** to get started.
- Builds long-term memory to **understand user intent** and act proactively.
@@ -77,7 +77,7 @@ Así como un sistema de archivos convierte bytes crudos en datos organizados, me
## ⭐️ Dale una estrella al repositorio
-
+
Si encuentras memU útil o interesante, te agradeceríamos mucho una estrella en GitHub ⭐️.
---
@@ -95,10 +95,14 @@ Si encuentras memU útil o interesante, te agradeceríamos mucho una estrella en
## 🔄 Cómo Funciona la Memoria Proactiva
```bash
-
+pip install "memu-py[claude]"
+# From a source checkout, use: uv sync --extra claude
+export OPENAI_API_KEY="..."
+export ANTHROPIC_API_KEY="..."
+# Optional when using memory.platform instead of memory.local:
+export MEMU_API_KEY="..."
cd examples/proactive
python proactive.py
-
```
---
@@ -275,18 +279,17 @@ Para despliegue empresarial con flujos de trabajo proactivos personalizados, con
#### Instalación
```bash
-pip install -e .
+pip install memu-py
```
#### Ejemplo Básico
-> **Requisitos**: Python 3.13+ y una clave API de OpenAI
+> **Requisitos**: Python 3.12+ y una clave API de OpenAI
**Probar Aprendizaje Continuo** (en memoria):
```bash
export OPENAI_API_KEY=your_api_key
-cd tests
-python test_inmemory.py
+python examples/getting_started_robust.py
```
**Probar con Almacenamiento Persistente** (PostgreSQL):
@@ -301,9 +304,10 @@ docker run -d \
pgvector/pgvector:pg16
# Ejecutar prueba de aprendizaje continuo
+uv sync --extra postgres
export OPENAI_API_KEY=your_api_key
-cd tests
-python test_postgres.py
+export MEMU_RUN_POSTGRES_TESTS=1
+uv run python -m pytest tests/test_postgres.py
```
Ambos ejemplos demuestran **flujos de trabajo de memoria proactiva**:
@@ -311,7 +315,9 @@ Ambos ejemplos demuestran **flujos de trabajo de memoria proactiva**:
2. **Auto-Extracción**: Creación inmediata de memoria
3. **Recuperación Proactiva**: Presentación de memoria consciente del contexto
-Ver [`tests/test_inmemory.py`](../tests/test_inmemory.py) y [`tests/test_postgres.py`](../tests/test_postgres.py) para detalles de implementación.
+Ver [`tests/test_inmemory.py`](../tests/test_inmemory.py), [`tests/test_sqlite.py`](../tests/test_sqlite.py)
+y [`tests/test_postgres.py`](../tests/test_postgres.py) para detalles de implementación. Las pruebas live LLM
+de in-memory y SQLite son opt-in con `MEMU_RUN_LIVE_LLM_TESTS=1`.
---
@@ -326,14 +332,14 @@ service = MemUService(
# Perfil predeterminado para operaciones LLM
"default": {
"base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
- "api_key": "your_api_key",
+ "api_key": "MEMU_QWEN_API_KEY",
"chat_model": "qwen3-max",
- "client_backend": "sdk" # "sdk" o "http"
+ "client_backend": "sdk" # "sdk", "httpx" o "lazyllm_backend"
},
# Perfil separado para embeddings
"embedding": {
"base_url": "https://api.voyageai.com/v1",
- "api_key": "your_voyage_api_key",
+ "api_key": "VOYAGE_API_KEY",
"embed_model": "voyage-3.5-lite"
}
},
@@ -341,6 +347,19 @@ service = MemUService(
)
```
+The `lazyllm_backend` adapter is optional. Install it with
+`pip install "memu-py[lazyllm]"` or, from a source checkout,
+`uv sync --extra lazyllm`.
+
+Optional LazyLLM live check:
+
+```bash
+uv sync --extra lazyllm
+export MEMU_QWEN_API_KEY=your_api_key
+export MEMU_RUN_LAZYLLM_TESTS=1
+uv run python -m pytest tests/test_lazyllm.py
+```
+
---
### Integración con OpenRouter
@@ -357,7 +376,7 @@ service = MemoryService(
"provider": "openrouter",
"client_backend": "httpx",
"base_url": "https://openrouter.ai",
- "api_key": "your_openrouter_api_key",
+ "api_key": "OPENROUTER_API_KEY",
"chat_model": "anthropic/claude-3.5-sonnet", # Cualquier modelo de OpenRouter
"embed_model": "openai/text-embedding-3-small", # Modelo de embedding
},
@@ -385,15 +404,10 @@ service = MemoryService(
#### Ejecutar Pruebas de OpenRouter
```bash
export OPENROUTER_API_KEY=your_api_key
+export MEMU_RUN_OPENROUTER_TESTS=1
# Prueba de flujo completo (memorize + retrieve)
-python tests/test_openrouter.py
-
-# Pruebas específicas de embedding
-python tests/test_openrouter_embedding.py
-
-# Pruebas específicas de visión
-python tests/test_openrouter_vision.py
+uv run python -m pytest tests/test_openrouter.py
```
Ver [`examples/example_4_openrouter_memory.py`](../examples/example_4_openrouter_memory.py) para un ejemplo completo funcional.
@@ -464,8 +478,8 @@ MemU soporta tanto **carga proactiva de contexto** como **consultas reactivas**:
# Recuperación proactiva con historial de contexto
result = await service.retrieve(
queries=[
- {"role": "user", "content": {"text": "¿Cuáles son sus preferencias?"}},
- {"role": "user", "content": {"text": "Cuéntame sobre los hábitos de trabajo"}}
+ {"role": "user", "content": "¿Cuáles son sus preferencias?"},
+ {"role": "user", "content": "Cuéntame sobre los hábitos de trabajo"}
],
where={"user_id": "123"}, # Opcional: filtro de alcance
method="rag" # o "llm" para razonamiento más profundo
@@ -485,7 +499,7 @@ result = await service.retrieve(
- `where={"agent_id__in": ["1", "2"]}` - Coordinación multi-agente
- Omitir `where` para conciencia de contexto global
-> 📚 **Para documentación completa de API**, ver [SERVICE_API.md](../docs/SERVICE_API.md) - incluye patrones de flujo de trabajo proactivo, configuración de pipeline y manejo de actualizaciones en tiempo real.
+> 📚 **Para documentación completa de API**, ver [memu.pro/docs](https://memu.pro/docs) - incluye patrones de flujo de trabajo proactivo, configuración de pipeline y manejo de actualizaciones en tiempo real.
---
@@ -559,7 +573,7 @@ Ver datos experimentales detallados: [memU-experiment](https://github.com/NevaMi
| Repositorio | Descripción | Características Proactivas |
|-------------|-------------|---------------------------|
-| **[memU](https://github.com/NevaMind-AI/memU)** | Motor principal de memoria proactiva | Pipeline de aprendizaje 7×24, auto-categorización |
+| **[memU](https://github.com/NevaMind-AI/MemU)** | Motor principal de memoria proactiva | Pipeline de aprendizaje 7×24, auto-categorización |
| **[memU-server](https://github.com/NevaMind-AI/memU-server)** | Backend con sincronización continua | Actualizaciones de memoria en tiempo real, triggers de webhook |
| **[memU-ui](https://github.com/NevaMind-AI/memU-ui)** | Dashboard visual de memoria | Monitoreo de evolución de memoria en vivo |
@@ -596,7 +610,7 @@ Ver datos experimentales detallados: [memU-experiment](https://github.com/NevaMi
Para empezar a contribuir a MemU, necesitarás configurar tu entorno de desarrollo:
#### Prerrequisitos
-- Python 3.13+
+- Python 3.12+
- [uv](https://github.com/astral-sh/uv) (gestor de paquetes Python)
- Git
@@ -649,7 +663,7 @@ Para guías detalladas de contribución, estándares de código y prácticas de
## 🌍 Comunidad
-- **GitHub Issues**: [Reportar bugs y solicitar características](https://github.com/NevaMind-AI/memU/issues)
+- **GitHub Issues**: [Reportar bugs y solicitar características](https://github.com/NevaMind-AI/MemU/issues)
- **Discord**: [Unirse a la comunidad](https://discord.com/invite/hQZntfGsbJ)
- **X (Twitter)**: [Seguir @memU_ai](https://x.com/memU_ai)
- **Contacto**: info@nevamind.ai
diff --git a/readme/README_fr.md b/readme/README_fr.md
index fd1e1308..cf5a0b84 100644
--- a/readme/README_fr.md
+++ b/readme/README_fr.md
@@ -8,7 +8,7 @@
[](https://badge.fury.io/py/memu-py)
[](https://opensource.org/licenses/Apache-2.0)
-[](https://www.python.org/downloads/)
+[](https://www.python.org/downloads/)
[](https://discord.gg/memu)
[](https://x.com/memU_ai)
@@ -28,7 +28,7 @@ memU **capture et comprend continuellement l'intention de l'utilisateur**. Même
## 🤖 [OpenClaw (Moltbot, Clawdbot) Alternative](https://memu.bot)
-
+
- **Download-and-use and simple** to get started.
- Builds long-term memory to **understand user intent** and act proactively.
@@ -77,7 +77,7 @@ Tout comme un système de fichiers transforme des octets bruts en données organ
## ⭐️ Mettez une étoile au dépôt
-
+
Si vous trouvez memU utile ou intéressant, une étoile GitHub ⭐️ serait grandement appréciée.
---
@@ -95,10 +95,14 @@ Si vous trouvez memU utile ou intéressant, une étoile GitHub ⭐️ serait gra
## 🔄 Comment Fonctionne la Mémoire Proactive
```bash
-
+pip install "memu-py[claude]"
+# From a source checkout, use: uv sync --extra claude
+export OPENAI_API_KEY="..."
+export ANTHROPIC_API_KEY="..."
+# Optional when using memory.platform instead of memory.local:
+export MEMU_API_KEY="..."
cd examples/proactive
python proactive.py
-
```
---
@@ -275,18 +279,17 @@ Pour un déploiement entreprise avec des workflows proactifs personnalisés, con
#### Installation
```bash
-pip install -e .
+pip install memu-py
```
#### Exemple de Base
-> **Prérequis**: Python 3.13+ et une clé API OpenAI
+> **Prérequis**: Python 3.12+ et une clé API OpenAI
**Tester l'Apprentissage Continu** (en mémoire):
```bash
export OPENAI_API_KEY=your_api_key
-cd tests
-python test_inmemory.py
+python examples/getting_started_robust.py
```
**Tester avec Stockage Persistant** (PostgreSQL):
@@ -301,9 +304,10 @@ docker run -d \
pgvector/pgvector:pg16
# Exécuter le test d'apprentissage continu
+uv sync --extra postgres
export OPENAI_API_KEY=your_api_key
-cd tests
-python test_postgres.py
+export MEMU_RUN_POSTGRES_TESTS=1
+uv run python -m pytest tests/test_postgres.py
```
Les deux exemples démontrent **les workflows de mémoire proactive**:
@@ -311,7 +315,9 @@ Les deux exemples démontrent **les workflows de mémoire proactive**:
2. **Auto-Extraction**: Création immédiate de mémoire
3. **Récupération Proactive**: Affichage de mémoire contextuel
-Voir [`tests/test_inmemory.py`](../tests/test_inmemory.py) et [`tests/test_postgres.py`](../tests/test_postgres.py) pour les détails d'implémentation.
+Voir [`tests/test_inmemory.py`](../tests/test_inmemory.py), [`tests/test_sqlite.py`](../tests/test_sqlite.py)
+et [`tests/test_postgres.py`](../tests/test_postgres.py) pour les détails d'implémentation. Les vérifications live LLM
+in-memory et SQLite sont opt-in avec `MEMU_RUN_LIVE_LLM_TESTS=1`.
---
@@ -326,14 +332,14 @@ service = MemUService(
# Profil par défaut pour les opérations LLM
"default": {
"base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
- "api_key": "your_api_key",
+ "api_key": "MEMU_QWEN_API_KEY",
"chat_model": "qwen3-max",
- "client_backend": "sdk" # "sdk" ou "http"
+ "client_backend": "sdk" # "sdk", "httpx" ou "lazyllm_backend"
},
# Profil séparé pour les embeddings
"embedding": {
"base_url": "https://api.voyageai.com/v1",
- "api_key": "your_voyage_api_key",
+ "api_key": "VOYAGE_API_KEY",
"embed_model": "voyage-3.5-lite"
}
},
@@ -341,6 +347,19 @@ service = MemUService(
)
```
+The `lazyllm_backend` adapter is optional. Install it with
+`pip install "memu-py[lazyllm]"` or, from a source checkout,
+`uv sync --extra lazyllm`.
+
+Optional LazyLLM live check:
+
+```bash
+uv sync --extra lazyllm
+export MEMU_QWEN_API_KEY=your_api_key
+export MEMU_RUN_LAZYLLM_TESTS=1
+uv run python -m pytest tests/test_lazyllm.py
+```
+
---
### Intégration OpenRouter
@@ -357,7 +376,7 @@ service = MemoryService(
"provider": "openrouter",
"client_backend": "httpx",
"base_url": "https://openrouter.ai",
- "api_key": "your_openrouter_api_key",
+ "api_key": "OPENROUTER_API_KEY",
"chat_model": "anthropic/claude-3.5-sonnet", # N'importe quel modèle OpenRouter
"embed_model": "openai/text-embedding-3-small", # Modèle d'embedding
},
@@ -385,15 +404,10 @@ service = MemoryService(
#### Exécuter les Tests OpenRouter
```bash
export OPENROUTER_API_KEY=your_api_key
+export MEMU_RUN_OPENROUTER_TESTS=1
# Test de workflow complet (memorize + retrieve)
-python tests/test_openrouter.py
-
-# Tests spécifiques aux embeddings
-python tests/test_openrouter_embedding.py
-
-# Tests spécifiques à la vision
-python tests/test_openrouter_vision.py
+uv run python -m pytest tests/test_openrouter.py
```
Voir [`examples/example_4_openrouter_memory.py`](../examples/example_4_openrouter_memory.py) pour un exemple complet fonctionnel.
@@ -464,8 +478,8 @@ MemU supporte à la fois **le chargement proactif de contexte** et **les requêt
# Récupération proactive avec historique de contexte
result = await service.retrieve(
queries=[
- {"role": "user", "content": {"text": "Quelles sont leurs préférences?"}},
- {"role": "user", "content": {"text": "Parle-moi des habitudes de travail"}}
+ {"role": "user", "content": "Quelles sont leurs préférences?"},
+ {"role": "user", "content": "Parle-moi des habitudes de travail"}
],
where={"user_id": "123"}, # Optionnel: filtre de portée
method="rag" # ou "llm" pour raisonnement plus profond
@@ -485,7 +499,7 @@ result = await service.retrieve(
- `where={"agent_id__in": ["1", "2"]}` - Coordination multi-agent
- Omettre `where` pour conscience de contexte globale
-> 📚 **Pour la documentation API complète**, voir [SERVICE_API.md](../docs/SERVICE_API.md) - inclut les patterns de workflow proactif, configuration de pipeline et gestion des mises à jour en temps réel.
+> 📚 **Pour la documentation API complète**, voir [memu.pro/docs](https://memu.pro/docs) - inclut les patterns de workflow proactif, configuration de pipeline et gestion des mises à jour en temps réel.
---
@@ -559,7 +573,7 @@ Voir les données expérimentales détaillées: [memU-experiment](https://github
| Dépôt | Description | Fonctionnalités Proactives |
|-------|-------------|---------------------------|
-| **[memU](https://github.com/NevaMind-AI/memU)** | Moteur principal de mémoire proactive | Pipeline d'apprentissage 7×24, auto-catégorisation |
+| **[memU](https://github.com/NevaMind-AI/MemU)** | Moteur principal de mémoire proactive | Pipeline d'apprentissage 7×24, auto-catégorisation |
| **[memU-server](https://github.com/NevaMind-AI/memU-server)** | Backend avec synchronisation continue | Mises à jour de mémoire en temps réel, déclencheurs webhook |
| **[memU-ui](https://github.com/NevaMind-AI/memU-ui)** | Dashboard visuel de mémoire | Surveillance de l'évolution de la mémoire en direct |
@@ -596,7 +610,7 @@ Nous accueillons les contributions de la communauté! Que vous corrigiez des bug
Pour commencer à contribuer à MemU, vous devrez configurer votre environnement de développement:
#### Prérequis
-- Python 3.13+
+- Python 3.12+
- [uv](https://github.com/astral-sh/uv) (gestionnaire de paquets Python)
- Git
@@ -649,7 +663,7 @@ Pour des directives de contribution détaillées, standards de code et pratiques
## 🌍 Communauté
-- **GitHub Issues**: [Signaler des bugs & demander des fonctionnalités](https://github.com/NevaMind-AI/memU/issues)
+- **GitHub Issues**: [Signaler des bugs & demander des fonctionnalités](https://github.com/NevaMind-AI/MemU/issues)
- **Discord**: [Rejoindre la communauté](https://discord.com/invite/hQZntfGsbJ)
- **X (Twitter)**: [Suivre @memU_ai](https://x.com/memU_ai)
- **Contact**: info@nevamind.ai
diff --git a/readme/README_ja.md b/readme/README_ja.md
index 24aa97b5..fab93e5d 100644
--- a/readme/README_ja.md
+++ b/readme/README_ja.md
@@ -8,7 +8,7 @@
[](https://badge.fury.io/py/memu-py)
[](https://opensource.org/licenses/Apache-2.0)
-[](https://www.python.org/downloads/)
+[](https://www.python.org/downloads/)
[](https://discord.gg/memu)
[](https://x.com/memU_ai)
@@ -28,7 +28,7 @@ memUは**ユーザーの意図を継続的にキャプチャして理解**しま
## 🤖 [OpenClaw (Moltbot, Clawdbot) Alternative](https://memu.bot)
-
+
- **Download-and-use and simple** to get started.
- Builds long-term memory to **understand user intent** and act proactively.
@@ -77,7 +77,7 @@ memory/
## ⭐️ リポジトリにスターを
-
+
memUが役立つまたは興味深いと思われた場合は、GitHub Star ⭐️をいただけると大変嬉しいです。
---
@@ -95,10 +95,14 @@ memUが役立つまたは興味深いと思われた場合は、GitHub Star ⭐
## 🔄 プロアクティブメモリの仕組み
```bash
-
+pip install "memu-py[claude]"
+# From a source checkout, use: uv sync --extra claude
+export OPENAI_API_KEY="..."
+export ANTHROPIC_API_KEY="..."
+# Optional when using memory.platform instead of memory.local:
+export MEMU_API_KEY="..."
cd examples/proactive
python proactive.py
-
```
---
@@ -275,18 +279,17 @@ MemUの3層システムは、**リアクティブクエリ**と**プロアクテ
#### インストール
```bash
-pip install -e .
+pip install memu-py
```
#### 基本例
-> **要件**：Python 3.13+ と OpenAI APIキー
+> **要件**：Python 3.12+ と OpenAI APIキー
**継続学習をテスト**（インメモリ）：
```bash
export OPENAI_API_KEY=your_api_key
-cd tests
-python test_inmemory.py
+python examples/getting_started_robust.py
```
**永続ストレージでテスト**（PostgreSQL）：
@@ -301,9 +304,10 @@ docker run -d \
pgvector/pgvector:pg16
# 継続学習テストを実行
+uv sync --extra postgres
export OPENAI_API_KEY=your_api_key
-cd tests
-python test_postgres.py
+export MEMU_RUN_POSTGRES_TESTS=1
+uv run python -m pytest tests/test_postgres.py
```
両方の例は**プロアクティブメモリワークフロー**を示しています：
@@ -311,7 +315,9 @@ python test_postgres.py
2. **自動抽出**：即座のメモリ作成
3. **プロアクティブ検索**：コンテキストに応じたメモリ表示
-実装の詳細については [`tests/test_inmemory.py`](../tests/test_inmemory.py) と [`tests/test_postgres.py`](../tests/test_postgres.py) を参照してください。
+実装の詳細については [`tests/test_inmemory.py`](../tests/test_inmemory.py)、[`tests/test_sqlite.py`](../tests/test_sqlite.py)、
+および [`tests/test_postgres.py`](../tests/test_postgres.py) を参照してください。in-memory と SQLite の live LLM チェックは
+`MEMU_RUN_LIVE_LLM_TESTS=1` による opt-in です。
---
@@ -326,14 +332,14 @@ service = MemUService(
# LLM操作のデフォルトプロファイル
"default": {
"base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
- "api_key": "your_api_key",
+ "api_key": "MEMU_QWEN_API_KEY",
"chat_model": "qwen3-max",
- "client_backend": "sdk" # "sdk" または "http"
+ "client_backend": "sdk" # "sdk"、"httpx"、または "lazyllm_backend"
},
# 埋め込み用の別プロファイル
"embedding": {
"base_url": "https://api.voyageai.com/v1",
- "api_key": "your_voyage_api_key",
+ "api_key": "VOYAGE_API_KEY",
"embed_model": "voyage-3.5-lite"
}
},
@@ -341,6 +347,19 @@ service = MemUService(
)
```
+The `lazyllm_backend` adapter is optional. Install it with
+`pip install "memu-py[lazyllm]"` or, from a source checkout,
+`uv sync --extra lazyllm`.
+
+Optional LazyLLM live check:
+
+```bash
+uv sync --extra lazyllm
+export MEMU_QWEN_API_KEY=your_api_key
+export MEMU_RUN_LAZYLLM_TESTS=1
+uv run python -m pytest tests/test_lazyllm.py
+```
+
---
### OpenRouter統合
@@ -357,7 +376,7 @@ service = MemoryService(
"provider": "openrouter",
"client_backend": "httpx",
"base_url": "https://openrouter.ai",
- "api_key": "your_openrouter_api_key",
+ "api_key": "OPENROUTER_API_KEY",
"chat_model": "anthropic/claude-3.5-sonnet", # 任意のOpenRouterモデル
"embed_model": "openai/text-embedding-3-small", # 埋め込みモデル
},
@@ -385,15 +404,10 @@ service = MemoryService(
#### OpenRouterテストの実行
```bash
export OPENROUTER_API_KEY=your_api_key
+export MEMU_RUN_OPENROUTER_TESTS=1
# フルワークフローテスト（メモリ化 + 検索）
-python tests/test_openrouter.py
-
-# 埋め込み固有のテスト
-python tests/test_openrouter_embedding.py
-
-# ビジョン固有のテスト
-python tests/test_openrouter_vision.py
+uv run python -m pytest tests/test_openrouter.py
```
完全な動作例については [`examples/example_4_openrouter_memory.py`](../examples/example_4_openrouter_memory.py) を参照してください。
@@ -464,8 +478,8 @@ MemUは**プロアクティブコンテキストロード**と**リアクティ
# コンテキスト履歴を含むプロアクティブ検索
result = await service.retrieve(
queries=[
- {"role": "user", "content": {"text": "彼らの好みは何ですか？"}},
- {"role": "user", "content": {"text": "仕事の習慣について教えて"}}
+ {"role": "user", "content": "彼らの好みは何ですか？"},
+ {"role": "user", "content": "仕事の習慣について教えて"}
],
where={"user_id": "123"}, # オプション：スコープフィルター
method="rag" # または "llm" でより深い推論
@@ -485,7 +499,7 @@ result = await service.retrieve(
- `where={"agent_id__in": ["1", "2"]}` - マルチエージェント調整
- `where`を省略してグローバルコンテキスト認識
-> 📚 **完全なAPIドキュメント**については、[SERVICE_API.md](../docs/SERVICE_API.md) を参照 - プロアクティブワークフローパターン、パイプライン設定、リアルタイム更新処理を含む。
+> 📚 **完全なAPIドキュメント**については、[memu.pro/docs](https://memu.pro/docs) を参照 - プロアクティブワークフローパターン、パイプライン設定、リアルタイム更新処理を含む。
---
@@ -559,7 +573,7 @@ MemUは、すべての推論タスクでLocomoベンチマークで**92.09%の
| リポジトリ | 説明 | プロアクティブ機能 |
|-----------|------|------------------|
-| **[memU](https://github.com/NevaMind-AI/memU)** | コアプロアクティブメモリエンジン | 7×24学習パイプライン、自動分類 |
+| **[memU](https://github.com/NevaMind-AI/MemU)** | コアプロアクティブメモリエンジン | 7×24学習パイプライン、自動分類 |
| **[memU-server](https://github.com/NevaMind-AI/memU-server)** | 継続同期を備えたバックエンド | リアルタイムメモリ更新、webhookトリガー |
| **[memU-ui](https://github.com/NevaMind-AI/memU-ui)** | ビジュアルメモリダッシュボード | ライブメモリ進化モニタリング |
@@ -596,7 +610,7 @@ MemUは、すべての推論タスクでLocomoベンチマークで**92.09%の
MemUへのコントリビュートを開始するには、開発環境をセットアップする必要があります：
#### 前提条件
-- Python 3.13+
+- Python 3.12+
- [uv](https://github.com/astral-sh/uv)（Pythonパッケージマネージャー）
- Git
@@ -649,7 +663,7 @@ make check
## 🌍 コミュニティ
-- **GitHub Issues**：[バグを報告 & 機能をリクエスト](https://github.com/NevaMind-AI/memU/issues)
+- **GitHub Issues**：[バグを報告 & 機能をリクエスト](https://github.com/NevaMind-AI/MemU/issues)
- **Discord**：[コミュニティに参加](https://discord.com/invite/hQZntfGsbJ)
- **X (Twitter)**：[@memU_ai をフォロー](https://x.com/memU_ai)
- **お問い合わせ**：info@nevamind.ai
diff --git a/readme/README_ko.md b/readme/README_ko.md
index d114897f..24ca00fa 100644
--- a/readme/README_ko.md
+++ b/readme/README_ko.md
@@ -8,7 +8,7 @@
[](https://badge.fury.io/py/memu-py)
[](https://opensource.org/licenses/Apache-2.0)
-[](https://www.python.org/downloads/)
+[](https://www.python.org/downloads/)
[](https://discord.gg/memu)
[](https://x.com/memU_ai)
@@ -28,7 +28,7 @@ memU는 **사용자 의도를 지속적으로 캡처하고 이해**합니다.
## 🤖 [OpenClaw (Moltbot, Clawdbot) Alternative](https://memu.bot)
-
+
- **Download-and-use and simple** to get started.
- Builds long-term memory to **understand user intent** and act proactively.
@@ -77,7 +77,7 @@ memory/
## ⭐️ 리포지토리에 스타를
-
+
MemU가 유용하거나 흥미롭다면, GitHub Star ⭐️를 눌러주시면 큰 힘이 됩니다.
---
@@ -95,10 +95,14 @@ MemU가 유용하거나 흥미롭다면, GitHub Star ⭐️를 눌러주시면
## 🔄 프로액티브 메모리 작동 방식
```bash
-
+pip install "memu-py[claude]"
+# From a source checkout, use: uv sync --extra claude
+export OPENAI_API_KEY="..."
+export ANTHROPIC_API_KEY="..."
+# Optional when using memory.platform instead of memory.local:
+export MEMU_API_KEY="..."
cd examples/proactive
python proactive.py
-
```
---
@@ -275,18 +279,17 @@ MemU의 3계층 시스템은 **반응적 쿼리**와 **프로액티브 컨텍스
#### 설치
```bash
-pip install -e .
+pip install memu-py
```
#### 기본 예제
-> **요구사항**: Python 3.13+ 및 OpenAI API 키
+> **요구사항**: Python 3.12+ 및 OpenAI API 키
**지속 학습 테스트** (인메모리):
```bash
export OPENAI_API_KEY=your_api_key
-cd tests
-python test_inmemory.py
+python examples/getting_started_robust.py
```
**영구 저장소로 테스트** (PostgreSQL):
@@ -301,9 +304,10 @@ docker run -d \
pgvector/pgvector:pg16
# 지속 학습 테스트 실행
+uv sync --extra postgres
export OPENAI_API_KEY=your_api_key
-cd tests
-python test_postgres.py
+export MEMU_RUN_POSTGRES_TESTS=1
+uv run python -m pytest tests/test_postgres.py
```
두 예제 모두 **프로액티브 메모리 워크플로우**를 보여줍니다:
@@ -311,7 +315,9 @@ python test_postgres.py
2. **자동 추출**: 즉각적인 메모리 생성
3. **프로액티브 검색**: 컨텍스트 인식 메모리 표시
-구현 세부사항은 [`tests/test_inmemory.py`](../tests/test_inmemory.py)와 [`tests/test_postgres.py`](../tests/test_postgres.py)를 참조하세요.
+구현 세부사항은 [`tests/test_inmemory.py`](../tests/test_inmemory.py), [`tests/test_sqlite.py`](../tests/test_sqlite.py),
+그리고 [`tests/test_postgres.py`](../tests/test_postgres.py)를 참조하세요. in-memory 및 SQLite live LLM 검사는
+`MEMU_RUN_LIVE_LLM_TESTS=1`로 opt-in해야 합니다.
---
@@ -326,14 +332,14 @@ service = MemUService(
# LLM 작업용 기본 프로필
"default": {
"base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
- "api_key": "your_api_key",
+ "api_key": "MEMU_QWEN_API_KEY",
"chat_model": "qwen3-max",
- "client_backend": "sdk" # "sdk" 또는 "http"
+ "client_backend": "sdk" # "sdk", "httpx" 또는 "lazyllm_backend"
},
# 임베딩용 별도 프로필
"embedding": {
"base_url": "https://api.voyageai.com/v1",
- "api_key": "your_voyage_api_key",
+ "api_key": "VOYAGE_API_KEY",
"embed_model": "voyage-3.5-lite"
}
},
@@ -341,6 +347,19 @@ service = MemUService(
)
```
+The `lazyllm_backend` adapter is optional. Install it with
+`pip install "memu-py[lazyllm]"` or, from a source checkout,
+`uv sync --extra lazyllm`.
+
+Optional LazyLLM live check:
+
+```bash
+uv sync --extra lazyllm
+export MEMU_QWEN_API_KEY=your_api_key
+export MEMU_RUN_LAZYLLM_TESTS=1
+uv run python -m pytest tests/test_lazyllm.py
+```
+
---
### OpenRouter 통합
@@ -357,7 +376,7 @@ service = MemoryService(
"provider": "openrouter",
"client_backend": "httpx",
"base_url": "https://openrouter.ai",
- "api_key": "your_openrouter_api_key",
+ "api_key": "OPENROUTER_API_KEY",
"chat_model": "anthropic/claude-3.5-sonnet", # 모든 OpenRouter 모델
"embed_model": "openai/text-embedding-3-small", # 임베딩 모델
},
@@ -385,15 +404,10 @@ service = MemoryService(
#### OpenRouter 테스트 실행
```bash
export OPENROUTER_API_KEY=your_api_key
+export MEMU_RUN_OPENROUTER_TESTS=1
# 전체 워크플로우 테스트 (메모라이즈 + 검색)
-python tests/test_openrouter.py
-
-# 임베딩 특화 테스트
-python tests/test_openrouter_embedding.py
-
-# 비전 특화 테스트
-python tests/test_openrouter_vision.py
+uv run python -m pytest tests/test_openrouter.py
```
완전한 작동 예제는 [`examples/example_4_openrouter_memory.py`](../examples/example_4_openrouter_memory.py)를 참조하세요.
@@ -464,8 +478,8 @@ MemU는 **프로액티브 컨텍스트 로딩**과 **반응적 쿼리**를 모
# 컨텍스트 히스토리를 포함한 프로액티브 검색
result = await service.retrieve(
queries=[
- {"role": "user", "content": {"text": "그들의 선호도가 무엇입니까?"}},
- {"role": "user", "content": {"text": "업무 습관에 대해 알려주세요"}}
+ {"role": "user", "content": "그들의 선호도가 무엇입니까?"},
+ {"role": "user", "content": "업무 습관에 대해 알려주세요"}
],
where={"user_id": "123"}, # 선택: 범위 필터
method="rag" # 또는 "llm"으로 더 깊은 추론
@@ -485,7 +499,7 @@ result = await service.retrieve(
- `where={"agent_id__in": ["1", "2"]}` - 다중 에이전트 조정
- `where` 생략으로 전역 컨텍스트 인식
-> 📚 **전체 API 문서**는 [SERVICE_API.md](../docs/SERVICE_API.md) 참조 - 프로액티브 워크플로우 패턴, 파이프라인 구성, 실시간 업데이트 처리 포함.
+> 📚 **전체 API 문서**는 [memu.pro/docs](https://memu.pro/docs) 참조 - 프로액티브 워크플로우 패턴, 파이프라인 구성, 실시간 업데이트 처리 포함.
---
@@ -559,7 +573,7 @@ MemU는 모든 추론 작업에서 Locomo 벤치마크에서 **92.09% 평균 정
| 리포지토리 | 설명 | 프로액티브 기능 |
|-----------|------|----------------|
-| **[memU](https://github.com/NevaMind-AI/memU)** | 핵심 프로액티브 메모리 엔진 | 7×24 학습 파이프라인, 자동 분류 |
+| **[memU](https://github.com/NevaMind-AI/MemU)** | 핵심 프로액티브 메모리 엔진 | 7×24 학습 파이프라인, 자동 분류 |
| **[memU-server](https://github.com/NevaMind-AI/memU-server)** | 지속 동기화가 포함된 백엔드 | 실시간 메모리 업데이트, 웹훅 트리거 |
| **[memU-ui](https://github.com/NevaMind-AI/memU-ui)** | 시각적 메모리 대시보드 | 라이브 메모리 진화 모니터링 |
@@ -596,7 +610,7 @@ MemU는 모든 추론 작업에서 Locomo 벤치마크에서 **92.09% 평균 정
MemU에 기여하려면 개발 환경을 설정해야 합니다:
#### 사전 요구사항
-- Python 3.13+
+- Python 3.12+
- [uv](https://github.com/astral-sh/uv) (Python 패키지 관리자)
- Git
@@ -649,7 +663,7 @@ make check
## 🌍 커뮤니티
-- **GitHub Issues**: [버그 보고 및 기능 요청](https://github.com/NevaMind-AI/memU/issues)
+- **GitHub Issues**: [버그 보고 및 기능 요청](https://github.com/NevaMind-AI/MemU/issues)
- **Discord**: [커뮤니티 참여](https://discord.com/invite/hQZntfGsbJ)
- **X (Twitter)**: [@memU_ai 팔로우](https://x.com/memU_ai)
- **연락처**: info@nevamind.ai
diff --git a/readme/README_zh.md b/readme/README_zh.md
index d6b3db1b..d86b9207 100644
--- a/readme/README_zh.md
+++ b/readme/README_zh.md
@@ -8,7 +8,7 @@
[](https://badge.fury.io/py/memu-py)
[](https://opensource.org/licenses/Apache-2.0)
-[](https://www.python.org/downloads/)
+[](https://www.python.org/downloads/)
[](https://discord.gg/memu)
[](https://x.com/memU_ai)
@@ -28,7 +28,7 @@ memU **持续捕获并理解用户意图**。即使没有明确指令，智能
## 🤖 [OpenClaw (Moltbot, Clawdbot) Alternative](https://memu.bot)
-
+
- **Download-and-use and simple** to get started.
- Builds long-term memory to **understand user intent** and act proactively.
@@ -77,7 +77,7 @@ memory/
## ⭐️ 给项目点个星
-
+
如果你觉得 memU 有用或有趣，请给项目点个星 ⭐️，这将是对我们最大的支持！
---
@@ -95,10 +95,14 @@ memory/
## 🔄 主动记忆工作原理
```bash
-
+pip install "memu-py[claude]"
+# From a source checkout, use: uv sync --extra claude
+export OPENAI_API_KEY="..."
+export ANTHROPIC_API_KEY="..."
+# Optional when using memory.platform instead of memory.local:
+export MEMU_API_KEY="..."
cd examples/proactive
python proactive.py
-
```
---
@@ -273,18 +277,17 @@ MemU 的三层系统同时支持**响应式查询**和**主动上下文加载**
#### 安装
```bash
-pip install -e .
+pip install memu-py
```
#### 基础示例
-> **要求**：Python 3.13+ 和 OpenAI API 密钥
+> **要求**：Python 3.12+ 和 OpenAI API 密钥
**测试持续学习**（内存模式）：
```bash
export OPENAI_API_KEY=your_api_key
-cd tests
-python test_inmemory.py
+python examples/getting_started_robust.py
```
**测试持久化存储**（PostgreSQL）：
@@ -299,9 +302,10 @@ docker run -d \
pgvector/pgvector:pg16
# 运行持续学习测试
+uv sync --extra postgres
export OPENAI_API_KEY=your_api_key
-cd tests
-python test_postgres.py
+export MEMU_RUN_POSTGRES_TESTS=1
+uv run python -m pytest tests/test_postgres.py
```
两个示例都演示了**主动记忆工作流**：
@@ -309,7 +313,9 @@ python test_postgres.py
2. **自动提取**：即时创建记忆
3. **主动检索**：上下文感知的记忆呈现
-查看 [`tests/test_inmemory.py`](../tests/test_inmemory.py) 和 [`tests/test_postgres.py`](../tests/test_postgres.py) 了解实现细节。
+查看 [`tests/test_inmemory.py`](../tests/test_inmemory.py)、[`tests/test_sqlite.py`](../tests/test_sqlite.py)
+和 [`tests/test_postgres.py`](../tests/test_postgres.py) 了解实现细节。in-memory 和 SQLite live LLM 检查需要通过
+`MEMU_RUN_LIVE_LLM_TESTS=1` 显式 opt-in。
---
@@ -324,14 +330,14 @@ service = MemUService(
# LLM 操作的默认配置
"default": {
"base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
- "api_key": "your_api_key",
+ "api_key": "MEMU_QWEN_API_KEY",
"chat_model": "qwen3-max",
- "client_backend": "sdk" # "sdk" 或 "http"
+ "client_backend": "sdk" # "sdk"、"httpx" 或 "lazyllm_backend"
},
# 嵌入的单独配置
"embedding": {
"base_url": "https://api.voyageai.com/v1",
- "api_key": "your_voyage_api_key",
+ "api_key": "VOYAGE_API_KEY",
"embed_model": "voyage-3.5-lite"
}
},
@@ -339,6 +345,19 @@ service = MemUService(
)
```
+The `lazyllm_backend` adapter is optional. Install it with
+`pip install "memu-py[lazyllm]"` or, from a source checkout,
+`uv sync --extra lazyllm`.
+
+Optional LazyLLM live check:
+
+```bash
+uv sync --extra lazyllm
+export MEMU_QWEN_API_KEY=your_api_key
+export MEMU_RUN_LAZYLLM_TESTS=1
+uv run python -m pytest tests/test_lazyllm.py
+```
+
---
### OpenRouter 集成
@@ -355,7 +374,7 @@ service = MemoryService(
"provider": "openrouter",
"client_backend": "httpx",
"base_url": "https://openrouter.ai",
- "api_key": "your_openrouter_api_key",
+ "api_key": "OPENROUTER_API_KEY",
"chat_model": "anthropic/claude-3.5-sonnet", # 任何 OpenRouter 模型
"embed_model": "openai/text-embedding-3-small", # 嵌入模型
},
@@ -383,15 +402,10 @@ service = MemoryService(
#### 运行 OpenRouter 测试
```bash
export OPENROUTER_API_KEY=your_api_key
+export MEMU_RUN_OPENROUTER_TESTS=1
# 完整工作流测试（记忆 + 检索）
-python tests/test_openrouter.py
-
-# 嵌入专项测试
-python tests/test_openrouter_embedding.py
-
-# 视觉专项测试
-python tests/test_openrouter_vision.py
+uv run python -m pytest tests/test_openrouter.py
```
查看 [`examples/example_4_openrouter_memory.py`](../examples/example_4_openrouter_memory.py) 获取完整示例。
@@ -462,8 +476,8 @@ MemU 同时支持**主动上下文加载**和**响应式查询**：
# 带上下文历史的主动检索
result = await service.retrieve(
queries=[
- {"role": "user", "content": {"text": "他们的偏好是什么？"}},
- {"role": "user", "content": {"text": "告诉我工作习惯"}}
+ {"role": "user", "content": "他们的偏好是什么？"},
+ {"role": "user", "content": "告诉我工作习惯"}
],
where={"user_id": "123"}, # 可选：范围过滤
method="rag" # 或 "llm" 用于更深入的推理
@@ -483,7 +497,7 @@ result = await service.retrieve(
- `where={"agent_id__in": ["1", "2"]}` - 多智能体协调
- 省略 `where` 以获取全局上下文感知
-> 📚 **完整 API 文档**，请参阅 [SERVICE_API.md](../docs/SERVICE_API.md) - 包含主动工作流模式、管道配置和实时更新处理。
+> 📚 **完整 API 文档**，请参阅 [memu.pro/docs](https://memu.pro/docs) - 包含主动工作流模式、管道配置和实时更新处理。
---
@@ -557,7 +571,7 @@ MemU 在 Locomo 基准测试中，在所有推理任务上实现了 **92.09% 的
| 仓库 | 描述 | 主动功能 |
|------|------|----------|
-| **[memU](https://github.com/NevaMind-AI/memU)** | 核心主动记忆引擎 | 7×24 学习管道、自动分类 |
+| **[memU](https://github.com/NevaMind-AI/MemU)** | 核心主动记忆引擎 | 7×24 学习管道、自动分类 |
| **[memU-server](https://github.com/NevaMind-AI/memU-server)** | 带持续同步的后端 | 实时记忆更新、webhook 触发 |
| **[memU-ui](https://github.com/NevaMind-AI/memU-ui)** | 可视化记忆仪表板 | 实时记忆演化监控 |
@@ -594,7 +608,7 @@ MemU 在 Locomo 基准测试中，在所有推理任务上实现了 **92.09% 的
要开始为 MemU 做贡献，您需要设置开发环境：
#### 先决条件
-- Python 3.13+
+- Python 3.12+
- [uv](https://github.com/astral-sh/uv)（Python 包管理器）
- Git
@@ -647,7 +661,7 @@ make check
## 🌍 社区
-- **GitHub Issues**：[报告错误和请求功能](https://github.com/NevaMind-AI/memU/issues)
+- **GitHub Issues**：[报告错误和请求功能](https://github.com/NevaMind-AI/MemU/issues)
- **Discord**：[加入社区](https://discord.com/invite/hQZntfGsbJ)
- **X (Twitter)**：[关注 @memU_ai](https://x.com/memU_ai)
- **联系方式**：info@nevamind.ai
diff --git a/src/memu/app/crud.py b/src/memu/app/crud.py
index 50d63d4c..47d96ef8 100644
--- a/src/memu/app/crud.py
+++ b/src/memu/app/crud.py
@@ -8,6 +8,7 @@
from pydantic import BaseModel
+from memu.app.scope import concrete_scope_from_where, normalize_scope_where, record_matches_scope
from memu.database.models import MemoryCategory, MemoryType
from memu.prompts.category_patch import CATEGORY_PATCH_PROMPT
from memu.workflow.step import WorkflowState, WorkflowStep
@@ -63,6 +64,9 @@ async def list_memory_categories(
ctx = self._get_context()
store = self._get_database()
where_filters = self._normalize_where(where)
+ bootstrap_scope = concrete_scope_from_where(where_filters)
+ if bootstrap_scope is not None:
+ await self._ensure_categories_ready(ctx, store, bootstrap_scope)
state: WorkflowState = {
"ctx": ctx,
@@ -149,6 +153,14 @@ def _build_list_memory_categories_workflow(self) -> list[WorkflowStep]:
def _build_clear_memory_workflow(self) -> list[WorkflowStep]:
steps = [
+ WorkflowStep(
+ step_id="clear_category_item_relations",
+ role="delete_memories",
+ handler=self._crud_clear_category_item_relations,
+ requires={"ctx", "store", "where"},
+ produces={"deleted_relations"},
+ capabilities={"db"},
+ ),
WorkflowStep(
step_id="clear_memory_categories",
role="delete_memories",
@@ -177,7 +189,14 @@ def _build_clear_memory_workflow(self) -> list[WorkflowStep]:
step_id="build_response",
role="emit",
handler=self._crud_build_clear_memory_response,
- requires={"ctx", "store", "deleted_categories", "deleted_items", "deleted_resources"},
+ requires={
+ "ctx",
+ "store",
+ "deleted_relations",
+ "deleted_categories",
+ "deleted_items",
+ "deleted_resources",
+ },
produces={"response"},
capabilities=set(),
),
@@ -194,22 +213,14 @@ def _list_clear_memories_initial_keys() -> set[str]:
def _normalize_where(self, where: Mapping[str, Any] | None) -> dict[str, Any]:
"""Validate and clean the `where` scope filters against the configured user model."""
- if not where:
- return {}
-
- valid_fields = set(getattr(self.user_model, "model_fields", {}).keys())
- cleaned: dict[str, Any] = {}
-
- for raw_key, value in where.items():
- if value is None:
- continue
- field = raw_key.split("__", 1)[0]
- if field not in valid_fields:
- msg = f"Unknown filter field '{field}' for current user scope"
- raise ValueError(msg)
- cleaned[raw_key] = value
+ return normalize_scope_where(self.user_model, where)
- return cleaned
+ @staticmethod
+ def _ensure_item_matches_user_scope(item: Any, user_scope: Mapping[str, Any] | None, memory_id: str) -> None:
+ if record_matches_scope(item, user_scope):
+ return
+ msg = f"Memory item with id {memory_id} not found"
+ raise ValueError(msg)
def _crud_list_memory_items(self, state: WorkflowState, step_context: Any) -> WorkflowState:
where_filters = state.get("where") or {}
@@ -243,6 +254,13 @@ def _crud_build_list_categories_response(self, state: WorkflowState, step_contex
state["response"] = response
return state
+ def _crud_clear_category_item_relations(self, state: WorkflowState, step_context: Any) -> WorkflowState:
+ where_filters = state.get("where") or {}
+ store = state["store"]
+ deleted = store.category_item_repo.clear_relations(where_filters)
+ state["deleted_relations"] = deleted
+ return state
+
def _crud_clear_memory_categories(self, state: WorkflowState, step_context: Any) -> WorkflowState:
where_filters = state.get("where") or {}
store = state["store"]
@@ -265,10 +283,12 @@ def _crud_clear_memory_resources(self, state: WorkflowState, step_context: Any)
return state
def _crud_build_clear_memory_response(self, state: WorkflowState, step_context: Any) -> WorkflowState:
+ deleted_relations = state.get("deleted_relations", [])
deleted_categories = state.get("deleted_categories", {})
deleted_items = state.get("deleted_items", {})
deleted_resources = state.get("deleted_resources", {})
response = {
+ "deleted_relations": [self._model_dump_without_embeddings(rel) for rel in deleted_relations],
"deleted_categories": [self._model_dump_without_embeddings(cat) for cat in deleted_categories.values()],
"deleted_items": [self._model_dump_without_embeddings(item) for item in deleted_items.values()],
"deleted_resources": [self._model_dump_without_embeddings(res) for res in deleted_resources.values()],
@@ -285,9 +305,9 @@ async def create_memory_item(
user: dict[str, Any] | None = None,
propagate: bool = True,
) -> dict[str, Any]:
- if memory_type not in get_args(MemoryType):
- msg = f"Invalid memory type: '{memory_type}', must be one of {get_args(MemoryType)}"
- raise ValueError(msg)
+ memory_type = _normalize_memory_type(memory_type)
+ memory_content = _normalize_memory_content(memory_content, field_name="memory_content")
+ memory_categories = _normalize_memory_categories(memory_categories, field_name="memory_categories")
ctx = self._get_context()
store = self._get_database()
@@ -327,9 +347,13 @@ async def update_memory_item(
if all((memory_type is None, memory_content is None, memory_categories is None)):
msg = "At least one of memory type, memory content, or memory categories is required for UPDATE operation"
raise ValueError(msg)
- if memory_type and memory_type not in get_args(MemoryType):
- msg = f"Invalid memory type: '{memory_type}', must be one of {get_args(MemoryType)}"
- raise ValueError(msg)
+ memory_id = _normalize_memory_id(memory_id)
+ if memory_type is not None:
+ memory_type = _normalize_memory_type(memory_type)
+ if memory_content is not None:
+ memory_content = _normalize_memory_content(memory_content, field_name="memory_content")
+ if memory_categories is not None:
+ memory_categories = _normalize_memory_categories(memory_categories, field_name="memory_categories")
ctx = self._get_context()
store = self._get_database()
@@ -364,6 +388,8 @@ async def delete_memory_item(
user: dict[str, Any] | None = None,
propagate: bool = True,
) -> dict[str, Any]:
+ memory_id = _normalize_memory_id(memory_id)
+
ctx = self._get_context()
store = self._get_database()
user_scope = self.user_model(**user).model_dump() if user is not None else None
@@ -517,6 +543,7 @@ async def _patch_create_memory_item(self, state: WorkflowState, step_context: An
content_embedding = (await self._get_step_embedding_client(step_context).embed(embed_payload))[0]
item = store.memory_item_repo.create_item(
+ resource_id=None,
memory_type=memory_payload["type"],
summary=memory_payload["content"],
embedding=content_embedding,
@@ -548,6 +575,7 @@ async def _patch_update_memory_item(self, state: WorkflowState, step_context: An
if not item:
msg = f"Memory item with id {memory_id} not found"
raise ValueError(msg)
+ self._ensure_item_matches_user_scope(item, user, memory_id)
old_content = item.summary
old_item_categories = store.category_item_repo.get_item_categories(memory_id)
mapped_old_cat_ids = [cat.category_id for cat in old_item_categories]
@@ -566,7 +594,10 @@ async def _patch_update_memory_item(self, state: WorkflowState, step_context: An
embedding=content_embedding,
)
new_cat_names = memory_payload["categories"]
- mapped_new_cat_ids = self._map_category_names_to_ids(new_cat_names, ctx)
+ if new_cat_names is None:
+ mapped_new_cat_ids = mapped_old_cat_ids
+ else:
+ mapped_new_cat_ids = self._map_category_names_to_ids(new_cat_names, ctx)
cats_to_remove = set(mapped_old_cat_ids) - set(mapped_new_cat_ids)
cats_to_add = set(mapped_new_cat_ids) - set(mapped_old_cat_ids)
@@ -599,7 +630,8 @@ async def _patch_delete_memory_item(self, state: WorkflowState, step_context: An
if not item:
msg = f"Memory item with id {memory_id} not found"
raise ValueError(msg)
- item_categories = store.category_item_repo.get_item_categories(memory_id)
+ self._ensure_item_matches_user_scope(item, state["user"], memory_id)
+ item_categories = store.category_item_repo.clear_relations({"item_id": memory_id})
if propagate:
for cat in item_categories:
category_memory_updates[cat.category_id] = (item.summary, None)
@@ -724,3 +756,36 @@ def _parse_category_patch_response(self, response: str) -> tuple[bool, str]:
if updated_content == "empty":
updated_content = ""
return need_update, updated_content
+
+
+def _normalize_memory_id(value: Any) -> str:
+ return _normalize_non_empty_string(value, field_name="memory_id")
+
+
+def _normalize_memory_type(value: Any) -> MemoryType:
+ memory_type = _normalize_non_empty_string(value, field_name="memory_type")
+ if memory_type not in get_args(MemoryType):
+ msg = f"Invalid memory type: '{memory_type}', must be one of {get_args(MemoryType)}"
+ raise ValueError(msg)
+ return cast(MemoryType, memory_type)
+
+
+def _normalize_memory_content(value: Any, *, field_name: str) -> str:
+ return _normalize_non_empty_string(value, field_name=field_name)
+
+
+def _normalize_memory_categories(value: Any, *, field_name: str) -> list[str]:
+ if not isinstance(value, list):
+ msg = f"'{field_name}' must be a list of non-empty strings"
+ raise ValueError(msg)
+ normalized: list[str] = []
+ for index, item in enumerate(value):
+ normalized.append(_normalize_non_empty_string(item, field_name=f"{field_name}[{index}]"))
+ return normalized
+
+
+def _normalize_non_empty_string(value: Any, *, field_name: str) -> str:
+ if not isinstance(value, str) or not value.strip():
+ msg = f"'{field_name}' must be a non-empty string"
+ raise ValueError(msg)
+ return value.strip()
diff --git a/src/memu/app/memorize.py b/src/memu/app/memorize.py
index 0f2a06fc..b6e7c7ed 100644
--- a/src/memu/app/memorize.py
+++ b/src/memu/app/memorize.py
@@ -12,6 +12,7 @@
import defusedxml.ElementTree as ET
from pydantic import BaseModel
+from memu.app.scope import scope_key_from_user
from memu.app.settings import CategoryConfig, CustomPrompt
from memu.database.models import CategoryItem, MemoryCategory, MemoryItem, MemoryType, Resource
from memu.prompts.category_summary import (
@@ -32,6 +33,7 @@
)
from memu.prompts.preprocess import PROMPTS as PREPROCESS_PROMPTS
from memu.utils.conversation import format_conversation_for_preprocess
+from memu.utils.dedupe import dedupe_resource_plans
from memu.utils.video import VideoFrameExtractor
from memu.workflow.step import WorkflowState, WorkflowStep
@@ -227,8 +229,7 @@ async def _memorize_extract_items(self, state: WorkflowState, step_context: Any)
return state
def _memorize_dedupe_merge(self, state: WorkflowState, step_context: Any) -> WorkflowState:
- # Placeholder for future dedup/merge logic
- state["resource_plans"] = state.get("resource_plans", [])
+ state["resource_plans"] = dedupe_resource_plans(state.get("resource_plans", []))
return state
async def _memorize_categorize_items(self, state: WorkflowState, step_context: Any) -> WorkflowState:
@@ -301,7 +302,7 @@ def _memorize_build_response(self, state: WorkflowState, step_context: Any) -> W
store = state["store"]
resources = [self._model_dump_without_embeddings(r) for r in state.get("resources", [])]
items = [self._model_dump_without_embeddings(item) for item in state.get("items", [])]
- relations = [rel.model_dump() for rel in state.get("relations", [])]
+ relations = [self._model_dump_without_embeddings(rel) for rel in state.get("relations", [])]
category_ids = state.get("category_ids") or list(ctx.category_ids)
categories = [
self._model_dump_without_embeddings(store.memory_category_repo.categories[c]) for c in category_ids
@@ -637,20 +638,48 @@ def _start_category_initialization(self, ctx: Context, store: Database) -> None:
async def _ensure_categories_ready(
self, ctx: Context, store: Database, user_scope: Mapping[str, Any] | None = None
) -> None:
- if ctx.categories_ready:
+ scope_key = scope_key_from_user(user_scope)
+ if ctx.categories_ready and ctx.category_scope_key == scope_key:
+ return
+ cached = ctx.category_cache.get(scope_key)
+ if cached is not None:
+ ctx.category_ids = list(cached[0])
+ ctx.category_name_to_id = dict(cached[1])
+ ctx.category_scope_key = scope_key
+ ctx.categories_ready = True
return
if ctx.category_init_task:
await ctx.category_init_task
ctx.category_init_task = None
- return
+ if ctx.categories_ready and ctx.category_scope_key == scope_key:
+ return
+ cached = ctx.category_cache.get(scope_key)
+ if cached is not None:
+ ctx.category_ids = list(cached[0])
+ ctx.category_name_to_id = dict(cached[1])
+ ctx.category_scope_key = scope_key
+ ctx.categories_ready = True
+ return
await self._initialize_categories(ctx, store, user_scope)
async def _initialize_categories(
self, ctx: Context, store: Database, user: Mapping[str, Any] | None = None
) -> None:
- if ctx.categories_ready:
+ scope_key = scope_key_from_user(user)
+ if ctx.categories_ready and ctx.category_scope_key == scope_key:
+ return
+ cached = ctx.category_cache.get(scope_key)
+ if cached is not None:
+ ctx.category_ids = list(cached[0])
+ ctx.category_name_to_id = dict(cached[1])
+ ctx.category_scope_key = scope_key
+ ctx.categories_ready = True
return
if not self.category_configs:
+ ctx.category_ids = []
+ ctx.category_name_to_id = {}
+ ctx.category_scope_key = scope_key
+ ctx.category_cache[scope_key] = ([], {})
ctx.categories_ready = True
return
cat_texts = [self._category_embedding_text(cfg) for cfg in self.category_configs]
@@ -665,6 +694,8 @@ async def _initialize_categories(
)
ctx.category_ids.append(cat.id)
ctx.category_name_to_id[name.lower()] = cat.id
+ ctx.category_scope_key = scope_key
+ ctx.category_cache[scope_key] = (list(ctx.category_ids), dict(ctx.category_name_to_id))
ctx.categories_ready = True
@staticmethod
diff --git a/src/memu/app/patch.py b/src/memu/app/patch.py
index c1796478..b0123cef 100644
--- a/src/memu/app/patch.py
+++ b/src/memu/app/patch.py
@@ -8,6 +8,7 @@
from pydantic import BaseModel
+from memu.app.scope import record_matches_scope
from memu.database.models import MemoryCategory, MemoryType
from memu.prompts.category_patch import CATEGORY_PATCH_PROMPT
from memu.workflow.step import WorkflowState, WorkflowStep
@@ -43,9 +44,9 @@ async def create_memory_item(
user: dict[str, Any] | None = None,
propagate: bool = True,
) -> dict[str, Any]:
- if memory_type not in get_args(MemoryType):
- msg = f"Invalid memory type: '{memory_type}', must be one of {get_args(MemoryType)}"
- raise ValueError(msg)
+ memory_type = _normalize_memory_type(memory_type)
+ memory_content = _normalize_memory_content(memory_content, field_name="memory_content")
+ memory_categories = _normalize_memory_categories(memory_categories, field_name="memory_categories")
ctx = self._get_context()
store = self._get_database()
@@ -85,9 +86,13 @@ async def update_memory_item(
if all((memory_type is None, memory_content is None, memory_categories is None)):
msg = "At least one of memory type, memory content, or memory categories is required for UPDATE operation"
raise ValueError(msg)
- if memory_type and memory_type not in get_args(MemoryType):
- msg = f"Invalid memory type: '{memory_type}', must be one of {get_args(MemoryType)}"
- raise ValueError(msg)
+ memory_id = _normalize_memory_id(memory_id)
+ if memory_type is not None:
+ memory_type = _normalize_memory_type(memory_type)
+ if memory_content is not None:
+ memory_content = _normalize_memory_content(memory_content, field_name="memory_content")
+ if memory_categories is not None:
+ memory_categories = _normalize_memory_categories(memory_categories, field_name="memory_categories")
ctx = self._get_context()
store = self._get_database()
@@ -122,6 +127,8 @@ async def delete_memory_item(
user: dict[str, Any] | None = None,
propagate: bool = True,
) -> dict[str, Any]:
+ memory_id = _normalize_memory_id(memory_id)
+
ctx = self._get_context()
store = self._get_database()
user_scope = self.user_model(**user).model_dump() if user is not None else None
@@ -258,6 +265,13 @@ def _list_delete_memory_item_initial_keys() -> set[str]:
"user",
}
+ @staticmethod
+ def _ensure_item_matches_user_scope(item: Any, user_scope: Mapping[str, Any] | None, memory_id: str) -> None:
+ if record_matches_scope(item, user_scope):
+ return
+ msg = f"Memory item with id {memory_id} not found"
+ raise ValueError(msg)
+
async def _patch_create_memory_item(self, state: WorkflowState, step_context: Any) -> WorkflowState:
memory_payload = state["memory_payload"]
ctx = state["ctx"]
@@ -270,6 +284,7 @@ async def _patch_create_memory_item(self, state: WorkflowState, step_context: An
content_embedding = (await self._get_llm_client().embed(embed_payload))[0]
item = store.memory_item_repo.create_item(
+ resource_id=None,
memory_type=memory_payload["type"],
summary=memory_payload["content"],
embedding=content_embedding,
@@ -301,6 +316,7 @@ async def _patch_update_memory_item(self, state: WorkflowState, step_context: An
if not item:
msg = f"Memory item with id {memory_id} not found"
raise ValueError(msg)
+ self._ensure_item_matches_user_scope(item, user, memory_id)
old_content = item.summary
old_item_categories = store.category_item_repo.get_item_categories(memory_id)
mapped_old_cat_ids = [cat.category_id for cat in old_item_categories]
@@ -319,7 +335,10 @@ async def _patch_update_memory_item(self, state: WorkflowState, step_context: An
embedding=content_embedding,
)
new_cat_names = memory_payload["categories"]
- mapped_new_cat_ids = self._map_category_names_to_ids(new_cat_names, ctx)
+ if new_cat_names is None:
+ mapped_new_cat_ids = mapped_old_cat_ids
+ else:
+ mapped_new_cat_ids = self._map_category_names_to_ids(new_cat_names, ctx)
cats_to_remove = set(mapped_old_cat_ids) - set(mapped_new_cat_ids)
cats_to_add = set(mapped_new_cat_ids) - set(mapped_old_cat_ids)
@@ -352,7 +371,8 @@ async def _patch_delete_memory_item(self, state: WorkflowState, step_context: An
if not item:
msg = f"Memory item with id {memory_id} not found"
raise ValueError(msg)
- item_categories = store.category_item_repo.get_item_categories(memory_id)
+ self._ensure_item_matches_user_scope(item, state["user"], memory_id)
+ item_categories = store.category_item_repo.clear_relations({"item_id": memory_id})
if propagate:
for cat in item_categories:
category_memory_updates[cat.category_id] = (item.summary, None)
@@ -477,3 +497,36 @@ def _parse_category_patch_response(self, response: str) -> tuple[bool, str]:
if updated_content == "empty":
updated_content = ""
return need_update, updated_content
+
+
+def _normalize_memory_id(value: Any) -> str:
+ return _normalize_non_empty_string(value, field_name="memory_id")
+
+
+def _normalize_memory_type(value: Any) -> MemoryType:
+ memory_type = _normalize_non_empty_string(value, field_name="memory_type")
+ if memory_type not in get_args(MemoryType):
+ msg = f"Invalid memory type: '{memory_type}', must be one of {get_args(MemoryType)}"
+ raise ValueError(msg)
+ return cast(MemoryType, memory_type)
+
+
+def _normalize_memory_content(value: Any, *, field_name: str) -> str:
+ return _normalize_non_empty_string(value, field_name=field_name)
+
+
+def _normalize_memory_categories(value: Any, *, field_name: str) -> list[str]:
+ if not isinstance(value, list):
+ msg = f"'{field_name}' must be a list of non-empty strings"
+ raise ValueError(msg)
+ normalized: list[str] = []
+ for index, item in enumerate(value):
+ normalized.append(_normalize_non_empty_string(item, field_name=f"{field_name}[{index}]"))
+ return normalized
+
+
+def _normalize_non_empty_string(value: Any, *, field_name: str) -> str:
+ if not isinstance(value, str) or not value.strip():
+ msg = f"'{field_name}' must be a non-empty string"
+ raise ValueError(msg)
+ return value.strip()
diff --git a/src/memu/app/retrieve.py b/src/memu/app/retrieve.py
index a7cbff5c..3e4ec7e5 100644
--- a/src/memu/app/retrieve.py
+++ b/src/memu/app/retrieve.py
@@ -8,12 +8,14 @@
from pydantic import BaseModel
+from memu.app.scope import concrete_scope_from_where, normalize_scope_where
from memu.database.inmemory.vector import cosine_topk
from memu.prompts.retrieve.llm_category_ranker import PROMPT as LLM_CATEGORY_RANKER_PROMPT
from memu.prompts.retrieve.llm_item_ranker import PROMPT as LLM_ITEM_RANKER_PROMPT
from memu.prompts.retrieve.llm_resource_ranker import PROMPT as LLM_RESOURCE_RANKER_PROMPT
from memu.prompts.retrieve.pre_retrieval_decision import SYSTEM_PROMPT as PRE_RETRIEVAL_SYSTEM_PROMPT
from memu.prompts.retrieve.pre_retrieval_decision import USER_PROMPT as PRE_RETRIEVAL_USER_PROMPT
+from memu.utils.retrieve import RetrieveMethod, RetrieveRanking, normalize_retrieve_method, normalize_retrieve_ranking
from memu.workflow.step import WorkflowState, WorkflowStep
logger = logging.getLogger(__name__)
@@ -30,7 +32,7 @@ class RetrieveMixin:
_run_workflow: Callable[..., Awaitable[WorkflowState]]
_get_context: Callable[[], Context]
_get_database: Callable[[], Database]
- _ensure_categories_ready: Callable[[Context, Database], Awaitable[None]]
+ _ensure_categories_ready: Callable[[Context, Database, Mapping[str, Any] | None], Awaitable[None]]
_get_step_llm_client: Callable[[Mapping[str, Any] | None], Any]
_get_step_embedding_client: Callable[[Mapping[str, Any] | None], Any]
_get_llm_client: Callable[..., Any]
@@ -41,36 +43,48 @@ class RetrieveMixin:
async def retrieve(
self,
- queries: list[dict[str, Any]],
+ queries: list[str | Mapping[str, Any]],
where: dict[str, Any] | None = None,
+ method: RetrieveMethod | str | None = None,
+ ranking: RetrieveRanking | str | None = None,
) -> dict[str, Any]:
+ if not isinstance(queries, list):
+ msg = "queries must be a non-empty list of strings or query objects"
+ raise TypeError(msg)
if not queries:
- raise ValueError("empty_queries")
+ msg = "queries must be a non-empty list of strings or query objects"
+ raise ValueError(msg)
+ normalized_queries = [self._normalize_query_item(query, index=index) for index, query in enumerate(queries)]
ctx = self._get_context()
store = self._get_database()
- original_query = self._extract_query_text(queries[-1])
- # await self._ensure_categories_ready(ctx, store)
+ original_query = self._extract_query_text(normalized_queries[-1])
where_filters = self._normalize_where(where)
- context_queries_objs = queries[:-1] if len(queries) > 1 else []
+ context_queries_objs: list[dict[str, Any]] = normalized_queries[:-1] if len(normalized_queries) > 1 else []
route_intention = self.retrieve_config.route_intention
retrieve_category = self.retrieve_config.category.enabled
retrieve_item = self.retrieve_config.item.enabled
retrieve_resource = self.retrieve_config.resource.enabled
sufficiency_check = self.retrieve_config.sufficiency_check
+ retrieve_method = normalize_retrieve_method(method, default=self.retrieve_config.method)
+ item_ranking = normalize_retrieve_ranking(ranking, default=self.retrieve_config.item.ranking)
+ bootstrap_scope = concrete_scope_from_where(where_filters)
+ if retrieve_category and bootstrap_scope is not None:
+ await self._ensure_categories_ready(ctx, store, bootstrap_scope)
- workflow_name = "retrieve_llm" if self.retrieve_config.method == "llm" else "retrieve_rag"
+ workflow_name = "retrieve_llm" if retrieve_method == "llm" else "retrieve_rag"
state: WorkflowState = {
- "method": self.retrieve_config.method,
+ "method": retrieve_method,
"original_query": original_query,
"context_queries": context_queries_objs,
"route_intention": route_intention,
- "skip_rewrite": len(queries) == 1,
+ "skip_rewrite": len(normalized_queries) == 1,
"retrieve_category": retrieve_category,
"retrieve_item": retrieve_item,
"retrieve_resource": retrieve_resource,
+ "item_ranking": item_ranking,
"sufficiency_check": sufficiency_check,
"ctx": ctx,
"store": store,
@@ -86,22 +100,38 @@ async def retrieve(
def _normalize_where(self, where: Mapping[str, Any] | None) -> dict[str, Any]:
"""Validate and clean the `where` scope filters against the configured user model."""
- if not where:
- return {}
+ return normalize_scope_where(self.user_model, where)
- valid_fields = set(getattr(self.user_model, "model_fields", {}).keys())
- cleaned: dict[str, Any] = {}
+ @staticmethod
+ def _normalize_query_item(query: str | Mapping[str, Any], *, index: int) -> dict[str, Any]:
+ if isinstance(query, str):
+ text = query.strip()
+ if not text:
+ raise ValueError(f"queries[{index}] must not be empty")
+ return {"role": "user", "content": text}
- for raw_key, value in where.items():
- if value is None:
- continue
- field = raw_key.split("__", 1)[0]
- if field not in valid_fields:
- msg = f"Unknown filter field '{field}' for current user scope"
- raise ValueError(msg)
- cleaned[raw_key] = value
+ if not isinstance(query, Mapping):
+ raise TypeError(f"queries[{index}] must be a string or query object")
+
+ role = query.get("role", "user")
+ if not isinstance(role, str) or not role.strip():
+ raise ValueError(f"queries[{index}].role must be a non-empty string")
+
+ content = query.get("content")
+ if isinstance(content, str):
+ text = content.strip()
+ if not text:
+ raise ValueError(f"queries[{index}].content must not be empty")
+ normalized_content: str | dict[str, str] = text
+ elif isinstance(content, Mapping):
+ text = content.get("text")
+ if not isinstance(text, str) or not text.strip():
+ raise ValueError(f"queries[{index}].content.text must be a non-empty string")
+ normalized_content = {"text": text.strip()}
+ else:
+ raise TypeError(f"queries[{index}].content must be a string or object with text")
- return cleaned
+ return {"role": role.strip(), "content": normalized_content}
def _build_rag_retrieve_workflow(self) -> list[WorkflowStep]:
steps = [
@@ -112,7 +142,7 @@ def _build_rag_retrieve_workflow(self) -> list[WorkflowStep]:
requires={"route_intention", "original_query", "context_queries", "skip_rewrite"},
produces={"needs_retrieval", "rewritten_query", "active_query", "next_step_query"},
capabilities={"llm"},
- config={"chat_llm_profile": self.retrieve_config.sufficiency_check_llm_profile},
+ config={"chat_llm_profile": self.retrieve_config.route_intention_llm_profile},
),
WorkflowStep(
step_id="route_category",
@@ -156,6 +186,7 @@ def _build_rag_retrieve_workflow(self) -> list[WorkflowStep]:
"where",
"active_query",
"query_vector",
+ "item_ranking",
},
produces={"item_hits", "query_vector"},
capabilities={"vector"},
@@ -219,6 +250,7 @@ def _list_retrieve_initial_keys(self) -> set[str]:
"retrieve_category",
"retrieve_item",
"retrieve_resource",
+ "item_ranking",
"sufficiency_check",
"ctx",
"store",
@@ -321,14 +353,15 @@ async def _rag_category_sufficiency(self, state: WorkflowState, step_context: An
state["query_vector"] = (await embed_client.embed([state["active_query"]]))[0]
return state
- def _extract_referenced_item_ids(self, state: WorkflowState) -> set[str]:
- """Extract item IDs from category summary references."""
+ def _extract_referenced_item_ids(self, state: WorkflowState) -> list[str]:
+ """Extract ordered, deduplicated ref IDs from category summary references."""
from memu.utils.references import extract_references
category_hits = state.get("category_hits") or []
summary_lookup = state.get("category_summary_lookup", {})
category_pool = state.get("category_pool") or {}
- referenced_item_ids: set[str] = set()
+ referenced_item_ids: list[str] = []
+ seen: set[str] = set()
for cid, _score in category_hits:
# Get summary from lookup or category
@@ -339,7 +372,11 @@ def _extract_referenced_item_ids(self, state: WorkflowState) -> set[str]:
summary = cat.summary
if summary:
refs = extract_references(summary)
- referenced_item_ids.update(refs)
+ for ref_id in refs:
+ if ref_id in seen:
+ continue
+ referenced_item_ids.append(ref_id)
+ seen.add(ref_id)
return referenced_item_ids
@@ -360,12 +397,34 @@ async def _rag_recall_items(self, state: WorkflowState, step_context: Any) -> Wo
qvec,
self.retrieve_config.item.top_k,
where=where_filters,
- ranking=self.retrieve_config.item.ranking,
+ ranking=state.get("item_ranking", self.retrieve_config.item.ranking),
recency_decay_days=self.retrieve_config.item.recency_decay_days,
)
+ if getattr(self.retrieve_config.item, "use_category_references", False):
+ ref_ids = self._extract_referenced_item_ids(state)
+ if ref_ids:
+ referenced_items = store.memory_item_repo.list_items_by_ref_ids(ref_ids, where_filters)
+ items_pool.update(referenced_items)
+ state["item_hits"] = self._merge_referenced_item_hits(
+ state["item_hits"],
+ referenced_items,
+ )
state["item_pool"] = items_pool
return state
+ @staticmethod
+ def _merge_referenced_item_hits(
+ item_hits: Sequence[tuple[str, float]],
+ referenced_items: Mapping[str, Any],
+ ) -> list[tuple[str, float]]:
+ merged = list(item_hits)
+ seen = {item_id for item_id, _score in merged}
+ for item_id in referenced_items:
+ if item_id not in seen:
+ merged.append((item_id, 1.0))
+ seen.add(item_id)
+ return merged
+
async def _rag_item_sufficiency(self, state: WorkflowState, step_context: Any) -> WorkflowState:
if not state.get("needs_retrieval"):
state["proceed_to_resources"] = False
@@ -457,16 +516,16 @@ def _build_llm_retrieve_workflow(self) -> list[WorkflowStep]:
step_id="route_intention",
role="route_intention",
handler=self._llm_route_intention,
- requires={"original_query", "context_queries", "skip_rewrite"},
+ requires={"route_intention", "original_query", "context_queries", "skip_rewrite"},
produces={"needs_retrieval", "rewritten_query", "active_query", "next_step_query"},
capabilities={"llm"},
- config={"llm_profile": self.retrieve_config.sufficiency_check_llm_profile},
+ config={"llm_profile": self.retrieve_config.route_intention_llm_profile},
),
WorkflowStep(
step_id="route_category",
role="route_category",
handler=self._llm_route_category,
- requires={"needs_retrieval", "active_query", "ctx", "store", "where"},
+ requires={"retrieve_category", "needs_retrieval", "active_query", "ctx", "store", "where"},
produces={"category_hits"},
capabilities={"llm"},
config={"llm_profile": self.retrieve_config.llm_ranking_llm_profile},
@@ -487,6 +546,7 @@ def _build_llm_retrieve_workflow(self) -> list[WorkflowStep]:
requires={
"needs_retrieval",
"proceed_to_items",
+ "retrieve_item",
"ctx",
"store",
"where",
@@ -513,6 +573,7 @@ def _build_llm_retrieve_workflow(self) -> list[WorkflowStep]:
requires={
"needs_retrieval",
"proceed_to_resources",
+ "retrieve_resource",
"active_query",
"ctx",
"store",
@@ -568,7 +629,7 @@ async def _llm_route_intention(self, state: WorkflowState, step_context: Any) ->
return state
async def _llm_route_category(self, state: WorkflowState, step_context: Any) -> WorkflowState:
- if not state.get("needs_retrieval"):
+ if not state.get("retrieve_category") or not state.get("needs_retrieval"):
state["category_hits"] = []
return state
llm_client = self._get_step_llm_client(step_context)
@@ -613,7 +674,7 @@ async def _llm_category_sufficiency(self, state: WorkflowState, step_context: An
return state
async def _llm_recall_items(self, state: WorkflowState, step_context: Any) -> WorkflowState:
- if not state.get("needs_retrieval") or not state.get("proceed_to_items"):
+ if not state.get("retrieve_item") or not state.get("needs_retrieval") or not state.get("proceed_to_items"):
state["item_hits"] = []
return state
@@ -682,7 +743,11 @@ async def _llm_item_sufficiency(self, state: WorkflowState, step_context: Any) -
return state
async def _llm_recall_resources(self, state: WorkflowState, step_context: Any) -> WorkflowState:
- if not state.get("needs_retrieval") or not state.get("proceed_to_resources"):
+ if (
+ not state.get("needs_retrieval")
+ or not state.get("retrieve_resource")
+ or not state.get("proceed_to_resources")
+ ):
state["resource_hits"] = []
return state
@@ -746,7 +811,7 @@ async def _rank_categories_by_summary(
async def _decide_if_retrieval_needed(
self,
query: str,
- context_queries: list[dict[str, Any]] | None,
+ context_queries: Sequence[str | Mapping[str, Any]] | None,
retrieved_content: str | None = None,
system_prompt: str | None = None,
llm_client: Any | None = None,
@@ -756,7 +821,7 @@ async def _decide_if_retrieval_needed(
Args:
query: The current query string
- context_queries: List of previous query objects with role and content
+ context_queries: Previous query strings or objects with role and content
retrieved_content: Content retrieved so far (if checking for sufficiency)
system_prompt: Optional system prompt override
@@ -783,7 +848,7 @@ async def _decide_if_retrieval_needed(
return decision == "RETRIEVE", rewritten
- def _format_query_context(self, queries: list[dict[str, Any]] | None) -> str:
+ def _format_query_context(self, queries: Sequence[str | Mapping[str, Any]] | None) -> str:
"""Format query context for prompts, including role information"""
if not queries:
return "No query context."
@@ -793,7 +858,7 @@ def _format_query_context(self, queries: list[dict[str, Any]] | None) -> str:
if isinstance(q, str):
# Backward compatibility
lines.append(f"- {q}")
- elif isinstance(q, dict):
+ elif isinstance(q, Mapping):
role = q.get("role", "user")
content = q.get("content")
if isinstance(content, dict):
@@ -809,32 +874,39 @@ def _format_query_context(self, queries: list[dict[str, Any]] | None) -> str:
return "\n".join(lines)
@staticmethod
- def _extract_query_text(query: dict[str, Any]) -> str:
+ def _extract_query_text(query: str | Mapping[str, Any]) -> str:
"""
Extract text content from query message structure.
Args:
- query: Query in format {"role": "user", "content": {"text": "..."}}
+ query: Query string or message in format {"role": "user", "content": "..."}.
+ The legacy {"content": {"text": "..."}} shape is also accepted.
Returns:
The extracted text string
"""
if isinstance(query, str):
# Backward compatibility: if it's already a string, return it
- return query
+ text = query.strip()
+ if not text:
+ raise ValueError("EMPTY")
+ return text
- if not isinstance(query, dict):
+ if not isinstance(query, Mapping):
raise TypeError("INVALID")
content = query.get("content")
if isinstance(content, dict):
text = content.get("text", "")
- if not text:
+ if not isinstance(text, str) or not text.strip():
raise ValueError("EMPTY")
- return str(text)
+ return text.strip()
elif isinstance(content, str):
# Also support {"role": "user", "content": "text"} format
- return content
+ text = content.strip()
+ if not text:
+ raise ValueError("EMPTY")
+ return text
else:
raise TypeError("INVALID")
@@ -868,7 +940,7 @@ async def _embedding_based_retrieve(
self,
query: str,
top_k: int,
- context_queries: list[dict[str, Any]] | None,
+ context_queries: Sequence[str | Mapping[str, Any]] | None,
ctx: Context,
store: Database,
llm_client: Any | None = None,
@@ -1022,7 +1094,7 @@ async def _llm_based_retrieve(
self,
query: str,
top_k: int,
- context_queries: list[dict[str, Any]] | None,
+ context_queries: Sequence[str | Mapping[str, Any]] | None,
ctx: Context,
store: Database,
llm_client: Any | None = None,
@@ -1253,7 +1325,7 @@ async def _llm_rank_items(
) -> list[dict[str, Any]]:
"""Use LLM to rank memory items from relevant categories"""
if not category_ids:
- print("[LLM Rank Items] No category_ids provided")
+ logger.debug("Skipping LLM item ranking because no category IDs were provided")
return []
item_pool = items if items is not None else store.memory_item_repo.items
diff --git a/src/memu/app/scope.py b/src/memu/app/scope.py
new file mode 100644
index 00000000..28423027
--- /dev/null
+++ b/src/memu/app/scope.py
@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Annotated, Any
+
+from pydantic import BaseModel, TypeAdapter, ValidationError
+
+from memu.utils.filtering import build_filter_key, normalize_filter_value, split_filter_key
+
+
+def normalize_scope_where(user_model: type[BaseModel], where: Mapping[str, Any] | None) -> dict[str, Any]:
+ """Validate and clean API `where` filters against the configured user model."""
+
+ if not where:
+ return {}
+
+ valid_fields = set(getattr(user_model, "model_fields", {}).keys())
+ cleaned: dict[str, Any] = {}
+
+ for raw_key, value in where.items():
+ if value is None:
+ continue
+ field, operator = split_filter_key(raw_key)
+ if field not in valid_fields:
+ msg = f"Unknown filter field '{field}' for current user scope"
+ raise ValueError(msg)
+ normalized_value = normalize_filter_value(field, operator, value)
+ cleaned[build_filter_key(field, operator)] = _validate_scope_filter_value(
+ user_model,
+ field,
+ operator,
+ normalized_value,
+ )
+
+ return cleaned
+
+
+def exact_scope_from_where(where: Mapping[str, Any] | None) -> dict[str, Any]:
+ """Extract exact equality scope fields that can be used as write-time user data."""
+
+ if not where:
+ return {}
+ exact: dict[str, Any] = {}
+ for raw_key, value in where.items():
+ if value is None:
+ continue
+ field, operator = split_filter_key(raw_key)
+ if operator is None:
+ exact[field] = value
+ return exact
+
+
+def concrete_scope_from_where(where: Mapping[str, Any] | None) -> dict[str, Any] | None:
+ """Return a concrete write scope when a read filter targets exactly one scope."""
+
+ if not where:
+ return {}
+ concrete: dict[str, Any] = {}
+ for raw_key, value in where.items():
+ if value is None:
+ continue
+ field, operator = split_filter_key(raw_key)
+ if operator is not None:
+ return None
+ concrete[field] = value
+ return concrete
+
+
+def record_matches_scope(record: Any, user_scope: Mapping[str, Any] | None) -> bool:
+ """Return whether a record belongs to a concrete user scope."""
+
+ if not user_scope:
+ return True
+ for field, expected in user_scope.items():
+ if expected is None:
+ continue
+ if getattr(record, str(field), None) != expected:
+ return False
+ return True
+
+
+def scope_key_from_user(user_scope: Mapping[str, Any] | None) -> tuple[tuple[str, str], ...]:
+ """Build a stable cache key for a concrete user/category scope."""
+
+ if not user_scope:
+ return ()
+ return tuple(
+ sorted(
+ (str(field), _scope_value_key(value))
+ for field, value in user_scope.items()
+ if value is not None
+ )
+ )
+
+
+def _scope_value_key(value: Any) -> str:
+ try:
+ return json.dumps(value, ensure_ascii=False, sort_keys=True)
+ except TypeError:
+ return str(value)
+
+
+def _validate_scope_filter_value(
+ user_model: type[BaseModel],
+ field: str,
+ operator: str | None,
+ value: Any,
+) -> Any:
+ if operator == "in":
+ values = (value,) if isinstance(value, str) else tuple(value)
+ return tuple(_validate_scope_field_value(user_model, field, item) for item in values)
+ return _validate_scope_field_value(user_model, field, value)
+
+
+def _validate_scope_field_value(user_model: type[BaseModel], field: str, value: Any) -> Any:
+ try:
+ model_field = user_model.model_fields[field]
+ annotation = model_field.annotation
+ if model_field.metadata:
+ annotation = Annotated[annotation, *model_field.metadata]
+ validated = TypeAdapter(annotation).validate_python(value)
+ except ValidationError as exc:
+ detail = exc.errors()[0]["msg"] if exc.errors() else "invalid value"
+ msg = f"Invalid filter value for field '{field}': {detail}"
+ raise ValueError(msg) from exc
+ return validated
+
+
+__all__ = [
+ "concrete_scope_from_where",
+ "exact_scope_from_where",
+ "normalize_scope_where",
+ "record_matches_scope",
+ "scope_key_from_user",
+]
diff --git a/src/memu/app/service.py b/src/memu/app/service.py
index 4e2dea04..bcd05601 100644
--- a/src/memu/app/service.py
+++ b/src/memu/app/service.py
@@ -19,6 +19,7 @@
MemorizeConfig,
RetrieveConfig,
UserConfig,
+ resolve_api_key,
)
from memu.blob.local_fs import LocalFS
from memu.database.factory import build_database
@@ -30,6 +31,7 @@
LLMInterceptorHandle,
LLMInterceptorRegistry,
)
+from memu.utils.serialization import model_dump_without_embeddings
from memu.workflow.interceptor import WorkflowInterceptorHandle, WorkflowInterceptorRegistry
from memu.workflow.pipeline import PipelineManager
from memu.workflow.runner import WorkflowRunner, resolve_workflow_runner
@@ -43,6 +45,8 @@ class Context:
categories_ready: bool = False
category_ids: list[str] = field(default_factory=list)
category_name_to_id: dict[str, str] = field(default_factory=dict)
+ category_scope_key: tuple[tuple[str, str], ...] = field(default_factory=tuple)
+ category_cache: dict[tuple[tuple[str, str], ...], tuple[list[str], dict[str, str]]] = field(default_factory=dict)
category_init_task: asyncio.Task | None = None
@@ -103,7 +107,7 @@ def _init_llm_client(self, config: LLMConfig | None = None) -> Any:
return OpenAISDKClient(
base_url=cfg.base_url,
- api_key=cfg.api_key,
+ api_key=resolve_api_key(cfg.api_key),
chat_model=cfg.chat_model,
embed_model=cfg.embed_model,
embed_batch_size=cfg.embed_batch_size,
@@ -111,7 +115,7 @@ def _init_llm_client(self, config: LLMConfig | None = None) -> Any:
elif backend == "httpx":
return HTTPLLMClient(
base_url=cfg.base_url,
- api_key=cfg.api_key,
+ api_key=resolve_api_key(cfg.api_key),
chat_model=cfg.chat_model,
provider=cfg.provider,
endpoint_overrides=cfg.endpoint_overrides,
@@ -373,8 +377,7 @@ def _escape_prompt_value(value: str) -> str:
return value.replace("{", "{{").replace("}", "}}")
def _model_dump_without_embeddings(self, obj: BaseModel) -> dict[str, Any]:
- data = obj.model_dump(exclude={"embedding"})
- return data
+ return model_dump_without_embeddings(obj)
@staticmethod
def _validate_config(
diff --git a/src/memu/app/settings.py b/src/memu/app/settings.py
index adcb4f16..6b4a2c1d 100644
--- a/src/memu/app/settings.py
+++ b/src/memu/app/settings.py
@@ -1,3 +1,4 @@
+import os
from collections.abc import Mapping
from typing import Annotated, Any, Literal
@@ -24,7 +25,23 @@ def normalize_value(v: str) -> str:
return v
+def resolve_api_key(value: str | None) -> str:
+ """Resolve an API key config value that may be a literal key or an environment variable name."""
+ if not value:
+ return ""
+ resolved = os.getenv(value, value)
+ return resolved.strip()
+
+
+def default_api_key_env(provider: str) -> str:
+ """Return the default API key environment variable for a provider."""
+ if provider.strip().lower() == "grok":
+ return "XAI_API_KEY"
+ return "OPENAI_API_KEY"
+
+
Normalize = BeforeValidator(normalize_value)
+ProfileName = Annotated[str, StringConstraints(strip_whitespace=True, min_length=1)]
def _default_memory_types() -> list[str]:
@@ -67,7 +84,7 @@ def complete_prompt_blocks(prompt: CustomPrompt, default_blocks: Mapping[str, in
class CategoryConfig(BaseModel):
name: str
description: str = ""
- target_length: int | None = None
+ target_length: int | None = Field(default=None, ge=1)
summary_prompt: str | Annotated[CustomPrompt, CompleteCategoryPrompt] | None = None
@@ -100,16 +117,16 @@ class LazyLLMSource(BaseModel):
class LLMConfig(BaseModel):
- provider: str = Field(
+ provider: Annotated[str, Normalize] = Field(
default="openai",
description="Identifier for the LLM provider implementation (used by HTTP client backend).",
)
base_url: str = Field(default="https://api.openai.com/v1")
api_key: str = Field(default="OPENAI_API_KEY")
chat_model: str = Field(default="gpt-4o-mini")
- client_backend: str = Field(
+ client_backend: Annotated[Literal["httpx", "sdk", "lazyllm_backend"], Normalize] = Field(
default="sdk",
- description="Which LLM client backend to use: 'httpx' (httpx), 'sdk' (official OpenAI), or 'lazyllm_backend' (for more LLM source like Qwen, Doubao, SIliconflow, etc.)",
+ description="Which LLM client backend to use: 'httpx' (httpx), 'sdk' (official OpenAI), or 'lazyllm_backend' (for more LLM source like Qwen, Doubao, SiliconFlow, etc.)",
)
lazyllm_source: LazyLLMSource = Field(default=LazyLLMSource())
endpoint_overrides: dict[str, str] = Field(
@@ -122,6 +139,7 @@ class LLMConfig(BaseModel):
)
embed_batch_size: int = Field(
default=1,
+ ge=1,
description="Maximum batch size for embedding API calls (used by SDK client backends).",
)
@@ -131,8 +149,8 @@ def set_provider_defaults(self) -> "LLMConfig":
# If values match the OpenAI defaults, switch them to Grok defaults
if self.base_url == "https://api.openai.com/v1":
self.base_url = "https://api.x.ai/v1"
- if self.api_key == "OPENAI_API_KEY":
- self.api_key = "XAI_API_KEY"
+ if self.api_key == default_api_key_env("openai"):
+ self.api_key = default_api_key_env("grok")
if self.chat_model == "gpt-4o-mini":
self.chat_model = "grok-2-latest"
return self
@@ -145,12 +163,12 @@ class BlobConfig(BaseModel):
class RetrieveCategoryConfig(BaseModel):
enabled: bool = Field(default=True, description="Whether to enable category retrieval.")
- top_k: int = Field(default=5, description="Total number of categories to retrieve.")
+ top_k: int = Field(default=5, ge=1, description="Total number of categories to retrieve.")
class RetrieveItemConfig(BaseModel):
enabled: bool = Field(default=True, description="Whether to enable item retrieval.")
- top_k: int = Field(default=5, description="Total number of items to retrieve.")
+ top_k: int = Field(default=5, ge=1, description="Total number of items to retrieve.")
# Reference-aware retrieval
use_category_references: bool = Field(
default=False,
@@ -163,13 +181,14 @@ class RetrieveItemConfig(BaseModel):
)
recency_decay_days: float = Field(
default=30.0,
+ gt=0,
description="Half-life in days for recency decay in salience scoring. After this many days, recency factor is ~0.5.",
)
class RetrieveResourceConfig(BaseModel):
enabled: bool = Field(default=True, description="Whether to enable resource retrieval.")
- top_k: int = Field(default=5, description="Total number of resources to retrieve.")
+ top_k: int = Field(default=5, ge=1, description="Total number of resources to retrieve.")
class RetrieveConfig(BaseModel):
@@ -191,32 +210,41 @@ class RetrieveConfig(BaseModel):
default=True, description="Whether to route intention (judge needs retrieval & rewrite query)."
)
# route_intention_prompt: str = Field(default="", description="User prompt for route intention.")
- # route_intention_llm_profile: str = Field(default="default", description="LLM profile for route intention.")
+ route_intention_llm_profile: ProfileName = Field(
+ default="default",
+ description="LLM profile for route intention.",
+ )
category: RetrieveCategoryConfig = Field(default=RetrieveCategoryConfig())
item: RetrieveItemConfig = Field(default=RetrieveItemConfig())
resource: RetrieveResourceConfig = Field(default=RetrieveResourceConfig())
sufficiency_check: bool = Field(default=True, description="Whether to check sufficiency after each tier.")
sufficiency_check_prompt: str = Field(default="", description="User prompt for sufficiency check.")
- sufficiency_check_llm_profile: str = Field(default="default", description="LLM profile for sufficiency check.")
- llm_ranking_llm_profile: str = Field(default="default", description="LLM profile for LLM ranking.")
+ sufficiency_check_llm_profile: ProfileName = Field(
+ default="default",
+ description="LLM profile for sufficiency check.",
+ )
+ llm_ranking_llm_profile: ProfileName = Field(default="default", description="LLM profile for LLM ranking.")
class MemorizeConfig(BaseModel):
- category_assign_threshold: float = Field(default=0.25)
+ category_assign_threshold: float = Field(default=0.25, ge=0, le=1)
multimodal_preprocess_prompts: dict[str, str | CustomPrompt] = Field(
default_factory=dict,
description="Optional mapping of modality -> preprocess system prompt.",
)
- preprocess_llm_profile: str = Field(default="default", description="LLM profile for preprocess.")
+ preprocess_llm_profile: ProfileName = Field(default="default", description="LLM profile for preprocess.")
memory_types: list[str] = Field(
default_factory=_default_memory_types,
- description="Ordered list of memory types (profile/event/knowledge/behavior by default).",
+ description="Ordered list of memory types (profile/event/knowledge/behavior/skill/tool by default).",
)
memory_type_prompts: dict[str, str | Annotated[CustomPrompt, CompleteMemoryTypePrompt]] = Field(
default_factory=_default_memory_type_prompts,
description="User prompt overrides for each memory type extraction.",
)
- memory_extract_llm_profile: str = Field(default="default", description="LLM profile for memory extract.")
+ memory_extract_llm_profile: ProfileName = Field(
+ default="default",
+ description="LLM profile for memory extract.",
+ )
memory_categories: list[CategoryConfig] = Field(
default_factory=_default_memory_categories,
description="Global memory category definitions embedded at service startup.",
@@ -228,9 +256,13 @@ class MemorizeConfig(BaseModel):
)
default_category_summary_target_length: int = Field(
default=400,
+ ge=1,
description="Target max length for auto-generated category summaries.",
)
- category_update_llm_profile: str = Field(default="default", description="LLM profile for category summary.")
+ category_update_llm_profile: ProfileName = Field(
+ default="default",
+ description="LLM profile for category summary.",
+ )
# Reference tracking for category summaries
enable_item_references: bool = Field(
default=False,
@@ -257,10 +289,7 @@ class UserConfig(BaseModel):
model: type[BaseModel] = Field(default=DefaultUserModel)
-Key = Annotated[str, StringConstraints(min_length=1)]
-
-
-class LLMProfilesConfig(RootModel[dict[Key, LLMConfig]]):
+class LLMProfilesConfig(RootModel[dict[ProfileName, LLMConfig]]):
root: dict[str, LLMConfig] = Field(default_factory=lambda: {"default": LLMConfig()})
def get(self, key: str, default: LLMConfig | None = None) -> LLMConfig | None:
@@ -278,7 +307,7 @@ def ensure_default(cls, data: Any) -> Any:
if data is None:
data = {}
elif isinstance(data, dict):
- data = dict(data)
+ data = {key.strip() if isinstance(key, str) else key: value for key, value in data.items()}
else:
return data
if "default" not in data:
@@ -299,7 +328,10 @@ def default(self) -> LLMConfig:
class MetadataStoreConfig(BaseModel):
provider: Annotated[Literal["inmemory", "postgres", "sqlite"], Normalize] = "inmemory"
ddl_mode: Annotated[Literal["create", "validate"], Normalize] = "create"
- dsn: str | None = Field(default=None, description="Database connection string (required for postgres/sqlite).")
+ dsn: str | None = Field(
+ default=None,
+ description="Database connection string. Required for postgres; optional for sqlite.",
+ )
class VectorIndexConfig(BaseModel):
diff --git a/src/memu/client/openai_wrapper.py b/src/memu/client/openai_wrapper.py
index 5c295f88..878c841a 100644
--- a/src/memu/client/openai_wrapper.py
+++ b/src/memu/client/openai_wrapper.py
@@ -8,12 +8,56 @@
from __future__ import annotations
import asyncio
+import inspect
from typing import TYPE_CHECKING, Any
+from memu.utils.retrieve import normalize_retrieve_ranking
+
if TYPE_CHECKING:
from memu.app.service import MemoryService
+def _normalize_top_k(top_k: int) -> int:
+ if isinstance(top_k, bool) or not isinstance(top_k, int) or top_k <= 0:
+ msg = "top_k must be a positive integer"
+ raise ValueError(msg)
+ return top_k
+
+
+def _copy_user_data(user_data: dict[str, Any]) -> dict[str, Any]:
+ return dict(user_data)
+
+
+def _extract_text_from_message_content(content: Any) -> str:
+ if isinstance(content, str):
+ return content
+ if isinstance(content, dict):
+ text = content.get("text")
+ return text if isinstance(text, str) else ""
+ if isinstance(content, list):
+ chunks: list[str] = []
+ for part in content:
+ if not isinstance(part, dict):
+ continue
+ text = part.get("text")
+ if isinstance(text, str) and text:
+ chunks.append(text)
+ return "\n".join(chunks)
+ return ""
+
+
+def _append_recall_context(content: Any, recall_context: str) -> str | list[Any]:
+ if isinstance(content, str):
+ return content + recall_context
+ if isinstance(content, list):
+ copied_parts = [dict(part) if isinstance(part, dict) else part for part in content]
+ copied_parts.append({"type": "text", "text": recall_context.lstrip("\n")})
+ return copied_parts
+ if content is None:
+ return recall_context.lstrip("\n")
+ return f"{content}{recall_context}"
+
+
class MemuChatCompletions:
"""Wrapper for chat.completions that injects recalled memories."""
@@ -27,22 +71,15 @@ def __init__(
):
self._original = original_completions
self._service = service
- self._user_data = user_data
- self._ranking = ranking
- self._top_k = top_k
+ self._user_data = _copy_user_data(user_data)
+ self._ranking = normalize_retrieve_ranking(ranking, default="salience")
+ self._top_k = _normalize_top_k(top_k)
def _extract_user_query(self, messages: list[dict]) -> str:
"""Extract the most recent user message."""
for msg in reversed(messages):
if msg.get("role") == "user":
- content = msg.get("content", "")
- if isinstance(content, str):
- return content
- # Handle content as list (vision models)
- if isinstance(content, list):
- for part in content:
- if isinstance(part, dict) and part.get("type") == "text":
- return part.get("text", "")
+ return _extract_text_from_message_content(msg.get("content", ""))
return ""
def _inject_memories(self, messages: list[dict], memories: list[dict]) -> list[dict]:
@@ -64,7 +101,7 @@ def _inject_memories(self, messages: list[dict], memories: list[dict]) -> list[d
# Inject into system message or create one
if messages and messages[0].get("role") == "system":
- messages[0]["content"] = messages[0]["content"] + recall_context
+ messages[0]["content"] = _append_recall_context(messages[0].get("content"), recall_context)
else:
messages.insert(0, {"role": "system", "content": recall_context.lstrip("\n")})
@@ -75,9 +112,13 @@ async def _retrieve_memories(self, query: str) -> list[dict]:
try:
result = await self._service.retrieve(
queries=[{"role": "user", "content": query}],
- where=self._user_data,
+ where=_copy_user_data(self._user_data),
+ ranking=self._ranking,
)
- return result.get("items", [])
+ items = result.get("items", [])
+ if not isinstance(items, list):
+ return []
+ return items[: self._top_k]
except Exception:
# Fail silently - don't break the LLM call
return []
@@ -119,8 +160,12 @@ async def acreate(self, **kwargs) -> Any:
# Call original async method if available
if hasattr(self._original, "acreate"):
- return await self._original.acreate(**kwargs)
- return self._original.create(**kwargs)
+ result = self._original.acreate(**kwargs)
+ else:
+ result = self._original.create(**kwargs)
+ if inspect.isawaitable(result):
+ return await result
+ return result
def __getattr__(self, name: str) -> Any:
"""Proxy all other attributes to original."""
@@ -192,21 +237,21 @@ def __init__(
service: memU MemoryService instance
user_data: User scope data (user_id, agent_id, session_id, etc.)
ranking: Retrieval ranking strategy ("similarity" or "salience")
- top_k: Number of memories to retrieve
+ top_k: Maximum number of recalled memory items to inject
"""
self._client = client
self._service = service
- self._user_data = user_data
- self._ranking = ranking
- self._top_k = top_k
+ self._user_data = _copy_user_data(user_data)
+ self._ranking = normalize_retrieve_ranking(ranking, default="salience")
+ self._top_k = _normalize_top_k(top_k)
# Wrap chat namespace
self.chat = MemuChat(
client.chat,
service,
- user_data,
- ranking,
- top_k,
+ self._user_data,
+ self._ranking,
+ self._top_k,
)
def __getattr__(self, name: str) -> Any:
@@ -235,7 +280,7 @@ def wrap_openai(
agent_id: Agent identifier (for multi-agent scoping)
session_id: Session identifier
ranking: Retrieval ranking ("similarity" or "salience")
- top_k: Number of memories to retrieve
+ top_k: Maximum number of recalled memory items to inject
Returns:
Wrapped client with auto-recall enabled
@@ -257,12 +302,14 @@ def wrap_openai(
)
"""
if user_data is None:
- user_data = {}
+ scope: dict[str, Any] = {}
+ else:
+ scope = _copy_user_data(user_data)
if user_id:
- user_data["user_id"] = user_id
+ scope["user_id"] = user_id
if agent_id:
- user_data["agent_id"] = agent_id
+ scope["agent_id"] = agent_id
if session_id:
- user_data["session_id"] = session_id
+ scope["session_id"] = session_id
- return MemuOpenAIWrapper(client, service, user_data, ranking, top_k)
+ return MemuOpenAIWrapper(client, service, scope, ranking, top_k)
diff --git a/src/memu/database/inmemory/repositories/category_item_repo.py b/src/memu/database/inmemory/repositories/category_item_repo.py
index 32e03fb2..203e1471 100644
--- a/src/memu/database/inmemory/repositories/category_item_repo.py
+++ b/src/memu/database/inmemory/repositories/category_item_repo.py
@@ -21,6 +21,14 @@ def list_relations(self, where: Mapping[str, Any] | None = None) -> list[Categor
return list(self.relations)
return [rel for rel in self.relations if matches_where(rel, where)]
+ def clear_relations(self, where: Mapping[str, Any] | None = None) -> list[CategoryItem]:
+ deleted = self.list_relations(where)
+ if not deleted:
+ return []
+ deleted_ids = {rel.id for rel in deleted}
+ self.relations[:] = [rel for rel in self.relations if rel.id not in deleted_ids]
+ return deleted
+
def link_item_category(self, item_id: str, cat_id: str, user_data: dict[str, Any]) -> CategoryItem:
_ = item_id # enforced by caller via existing state
for rel in self.relations:
@@ -39,7 +47,9 @@ def get_item_categories(self, item_id: str) -> list[CategoryItem]:
@override
def unlink_item_category(self, item_id: str, cat_id: str) -> None:
- self.relations = [rel for rel in self.relations if not (rel.item_id == item_id and rel.category_id == cat_id)]
+ self.relations[:] = [
+ rel for rel in self.relations if not (rel.item_id == item_id and rel.category_id == cat_id)
+ ]
__all__ = ["InMemoryCategoryItemRepository"]
diff --git a/src/memu/database/inmemory/repositories/filter.py b/src/memu/database/inmemory/repositories/filter.py
index ad245cc7..71faa4ad 100644
--- a/src/memu/database/inmemory/repositories/filter.py
+++ b/src/memu/database/inmemory/repositories/filter.py
@@ -3,6 +3,8 @@
from collections.abc import Mapping
from typing import Any
+from memu.utils.filtering import normalize_filter_value, split_filter_key
+
def matches_where(obj: Any, where: Mapping[str, Any] | None) -> bool:
"""Basic field/`__in` matcher for in-memory repos."""
@@ -11,7 +13,8 @@ def matches_where(obj: Any, where: Mapping[str, Any] | None) -> bool:
for raw_key, expected in where.items():
if expected is None:
continue
- field, op = [*raw_key.split("__", 1), None][:2]
+ field, op = split_filter_key(raw_key)
+ expected = normalize_filter_value(field, op, expected)
actual = getattr(obj, str(field), None)
if op == "in":
if isinstance(expected, str):
diff --git a/src/memu/database/inmemory/repositories/memory_category_repo.py b/src/memu/database/inmemory/repositories/memory_category_repo.py
index bb07ec10..04ac1b1e 100644
--- a/src/memu/database/inmemory/repositories/memory_category_repo.py
+++ b/src/memu/database/inmemory/repositories/memory_category_repo.py
@@ -29,7 +29,8 @@ def clear_categories(self, where: Mapping[str, Any] | None = None) -> dict[str,
self.categories.clear()
return matches
matches = {cid: cat for cid, cat in self.categories.items() if matches_where(cat, where)}
- self.categories = {cid: cat for cid, cat in self.categories.items() if cid not in matches}
+ for cat_id in matches:
+ self.categories.pop(cat_id, None)
return matches
def get_or_create_category(
diff --git a/src/memu/database/inmemory/repositories/memory_item_repo.py b/src/memu/database/inmemory/repositories/memory_item_repo.py
index da28e14f..c67fe7a7 100644
--- a/src/memu/database/inmemory/repositories/memory_item_repo.py
+++ b/src/memu/database/inmemory/repositories/memory_item_repo.py
@@ -56,7 +56,8 @@ def clear_items(self, where: Mapping[str, Any] | None = None) -> dict[str, Memor
self.items.clear()
return matches
matches = {mid: item for mid, item in self.items.items() if matches_where(item, where)}
- self.items = {mid: item for mid, item in self.items.items() if mid not in matches}
+ for item_id in matches:
+ self.items.pop(item_id, None)
return matches
def _find_by_hash(self, content_hash: str, user_data: dict[str, Any]) -> MemoryItem | None:
@@ -79,7 +80,7 @@ def _find_by_hash(self, content_hash: str, user_data: dict[str, Any]) -> MemoryI
def create_item(
self,
*,
- resource_id: str,
+ resource_id: str | None = None,
memory_type: MemoryType,
summary: str,
embedding: list[float],
@@ -122,7 +123,7 @@ def create_item(
def create_item_reinforce(
self,
*,
- resource_id: str,
+ resource_id: str | None = None,
memory_type: MemoryType,
summary: str,
embedding: list[float],
diff --git a/src/memu/database/inmemory/repositories/resource_repo.py b/src/memu/database/inmemory/repositories/resource_repo.py
index ba60e52b..26c4f266 100644
--- a/src/memu/database/inmemory/repositories/resource_repo.py
+++ b/src/memu/database/inmemory/repositories/resource_repo.py
@@ -27,7 +27,8 @@ def clear_resources(self, where: Mapping[str, Any] | None = None) -> dict[str, R
self.resources.clear()
return matches
matches = {rid: res for rid, res in self.resources.items() if matches_where(res, where)}
- self.resources = {rid: res for rid, res in self.resources.items() if rid not in matches}
+ for res_id in matches:
+ self.resources.pop(res_id, None)
return matches
def create_resource(
diff --git a/src/memu/database/inmemory/vector.py b/src/memu/database/inmemory/vector.py
index cd5355c7..001b53e5 100644
--- a/src/memu/database/inmemory/vector.py
+++ b/src/memu/database/inmemory/vector.py
@@ -58,6 +58,9 @@ def cosine_topk(
corpus: Iterable[tuple[str, list[float] | None]],
k: int = 5,
) -> list[tuple[str, float]]:
+ if k <= 0:
+ return []
+
# Filter out None vectors and collect valid entries
ids: list[str] = []
vecs: list[list[float]] = []
@@ -111,6 +114,9 @@ def cosine_topk_salience(
Returns:
List of (id, salience_score) tuples, sorted by score descending
"""
+ if k <= 0:
+ return []
+
q = np.array(query_vec, dtype=np.float32)
scored: list[tuple[str, float]] = []
diff --git a/src/memu/database/models.py b/src/memu/database/models.py
index 0124b784..bc7a8cb2 100644
--- a/src/memu/database/models.py
+++ b/src/memu/database/models.py
@@ -9,32 +9,16 @@
import pendulum
from pydantic import BaseModel, ConfigDict, Field
-MemoryType = Literal["profile", "event", "knowledge", "behavior", "skill", "tool"]
-
-
-def compute_content_hash(summary: str, memory_type: str) -> str:
- """
- Generate unique hash for memory deduplication.
-
- Operates on post-summary content. Normalizes whitespace to handle
- minor formatting differences like "I love coffee" vs "I love coffee".
+from memu.utils.dedupe import compute_content_hash
- Args:
- summary: The memory summary text
- memory_type: The type of memory (profile, event, etc.)
-
- Returns:
- A 16-character hex hash string
- """
- # Normalize: lowercase, strip, collapse whitespace
- normalized = " ".join(summary.lower().split())
- content = f"{memory_type}:{normalized}"
- return hashlib.sha256(content.encode()).hexdigest()[:16]
+MemoryType = Literal["profile", "event", "knowledge", "behavior", "skill", "tool"]
class BaseRecord(BaseModel):
"""Backend-agnostic record interface."""
+ model_config = ConfigDict(extra="allow")
+
id: str = Field(default_factory=lambda: str(uuid.uuid4()))
created_at: datetime = Field(default_factory=lambda: pendulum.now("UTC"))
updated_at: datetime = Field(default_factory=lambda: pendulum.now("UTC"))
@@ -79,7 +63,7 @@ class MemoryItem(BaseRecord):
summary: str
embedding: list[float] | None = None
happened_at: datetime | None = None
- extra: dict[str, Any] = {}
+ extra: dict[str, Any] = Field(default_factory=dict)
# extra may contain:
# # reinforcement tracking fields
# - content_hash: str
diff --git a/src/memu/database/postgres/models.py b/src/memu/database/postgres/models.py
index e83797a2..4e083e0f 100644
--- a/src/memu/database/postgres/models.py
+++ b/src/memu/database/postgres/models.py
@@ -6,11 +6,12 @@
import pendulum
+from memu.database.postgres.optional import postgres_extra_import_error
+
try:
from pgvector.sqlalchemy import VECTOR as Vector
except ImportError as exc:
- msg = "pgvector is required for Postgres vector support"
- raise ImportError(msg) from exc
+ raise postgres_extra_import_error() from exc
from pydantic import BaseModel
from sqlalchemy import ForeignKey, MetaData, String, Text
@@ -57,7 +58,7 @@ class MemoryItemModel(BaseModelMixin, MemoryItem):
summary: str = Field(sa_column=Column(Text, nullable=False))
embedding: list[float] | None = Field(default=None, sa_column=Column(Vector(), nullable=True))
happened_at: datetime | None = Field(default=None, sa_column=Column(DateTime, nullable=True))
- extra: dict[str, Any] = Field(default={}, sa_column=Column(JSONB, nullable=True))
+ extra: dict[str, Any] = Field(default_factory=dict, sa_column=Column(JSONB, nullable=True))
class MemoryCategoryModel(BaseModelMixin, MemoryCategory):
diff --git a/src/memu/database/postgres/optional.py b/src/memu/database/postgres/optional.py
new file mode 100644
index 00000000..c7d5bde9
--- /dev/null
+++ b/src/memu/database/postgres/optional.py
@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+POSTGRES_EXTRA_INSTALL_HINT = (
+ "Postgres storage requires the optional Postgres dependencies. "
+ "Install them with `pip install 'memu-py[postgres]'`, or run "
+ "`uv sync --extra postgres` from a source checkout."
+)
+
+
+def postgres_extra_import_error() -> ImportError:
+ return ImportError(POSTGRES_EXTRA_INSTALL_HINT)
+
+
+__all__ = ["POSTGRES_EXTRA_INSTALL_HINT", "postgres_extra_import_error"]
diff --git a/src/memu/database/postgres/repositories/base.py b/src/memu/database/postgres/repositories/base.py
index 0823dbf8..32745933 100644
--- a/src/memu/database/postgres/repositories/base.py
+++ b/src/memu/database/postgres/repositories/base.py
@@ -7,6 +7,7 @@
import pendulum
from memu.database.postgres.session import SessionManager
+from memu.utils.filtering import normalize_filter_value, split_filter_key
from memu.database.state import DatabaseState
logger = logging.getLogger(__name__)
@@ -71,7 +72,8 @@ def _build_filters(self, model: Any, where: Mapping[str, Any] | None) -> list[An
for raw_key, expected in where.items():
if expected is None:
continue
- field, op = [*raw_key.split("__", 1), None][:2]
+ field, op = split_filter_key(raw_key)
+ expected = normalize_filter_value(field, op, expected)
column = getattr(model, str(field), None)
if column is None:
msg = f"Unknown filter field '{field}' for model '{model.__name__}'"
@@ -92,7 +94,8 @@ def _matches_where(obj: Any, where: Mapping[str, Any] | None) -> bool:
for raw_key, expected in where.items():
if expected is None:
continue
- field, op = [*raw_key.split("__", 1), None][:2]
+ field, op = split_filter_key(raw_key)
+ expected = normalize_filter_value(field, op, expected)
actual = getattr(obj, str(field), None)
if op == "in":
if isinstance(expected, str):
diff --git a/src/memu/database/postgres/repositories/category_item_repo.py b/src/memu/database/postgres/repositories/category_item_repo.py
index 90409807..1affd21a 100644
--- a/src/memu/database/postgres/repositories/category_item_repo.py
+++ b/src/memu/database/postgres/repositories/category_item_repo.py
@@ -32,6 +32,24 @@ def list_relations(self, where: Mapping[str, Any] | None = None) -> list[Categor
rows = session.scalars(select(self._sqla_models.CategoryItem).where(*filters)).all()
return [self._cache_relation(row) for row in rows]
+ def clear_relations(self, where: Mapping[str, Any] | None = None) -> list[CategoryItem]:
+ from sqlmodel import delete, select
+
+ filters = self._build_filters(self._sqla_models.CategoryItem, where)
+ with self._sessions.session() as session:
+ rows = session.scalars(select(self._sqla_models.CategoryItem).where(*filters)).all()
+ deleted = list(rows)
+
+ if not deleted:
+ return []
+
+ session.exec(delete(self._sqla_models.CategoryItem).where(*filters))
+ session.commit()
+
+ deleted_ids = {rel.id for rel in deleted}
+ self.relations[:] = [rel for rel in self.relations if rel.id not in deleted_ids]
+ return deleted
+
def link_item_category(self, item_id: str, cat_id: str, user_data: dict[str, Any]) -> CategoryItem:
from sqlmodel import select
@@ -76,6 +94,9 @@ def unlink_item_category(self, item_id: str, cat_id: str) -> None:
)
)
session.commit()
+ self.relations[:] = [
+ rel for rel in self.relations if not (rel.item_id == item_id and rel.category_id == cat_id)
+ ]
def get_item_categories(self, item_id: str) -> list[CategoryItem]:
from sqlmodel import select
@@ -95,6 +116,10 @@ def load_existing(self) -> None:
self._cache_relation(row)
def _cache_relation(self, rel: CategoryItem) -> CategoryItem:
+ for idx, existing in enumerate(self.relations):
+ if existing.id == rel.id:
+ self.relations[idx] = rel
+ return rel
self.relations.append(rel)
return rel
diff --git a/src/memu/database/postgres/repositories/memory_category_repo.py b/src/memu/database/postgres/repositories/memory_category_repo.py
index 229cd200..614a2cb3 100644
--- a/src/memu/database/postgres/repositories/memory_category_repo.py
+++ b/src/memu/database/postgres/repositories/memory_category_repo.py
@@ -57,8 +57,12 @@ def clear_categories(self, where: Mapping[str, Any] | None = None) -> dict[str,
session.commit()
# Clean up cache
- for cat_id in deleted:
+ deleted_category_ids = set(deleted)
+ for cat_id in deleted_category_ids:
self.categories.pop(cat_id, None)
+ self._state.relations[:] = [
+ rel for rel in self._state.relations if rel.category_id not in deleted_category_ids
+ ]
return deleted
diff --git a/src/memu/database/postgres/repositories/memory_item_repo.py b/src/memu/database/postgres/repositories/memory_item_repo.py
index 6d04f61b..5b9953c6 100644
--- a/src/memu/database/postgres/repositories/memory_item_repo.py
+++ b/src/memu/database/postgres/repositories/memory_item_repo.py
@@ -105,8 +105,10 @@ def clear_items(self, where: Mapping[str, Any] | None = None) -> dict[str, Memor
session.commit()
# Clean up cache
- for item_id in deleted:
+ deleted_item_ids = set(deleted)
+ for item_id in deleted_item_ids:
self.items.pop(item_id, None)
+ self._drop_relation_cache_for_items(deleted_item_ids)
return deleted
@@ -276,6 +278,8 @@ def delete_item(self, item_id: str) -> None:
with self._sessions.session() as session:
session.exec(delete(self._sqla_models.MemoryItem).where(self._sqla_models.MemoryItem.id == item_id))
session.commit()
+ self.items.pop(item_id, None)
+ self._drop_relation_cache_for_items({item_id})
def vector_search_items(
self,
@@ -286,6 +290,8 @@ def vector_search_items(
ranking: str = "similarity",
recency_decay_days: float = 30.0,
) -> list[tuple[str, float]]:
+ if top_k <= 0:
+ return []
if not self._use_vector or ranking == "salience":
# For salience ranking or when pgvector is not available, use local search
return self._vector_search_local(
@@ -326,11 +332,10 @@ def _vector_search_local(
recency_decay_days: float = 30.0,
) -> list[tuple[str, float]]:
scored: list[tuple[str, float]] = []
- for item in self.items.values():
+ pool = self.list_items(where)
+ for item in pool.values():
if item.embedding is None:
continue
- if not self._matches_where(item, where):
- continue
similarity = self._cosine(query_vec, item.embedding)
@@ -376,6 +381,13 @@ def _cache_item(self, item: MemoryItem) -> MemoryItem:
self.items[item.id] = item
return item
+ def _drop_relation_cache_for_items(self, item_ids: set[str]) -> None:
+ if not item_ids:
+ return
+ self._state.relations[:] = [
+ rel for rel in self._state.relations if rel.item_id not in item_ids
+ ]
+
@staticmethod
def _parse_datetime(dt_str: str | None) -> datetime | None:
"""Parse ISO datetime string from extra dict."""
diff --git a/src/memu/database/postgres/repositories/resource_repo.py b/src/memu/database/postgres/repositories/resource_repo.py
index d358febc..961afff0 100644
--- a/src/memu/database/postgres/repositories/resource_repo.py
+++ b/src/memu/database/postgres/repositories/resource_repo.py
@@ -57,8 +57,20 @@ def clear_resources(self, where: Mapping[str, Any] | None = None) -> dict[str, R
session.commit()
# Clean up cache
- for res_id in deleted:
+ deleted_resource_ids = set(deleted)
+ for res_id in deleted_resource_ids:
self.resources.pop(res_id, None)
+ deleted_item_ids = {
+ item_id
+ for item_id, item in self._state.items.items()
+ if item.resource_id in deleted_resource_ids
+ }
+ for item_id in deleted_item_ids:
+ self._state.items.pop(item_id, None)
+ if deleted_item_ids:
+ self._state.relations[:] = [
+ rel for rel in self._state.relations if rel.item_id not in deleted_item_ids
+ ]
return deleted
diff --git a/src/memu/database/postgres/schema.py b/src/memu/database/postgres/schema.py
index ac6e8b52..eca21237 100644
--- a/src/memu/database/postgres/schema.py
+++ b/src/memu/database/postgres/schema.py
@@ -5,6 +5,8 @@
from pydantic import BaseModel
+from memu.database.postgres.optional import postgres_extra_import_error
+
try:
from sqlmodel import SQLModel
except ImportError as exc:
@@ -20,8 +22,7 @@
try:
from pgvector.sqlalchemy import VECTOR as Vector
except ImportError as exc:
- msg = "pgvector is required for Postgres vector support"
- raise ImportError(msg) from exc
+ raise postgres_extra_import_error() from exc
from memu.database.postgres.models import (
CategoryItemModel,
@@ -72,6 +73,7 @@ def get_sqlalchemy_models(*, scope_model: type[BaseModel] | None = None) -> SQLA
MemoryCategoryModel,
tablename="memory_categories",
metadata=metadata_obj,
+ unique_with_scope=["name"],
)
memory_item_model = build_table_model(
scope,
diff --git a/src/memu/database/repositories/category_item.py b/src/memu/database/repositories/category_item.py
index 582a2845..49001a64 100644
--- a/src/memu/database/repositories/category_item.py
+++ b/src/memu/database/repositories/category_item.py
@@ -14,6 +14,8 @@ class CategoryItemRepo(Protocol):
def list_relations(self, where: Mapping[str, Any] | None = None) -> list[CategoryItem]: ...
+ def clear_relations(self, where: Mapping[str, Any] | None = None) -> list[CategoryItem]: ...
+
def link_item_category(self, item_id: str, cat_id: str, user_data: dict[str, Any]) -> CategoryItem: ...
def unlink_item_category(self, item_id: str, cat_id: str) -> None: ...
diff --git a/src/memu/database/repositories/memory_item.py b/src/memu/database/repositories/memory_item.py
index 39bb856b..a2124005 100644
--- a/src/memu/database/repositories/memory_item.py
+++ b/src/memu/database/repositories/memory_item.py
@@ -21,7 +21,7 @@ def clear_items(self, where: Mapping[str, Any] | None = None) -> dict[str, Memor
def create_item(
self,
*,
- resource_id: str,
+ resource_id: str | None = None,
memory_type: MemoryType,
summary: str,
embedding: list[float],
diff --git a/src/memu/database/sqlite/models.py b/src/memu/database/sqlite/models.py
index 6cdaed49..aa405d0d 100644
--- a/src/memu/database/sqlite/models.py
+++ b/src/memu/database/sqlite/models.py
@@ -84,7 +84,7 @@ class SQLiteMemoryItemModel(SQLiteBaseModelMixin, MemoryItem):
# Store embedding as JSON string since SQLite doesn't have native vector type
embedding_json: str | None = Field(default=None, sa_column=Column(Text, nullable=True))
happened_at: datetime | None = Field(default=None, sa_column=Column(DateTime, nullable=True))
- extra: dict[str, Any] = Field(default={}, sa_column=Column(JSON, nullable=True))
+ extra: dict[str, Any] = Field(default_factory=dict, sa_column=Column(JSON, nullable=True))
@property
def embedding(self) -> list[float] | None:
diff --git a/src/memu/database/sqlite/repositories/base.py b/src/memu/database/sqlite/repositories/base.py
index 44099859..6dc1834f 100644
--- a/src/memu/database/sqlite/repositories/base.py
+++ b/src/memu/database/sqlite/repositories/base.py
@@ -10,6 +10,7 @@
import pendulum
from memu.database.sqlite.session import SQLiteSessionManager
+from memu.utils.filtering import normalize_filter_value, split_filter_key
from memu.database.state import DatabaseState
logger = logging.getLogger(__name__)
@@ -85,7 +86,8 @@ def _build_filters(self, model: Any, where: Mapping[str, Any] | None) -> list[An
for raw_key, expected in where.items():
if expected is None:
continue
- field, op = [*raw_key.split("__", 1), None][:2]
+ field, op = split_filter_key(raw_key)
+ expected = normalize_filter_value(field, op, expected)
column = getattr(model, str(field), None)
if column is None:
msg = f"Unknown filter field '{field}' for model '{model.__name__}'"
@@ -107,7 +109,8 @@ def _matches_where(obj: Any, where: Mapping[str, Any] | None) -> bool:
for raw_key, expected in where.items():
if expected is None:
continue
- field, op = [*raw_key.split("__", 1), None][:2]
+ field, op = split_filter_key(raw_key)
+ expected = normalize_filter_value(field, op, expected)
actual = getattr(obj, str(field), None)
if op == "in":
if isinstance(expected, str):
diff --git a/src/memu/database/sqlite/repositories/category_item_repo.py b/src/memu/database/sqlite/repositories/category_item_repo.py
index f6996650..cc0de064 100644
--- a/src/memu/database/sqlite/repositories/category_item_repo.py
+++ b/src/memu/database/sqlite/repositories/category_item_repo.py
@@ -6,7 +6,7 @@
from collections.abc import Mapping
from typing import Any
-from sqlmodel import select
+from sqlmodel import delete, select
from memu.database.models import CategoryItem
from memu.database.repositories.category_item import CategoryItemRepo
@@ -66,21 +66,35 @@ def list_relations(self, where: Mapping[str, Any] | None = None) -> list[Categor
result: list[CategoryItem] = []
for row in rows:
- rel = CategoryItem(
- id=row.id,
- item_id=row.item_id,
- category_id=row.category_id,
- created_at=row.created_at,
- updated_at=row.updated_at,
- **self._scope_kwargs_from(row),
- )
+ rel = self._relation_from_row(row)
result.append(rel)
- # Update cache
- if not any(r.id == rel.id for r in self.relations):
- self.relations.append(rel)
+ self._cache_relation(rel)
return result
+ def clear_relations(self, where: Mapping[str, Any] | None = None) -> list[CategoryItem]:
+ """Clear category-item relations matching the where clause."""
+ filters = self._build_filters(self._category_item_model, where)
+ with self._sessions.session() as session:
+ stmt = select(self._category_item_model)
+ if filters:
+ stmt = stmt.where(*filters)
+ rows = session.exec(stmt).all()
+ deleted = [self._relation_from_row(row) for row in rows]
+
+ if not deleted:
+ return []
+
+ del_stmt = delete(self._category_item_model)
+ if filters:
+ del_stmt = del_stmt.where(*filters)
+ session.exec(del_stmt)
+ session.commit()
+
+ deleted_ids = {rel.id for rel in deleted}
+ self.relations[:] = [rel for rel in self.relations if rel.id not in deleted_ids]
+ return deleted
+
def link_item_category(self, item_id: str, category_id: str, user_data: dict[str, Any]) -> CategoryItem:
"""Create a link between an item and a category.
@@ -106,15 +120,7 @@ def link_item_category(self, item_id: str, category_id: str, user_data: dict[str
existing = session.exec(stmt).first()
if existing:
- rel = CategoryItem(
- id=existing.id,
- item_id=existing.item_id,
- category_id=existing.category_id,
- created_at=existing.created_at,
- updated_at=existing.updated_at,
- **self._scope_kwargs_from(existing),
- )
- return rel
+ return self._cache_relation(self._relation_from_row(existing))
# Create new relation
now = self._now()
@@ -129,16 +135,7 @@ def link_item_category(self, item_id: str, category_id: str, user_data: dict[str
session.commit()
session.refresh(row)
- rel = CategoryItem(
- id=row.id,
- item_id=row.item_id,
- category_id=row.category_id,
- created_at=row.created_at,
- updated_at=row.updated_at,
- **user_data,
- )
- self.relations.append(rel)
- return rel
+ return self._cache_relation(self._relation_from_row(row))
def unlink_item_category(self, item_id: str, category_id: str) -> None:
"""Remove a link between an item and a category.
@@ -176,5 +173,23 @@ def load_existing(self) -> None:
"""Load all existing relations from database into cache."""
self.list_relations()
+ def _relation_from_row(self, row: Any) -> CategoryItem:
+ return CategoryItem(
+ id=row.id,
+ item_id=row.item_id,
+ category_id=row.category_id,
+ created_at=row.created_at,
+ updated_at=row.updated_at,
+ **self._scope_kwargs_from(row),
+ )
+
+ def _cache_relation(self, rel: CategoryItem) -> CategoryItem:
+ for idx, existing in enumerate(self.relations):
+ if existing.id == rel.id:
+ self.relations[idx] = rel
+ return rel
+ self.relations.append(rel)
+ return rel
+
__all__ = ["SQLiteCategoryItemRepo"]
diff --git a/src/memu/database/sqlite/repositories/memory_item_repo.py b/src/memu/database/sqlite/repositories/memory_item_repo.py
index 0bff124e..1ca32481 100644
--- a/src/memu/database/sqlite/repositories/memory_item_repo.py
+++ b/src/memu/database/sqlite/repositories/memory_item_repo.py
@@ -211,7 +211,7 @@ def clear_items(self, where: Mapping[str, Any] | None = None) -> dict[str, Memor
def create_item(
self,
*,
- resource_id: str,
+ resource_id: str | None = None,
memory_type: MemoryType,
summary: str,
embedding: list[float],
@@ -285,7 +285,7 @@ def create_item(
def create_item_reinforce(
self,
*,
- resource_id: str,
+ resource_id: str | None = None,
memory_type: MemoryType,
summary: str,
embedding: list[float],
diff --git a/src/memu/database/sqlite/schema.py b/src/memu/database/sqlite/schema.py
index 63291cb1..24b97b2c 100644
--- a/src/memu/database/sqlite/schema.py
+++ b/src/memu/database/sqlite/schema.py
@@ -60,6 +60,7 @@ def get_sqlite_sqlalchemy_models(*, scope_model: type[BaseModel] | None = None)
SQLiteMemoryCategoryModel,
tablename="sqlite_memory_categories",
metadata=metadata_obj,
+ unique_with_scope=["name"],
)
memory_item_model = build_sqlite_table_model(
scope,
diff --git a/src/memu/embedding/http_client.py b/src/memu/embedding/http_client.py
index 0c3066a7..bef5f608 100644
--- a/src/memu/embedding/http_client.py
+++ b/src/memu/embedding/http_client.py
@@ -97,9 +97,10 @@ async def embed_multimodal(
List of embedding vectors
Example:
+ >>> import os
>>> client = HTTPEmbeddingClient(
... base_url="https://ark.cn-beijing.volces.com",
- ... api_key="your-api-key",
+ ... api_key=os.environ["DOUBAO_API_KEY"],
... embed_model="doubao-embedding-vision-250615",
... provider="doubao",
... )
diff --git a/src/memu/integrations/langgraph.py b/src/memu/integrations/langgraph.py
index 2e24ddc6..212a2e59 100644
--- a/src/memu/integrations/langgraph.py
+++ b/src/memu/integrations/langgraph.py
@@ -7,19 +7,26 @@
import os
import tempfile
import uuid
-from typing import Any
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Annotated, Any
-# MUST explicitly import langgraph to satisfy DEP002
-import langgraph
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, StringConstraints
-from memu.app.service import MemoryService
+if TYPE_CHECKING:
+ from langchain_core.tools import BaseTool, StructuredTool
+ from memu.app.service import MemoryService
try:
+ # Explicit import keeps the optional integration dependency visible to tooling.
+ import langgraph
from langchain_core.tools import BaseTool, StructuredTool
-except ImportError as e:
- msg = "Please install 'langchain-core' (and 'langgraph') to use the LangGraph integration."
- raise ImportError(msg) from e
+except ImportError as exc: # pragma: no cover - covered by optional-dependency smoke tests.
+ langgraph = None # type: ignore[assignment]
+ BaseTool = Any # type: ignore[misc, assignment]
+ StructuredTool = None # type: ignore[assignment]
+ _LANGGRAPH_IMPORT_ERROR: ImportError | None = exc
+else:
+ _LANGGRAPH_IMPORT_ERROR = None
# Setup logger
@@ -30,24 +37,55 @@ class MemUIntegrationError(Exception):
"""Base exception for MemU integration issues."""
+NonEmptyString = Annotated[str, StringConstraints(strip_whitespace=True, min_length=1)]
+
+
class SaveRecallInput(BaseModel):
"""Input schema for the save_memory tool."""
- content: str = Field(description="The text content or information to save/remember.")
- user_id: str = Field(description="The unique identifier of the user.")
+ content: NonEmptyString = Field(description="The text content or information to save/remember.")
+ user_id: NonEmptyString = Field(description="The unique identifier of the user.")
metadata: dict[str, Any] | None = Field(default=None, description="Additional metadata related to the memory.")
class SearchRecallInput(BaseModel):
"""Input schema for the search_memory tool."""
- query: str = Field(description="The search query to retrieve relevant memories.")
- user_id: str = Field(description="The unique identifier of the user.")
- limit: int = Field(default=5, description="Number of memories to retrieve.")
+ query: NonEmptyString = Field(description="The search query to retrieve relevant memories.")
+ user_id: NonEmptyString = Field(description="The unique identifier of the user.")
+ limit: int = Field(default=5, ge=1, description="Number of memories to retrieve.")
metadata_filter: dict[str, Any] | None = Field(
default=None, description="Optional filter for memory metadata (e.g., {'category': 'work'})."
)
- min_relevance_score: float = Field(default=0.0, description="Minimum relevance score (0.0 to 1.0) for results.")
+ min_relevance_score: float = Field(
+ default=0.0,
+ ge=0.0,
+ le=1.0,
+ description="Minimum relevance score (0.0 to 1.0) for results.",
+ )
+
+
+def _ensure_langgraph_dependencies() -> None:
+ if _LANGGRAPH_IMPORT_ERROR is None:
+ return
+ msg = (
+ "Please install the LangGraph integration dependencies with "
+ "`pip install 'memu-py[langgraph]'`, or run `uv sync --extra langgraph` "
+ "from a source checkout."
+ )
+ raise ImportError(msg) from _LANGGRAPH_IMPORT_ERROR
+
+
+def _scope_with_user(user_id: str, metadata: Mapping[str, Any] | None = None) -> dict[str, Any]:
+ if not isinstance(user_id, str) or not user_id.strip():
+ msg = "user_id must be a non-empty string"
+ raise ValueError(msg)
+ if metadata is not None and not isinstance(metadata, Mapping):
+ msg = "metadata must be an object"
+ raise ValueError(msg)
+ scope = dict(metadata or {})
+ scope["user_id"] = user_id.strip()
+ return scope
class MemULangGraphTools:
@@ -59,6 +97,7 @@ class MemULangGraphTools:
def __init__(self, memory_service: MemoryService):
"""Initializes the MemULangGraphTools with a memory service."""
+ _ensure_langgraph_dependencies()
self.memory_service = memory_service
# Expose the langgraph module to ensure it's "used" even if just by reference in this class
self._graph_backend = langgraph
@@ -75,6 +114,8 @@ def save_memory_tool(self) -> StructuredTool:
async def _save(content: str, user_id: str, metadata: dict | None = None) -> str:
logger.info("Entering save_memory_tool for user_id: %s", user_id)
+ content = content.strip()
+ user_scope = _scope_with_user(user_id, metadata)
filename = f"memu_input_{uuid.uuid4()}.txt"
temp_dir = tempfile.gettempdir()
file_path = os.path.join(temp_dir, filename)
@@ -87,9 +128,9 @@ async def _save(content: str, user_id: str, metadata: dict | None = None) -> str
await self.memory_service.memorize(
resource_url=file_path,
modality="conversation",
- user={"user_id": user_id, **(metadata or {})},
+ user=user_scope,
)
- logger.info("Successfully saved memory for user_id: %s", user_id)
+ logger.info("Successfully saved memory for user_id: %s", user_scope["user_id"])
except Exception as e:
error_msg = f"Failed to save memory for user {user_id}: {e!s}"
logger.exception(error_msg)
@@ -122,10 +163,9 @@ async def _search(
) -> str:
logger.info("Entering search_memory_tool for user_id: %s, query: '%s'", user_id, query)
try:
+ query = query.strip()
queries = [{"role": "user", "content": query}]
- where_filter = {"user_id": user_id}
- if metadata_filter:
- where_filter.update(metadata_filter)
+ where_filter = _scope_with_user(user_id, metadata_filter)
logger.debug("Calling memory_service.retrieve with where_filter: %s", where_filter)
result = await self.memory_service.retrieve(
diff --git a/src/memu/llm/lazyllm_client.py b/src/memu/llm/lazyllm_client.py
index 8446b6a5..aae06204 100644
--- a/src/memu/llm/lazyllm_client.py
+++ b/src/memu/llm/lazyllm_client.py
@@ -1,9 +1,28 @@
import asyncio
import functools
+import logging
from typing import Any, cast
-import lazyllm
-from lazyllm import LOG
+try:
+ import lazyllm
+ from lazyllm import LOG
+except ImportError as exc: # pragma: no cover - covered by optional-dependency smoke tests.
+ lazyllm = None # type: ignore[assignment]
+ LOG = logging.getLogger("memu.llm.lazyllm")
+ _LAZYLLM_IMPORT_ERROR: ImportError | None = exc
+else:
+ _LAZYLLM_IMPORT_ERROR = None
+
+
+def _lazyllm_module() -> Any:
+ if _LAZYLLM_IMPORT_ERROR is None:
+ return lazyllm
+ msg = (
+ "Please install the LazyLLM backend dependencies with "
+ "`pip install 'memu-py[lazyllm]'`, or run `uv sync --extra lazyllm` "
+ "from a source checkout."
+ )
+ raise ImportError(msg) from _LAZYLLM_IMPORT_ERROR
class LazyLLMClient:
@@ -23,6 +42,7 @@ def __init__(
embed_model: str | None = None,
stt_model: str | None = None,
):
+ _lazyllm_module()
self.llm_source = llm_source or self.DEFAULT_SOURCE
self.vlm_source = vlm_source or self.DEFAULT_SOURCE
self.embed_source = embed_source or self.DEFAULT_SOURCE
@@ -59,7 +79,9 @@ async def chat(
Return:
The generated summary text as a string.
"""
- client = lazyllm.namespace("MEMU").OnlineModule(source=self.llm_source, model=self.chat_model, type="llm")
+ client = _lazyllm_module().namespace("MEMU").OnlineModule(
+ source=self.llm_source, model=self.chat_model, type="llm"
+ )
prompt = f"{system_prompt}\n\n" if system_prompt else ""
full_prompt = f"{prompt}text:\n{text}"
LOG.debug(f"Summarizing text with {self.llm_source}/{self.chat_model}")
@@ -83,7 +105,9 @@ async def summarize(
Return:
The generated summary text as a string.
"""
- client = lazyllm.namespace("MEMU").OnlineModule(source=self.llm_source, model=self.chat_model, type="llm")
+ client = _lazyllm_module().namespace("MEMU").OnlineModule(
+ source=self.llm_source, model=self.chat_model, type="llm"
+ )
prompt = system_prompt or "Summarize the text in one short paragraph."
full_prompt = f"{prompt}\n\ntext:\n{text}"
LOG.debug(f"Summarizing text with {self.llm_source}/{self.chat_model}")
@@ -110,7 +134,9 @@ async def vision(
Return:
A tuple containing the generated text response and None (reserved for metadata).
"""
- client = lazyllm.namespace("MEMU").OnlineModule(source=self.vlm_source, model=self.vlm_model, type="vlm")
+ client = _lazyllm_module().namespace("MEMU").OnlineModule(
+ source=self.vlm_source, model=self.vlm_model, type="vlm"
+ )
LOG.debug(f"Processing image with {self.vlm_source}/{self.vlm_model}: {image_path}")
# LazyLLM VLM accepts prompt as first positional argument and image_path as keyword argument
response = await self._call_async(client, prompt, lazyllm_files=image_path)
@@ -130,7 +156,7 @@ async def embed(
Return:
A list of embedding vectors (list of floats), one for each input text.
"""
- client = lazyllm.namespace("MEMU").OnlineModule(
+ client = _lazyllm_module().namespace("MEMU").OnlineModule(
source=self.embed_source, model=self.embed_model, type="embed", batch_size=batch_size
)
LOG.debug(f"embed {len(texts)} texts with {self.embed_source}/{self.embed_model}")
@@ -153,7 +179,12 @@ async def transcribe(
Return:
The transcribed text as a string.
"""
- client = lazyllm.namespace("MEMU").OnlineModule(source=self.stt_source, model=self.stt_model, type="stt")
+ client = _lazyllm_module().namespace("MEMU").OnlineModule(
+ source=self.stt_source, model=self.stt_model, type="stt"
+ )
LOG.debug(f"Transcribing audio with {self.stt_source}/{self.stt_model}: {audio_path}")
response = await self._call_async(client, audio_path)
return cast(str, response)
+
+
+__all__ = ["LazyLLMClient"]
diff --git a/src/memu/llm/openai_sdk.py b/src/memu/llm/openai_sdk.py
index 38c6c8bb..2bd7e9e7 100644
--- a/src/memu/llm/openai_sdk.py
+++ b/src/memu/llm/openai_sdk.py
@@ -152,22 +152,23 @@ async def vision(
logger.debug("OpenAI vision response: %s", response)
return content or "", response
- async def embed(self, inputs: list[str]) -> tuple[list[list[float]], CreateEmbeddingResponse | None]:
+ async def embed(
+ self, inputs: list[str]
+ ) -> tuple[list[list[float]], CreateEmbeddingResponse | list[CreateEmbeddingResponse] | None]:
"""Create text embeddings via the official SDK."""
if len(inputs) <= self.embed_batch_size:
response = await self.client.embeddings.create(model=self.embed_model, input=inputs)
return [cast(list[float], d.embedding) for d in response.data], response
- # For batched requests, we aggregate embeddings but only return the last response for usage
all_embeddings: list[list[float]] = []
- last_response: CreateEmbeddingResponse | None = None
+ raw_responses: list[CreateEmbeddingResponse] = []
for idx in range(0, len(inputs), self.embed_batch_size):
batch = inputs[idx : idx + self.embed_batch_size]
response = await self.client.embeddings.create(model=self.embed_model, input=batch)
all_embeddings.extend([cast(list[float], d.embedding) for d in response.data])
- last_response = response
+ raw_responses.append(response)
- return all_embeddings, last_response
+ return all_embeddings, raw_responses
async def transcribe(
self,
diff --git a/src/memu/llm/wrapper.py b/src/memu/llm/wrapper.py
index 175b78fc..85f41cd4 100644
--- a/src/memu/llm/wrapper.py
+++ b/src/memu/llm/wrapper.py
@@ -8,6 +8,8 @@
import uuid
from collections.abc import Callable, Mapping, Sequence
from dataclasses import dataclass, field
+from datetime import date, datetime
+from enum import Enum
from pathlib import Path
from typing import Any
@@ -602,6 +604,14 @@ def _get_attr_or_key(obj: Any, key: str) -> Any:
return None
+def _get_first_attr_or_key(obj: Any, *keys: str) -> Any:
+ for key in keys:
+ value = _get_attr_or_key(obj, key)
+ if value is not None:
+ return value
+ return None
+
+
def _extract_finish_reason(raw_response: Any) -> str | None:
"""Extract finish_reason from choices[0] if available."""
choices = _get_attr_or_key(raw_response, "choices")
@@ -623,29 +633,66 @@ def _get_usage_object(raw_response: Any) -> Any:
def _convert_to_dict(obj: Any) -> dict[str, Any] | None:
"""Convert object to dict using available methods."""
if hasattr(obj, "model_dump"):
- result: dict[str, Any] = obj.model_dump()
- return result
+ result = _model_dump(obj)
+ return _json_safe_dict(result)
if hasattr(obj, "__dict__"):
- return dict(obj.__dict__)
+ return _json_safe_dict(dict(obj.__dict__))
if isinstance(obj, dict):
- return obj
+ return _json_safe_dict(obj)
return None
+def _json_safe_dict(value: Any) -> dict[str, Any] | None:
+ if not isinstance(value, dict):
+ return None
+ return {str(key): _json_safe_value(item) for key, item in value.items()}
+
+
+def _json_safe_value(value: Any) -> Any:
+ if value is None or isinstance(value, (str, int, float, bool)):
+ return value
+ if isinstance(value, (datetime, date)):
+ return value.isoformat()
+ if isinstance(value, Enum):
+ return value.value
+ if hasattr(value, "model_dump"):
+ return _json_safe_value(_model_dump(value))
+ if isinstance(value, Mapping):
+ return {str(key): _json_safe_value(item) for key, item in value.items()}
+ if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+ return [_json_safe_value(item) for item in value]
+ return str(value)
+
+
+def _model_dump(value: Any) -> Any:
+ try:
+ return value.model_dump(mode="json")
+ except TypeError:
+ return value.model_dump()
+
+
def _extract_token_details(usage_obj: Any, usage_data: dict[str, Any]) -> None:
"""Extract token breakdown and cached tokens from usage object."""
- completion_tokens_details = _get_attr_or_key(usage_obj, "completion_tokens_details")
- if completion_tokens_details is not None:
- breakdown = _convert_to_dict(completion_tokens_details)
+ output_tokens_details = _get_first_attr_or_key(
+ usage_obj,
+ "output_tokens_details",
+ "completion_tokens_details",
+ )
+ if output_tokens_details is not None:
+ breakdown = _convert_to_dict(output_tokens_details)
if breakdown is not None:
usage_data["tokens_breakdown"] = breakdown
- reasoning_tokens = _get_attr_or_key(completion_tokens_details, "reasoning_tokens")
+ reasoning_tokens = _get_attr_or_key(output_tokens_details, "reasoning_tokens")
if reasoning_tokens is not None:
usage_data["reasoning_tokens"] = reasoning_tokens
- prompt_tokens_details = _get_attr_or_key(usage_obj, "prompt_tokens_details")
- if prompt_tokens_details is not None:
- cached_tokens = _get_attr_or_key(prompt_tokens_details, "cached_tokens")
+ input_tokens_details = _get_first_attr_or_key(
+ usage_obj,
+ "input_tokens_details",
+ "prompt_tokens_details",
+ )
+ if input_tokens_details is not None:
+ cached_tokens = _get_attr_or_key(input_tokens_details, "cached_tokens")
if cached_tokens is not None:
usage_data["cached_input_tokens"] = cached_tokens
@@ -665,6 +712,8 @@ def _extract_usage_from_raw_response(kind: str, raw_response: Any) -> dict[str,
if raw_response is None:
return usage_data
+ if _is_raw_response_batch(raw_response):
+ return _extract_usage_from_raw_response_batch(kind, raw_response)
try:
finish_reason = _extract_finish_reason(raw_response)
@@ -675,17 +724,15 @@ def _extract_usage_from_raw_response(kind: str, raw_response: Any) -> dict[str,
if usage_obj is None:
return usage_data
- # Map prompt_tokens -> input_tokens
- prompt_tokens = _get_attr_or_key(usage_obj, "prompt_tokens")
- if prompt_tokens is not None:
- usage_data["input_tokens"] = prompt_tokens
+ # Normalize OpenAI-compatible chat-completions and responses-style usage names.
+ input_tokens = _get_first_attr_or_key(usage_obj, "input_tokens", "prompt_tokens")
+ if input_tokens is not None:
+ usage_data["input_tokens"] = input_tokens
- # Map completion_tokens -> output_tokens
- completion_tokens = _get_attr_or_key(usage_obj, "completion_tokens")
- if completion_tokens is not None:
- usage_data["output_tokens"] = completion_tokens
+ output_tokens = _get_first_attr_or_key(usage_obj, "output_tokens", "completion_tokens")
+ if output_tokens is not None:
+ usage_data["output_tokens"] = output_tokens
- # total_tokens stays the same
total_tokens = _get_attr_or_key(usage_obj, "total_tokens")
if total_tokens is not None:
usage_data["total_tokens"] = total_tokens
@@ -703,6 +750,44 @@ def _extract_usage_from_raw_response(kind: str, raw_response: Any) -> dict[str,
return usage_data
+def _is_raw_response_batch(raw_response: Any) -> bool:
+ return isinstance(raw_response, Sequence) and not isinstance(raw_response, (str, bytes, bytearray, dict))
+
+
+def _extract_usage_from_raw_response_batch(kind: str, raw_responses: Sequence[Any]) -> dict[str, Any]:
+ aggregated: dict[str, Any] = {}
+ token_fields = (
+ "input_tokens",
+ "output_tokens",
+ "total_tokens",
+ "cached_input_tokens",
+ "reasoning_tokens",
+ )
+
+ for raw_response in raw_responses:
+ usage = _extract_usage_from_raw_response(kind, raw_response)
+ for field_name in token_fields:
+ value = usage.get(field_name)
+ if isinstance(value, int | float):
+ aggregated[field_name] = aggregated.get(field_name, 0) + value
+ if usage.get("finish_reason") is not None:
+ aggregated["finish_reason"] = usage["finish_reason"]
+ breakdown = usage.get("tokens_breakdown")
+ if isinstance(breakdown, dict):
+ _sum_token_breakdown(aggregated, breakdown)
+
+ return aggregated
+
+
+def _sum_token_breakdown(aggregated: dict[str, Any], breakdown: dict[str, Any]) -> None:
+ current = aggregated.setdefault("tokens_breakdown", {})
+ if not isinstance(current, dict):
+ return
+ for key, value in breakdown.items():
+ if isinstance(value, int | float):
+ current[key] = current.get(key, 0) + value
+
+
def _coerce_filter(
where: LLMCallFilter | Callable[[LLMCallContext, str | None], bool] | Mapping[str, Any] | None,
) -> LLMCallFilter | Callable[[LLMCallContext, str | None], bool] | None:
diff --git a/src/memu/utils/dedupe.py b/src/memu/utils/dedupe.py
new file mode 100644
index 00000000..aad6d988
--- /dev/null
+++ b/src/memu/utils/dedupe.py
@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+
+def compute_content_hash(summary: str, memory_type: str) -> str:
+ """
+ Generate a stable hash for memory deduplication.
+
+ The normalization intentionally matches the salience/reinforcement content
+ hash used by storage backends: lowercase, trim, and collapse whitespace.
+ """
+ normalized = " ".join(summary.lower().split())
+ content = f"{memory_type}:{normalized}"
+ return hashlib.sha256(content.encode()).hexdigest()[:16]
+
+
+def dedupe_resource_plans(resource_plans: Sequence[Mapping[str, Any]]) -> list[dict[str, Any]]:
+ """Remove duplicate extracted memory entries while preserving first-seen order."""
+ seen_categories: dict[str, list[str]] = {}
+ deduped_plans: list[dict[str, Any]] = []
+
+ for plan in resource_plans:
+ next_plan = dict(plan)
+ next_entries: list[tuple[str, str, list[str]]] = []
+ for raw_entry in plan.get("entries") or []:
+ normalized_entry = normalize_extracted_entry(raw_entry)
+ if normalized_entry is None:
+ continue
+ memory_type, content, categories = normalized_entry
+ key = compute_content_hash(content, memory_type)
+ if key in seen_categories:
+ seen_categories[key][:] = merge_category_names(seen_categories[key], categories)
+ continue
+ next_entries.append((memory_type, content, categories))
+ seen_categories[key] = categories
+ next_plan["entries"] = next_entries
+ deduped_plans.append(next_plan)
+
+ return deduped_plans
+
+
+def normalize_extracted_entry(raw_entry: Any) -> tuple[str, str, list[str]] | None:
+ if not isinstance(raw_entry, tuple) or len(raw_entry) != 3:
+ return None
+ raw_memory_type, raw_content, raw_categories = raw_entry
+ if not isinstance(raw_memory_type, str) or not isinstance(raw_content, str):
+ return None
+ content = raw_content.strip()
+ if not content:
+ return None
+ categories = [
+ category.strip()
+ for category in (raw_categories or [])
+ if isinstance(category, str) and category.strip()
+ ]
+ return raw_memory_type, content, merge_category_names([], categories)
+
+
+def merge_category_names(existing: Sequence[str], incoming: Sequence[str]) -> list[str]:
+ merged: list[str] = []
+ seen: set[str] = set()
+ for category in [*existing, *incoming]:
+ key = category.strip().lower()
+ if not key or key in seen:
+ continue
+ merged.append(category.strip())
+ seen.add(key)
+ return merged
+
+
+__all__ = [
+ "compute_content_hash",
+ "dedupe_resource_plans",
+ "merge_category_names",
+ "normalize_extracted_entry",
+]
diff --git a/src/memu/utils/filtering.py b/src/memu/utils/filtering.py
new file mode 100644
index 00000000..bf8aa809
--- /dev/null
+++ b/src/memu/utils/filtering.py
@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+
+SUPPORTED_FILTER_OPERATORS = frozenset({"in"})
+
+
+def split_filter_key(raw_key: Any) -> tuple[str, str | None]:
+ """Split and validate a filter key.
+
+ Supported filters are equality (`field`) and membership (`field__in`).
+ """
+
+ if not isinstance(raw_key, str) or not raw_key.strip():
+ msg = "Filter field must be a non-empty string"
+ raise ValueError(msg)
+
+ key = raw_key.strip()
+ field, separator, operator = key.partition("__")
+ if not field:
+ msg = "Filter field must be a non-empty string"
+ raise ValueError(msg)
+ if not separator:
+ return field, None
+ if operator not in SUPPORTED_FILTER_OPERATORS:
+ msg = f"Unsupported filter operator '__{operator}' for field '{field}'"
+ raise ValueError(msg)
+ return field, operator
+
+
+def normalize_filter_value(field: str, operator: str | None, expected: Any) -> Any:
+ """Normalize a filter value after its key has been validated."""
+
+ if operator != "in":
+ return expected
+ if isinstance(expected, str):
+ return expected
+ if isinstance(expected, Mapping):
+ msg = f"Filter '{field}__in' must be a string or an iterable of values"
+ raise ValueError(msg)
+ if not isinstance(expected, Iterable):
+ msg = f"Filter '{field}__in' must be a string or an iterable of values"
+ raise ValueError(msg)
+ return tuple(expected)
+
+
+def build_filter_key(field: str, operator: str | None) -> str:
+ return field if operator is None else f"{field}__{operator}"
+
+
+__all__ = [
+ "SUPPORTED_FILTER_OPERATORS",
+ "build_filter_key",
+ "normalize_filter_value",
+ "split_filter_key",
+]
diff --git a/src/memu/utils/retrieve.py b/src/memu/utils/retrieve.py
new file mode 100644
index 00000000..01126001
--- /dev/null
+++ b/src/memu/utils/retrieve.py
@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Literal, cast
+
+RetrieveMethod = Literal["rag", "llm"]
+RetrieveRanking = Literal["similarity", "salience"]
+
+
+def normalize_retrieve_method(method: str | None, *, default: str) -> RetrieveMethod:
+ """Resolve and validate the retrieval method for a single request."""
+
+ raw_method = default if method is None else method
+ if not isinstance(raw_method, str) or not raw_method.strip():
+ msg = "retrieve method must be 'rag' or 'llm'"
+ raise ValueError(msg)
+ normalized = raw_method.strip().lower()
+ if normalized not in {"rag", "llm"}:
+ msg = "retrieve method must be 'rag' or 'llm'"
+ raise ValueError(msg)
+ return cast(RetrieveMethod, normalized)
+
+
+def normalize_retrieve_ranking(ranking: str | None, *, default: str) -> RetrieveRanking:
+ """Resolve and validate the item ranking strategy for a single retrieve request."""
+
+ raw_ranking = default if ranking is None else ranking
+ if not isinstance(raw_ranking, str) or not raw_ranking.strip():
+ msg = "retrieve ranking must be 'similarity' or 'salience'"
+ raise ValueError(msg)
+ normalized = raw_ranking.strip().lower()
+ if normalized not in {"similarity", "salience"}:
+ msg = "retrieve ranking must be 'similarity' or 'salience'"
+ raise ValueError(msg)
+ return cast(RetrieveRanking, normalized)
+
+
+__all__ = ["RetrieveMethod", "RetrieveRanking", "normalize_retrieve_method", "normalize_retrieve_ranking"]
diff --git a/src/memu/utils/serialization.py b/src/memu/utils/serialization.py
new file mode 100644
index 00000000..717ee16a
--- /dev/null
+++ b/src/memu/utils/serialization.py
@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+
+def model_dump_without_embeddings(obj: BaseModel) -> dict[str, Any]:
+ """Dump a Pydantic model into a JSON-safe public response shape."""
+
+ return obj.model_dump(mode="json", exclude={"embedding"})
+
+
+__all__ = ["model_dump_without_embeddings"]
diff --git a/src/memu/utils/tool.py b/src/memu/utils/tool.py
index aa1c0067..5167f90b 100644
--- a/src/memu/utils/tool.py
+++ b/src/memu/utils/tool.py
@@ -48,7 +48,7 @@ def add_tool_call(item: MemoryItem, tool_call: ToolCallResult) -> None:
raise ValueError(msg)
tool_call.ensure_hash()
tool_calls = get_tool_calls(item)
- tool_calls.append(tool_call.model_dump())
+ tool_calls.append(tool_call.model_dump(mode="json"))
set_tool_calls(item, tool_calls)
diff --git a/src/memu/workflow/pipeline.py b/src/memu/workflow/pipeline.py
index ddb5a5af..63a5d907 100644
--- a/src/memu/workflow/pipeline.py
+++ b/src/memu/workflow/pipeline.py
@@ -8,6 +8,8 @@
from memu.workflow.step import WorkflowStep
+LLM_PROFILE_CONFIG_KEYS = ("llm_profile", "chat_llm_profile", "embed_llm_profile")
+
@dataclass
class PipelineRevision:
@@ -144,11 +146,17 @@ def _validate_steps(self, steps: list[WorkflowStep], *, initial_state_keys: set[
msg = f"Step '{step.step_id}' requests unavailable capabilities: {', '.join(sorted(unknown_caps))}"
raise ValueError(msg)
- if getattr(step, "config", None):
- profile_name = step.config.get("llm_profile")
- if profile_name and profile_name not in self.llm_profiles:
+ for profile_key in LLM_PROFILE_CONFIG_KEYS:
+ profile_name = (getattr(step, "config", None) or {}).get(profile_key)
+ if profile_name is None:
+ continue
+ if not isinstance(profile_name, str) or not profile_name.strip():
+ msg = f"Step '{step.step_id}' references invalid {profile_key}; profile name must be non-empty"
+ raise ValueError(msg)
+ profile_name = profile_name.strip()
+ if profile_name not in self.llm_profiles:
msg = (
- f"Step '{step.step_id}' references unknown llm_profile '{profile_name}'. "
+ f"Step '{step.step_id}' references unknown {profile_key} '{profile_name}'. "
f"Available profiles: {', '.join(sorted(self.llm_profiles))}"
)
raise ValueError(msg)
diff --git a/tests/test_client_wrapper.py b/tests/test_client_wrapper.py
index 4ada1107..999be91f 100644
--- a/tests/test_client_wrapper.py
+++ b/tests/test_client_wrapper.py
@@ -4,9 +4,46 @@
from __future__ import annotations
+import asyncio
from unittest.mock import MagicMock
+class FakeMemoryService:
+ def __init__(self) -> None:
+ self.retrieve_calls = []
+
+ async def retrieve(self, queries, where=None, ranking=None):
+ self.retrieve_calls.append({"queries": queries, "where": where, "ranking": ranking})
+ return {
+ "items": [
+ {"summary": "one"},
+ {"summary": "two"},
+ {"summary": "three"},
+ ]
+ }
+
+
+class AsyncCreateCompletions:
+ def __init__(self) -> None:
+ self.kwargs = {}
+
+ async def create(self, **kwargs):
+ self.kwargs = kwargs
+ return {"ok": True, "method": "create"}
+
+
+class AsyncAcreateCompletions:
+ def __init__(self) -> None:
+ self.kwargs = {}
+
+ async def acreate(self, **kwargs):
+ self.kwargs = kwargs
+ return {"ok": True, "method": "acreate"}
+
+ def create(self, **kwargs):
+ raise AssertionError("acreate should be preferred when present")
+
+
class TestMemuOpenAIWrapper:
"""Tests for OpenAI client wrapper."""
@@ -39,6 +76,27 @@ def test_extract_user_query_multiple_turns(self):
query = completions._extract_user_query(messages)
assert query == "What's my name?"
+ def test_extract_user_query_from_multiple_text_parts(self):
+ """Should concatenate text parts from multimodal user content."""
+ from memu.client.openai_wrapper import MemuChatCompletions
+
+ completions = MemuChatCompletions(MagicMock(), MagicMock(), {}, "salience", 5)
+
+ messages = [
+ {
+ "role": "user",
+ "content": [
+ {"type": "text", "text": "Remember that I like coffee."},
+ {"type": "image_url", "image_url": {"url": "https://example.test/photo.png"}},
+ {"type": "text", "text": "What should I order today?"},
+ {"type": "text", "text": 123},
+ ],
+ },
+ ]
+
+ query = completions._extract_user_query(messages)
+ assert query == "Remember that I like coffee.\nWhat should I order today?"
+
def test_inject_memories_into_existing_system(self):
"""Should append memories to existing system message."""
from memu.client.openai_wrapper import MemuChatCompletions
@@ -63,6 +121,46 @@ def test_inject_memories_into_existing_system(self):
assert "User is named Alex" in result[0]["content"]
assert result[0]["content"].startswith("You are helpful.")
+ def test_inject_memories_does_not_mutate_original_messages(self):
+ """Should leave caller-owned message dictionaries untouched."""
+ from memu.client.openai_wrapper import MemuChatCompletions
+
+ completions = MemuChatCompletions(MagicMock(), MagicMock(), {}, "salience", 5)
+ messages = [
+ {"role": "system", "content": "You are helpful."},
+ {"role": "user", "content": "Hi"},
+ ]
+
+ result = completions._inject_memories(messages, [{"summary": "User loves coffee"}])
+
+ assert messages == [
+ {"role": "system", "content": "You are helpful."},
+ {"role": "user", "content": "Hi"},
+ ]
+ assert result is not messages
+ assert result[0] is not messages[0]
+
+ def test_inject_memories_appends_to_system_content_parts(self):
+ """Should support system messages whose content is a list of text parts."""
+ from memu.client.openai_wrapper import MemuChatCompletions
+
+ completions = MemuChatCompletions(MagicMock(), MagicMock(), {}, "salience", 5)
+ original_part = {"type": "text", "text": "You are helpful."}
+ messages = [
+ {"role": "system", "content": [original_part]},
+ {"role": "user", "content": "Hi"},
+ ]
+
+ result = completions._inject_memories(messages, [{"summary": "User loves coffee"}])
+
+ assert messages[0]["content"] == [original_part]
+ assert result[0]["content"] is not messages[0]["content"]
+ assert result[0]["content"][0] == original_part
+ assert result[0]["content"][0] is not original_part
+ assert result[0]["content"][1]["type"] == "text"
+ assert "" in result[0]["content"][1]["text"]
+ assert "User loves coffee" in result[0]["content"][1]["text"]
+
def test_inject_memories_creates_system_message(self):
"""Should create system message if none exists."""
from memu.client.openai_wrapper import MemuChatCompletions
@@ -114,6 +212,109 @@ def test_wrap_openai_convenience_function(self):
assert wrapped._ranking == "salience"
assert wrapped._top_k == 3
+ def test_wrap_openai_does_not_mutate_user_data(self):
+ """Should not mutate caller-owned user_data dictionaries."""
+ from memu.client import wrap_openai
+
+ mock_client = MagicMock()
+ mock_client.chat.completions = MagicMock()
+ user_data = {"user_id": "original", "team_id": "team1"}
+
+ wrapped = wrap_openai(
+ mock_client,
+ MagicMock(),
+ user_data=user_data,
+ user_id="override",
+ agent_id="agent1",
+ )
+
+ assert user_data == {"user_id": "original", "team_id": "team1"}
+ assert wrapped._user_data == {
+ "user_id": "override",
+ "team_id": "team1",
+ "agent_id": "agent1",
+ }
+
+ def test_wrapper_scope_is_stable_after_external_user_data_mutation(self):
+ """Should keep the wrapper's retrieve scope stable after construction."""
+ from memu.client import wrap_openai
+
+ mock_client = MagicMock()
+ mock_client.chat.completions = MagicMock()
+ service = FakeMemoryService()
+ user_data = {"user_id": "u1"}
+ wrapped = wrap_openai(mock_client, service, user_data=user_data)
+ user_data["user_id"] = "u2"
+
+ asyncio.run(wrapped.chat.completions._retrieve_memories("what do I like?"))
+
+ assert service.retrieve_calls[0]["where"] == {"user_id": "u1"}
+
+ def test_retrieve_memories_respects_top_k_limit(self):
+ """Should inject at most top_k retrieved memories."""
+ from memu.client.openai_wrapper import MemuChatCompletions
+
+ service = FakeMemoryService()
+ completions = MemuChatCompletions(MagicMock(), service, {}, "salience", 2)
+
+ memories = asyncio.run(completions._retrieve_memories("what do I like?"))
+
+ assert [memory["summary"] for memory in memories] == ["one", "two"]
+ assert service.retrieve_calls[0]["ranking"] == "salience"
+
+ def test_acreate_awaits_async_create_result(self):
+ """Should await AsyncOpenAI-style create() coroutine results."""
+ from memu.client.openai_wrapper import MemuChatCompletions
+
+ original = AsyncCreateCompletions()
+ completions = MemuChatCompletions(original, FakeMemoryService(), {}, "salience", 1)
+
+ result = asyncio.run(completions.acreate(messages=[{"role": "user", "content": "What do I like?"}]))
+
+ assert result == {"ok": True, "method": "create"}
+ assert "" in original.kwargs["messages"][0]["content"]
+ assert "one" in original.kwargs["messages"][0]["content"]
+
+ def test_acreate_prefers_legacy_acreate_when_present(self):
+ """Should keep compatibility with clients exposing acreate()."""
+ from memu.client.openai_wrapper import MemuChatCompletions
+
+ original = AsyncAcreateCompletions()
+ completions = MemuChatCompletions(original, FakeMemoryService(), {}, "salience", 1)
+
+ result = asyncio.run(completions.acreate(messages=[{"role": "user", "content": "What do I like?"}]))
+
+ assert result == {"ok": True, "method": "acreate"}
+ assert "" in original.kwargs["messages"][0]["content"]
+
+ def test_wrapper_rejects_unknown_ranking(self):
+ """Should reject invalid ranking at the integration boundary."""
+ from memu.client import wrap_openai
+
+ mock_client = MagicMock()
+ mock_client.chat.completions = MagicMock()
+
+ try:
+ wrap_openai(mock_client, MagicMock(), ranking="random")
+ except ValueError as exc:
+ assert "retrieve ranking must be 'similarity' or 'salience'" in str(exc)
+ else:
+ raise AssertionError("wrap_openai should reject unknown ranking")
+
+ def test_wrapper_rejects_non_positive_top_k(self):
+ """Should reject invalid top_k at the integration boundary."""
+ from memu.client import wrap_openai
+
+ mock_client = MagicMock()
+ mock_client.chat.completions = MagicMock()
+
+ try:
+ wrap_openai(mock_client, MagicMock(), top_k=0)
+ except ValueError as exc:
+ assert "top_k must be a positive integer" in str(exc)
+ else:
+ raise AssertionError("wrap_openai should reject non-positive top_k")
+
def test_wrapper_proxies_other_attributes(self):
"""Should proxy non-chat attributes to original client."""
from memu.client import MemuOpenAIWrapper
diff --git a/tests/test_crud_contracts.py b/tests/test_crud_contracts.py
new file mode 100644
index 00000000..fe00411b
--- /dev/null
+++ b/tests/test_crud_contracts.py
@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_manual_create_memory_item_passes_source_less_resource_id() -> None:
+ for relative_path in ["src/memu/app/crud.py", "src/memu/app/patch.py"]:
+ source = (ROOT / relative_path).read_text(encoding="utf-8")
+ function_source = _async_function_source(source, "_patch_create_memory_item")
+ create_call = _first_method_call(function_source, "create_item")
+ keyword_values = {keyword.arg: keyword.value for keyword in create_call.keywords}
+
+ assert "resource_id" in keyword_values, f"{relative_path} must pass resource_id explicitly"
+ assert isinstance(keyword_values["resource_id"], ast.Constant)
+ assert keyword_values["resource_id"].value is None
+
+
+def test_memory_item_repo_create_item_accepts_source_less_records() -> None:
+ checked_paths = [
+ "src/memu/database/repositories/memory_item.py",
+ "src/memu/database/inmemory/repositories/memory_item_repo.py",
+ "src/memu/database/sqlite/repositories/memory_item_repo.py",
+ "src/memu/database/postgres/repositories/memory_item_repo.py",
+ ]
+
+ for relative_path in checked_paths:
+ source = (ROOT / relative_path).read_text(encoding="utf-8")
+ create_fn = _function_node(source, "create_item")
+ resource_arg = next(arg for arg in create_fn.args.kwonlyargs if arg.arg == "resource_id")
+ resource_default = _kwonly_default(create_fn, "resource_id")
+
+ assert ast.unparse(resource_arg.annotation) == "str | None"
+ assert isinstance(resource_default, ast.Constant)
+ assert resource_default.value is None
+
+
+def test_update_memory_item_preserves_categories_when_categories_are_omitted() -> None:
+ for relative_path in ["src/memu/app/crud.py", "src/memu/app/patch.py"]:
+ source = (ROOT / relative_path).read_text(encoding="utf-8")
+ function_source = _async_function_source(source, "_patch_update_memory_item")
+
+ assert 'new_cat_names = memory_payload["categories"]' in function_source
+ assert "if new_cat_names is None:" in function_source
+ assert "mapped_new_cat_ids = mapped_old_cat_ids" in function_source
+ assert "else:" in function_source
+ assert "mapped_new_cat_ids = self._map_category_names_to_ids(new_cat_names, ctx)" in function_source
+
+
+def test_manual_memory_item_inputs_are_normalized_before_workflow() -> None:
+ for relative_path in ["src/memu/app/crud.py", "src/memu/app/patch.py"]:
+ source = (ROOT / relative_path).read_text(encoding="utf-8")
+ create_source = _async_function_source(source, "create_memory_item")
+ update_source = _async_function_source(source, "update_memory_item")
+ delete_source = _async_function_source(source, "delete_memory_item")
+ memory_type_helper = _function_source(source, "_normalize_memory_type")
+ categories_helper = _function_source(source, "_normalize_memory_categories")
+ string_helper = _function_source(source, "_normalize_non_empty_string")
+
+ assert "memory_type = _normalize_memory_type(memory_type)" in create_source
+ assert 'memory_content = _normalize_memory_content(memory_content, field_name="memory_content")' in create_source
+ assert (
+ 'memory_categories = _normalize_memory_categories(memory_categories, field_name="memory_categories")'
+ in create_source
+ )
+ assert "memory_id = _normalize_memory_id(memory_id)" in update_source
+ assert "memory_type = _normalize_memory_type(memory_type)" in update_source
+ assert "memory_id = _normalize_memory_id(memory_id)" in delete_source
+ assert "if memory_content is not None:" in update_source
+ assert 'memory_content = _normalize_memory_content(memory_content, field_name="memory_content")' in update_source
+ assert "if memory_categories is not None:" in update_source
+ assert (
+ 'memory_categories = _normalize_memory_categories(memory_categories, field_name="memory_categories")'
+ in update_source
+ )
+ assert '_normalize_non_empty_string(value, field_name="memory_type")' in memory_type_helper
+ assert "memory_type not in get_args(MemoryType)" in memory_type_helper
+ assert "cast(MemoryType, memory_type)" in memory_type_helper
+ assert "not isinstance(value, list)" in categories_helper
+ assert "not isinstance(value, str) or not value.strip()" in string_helper
+ assert "return value.strip()" in string_helper
+
+
+def test_clear_memory_clears_category_item_relations_before_records() -> None:
+ source = (ROOT / "src/memu/app/crud.py").read_text(encoding="utf-8")
+ workflow_fn = _function_node(source, "_build_clear_memory_workflow")
+ step_ids = _workflow_step_ids(workflow_fn)
+
+ assert "clear_category_item_relations" in step_ids
+ assert step_ids.index("clear_category_item_relations") < step_ids.index("clear_memory_categories")
+ assert step_ids.index("clear_category_item_relations") < step_ids.index("clear_memory_items")
+ assert step_ids.index("clear_category_item_relations") < step_ids.index("clear_memory_resources")
+
+ clear_fn_source = _function_source(source, "_crud_clear_category_item_relations")
+ response_fn_source = _function_source(source, "_crud_build_clear_memory_response")
+
+ assert "store.category_item_repo.clear_relations(where_filters)" in clear_fn_source
+ assert '"deleted_relations"' in response_fn_source
+
+
+def test_category_item_repo_contract_exposes_scoped_clear_relations() -> None:
+ checked_paths = [
+ "src/memu/database/repositories/category_item.py",
+ "src/memu/database/inmemory/repositories/category_item_repo.py",
+ "src/memu/database/sqlite/repositories/category_item_repo.py",
+ "src/memu/database/postgres/repositories/category_item_repo.py",
+ ]
+
+ for relative_path in checked_paths:
+ source = (ROOT / relative_path).read_text(encoding="utf-8")
+ clear_fn = _function_node(source, "clear_relations")
+ arg_names = [arg.arg for arg in clear_fn.args.args]
+
+ assert "where" in arg_names
+ assert "list[CategoryItem]" in ast.unparse(clear_fn.returns)
+
+
+def test_delete_memory_item_clears_relations_before_item_delete() -> None:
+ for relative_path in ["src/memu/app/crud.py", "src/memu/app/patch.py"]:
+ source = (ROOT / relative_path).read_text(encoding="utf-8")
+ delete_fn_source = _async_function_source(source, "_patch_delete_memory_item")
+
+ clear_idx = delete_fn_source.index('store.category_item_repo.clear_relations({"item_id": memory_id})')
+ delete_idx = delete_fn_source.index("store.memory_item_repo.delete_item(memory_id)")
+
+ assert clear_idx < delete_idx
+ assert "get_item_categories(memory_id)" not in delete_fn_source
+
+
+def test_postgres_delete_item_removes_cache_entry() -> None:
+ source = (ROOT / "src/memu/database/postgres/repositories/memory_item_repo.py").read_text(encoding="utf-8")
+ delete_fn_source = _function_source(source, "delete_item")
+
+ assert "self.items.pop(item_id, None)" in delete_fn_source
+
+
+def test_inmemory_scoped_clear_preserves_shared_state_dicts() -> None:
+ checked = [
+ ("src/memu/database/inmemory/repositories/memory_item_repo.py", "clear_items", "items"),
+ ("src/memu/database/inmemory/repositories/resource_repo.py", "clear_resources", "resources"),
+ ("src/memu/database/inmemory/repositories/memory_category_repo.py", "clear_categories", "categories"),
+ ]
+
+ for relative_path, function_name, attribute_name in checked:
+ source = (ROOT / relative_path).read_text(encoding="utf-8")
+ function = _function_node(source, function_name)
+ function_source = _function_source(source, function_name)
+
+ assert not _assigns_to_self_attribute(function, attribute_name)
+ assert f"self.{attribute_name}.pop(" in function_source
+
+
+def _async_function_source(source: str, name: str) -> str:
+ module = ast.parse(source)
+ for node in ast.walk(module):
+ if isinstance(node, ast.AsyncFunctionDef) and node.name == name:
+ segment = ast.get_source_segment(source, node)
+ assert segment is not None
+ return segment
+ raise AssertionError(f"async function {name!r} not found")
+
+
+def _function_source(source: str, name: str) -> str:
+ module = ast.parse(source)
+ for node in ast.walk(module):
+ if isinstance(node, ast.FunctionDef) and node.name == name:
+ segment = ast.get_source_segment(source, node)
+ assert segment is not None
+ return segment
+ raise AssertionError(f"function {name!r} not found")
+
+
+def _function_node(source: str, name: str) -> ast.FunctionDef:
+ module = ast.parse(source)
+ for node in ast.walk(module):
+ if isinstance(node, ast.FunctionDef) and node.name == name:
+ return node
+ raise AssertionError(f"function {name!r} not found")
+
+
+def _first_method_call(source: str, method_name: str) -> ast.Call:
+ module = ast.parse(source)
+ for node in ast.walk(module):
+ if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute) and node.func.attr == method_name:
+ return node
+ raise AssertionError(f"method call {method_name!r} not found")
+
+
+def _kwonly_default(function: ast.FunctionDef, arg_name: str) -> ast.expr | None:
+ for arg, default in zip(function.args.kwonlyargs, function.args.kw_defaults, strict=True):
+ if arg.arg == arg_name:
+ return default
+ raise AssertionError(f"keyword-only argument {arg_name!r} not found")
+
+
+def _workflow_step_ids(function: ast.FunctionDef) -> list[str]:
+ step_ids: list[str] = []
+
+ class Visitor(ast.NodeVisitor):
+ def visit_Call(self, node: ast.Call) -> None:
+ if isinstance(node.func, ast.Name) and node.func.id == "WorkflowStep":
+ for keyword in node.keywords:
+ if keyword.arg == "step_id":
+ assert isinstance(keyword.value, ast.Constant)
+ assert isinstance(keyword.value.value, str)
+ step_ids.append(keyword.value.value)
+ self.generic_visit(node)
+
+ Visitor().visit(function)
+ return step_ids
+
+
+def _assigns_to_self_attribute(function: ast.FunctionDef, attribute_name: str) -> bool:
+ for node in ast.walk(function):
+ targets: list[ast.expr] = []
+ if isinstance(node, ast.Assign):
+ targets.extend(node.targets)
+ elif isinstance(node, ast.AnnAssign):
+ targets.append(node.target)
+ elif isinstance(node, ast.AugAssign):
+ targets.append(node.target)
+
+ for target in targets:
+ if not isinstance(target, ast.Attribute) or target.attr != attribute_name:
+ continue
+ if isinstance(target.value, ast.Name) and target.value.id == "self":
+ return True
+ return False
diff --git a/tests/test_inmemory.py b/tests/test_inmemory.py
index 250f15a2..bc9c3314 100644
--- a/tests/test_inmemory.py
+++ b/tests/test_inmemory.py
@@ -1,14 +1,33 @@
+#!/usr/bin/env python3
+"""Opt-in live LLM smoke test for the in-memory backend."""
+
+from __future__ import annotations
+
+import asyncio
import os
+import sys
+from pathlib import Path
+from typing import Any
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+RUN_LIVE_LLM_TESTS_ENV = "MEMU_RUN_LIVE_LLM_TESTS"
+
+# Add src to sys.path before importing memu from a source checkout.
+src_path = str(PROJECT_ROOT / "src")
+if src_path not in sys.path:
+ sys.path.insert(0, src_path)
-from memu.app import MemoryService
+async def run_inmemory_workflow() -> None:
+ """Run the in-memory memorize/retrieve smoke workflow against a real LLM."""
+ from memu import MemoryService
-async def main():
- """Test with in-memory storage (default)."""
api_key = os.environ.get("OPENAI_API_KEY")
- # dashscope_api_key = os.environ.get("DASHSCOPE_API_KEY")
- # voyage_api_key = os.environ.get("VOYAGE_API_KEY")
- file_path = os.path.abspath("example/example_conversation.json")
+ if not api_key:
+ msg = "OPENAI_API_KEY is required for the in-memory live LLM workflow"
+ raise RuntimeError(msg)
+
+ file_path = Path(__file__).resolve().parent / "example" / "example_conversation.json"
print("\n" + "=" * 60)
print("[INMEMORY] Starting test...")
@@ -16,74 +35,69 @@ async def main():
service = MemoryService(
llm_profiles={"default": {"api_key": api_key}},
- # llm_profiles={
- # "default": {
- # "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
- # "api_key": dashscope_api_key,
- # "chat_model": "qwen3-max",
- # "client_backend": "sdk"
- # },
- # "embedding": {
- # "base_url": "https://api.voyageai.com/v1",
- # "api_key": voyage_api_key,
- # "embed_model": "voyage-3.5-lite"
- # }
- # },
database_config={
"metadata_store": {"provider": "inmemory"},
},
retrieve_config={"method": "rag"},
)
- # Memorize
print("\n[INMEMORY] Memorizing...")
- memory = await service.memorize(resource_url=file_path, modality="conversation", user={"user_id": "123"})
+ memory = await service.memorize(resource_url=str(file_path), modality="conversation", user={"user_id": "123"})
for cat in memory.get("categories", []):
print(f" - {cat.get('name')}: {(cat.get('summary') or '')[:80]}...")
- queries = [
- {"role": "user", "content": {"text": "Tell me about preferences"}},
- {"role": "assistant", "content": {"text": "Sure, I'll tell you about their preferences"}},
- {
- "role": "user",
- "content": {"text": "What are they"},
- }, # This is the query that will be used to retrieve the memory, the context will be used for query rewriting
- ]
+ queries = _sample_queries()
- # RAG-based retrieval
print("\n[INMEMORY] RETRIEVED - RAG")
service.retrieve_config.method = "rag"
result_rag = await service.retrieve(queries=queries, where={"user_id": "123"})
- print(" Categories:")
- for cat in result_rag.get("categories", [])[:3]:
- print(f" - {cat.get('name')}: {(cat.get('summary') or cat.get('description', ''))[:80]}...")
- print(" Items:")
- for item in result_rag.get("items", [])[:3]:
- print(f" - [{item.get('memory_type')}] {item.get('summary', '')[:100]}...")
- if result_rag.get("resources"):
- print(" Resources:")
- for res in result_rag.get("resources", [])[:3]:
- print(f" - [{res.get('modality')}] {res.get('url', '')[:80]}...")
+ _print_results(result_rag)
- # LLM-based retrieval
print("\n[INMEMORY] RETRIEVED - LLM")
service.retrieve_config.method = "llm"
result_llm = await service.retrieve(queries=queries, where={"user_id": "123"})
+ _print_results(result_llm)
+
+ print("\n[INMEMORY] Test completed!")
+
+
+async def test_inmemory_full_workflow() -> None:
+ """Opt-in pytest integration check for the in-memory backend and a real LLM."""
+ import pytest
+
+ if os.environ.get(RUN_LIVE_LLM_TESTS_ENV) != "1":
+ pytest.skip(f"Set {RUN_LIVE_LLM_TESTS_ENV}=1 to run live LLM storage workflows")
+ if not os.environ.get("OPENAI_API_KEY"):
+ pytest.skip("OPENAI_API_KEY is required for live LLM storage workflows")
+
+ await run_inmemory_workflow()
+
+
+def _sample_queries() -> list[dict[str, dict[str, str] | str]]:
+ return [
+ {"role": "user", "content": {"text": "Tell me about preferences"}},
+ {"role": "assistant", "content": {"text": "Sure, I'll tell you about their preferences"}},
+ {"role": "user", "content": {"text": "What are they"}},
+ ]
+
+
+def _print_results(result: dict[str, Any]) -> None:
print(" Categories:")
- for cat in result_llm.get("categories", [])[:3]:
+ for cat in result.get("categories", [])[:3]:
print(f" - {cat.get('name')}: {(cat.get('summary') or cat.get('description', ''))[:80]}...")
print(" Items:")
- for item in result_llm.get("items", [])[:3]:
+ for item in result.get("items", [])[:3]:
print(f" - [{item.get('memory_type')}] {item.get('summary', '')[:100]}...")
- if result_llm.get("resources"):
+ if result.get("resources"):
print(" Resources:")
- for res in result_llm.get("resources", [])[:3]:
+ for res in result.get("resources", [])[:3]:
print(f" - [{res.get('modality')}] {res.get('url', '')[:80]}...")
- print("\n[INMEMORY] Test completed!")
+def main() -> int:
+ asyncio.run(run_inmemory_workflow())
+ return 0
-if __name__ == "__main__":
- import asyncio
- asyncio.run(main())
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/tests/test_langgraph_optional.py b/tests/test_langgraph_optional.py
new file mode 100644
index 00000000..7edcc99b
--- /dev/null
+++ b/tests/test_langgraph_optional.py
@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from pydantic import ValidationError
+
+from memu.integrations import langgraph
+
+
+def test_langgraph_module_imports_without_optional_dependencies() -> None:
+ assert langgraph.MemULangGraphTools.__name__ == "MemULangGraphTools"
+
+
+def test_langgraph_missing_dependency_error_is_actionable() -> None:
+ if langgraph._LANGGRAPH_IMPORT_ERROR is None:
+ return
+
+ try:
+ langgraph.MemULangGraphTools(object())
+ except ImportError as exc:
+ message = str(exc)
+ assert "memu-py[langgraph]" in message
+ assert "uv sync --extra langgraph" in message
+ else:
+ raise AssertionError("missing LangGraph dependencies should raise an actionable ImportError")
+
+
+def test_langgraph_scope_keeps_explicit_user_id_authoritative() -> None:
+ metadata = {"user_id": "metadata-user", "team_id": "team1"}
+
+ scope = langgraph._scope_with_user(" explicit-user ", metadata)
+
+ assert scope == {"user_id": "explicit-user", "team_id": "team1"}
+ assert metadata == {"user_id": "metadata-user", "team_id": "team1"}
+
+
+def test_langgraph_input_schemas_trim_and_validate_bounds() -> None:
+ save_input = langgraph.SaveRecallInput(content=" remember this ", user_id=" user1 ")
+ search_input = langgraph.SearchRecallInput(query=" what changed? ", user_id=" user1 ", limit=3)
+
+ assert save_input.content == "remember this"
+ assert save_input.user_id == "user1"
+ assert search_input.query == "what changed?"
+ assert search_input.user_id == "user1"
+ assert search_input.limit == 3
+
+ for kwargs in (
+ {"query": "", "user_id": "user1"},
+ {"query": "x", "user_id": ""},
+ {"query": "x", "user_id": "user1", "limit": 0},
+ {"query": "x", "user_id": "user1", "min_relevance_score": 1.1},
+ ):
+ try:
+ langgraph.SearchRecallInput(**kwargs)
+ except ValidationError:
+ pass
+ else:
+ raise AssertionError(f"SearchRecallInput should reject invalid values: {kwargs}")
diff --git a/tests/test_lazyllm.py b/tests/test_lazyllm.py
index 6e107414..fbdd2fd9 100644
--- a/tests/test_lazyllm.py
+++ b/tests/test_lazyllm.py
@@ -1,30 +1,44 @@
#!/usr/bin/env python3
"""
-Quick test script to verify LazyLLM backend configuration and basic functionality.
+Opt-in LazyLLM integration smoke test.
Usage:
export MEMU_QWEN_API_KEY=your_api_key
- python examples/test_lazyllm.py
+ export MEMU_RUN_LAZYLLM_TESTS=1
+ uv run python -m pytest tests/test_lazyllm.py
+
+Manual run:
+ export MEMU_QWEN_API_KEY=your_api_key
+ python tests/test_lazyllm.py
"""
+from __future__ import annotations
+
import asyncio
import os
import sys
+from pathlib import Path
-# Add src to sys.path
-src_path = os.path.abspath("src")
-sys.path.insert(0, src_path)
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+RUN_LAZYLLM_TESTS_ENV = "MEMU_RUN_LAZYLLM_TESTS"
+
+# Add src to sys.path before importing memu from a source checkout.
+src_path = str(PROJECT_ROOT / "src")
+if src_path not in sys.path:
+ sys.path.insert(0, src_path)
from memu.llm.lazyllm_client import LazyLLMClient # noqa: E402
-async def test_lazyllm_client():
- """Test LazyLLMClient with basic operations."""
+async def run_lazyllm_workflow() -> bool:
+ """Run the LazyLLM-backed chat/embed/vision smoke workflow."""
+ if not os.environ.get("MEMU_QWEN_API_KEY"):
+ msg = "MEMU_QWEN_API_KEY is required for the LazyLLM integration workflow"
+ raise RuntimeError(msg)
print("LazyLLM Backend Test")
print("=" * 60)
- # Get API key from environment
try:
client = LazyLLMClient(
llm_source="qwen",
@@ -36,56 +50,67 @@ async def test_lazyllm_client():
embed_model="text-embedding-v3",
stt_model="qwen-audio-turbo",
)
- print("✓ LazyLLMClient initialized successfully")
- except Exception as e:
- print(f"❌ Failed to initialize LazyLLMClient: {e}")
+ print("[OK] LazyLLMClient initialized successfully")
+ except Exception as exc:
+ print(f"[ERROR] Failed to initialize LazyLLMClient: {exc}")
return False
- # Test 1: Summarization
- print("\n[Test 1] Testing summarization...")
+ print("\n[Test 1] Testing chat...")
try:
- test_text = "这是一段关于Python编程的文本。Python是一种高级编程语言，具有简单易学的语法。它被广泛用于数据分析、机器学习和Web开发。" # noqa: RUF001
+ test_text = (
+ "Python is widely used for data analysis, machine learning, and web services. "
+ "Summarize this short technical note in one sentence."
+ )
result = await client.chat(test_text)
- print("✓ Summarization successful")
+ print("[OK] Chat successful")
print(f" Result: {result[:100]}...")
- except Exception as e:
- print(f"❌ Summarization failed: {e}")
- import traceback
-
- traceback.print_exc()
+ except Exception as exc:
+ print(f"[ERROR] Chat failed: {exc}")
+ return False
- # Test 2: Embedding
print("\n[Test 2] Testing embedding...")
try:
test_texts = ["Hello world", "How are you", "Nice to meet you"]
embeddings = await client.embed(test_texts)
- print("✓ Embedding successful")
+ print("[OK] Embedding successful")
print(f" Generated {len(embeddings)} embeddings")
if embeddings and embeddings[0]:
print(f" Embedding dimension: {len(embeddings[0])}")
- except Exception as e:
- print(f"❌ Embedding failed: {e}")
- import traceback
-
- traceback.print_exc()
+ except Exception as exc:
+ print(f"[ERROR] Embedding failed: {exc}")
+ return False
- # Test 3: Vision (requires image file)
print("\n[Test 3] Testing vision...")
- test_image_path = "examples/resources/images/image1.png"
- if os.path.exists(test_image_path):
+ test_image_path = PROJECT_ROOT / "examples" / "resources" / "images" / "image1.png"
+ if test_image_path.exists():
try:
- result, _ = await client.vision(prompt="描述这张图片的内容", image_path=test_image_path)
- print("✓ Vision successful")
+ result, _ = await client.vision(prompt="Describe the image content.", image_path=str(test_image_path))
+ print("[OK] Vision successful")
print(f" Result: {result[:100]}...")
- except Exception as e:
- print(f"❌ Vision failed: {e}")
- import traceback
-
- traceback.print_exc()
+ except Exception as exc:
+ print(f"[ERROR] Vision failed: {exc}")
+ return False
else:
- print(f"⚠ Skipped: Test image not found at {test_image_path}")
+ print(f"[WARN] Skipped vision check: test image not found at {test_image_path}")
+
+ return True
+
+
+async def test_lazyllm_client() -> None:
+ """Opt-in pytest integration check for LazyLLM-backed model calls."""
+ import pytest
+
+ if os.environ.get(RUN_LAZYLLM_TESTS_ENV) != "1":
+ pytest.skip(f"Set {RUN_LAZYLLM_TESTS_ENV}=1 to run the LazyLLM integration workflow")
+ if not os.environ.get("MEMU_QWEN_API_KEY"):
+ pytest.skip("MEMU_QWEN_API_KEY is required for the LazyLLM integration workflow")
+
+ assert await run_lazyllm_workflow()
+
+
+def main() -> int:
+ return 0 if asyncio.run(run_lazyllm_workflow()) else 1
if __name__ == "__main__":
- success = asyncio.run(test_lazyllm_client())
- sys.exit(0 if success else 1)
+ raise SystemExit(main())
diff --git a/tests/test_lazyllm_optional.py b/tests/test_lazyllm_optional.py
new file mode 100644
index 00000000..410b164d
--- /dev/null
+++ b/tests/test_lazyllm_optional.py
@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from memu.llm import lazyllm_client
+
+
+def test_lazyllm_client_module_imports_without_optional_dependency() -> None:
+ assert lazyllm_client.LazyLLMClient.__name__ == "LazyLLMClient"
+
+
+def test_lazyllm_missing_dependency_error_is_actionable() -> None:
+ if lazyllm_client._LAZYLLM_IMPORT_ERROR is None:
+ return
+
+ try:
+ lazyllm_client.LazyLLMClient()
+ except ImportError as exc:
+ message = str(exc)
+ assert "memu-py[lazyllm]" in message
+ assert "uv sync --extra lazyllm" in message
+ else:
+ raise AssertionError("missing LazyLLM dependency should raise an actionable ImportError")
diff --git a/tests/test_llm_observability.py b/tests/test_llm_observability.py
new file mode 100644
index 00000000..f61661b9
--- /dev/null
+++ b/tests/test_llm_observability.py
@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import ast
+import json
+from pathlib import Path
+
+from memu.llm.wrapper import _extract_usage_from_raw_response
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_llm_usage_aggregates_batched_embedding_raw_responses() -> None:
+ raw_responses = [
+ {
+ "usage": {
+ "prompt_tokens": 3,
+ "total_tokens": 3,
+ "prompt_tokens_details": {"cached_tokens": 1},
+ }
+ },
+ {
+ "usage": {
+ "prompt_tokens": 5,
+ "total_tokens": 5,
+ "prompt_tokens_details": {"cached_tokens": 2},
+ }
+ },
+ ]
+
+ usage = _extract_usage_from_raw_response(kind="embed", raw_response=raw_responses)
+
+ assert usage["input_tokens"] == 8
+ assert usage["total_tokens"] == 8
+ assert usage["cached_input_tokens"] == 3
+ json.dumps(usage)
+
+
+def test_openai_sdk_batched_embed_returns_all_raw_responses_for_usage() -> None:
+ source = (ROOT / "src/memu/llm/openai_sdk.py").read_text(encoding="utf-8")
+ function_source = _function_source(source, "embed")
+
+ assert "raw_responses.append(response)" in function_source
+ assert "return all_embeddings, raw_responses" in function_source
+ assert "last_response" not in function_source
+
+
+def _function_source(source: str, name: str) -> str:
+ module = ast.parse(source)
+ for node in ast.walk(module):
+ if isinstance(node, ast.AsyncFunctionDef | ast.FunctionDef) and node.name == name:
+ segment = ast.get_source_segment(source, node)
+ assert segment is not None
+ return segment
+ raise AssertionError(f"function {name!r} not found")
diff --git a/tests/test_memorize_dedupe.py b/tests/test_memorize_dedupe.py
new file mode 100644
index 00000000..c4607c1f
--- /dev/null
+++ b/tests/test_memorize_dedupe.py
@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from memu.utils.dedupe import dedupe_resource_plans
+
+
+def test_dedupe_resource_plans_removes_duplicate_entries_across_segments() -> None:
+ plans = [
+ {
+ "resource_url": "conversation_#segment_0.json",
+ "entries": [
+ ("profile", "User likes coffee.", ["preferences"]),
+ ("knowledge", "User works in AI.", ["work_life"]),
+ ],
+ },
+ {
+ "resource_url": "conversation_#segment_1.json",
+ "entries": [
+ ("profile", " user likes coffee. ", ["preferences", "habits"]),
+ ("event", "User joined a hackathon.", ["experiences"]),
+ ],
+ },
+ ]
+
+ deduped = dedupe_resource_plans(plans)
+
+ assert [entry[1] for plan in deduped for entry in plan["entries"]] == [
+ "User likes coffee.",
+ "User works in AI.",
+ "User joined a hackathon.",
+ ]
+ assert deduped[0]["entries"][0][2] == ["preferences", "habits"]
+ assert deduped[1]["entries"] == [("event", "User joined a hackathon.", ["experiences"])]
+
+
+def test_dedupe_resource_plans_keeps_same_content_for_different_memory_types() -> None:
+ plans = [
+ {
+ "resource_url": "notes.txt",
+ "entries": [
+ ("profile", "Uses Python daily.", ["preferences"]),
+ ("skill", "Uses Python daily.", ["knowledge"]),
+ ],
+ }
+ ]
+
+ deduped = dedupe_resource_plans(plans)
+
+ assert deduped[0]["entries"] == [
+ ("profile", "Uses Python daily.", ["preferences"]),
+ ("skill", "Uses Python daily.", ["knowledge"]),
+ ]
+
+
+def test_dedupe_resource_plans_drops_empty_and_malformed_entries() -> None:
+ plans = [
+ {
+ "resource_url": "notes.txt",
+ "entries": [
+ ("profile", " ", ["preferences"]),
+ ("profile", "Valid memory.", ["preferences", "Preferences", ""]),
+ ["profile", "not a tuple", []],
+ ],
+ }
+ ]
+
+ deduped = dedupe_resource_plans(plans)
+
+ assert deduped[0]["entries"] == [("profile", "Valid memory.", ["preferences"])]
diff --git a/tests/test_openrouter.py b/tests/test_openrouter.py
index ba4b47c4..8908613b 100644
--- a/tests/test_openrouter.py
+++ b/tests/test_openrouter.py
@@ -1,99 +1,44 @@
+#!/usr/bin/env python3
"""
-Test OpenRouter integration with MemU's full workflow.
-
-Tests:
-1. Conversation memorization using OpenRouter
-2. RAG-based retrieval using OpenRouter embeddings
-3. LLM-based retrieval using OpenRouter
+Opt-in OpenRouter integration smoke test.
Usage:
+ export OPENROUTER_API_KEY=your_api_key
+ export MEMU_RUN_OPENROUTER_TESTS=1
+ uv run python -m pytest tests/test_openrouter.py
+
+Manual run:
export OPENROUTER_API_KEY=your_api_key
python tests/test_openrouter.py
"""
+from __future__ import annotations
+
import asyncio
-import json
import os
import sys
+from pathlib import Path
from typing import Any
-import pytest
-
-sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "src")))
-
-from memu.app import MemoryService
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+RUN_OPENROUTER_TESTS_ENV = "MEMU_RUN_OPENROUTER_TESTS"
+# Add src to sys.path before importing memu from a source checkout.
+src_path = str(PROJECT_ROOT / "src")
+if src_path not in sys.path:
+ sys.path.insert(0, src_path)
-def _print_categories(categories, max_items=3):
- """Print category summaries."""
- if categories:
- print(" Categories:")
- for cat in categories[:max_items]:
- summary = cat.get("summary") or cat.get("description", "")
- print(f" - {cat.get('name')}: {summary[:60]}...")
+async def run_openrouter_workflow() -> None:
+ """Run the OpenRouter-backed memorize/retrieve smoke workflow."""
+ from memu import MemoryService
-def _print_items(items, max_items=3):
- """Print memory item summaries."""
- if items:
- print(" Items:")
- for item in items[:max_items]:
- memory_type = item.get("memory_type", "unknown")
- summary = item.get("summary", "")[:80]
- print(f" - [{memory_type}] {summary}...")
-
-
-async def _test_memorize(service, file_path, output_data):
- """Test conversation memorization."""
- print("\n[OPENROUTER] Test 1: Memorizing conversation...")
- memory = await service.memorize(
- resource_url=file_path, modality="conversation", user={"user_id": "openrouter_test_user"}
- )
- items_count = len(memory.get("items", []))
- categories_count = len(memory.get("categories", []))
-
- print(f" Memorized {items_count} items")
- print(f" Created {categories_count} categories")
-
- output_data["memorize"] = memory
-
- assert items_count > 0, "Expected at least 1 memory item"
- assert categories_count > 0, "Expected at least 1 category"
-
- _print_categories(memory.get("categories", []))
- return memory
-
-
-async def _test_retrieve(service, queries, method, test_num, output_data):
- """Test retrieval with specified method."""
- print(f"\n[OPENROUTER] Test {test_num}: {method.upper()}-based retrieval...")
- service.retrieve_config.method = method
- result = await service.retrieve(queries=queries, where={"user_id": "openrouter_test_user"})
-
- categories_retrieved = len(result.get("categories", []))
- items_retrieved = len(result.get("items", []))
-
- print(f" Retrieved {categories_retrieved} categories")
- print(f" Retrieved {items_retrieved} items")
-
- output_data[f"retrieve_{method}"] = result
-
- _print_categories(result.get("categories", []))
- _print_items(result.get("items", []))
- return result
-
-
-async def test_openrouter_full_workflow():
- """Test OpenRouter integration with full MemU workflow."""
api_key = os.environ.get("OPENROUTER_API_KEY")
if not api_key:
- pytest.skip("OPENROUTER_API_KEY environment variable not set")
-
- file_path = os.path.abspath(os.path.join(os.path.dirname(__file__), "example", "example_conversation.json"))
- if not os.path.exists(file_path):
- pytest.skip(f"Test file not found: {file_path}")
+ msg = "OPENROUTER_API_KEY is required for the OpenRouter integration workflow"
+ raise RuntimeError(msg)
- output_data: dict[str, Any] = {}
+ file_path = Path(__file__).resolve().parent / "example" / "example_conversation.json"
print("\n" + "=" * 60)
print("[OPENROUTER] Starting full workflow test...")
@@ -119,15 +64,15 @@ async def test_openrouter_full_workflow():
},
)
+ output_data: dict[str, Any] = {}
queries = [
{"role": "user", "content": {"text": "What foods does the user like to eat?"}},
]
- await _test_memorize(service, file_path, output_data)
+ await _test_memorize(service, str(file_path), output_data)
await _test_retrieve(service, queries, "rag", 2, output_data)
await _test_retrieve(service, queries, "llm", 3, output_data)
- # Test 4: List memory items
print("\n[OPENROUTER] Test 4: List memory items...")
items_result = await service.list_memory_items(where={"user_id": "openrouter_test_user"})
items_list = items_result.get("items", [])
@@ -135,7 +80,6 @@ async def test_openrouter_full_workflow():
output_data["list_items"] = items_result
assert len(items_list) > 0, "Expected at least 1 item in list"
- # Test 5: List memory categories
print("\n[OPENROUTER] Test 5: List memory categories...")
cats_result = await service.list_memory_categories(where={"user_id": "openrouter_test_user"})
cats_list = cats_result.get("categories", [])
@@ -143,19 +87,90 @@ async def test_openrouter_full_workflow():
output_data["list_categories"] = cats_result
assert len(cats_list) > 0, "Expected at least 1 category in list"
- # Save output to file
- output_file = os.path.abspath(
- os.path.join(os.path.dirname(__file__), "..", "examples", "output", "openrouter_test_output.json")
- )
- os.makedirs(os.path.dirname(output_file), exist_ok=True)
- with open(output_file, "w", encoding="utf-8") as f:
- json.dump(output_data, f, indent=2, default=str)
- print(f"\n[OPENROUTER] Output saved to: {output_file}")
-
print("\n" + "=" * 60)
print("[OPENROUTER] All tests completed!")
print("=" * 60)
+async def test_openrouter_full_workflow() -> None:
+ """Opt-in pytest integration check for OpenRouter-backed model calls."""
+ import pytest
+
+ if os.environ.get(RUN_OPENROUTER_TESTS_ENV) != "1":
+ pytest.skip(f"Set {RUN_OPENROUTER_TESTS_ENV}=1 to run the OpenRouter integration workflow")
+ if not os.environ.get("OPENROUTER_API_KEY"):
+ pytest.skip("OPENROUTER_API_KEY is required for the OpenRouter integration workflow")
+
+ await run_openrouter_workflow()
+
+
+async def _test_memorize(service: Any, file_path: str, output_data: dict[str, Any]) -> None:
+ print("\n[OPENROUTER] Test 1: Memorizing conversation...")
+ memory = await service.memorize(
+ resource_url=file_path,
+ modality="conversation",
+ user={"user_id": "openrouter_test_user"},
+ )
+ items_count = len(memory.get("items", []))
+ categories_count = len(memory.get("categories", []))
+
+ print(f" Memorized {items_count} items")
+ print(f" Created {categories_count} categories")
+
+ output_data["memorize"] = memory
+
+ assert items_count > 0, "Expected at least 1 memory item"
+ assert categories_count > 0, "Expected at least 1 category"
+
+ _print_categories(memory.get("categories", []))
+
+
+async def _test_retrieve(
+ service: Any,
+ queries: list[dict[str, Any]],
+ method: str,
+ test_num: int,
+ output_data: dict[str, Any],
+) -> None:
+ print(f"\n[OPENROUTER] Test {test_num}: {method.upper()}-based retrieval...")
+ service.retrieve_config.method = method
+ result = await service.retrieve(queries=queries, where={"user_id": "openrouter_test_user"})
+
+ categories_retrieved = len(result.get("categories", []))
+ items_retrieved = len(result.get("items", []))
+
+ print(f" Retrieved {categories_retrieved} categories")
+ print(f" Retrieved {items_retrieved} items")
+
+ output_data[f"retrieve_{method}"] = result
+
+ _print_categories(result.get("categories", []))
+ _print_items(result.get("items", []))
+
+
+def _print_categories(categories: list[dict[str, Any]], max_items: int = 3) -> None:
+ if not categories:
+ return
+ print(" Categories:")
+ for cat in categories[:max_items]:
+ summary = cat.get("summary") or cat.get("description", "")
+ print(f" - {cat.get('name')}: {summary[:60]}...")
+
+
+def _print_items(items: list[dict[str, Any]], max_items: int = 3) -> None:
+ if not items:
+ return
+ print(" Items:")
+ for item in items[:max_items]:
+ memory_type = item.get("memory_type", "unknown")
+ summary = item.get("summary", "")[:80]
+ print(f" - [{memory_type}] {summary}...")
+
+
+def main() -> int:
+ asyncio.run(run_openrouter_workflow())
+ return 0
+
+
if __name__ == "__main__":
- asyncio.run(test_openrouter_full_workflow())
+ raise SystemExit(main())
diff --git a/tests/test_postgres.py b/tests/test_postgres.py
index 8b375a30..20bc7fe0 100644
--- a/tests/test_postgres.py
+++ b/tests/test_postgres.py
@@ -1,14 +1,32 @@
+from __future__ import annotations
+
+import asyncio
import os
+import sys
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_POSTGRES_DSN = "postgresql+psycopg://postgres:postgres@127.0.0.1:5432/memu"
+RUN_POSTGRES_TESTS_ENV = "MEMU_RUN_POSTGRES_TESTS"
+
+# Add src to sys.path before importing memu from a source checkout.
+src_path = str(PROJECT_ROOT / "src")
+if src_path not in sys.path:
+ sys.path.insert(0, src_path)
-from memu.app import MemoryService
+async def run_postgres_workflow() -> None:
+ """Run the PostgreSQL-backed memorize/retrieve smoke workflow."""
+ from memu import MemoryService
-async def main():
- """Test with PostgreSQL storage."""
api_key = os.environ.get("OPENAI_API_KEY")
+ if not api_key:
+ msg = "OPENAI_API_KEY is required for the PostgreSQL integration workflow"
+ raise RuntimeError(msg)
+
# Default port 5432; use 5433 if 5432 is occupied
- postgres_dsn = os.environ.get("POSTGRES_DSN", "postgresql+psycopg://postgres:postgres@127.0.0.1:5432/memu")
- file_path = os.path.abspath("tests/example/example_conversation.json")
+ postgres_dsn = os.environ.get("POSTGRES_DSN", DEFAULT_POSTGRES_DSN)
+ file_path = Path(__file__).resolve().parent / "example" / "example_conversation.json"
print("\n" + "=" * 60)
print("[POSTGRES] Starting test...")
@@ -30,7 +48,7 @@ async def main():
# Memorize
print("\n[POSTGRES] Memorizing...")
- memory = await service.memorize(resource_url=file_path, modality="conversation", user={"user_id": "123"})
+ memory = await service.memorize(resource_url=str(file_path), modality="conversation", user={"user_id": "123"})
for cat in memory.get("categories", []):
print(f" - {cat.get('name')}: {(cat.get('summary') or '')[:80]}...")
@@ -76,7 +94,22 @@ async def main():
print("\n[POSTGRES] Test completed!")
-if __name__ == "__main__":
- import asyncio
+async def test_postgres_full_workflow() -> None:
+ """Opt-in pytest integration check for a local PostgreSQL + pgvector service."""
+ import pytest
+
+ if os.environ.get(RUN_POSTGRES_TESTS_ENV) != "1":
+ pytest.skip(f"Set {RUN_POSTGRES_TESTS_ENV}=1 to run the PostgreSQL integration workflow")
+ if not os.environ.get("OPENAI_API_KEY"):
+ pytest.skip("OPENAI_API_KEY is required for the PostgreSQL integration workflow")
- asyncio.run(main())
+ await run_postgres_workflow()
+
+
+def main() -> int:
+ asyncio.run(run_postgres_workflow())
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/tests/test_postgres_repository_source.py b/tests/test_postgres_repository_source.py
new file mode 100644
index 00000000..54991866
--- /dev/null
+++ b/tests/test_postgres_repository_source.py
@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+MEMORY_ITEM_REPO = ROOT / "src" / "memu" / "database" / "postgres" / "repositories" / "memory_item_repo.py"
+MEMORY_CATEGORY_REPO = (
+ ROOT / "src" / "memu" / "database" / "postgres" / "repositories" / "memory_category_repo.py"
+)
+RESOURCE_REPO = ROOT / "src" / "memu" / "database" / "postgres" / "repositories" / "resource_repo.py"
+
+
+def _function_node(module: ast.Module, name: str) -> ast.FunctionDef:
+ for node in ast.walk(module):
+ if isinstance(node, ast.FunctionDef) and node.name == name:
+ return node
+ raise AssertionError(f"missing function {name}")
+
+
+def _calls_method(node: ast.AST, method_name: str) -> bool:
+ return any(
+ isinstance(child, ast.Call)
+ and isinstance(child.func, ast.Attribute)
+ and child.func.attr == method_name
+ and isinstance(child.func.value, ast.Name)
+ and child.func.value.id == "self"
+ for child in ast.walk(node)
+ )
+
+
+def test_postgres_local_vector_search_queries_current_items() -> None:
+ module = ast.parse(MEMORY_ITEM_REPO.read_text(encoding="utf-8"), filename=str(MEMORY_ITEM_REPO))
+ vector_search_fn = _function_node(module, "vector_search_items")
+ local_search_fn = _function_node(module, "_vector_search_local")
+
+ assert any(
+ isinstance(node, ast.Compare)
+ and isinstance(node.left, ast.Name)
+ and node.left.id == "top_k"
+ and any(isinstance(op, ast.LtE) for op in node.ops)
+ for node in ast.walk(vector_search_fn)
+ )
+ assert _calls_method(vector_search_fn, "_vector_search_local")
+ assert _calls_method(local_search_fn, "list_items")
+
+
+def test_postgres_cascade_delete_paths_prune_relation_cache() -> None:
+ item_source = MEMORY_ITEM_REPO.read_text(encoding="utf-8")
+ category_source = MEMORY_CATEGORY_REPO.read_text(encoding="utf-8")
+ resource_source = RESOURCE_REPO.read_text(encoding="utf-8")
+
+ assert "_drop_relation_cache_for_items(deleted_item_ids)" in item_source
+ assert "_drop_relation_cache_for_items({item_id})" in item_source
+ assert "rel.item_id not in item_ids" in item_source
+
+ assert "deleted_category_ids = set(deleted)" in category_source
+ assert "rel.category_id not in deleted_category_ids" in category_source
+
+ assert "deleted_resource_ids = set(deleted)" in resource_source
+ assert "item.resource_id in deleted_resource_ids" in resource_source
+ assert "rel.item_id not in deleted_item_ids" in resource_source
diff --git a/tests/test_retrieve_method.py b/tests/test_retrieve_method.py
new file mode 100644
index 00000000..279cbf4d
--- /dev/null
+++ b/tests/test_retrieve_method.py
@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from memu.utils.retrieve import normalize_retrieve_method, normalize_retrieve_ranking
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_normalize_retrieve_method_uses_config_default() -> None:
+ assert normalize_retrieve_method(None, default="llm") == "llm"
+
+
+def test_normalize_retrieve_method_accepts_case_insensitive_override() -> None:
+ assert normalize_retrieve_method(" RAG ", default="llm") == "rag"
+
+
+def test_normalize_retrieve_method_rejects_unknown_values() -> None:
+ try:
+ normalize_retrieve_method("hybrid", default="rag")
+ except ValueError as exc:
+ assert "retrieve method must be 'rag' or 'llm'" in str(exc)
+ else:
+ raise AssertionError("unknown retrieve method should raise ValueError")
+
+
+def test_normalize_retrieve_ranking_accepts_case_insensitive_override() -> None:
+ assert normalize_retrieve_ranking(" SALIENCE ", default="similarity") == "salience"
+
+
+def test_normalize_retrieve_ranking_rejects_unknown_values() -> None:
+ try:
+ normalize_retrieve_ranking("random", default="similarity")
+ except ValueError as exc:
+ assert "retrieve ranking must be 'similarity' or 'salience'" in str(exc)
+ else:
+ raise AssertionError("unknown retrieve ranking should raise ValueError")
+
+
+def test_retrieve_method_override_is_wired_into_retrieve_pipeline() -> None:
+ source = (ROOT / "src" / "memu" / "app" / "retrieve.py").read_text(encoding="utf-8")
+ module = ast.parse(source)
+ retrieve_fn = next(
+ node for node in ast.walk(module) if isinstance(node, ast.AsyncFunctionDef) and node.name == "retrieve"
+ )
+ arg_names = [arg.arg for arg in retrieve_fn.args.args]
+
+ assert "method" in arg_names
+ assert "normalize_retrieve_method(method, default=self.retrieve_config.method)" in source
+ assert '"retrieve_llm" if retrieve_method == "llm" else "retrieve_rag"' in source
+ assert '"method": retrieve_method' in source
+
+
+def test_retrieve_ranking_override_is_wired_into_rag_item_recall() -> None:
+ source = (ROOT / "src" / "memu" / "app" / "retrieve.py").read_text(encoding="utf-8")
+ module = ast.parse(source)
+ retrieve_fn = next(
+ node for node in ast.walk(module) if isinstance(node, ast.AsyncFunctionDef) and node.name == "retrieve"
+ )
+ arg_names = [arg.arg for arg in retrieve_fn.args.args]
+ rag_recall_items = _async_function_source(source, "_rag_recall_items")
+
+ assert "ranking" in arg_names
+ assert "normalize_retrieve_ranking(ranking, default=self.retrieve_config.item.ranking)" in source
+ assert '"item_ranking": item_ranking' in source
+ assert '"item_ranking",' in source
+ assert 'ranking=state.get("item_ranking", self.retrieve_config.item.ranking)' in rag_recall_items
+
+
+def test_rag_retrieve_follows_category_references_with_scope_filters() -> None:
+ source = (ROOT / "src" / "memu" / "app" / "retrieve.py").read_text(encoding="utf-8")
+ rag_recall_items = _async_function_source(source, "_rag_recall_items")
+ merge_hits = _function_source(source, "_merge_referenced_item_hits")
+
+ assert 'getattr(self.retrieve_config.item, "use_category_references", False)' in rag_recall_items
+ assert "ref_ids = self._extract_referenced_item_ids(state)" in rag_recall_items
+ assert "store.memory_item_repo.list_items_by_ref_ids(ref_ids, where_filters)" in rag_recall_items
+ assert "items_pool.update(referenced_items)" in rag_recall_items
+ assert "self._merge_referenced_item_hits(" in rag_recall_items
+ assert "if item_id not in seen:" in merge_hits
+
+
+def test_llm_retrieve_respects_category_item_resource_toggles() -> None:
+ source = (ROOT / "src" / "memu" / "app" / "retrieve.py").read_text(encoding="utf-8")
+ workflow_source = _function_source(source, "_build_llm_retrieve_workflow")
+ route_category = _async_function_source(source, "_llm_route_category")
+ recall_items = _async_function_source(source, "_llm_recall_items")
+ recall_resources = _async_function_source(source, "_llm_recall_resources")
+
+ assert '"retrieve_category", "needs_retrieval", "active_query", "ctx", "store", "where"' in workflow_source
+ assert '"retrieve_item",' in workflow_source
+ assert '"retrieve_resource",' in workflow_source
+ assert 'not state.get("retrieve_category") or not state.get("needs_retrieval")' in route_category
+ assert 'not state.get("retrieve_item") or not state.get("needs_retrieval")' in recall_items
+ assert 'not state.get("retrieve_resource")' in recall_resources
+
+
+def test_route_intention_uses_independent_llm_profile() -> None:
+ source = (ROOT / "src" / "memu" / "app" / "retrieve.py").read_text(encoding="utf-8")
+ rag_workflow = _function_source(source, "_build_rag_retrieve_workflow")
+ llm_workflow = _function_source(source, "_build_llm_retrieve_workflow")
+
+ assert "self.retrieve_config.route_intention_llm_profile" in rag_workflow
+ assert "self.retrieve_config.route_intention_llm_profile" in llm_workflow
+ assert 'config={"chat_llm_profile": self.retrieve_config.sufficiency_check_llm_profile}' not in rag_workflow
+ assert 'config={"llm_profile": self.retrieve_config.sufficiency_check_llm_profile}' not in llm_workflow.split(
+ 'step_id="route_category"',
+ 1,
+ )[0]
+
+
+def test_direct_retrieve_query_text_is_trimmed_and_rejects_blank_values() -> None:
+ source = (ROOT / "src" / "memu" / "app" / "retrieve.py").read_text(encoding="utf-8")
+ extract_query_text = _function_source(source, "_extract_query_text")
+
+ assert "text = query.strip()" in extract_query_text
+ assert "text = content.strip()" in extract_query_text
+ assert "text = content.get(\"text\", \"\")" in extract_query_text
+ assert "not isinstance(text, str) or not text.strip()" in extract_query_text
+ assert "return text.strip()" in extract_query_text
+ assert 'raise ValueError("EMPTY")' in extract_query_text
+
+
+def test_direct_retrieve_type_hints_accept_string_query_items_without_raw_string_collection() -> None:
+ source = (ROOT / "src" / "memu" / "app" / "retrieve.py").read_text(encoding="utf-8")
+ module = ast.parse(source)
+ retrieve_fn = next(
+ node for node in ast.walk(module) if isinstance(node, ast.AsyncFunctionDef) and node.name == "retrieve"
+ )
+ query_arg = next(arg for arg in retrieve_fn.args.args if arg.arg == "queries")
+ retrieve_source = _async_function_source(source, "retrieve")
+ format_query_context = _function_source(source, "_format_query_context")
+ extract_query_text = _function_source(source, "_extract_query_text")
+
+ assert ast.unparse(query_arg.annotation) == "list[str | Mapping[str, Any]]"
+ assert "if not isinstance(queries, list):" in retrieve_source
+ assert "queries must be a non-empty list of strings or query objects" in retrieve_source
+ assert 'raise ValueError("empty_queries")' not in retrieve_source
+ assert "def _format_query_context(self, queries: Sequence[str | Mapping[str, Any]] | None)" in format_query_context
+ assert "elif isinstance(q, Mapping):" in format_query_context
+ assert "def _extract_query_text(query: str | Mapping[str, Any])" in extract_query_text
+ assert "if not isinstance(query, Mapping):" in extract_query_text
+
+
+def test_direct_retrieve_normalizes_all_query_items_before_workflow() -> None:
+ source = (ROOT / "src" / "memu" / "app" / "retrieve.py").read_text(encoding="utf-8")
+ retrieve_source = _async_function_source(source, "retrieve")
+ normalize_query_item = _function_source(source, "_normalize_query_item")
+
+ assert (
+ "normalized_queries = [self._normalize_query_item(query, index=index) for index, query in enumerate(queries)]"
+ in retrieve_source
+ )
+ assert "original_query = self._extract_query_text(normalized_queries[-1])" in retrieve_source
+ assert "context_queries_objs: list[dict[str, Any]] = normalized_queries[:-1]" in retrieve_source
+ assert '"skip_rewrite": len(normalized_queries) == 1' in retrieve_source
+ assert 'return {"role": "user", "content": text}' in normalize_query_item
+ assert 'role = query.get("role", "user")' in normalize_query_item
+ assert 'normalized_content = {"text": text.strip()}' in normalize_query_item
+ assert 'raise ValueError(f"queries[{index}].content.text must be a non-empty string")' in normalize_query_item
+
+
+def _async_function_source(source: str, name: str) -> str:
+ module = ast.parse(source)
+ for node in ast.walk(module):
+ if isinstance(node, ast.AsyncFunctionDef) and node.name == name:
+ segment = ast.get_source_segment(source, node)
+ assert segment is not None
+ return segment
+ raise AssertionError(f"async function {name!r} not found")
+
+
+def _function_source(source: str, name: str) -> str:
+ module = ast.parse(source)
+ for node in ast.walk(module):
+ if isinstance(node, ast.FunctionDef) and node.name == name:
+ segment = ast.get_source_segment(source, node)
+ assert segment is not None
+ return segment
+ raise AssertionError(f"function {name!r} not found")
diff --git a/tests/test_salience.py b/tests/test_salience.py
index bb5d84a2..9df638d9 100644
--- a/tests/test_salience.py
+++ b/tests/test_salience.py
@@ -8,8 +8,25 @@
from __future__ import annotations
import hashlib
+import importlib.util
import math
from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+
+def _load_runtime_vector_module():
+ vector_path = Path(__file__).resolve().parents[1] / "src/memu/database/inmemory/vector.py"
+ spec = importlib.util.spec_from_file_location("memu_runtime_vector", vector_path)
+ assert spec is not None
+ assert spec.loader is not None
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+_RUNTIME_VECTOR = _load_runtime_vector_module()
+runtime_cosine_topk = _RUNTIME_VECTOR.cosine_topk
+runtime_cosine_topk_salience = _RUNTIME_VECTOR.cosine_topk_salience
# Inline implementations to avoid circular import issues during testing
@@ -207,3 +224,13 @@ def test_respects_k_limit(self) -> None:
results = cosine_topk_salience(query, corpus, k=2, recency_decay_days=30.0)
assert len(results) == 2
+
+
+def test_runtime_vector_topk_returns_empty_for_non_positive_k() -> None:
+ query = [1.0, 0.0]
+ corpus = [("id1", [1.0, 0.0]), ("id2", [0.0, 1.0])]
+ salience_corpus = [("id1", [1.0, 0.0], 1, datetime.now(UTC))]
+
+ assert runtime_cosine_topk(query, corpus, k=0) == []
+ assert runtime_cosine_topk(query, corpus, k=-1) == []
+ assert runtime_cosine_topk_salience(query, salience_corpus, k=0) == []
diff --git a/tests/test_scope_filters.py b/tests/test_scope_filters.py
new file mode 100644
index 00000000..e7d02f60
--- /dev/null
+++ b/tests/test_scope_filters.py
@@ -0,0 +1,284 @@
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from memu.app.scope import (
+ concrete_scope_from_where,
+ exact_scope_from_where,
+ normalize_scope_where,
+ record_matches_scope,
+ scope_key_from_user,
+)
+from memu.utils.filtering import normalize_filter_value, split_filter_key
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+class UserScope(BaseModel):
+ user_id: str | None = None
+ agent_id: str | None = None
+
+
+class TenantScope(BaseModel):
+ tenant_id: int | None = None
+ user_id: str | None = None
+
+
+class RequiredTenantScope(BaseModel):
+ tenant_id: int
+ user_id: str
+
+
+class ConstrainedScope(BaseModel):
+ user_id: str = Field(min_length=2)
+
+
+class ScopedRecord:
+ def __init__(self, **values: object) -> None:
+ for key, value in values.items():
+ setattr(self, key, value)
+
+
+def _assert_value_error(func: Any, expected: str) -> None:
+ try:
+ func()
+ except ValueError as exc:
+ assert expected in str(exc)
+ else:
+ raise AssertionError("Expected ValueError")
+
+
+def test_normalize_scope_where_accepts_equality_and_in_filters() -> None:
+ where = normalize_scope_where(
+ UserScope,
+ {
+ "user_id": "u1",
+ "agent_id__in": ["agent-a", "agent-b"],
+ "agent_id": None,
+ },
+ )
+
+ assert where == {
+ "user_id": "u1",
+ "agent_id__in": ("agent-a", "agent-b"),
+ }
+
+
+def test_normalize_scope_where_validates_and_normalizes_values_with_user_model() -> None:
+ where = normalize_scope_where(
+ TenantScope,
+ {
+ "tenant_id": "42",
+ "tenant_id__in": ["1", 2],
+ "user_id__in": "u1",
+ },
+ )
+
+ assert where == {
+ "tenant_id": 42,
+ "tenant_id__in": (1, 2),
+ "user_id__in": ("u1",),
+ }
+
+
+def test_normalize_scope_where_validates_single_fields_without_requiring_full_model() -> None:
+ where = normalize_scope_where(RequiredTenantScope, {"tenant_id": "42"})
+
+ assert where == {"tenant_id": 42}
+
+
+def test_normalize_scope_where_rejects_unknown_scope_fields() -> None:
+ _assert_value_error(
+ lambda: normalize_scope_where(UserScope, {"session_id": "s1"}),
+ "Unknown filter field 'session_id'",
+ )
+
+
+def test_normalize_scope_where_rejects_unsupported_filter_operators() -> None:
+ _assert_value_error(
+ lambda: normalize_scope_where(UserScope, {"user_id__ne": "u1"}),
+ "Unsupported filter operator '__ne'",
+ )
+
+
+def test_normalize_scope_where_rejects_non_iterable_in_filter_values() -> None:
+ _assert_value_error(
+ lambda: normalize_scope_where(UserScope, {"user_id__in": 123}),
+ "Filter 'user_id__in' must be a string or an iterable of values",
+ )
+
+
+def test_normalize_scope_where_rejects_values_invalid_for_user_model() -> None:
+ _assert_value_error(
+ lambda: normalize_scope_where(TenantScope, {"tenant_id": "not-an-int"}),
+ "Invalid filter value for field 'tenant_id'",
+ )
+ _assert_value_error(
+ lambda: normalize_scope_where(TenantScope, {"tenant_id__in": ["1", "not-an-int"]}),
+ "Invalid filter value for field 'tenant_id'",
+ )
+ _assert_value_error(
+ lambda: normalize_scope_where(ConstrainedScope, {"user_id": "x"}),
+ "Invalid filter value for field 'user_id'",
+ )
+
+
+def test_split_filter_key_rejects_empty_filter_fields() -> None:
+ _assert_value_error(lambda: split_filter_key(""), "Filter field must be a non-empty string")
+ _assert_value_error(lambda: split_filter_key("__in"), "Filter field must be a non-empty string")
+
+
+def test_in_filter_preserves_string_as_single_value() -> None:
+ field, operator = split_filter_key("user_id__in")
+
+ assert (field, operator) == ("user_id", "in")
+ assert normalize_filter_value(field, operator, "u1") == "u1"
+
+
+def test_scope_key_from_user_is_stable_and_ignores_none_values() -> None:
+ assert scope_key_from_user({"agent_id": None, "user_id": "u1"}) == (("user_id", '"u1"'),)
+ assert scope_key_from_user({"user_id": "u1", "agent_id": "a1"}) == (
+ ("agent_id", '"a1"'),
+ ("user_id", '"u1"'),
+ )
+
+
+def test_exact_scope_from_where_uses_only_equality_filters() -> None:
+ assert exact_scope_from_where({"user_id": "u1", "agent_id__in": ["a1", "a2"], "session_id": None}) == {
+ "user_id": "u1"
+ }
+
+
+def test_concrete_scope_from_where_requires_single_exact_scope() -> None:
+ assert concrete_scope_from_where(None) == {}
+ assert concrete_scope_from_where({"user_id": "u1", "agent_id": "a1"}) == {"user_id": "u1", "agent_id": "a1"}
+ assert concrete_scope_from_where({"user_id": "u1", "agent_id__in": ("a1", "a2")}) is None
+
+
+def test_record_matches_scope_requires_all_non_null_scope_fields() -> None:
+ record = ScopedRecord(user_id="u1", agent_id="a1")
+
+ assert record_matches_scope(record, {"user_id": "u1", "agent_id": "a1"})
+ assert record_matches_scope(record, {"user_id": "u1", "agent_id": None})
+ assert not record_matches_scope(record, {"user_id": "u2"})
+ assert not record_matches_scope(record, {"user_id": "u1", "agent_id": "a2"})
+
+
+def test_backend_records_preserve_scope_extras_for_sqlite_cache() -> None:
+ models_source = (ROOT / "src" / "memu" / "database" / "models.py").read_text(encoding="utf-8")
+ base_record = _class_node(models_source, "BaseRecord")
+ model_config = _class_assignment(base_record, "model_config")
+
+ assert isinstance(model_config, ast.Call)
+ assert getattr(model_config.func, "id", "") == "ConfigDict"
+ assert any(
+ keyword.arg == "extra"
+ and isinstance(keyword.value, ast.Constant)
+ and keyword.value.value == "allow"
+ for keyword in model_config.keywords
+ )
+
+ sqlite_paths = [
+ "src/memu/database/sqlite/repositories/resource_repo.py",
+ "src/memu/database/sqlite/repositories/memory_category_repo.py",
+ "src/memu/database/sqlite/repositories/memory_item_repo.py",
+ "src/memu/database/sqlite/repositories/category_item_repo.py",
+ ]
+ for relative_path in sqlite_paths:
+ source = (ROOT / relative_path).read_text(encoding="utf-8")
+ assert "**self._scope_kwargs_from(row)" in source or "**self._scope_kwargs_from(existing)" in source
+
+
+def test_persistent_category_schema_enforces_name_uniqueness_per_scope() -> None:
+ checked = [
+ ("src/memu/database/sqlite/schema.py", "build_sqlite_table_model"),
+ ("src/memu/database/postgres/schema.py", "build_table_model"),
+ ]
+
+ for relative_path, builder_name in checked:
+ source = (ROOT / relative_path).read_text(encoding="utf-8")
+ call = _assignment_call(source, "memory_category_model", builder_name)
+ keyword_values = {keyword.arg: keyword.value for keyword in call.keywords}
+
+ assert "unique_with_scope" in keyword_values
+ assert ast.unparse(keyword_values["unique_with_scope"]) == "['name']"
+
+
+def test_category_context_is_cached_per_scope() -> None:
+ service_source = (ROOT / "src" / "memu" / "app" / "service.py").read_text(encoding="utf-8")
+ memorize_source = (ROOT / "src" / "memu" / "app" / "memorize.py").read_text(encoding="utf-8")
+
+ assert "category_scope_key" in service_source
+ assert "category_cache" in service_source
+ assert "scope_key = scope_key_from_user(user_scope)" in memorize_source
+ assert "ctx.category_cache[scope_key]" in memorize_source
+
+
+def test_patch_update_and_delete_guard_memory_items_by_user_scope() -> None:
+ crud_source = (ROOT / "src" / "memu" / "app" / "crud.py").read_text(encoding="utf-8")
+ patch_source = (ROOT / "src" / "memu" / "app" / "patch.py").read_text(encoding="utf-8")
+
+ assert "record_matches_scope" in crud_source
+ assert "record_matches_scope" in patch_source
+ assert "self._ensure_item_matches_user_scope(item, user, memory_id)" in crud_source
+ assert 'self._ensure_item_matches_user_scope(item, state["user"], memory_id)' in crud_source
+ assert "self._ensure_item_matches_user_scope(item, user, memory_id)" in patch_source
+ assert 'self._ensure_item_matches_user_scope(item, state["user"], memory_id)' in patch_source
+
+
+def test_first_run_category_bootstrap_uses_concrete_scope_only() -> None:
+ crud_source = (ROOT / "src" / "memu" / "app" / "crud.py").read_text(encoding="utf-8")
+ retrieve_source = (ROOT / "src" / "memu" / "app" / "retrieve.py").read_text(encoding="utf-8")
+ list_items_source = _async_function_source(crud_source, "list_memory_items")
+ list_categories_source = _async_function_source(crud_source, "list_memory_categories")
+ retrieve_fn_source = _async_function_source(retrieve_source, "retrieve")
+
+ assert "bootstrap_scope = concrete_scope_from_where(where_filters)" not in list_items_source
+ assert "bootstrap_scope = concrete_scope_from_where(where_filters)" in list_categories_source
+ assert "await self._ensure_categories_ready(ctx, store, bootstrap_scope)" in list_categories_source
+ assert "bootstrap_scope = concrete_scope_from_where(where_filters)" in retrieve_fn_source
+ assert "if retrieve_category and bootstrap_scope is not None:" in retrieve_fn_source
+ assert "await self._ensure_categories_ready(ctx, store, bootstrap_scope)" in retrieve_fn_source
+
+
+def _async_function_source(source: str, name: str) -> str:
+ module = ast.parse(source)
+ for node in ast.walk(module):
+ if isinstance(node, ast.AsyncFunctionDef) and node.name == name:
+ segment = ast.get_source_segment(source, node)
+ assert segment is not None
+ return segment
+ raise AssertionError(f"async function {name!r} not found")
+
+
+def _class_node(source: str, name: str) -> ast.ClassDef:
+ module = ast.parse(source)
+ for node in ast.walk(module):
+ if isinstance(node, ast.ClassDef) and node.name == name:
+ return node
+ raise AssertionError(f"class {name!r} not found")
+
+
+def _class_assignment(class_node: ast.ClassDef, name: str) -> ast.expr:
+ for statement in class_node.body:
+ if not isinstance(statement, ast.Assign):
+ continue
+ if any(isinstance(target, ast.Name) and target.id == name for target in statement.targets):
+ return statement.value
+ raise AssertionError(f"class assignment {name!r} not found")
+
+
+def _assignment_call(source: str, target_name: str, call_name: str) -> ast.Call:
+ module = ast.parse(source)
+ for node in ast.walk(module):
+ if not isinstance(node, ast.Assign):
+ continue
+ if not any(isinstance(target, ast.Name) and target.id == target_name for target in node.targets):
+ continue
+ if isinstance(node.value, ast.Call) and getattr(node.value.func, "id", "") == call_name:
+ return node.value
+ raise AssertionError(f"assignment call {target_name} = {call_name}(...) not found")
diff --git a/tests/test_serialization.py b/tests/test_serialization.py
new file mode 100644
index 00000000..bc9bd90c
--- /dev/null
+++ b/tests/test_serialization.py
@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+import ast
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from memu.llm.wrapper import _extract_usage_from_raw_response
+from memu.utils.serialization import model_dump_without_embeddings
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+class ResponseRecord(BaseModel):
+ id: str
+ summary: str
+ embedding: list[float] | None
+ created_at: datetime
+ extra: dict[str, object] = Field(default_factory=dict)
+
+
+class CompletionTokenDetails(BaseModel):
+ reasoning_tokens: int
+ generated_at: datetime
+
+
+class PromptTokenDetails(BaseModel):
+ cached_tokens: int
+
+
+class UsageRecord(BaseModel):
+ prompt_tokens: int
+ completion_tokens: int
+ total_tokens: int
+ completion_tokens_details: CompletionTokenDetails
+ prompt_tokens_details: PromptTokenDetails
+
+
+class RawLLMResponse:
+ def __init__(self, usage: object) -> None:
+ self.choices = [{"finish_reason": "stop"}]
+ self.usage = usage
+
+
+class LegacyCompletionTokenDetails:
+ reasoning_tokens = 2
+
+ def model_dump(self) -> dict[str, object]:
+ return {
+ "reasoning_tokens": self.reasoning_tokens,
+ "generated_at": datetime(2026, 6, 5, 3, 0, tzinfo=timezone.utc),
+ }
+
+
+class LegacyUsageRecord:
+ prompt_tokens = 8
+ completion_tokens = 2
+ total_tokens = 10
+ completion_tokens_details = LegacyCompletionTokenDetails()
+ prompt_tokens_details = {"cached_tokens": 4}
+
+
+def test_model_dump_without_embeddings_returns_json_safe_values() -> None:
+ record = ResponseRecord(
+ id="m1",
+ summary="User likes concise answers.",
+ embedding=[0.1, 0.2, 0.3],
+ created_at=datetime(2026, 6, 5, 1, 40, tzinfo=timezone.utc),
+ extra={"score": 0.9},
+ )
+
+ data = model_dump_without_embeddings(record)
+
+ assert data == {
+ "id": "m1",
+ "summary": "User likes concise answers.",
+ "created_at": "2026-06-05T01:40:00Z",
+ "extra": {"score": 0.9},
+ }
+
+
+def test_memorize_response_relations_use_json_safe_public_dump() -> None:
+ source = (ROOT / "src/memu/app/memorize.py").read_text(encoding="utf-8")
+ function_source = _function_source(source, "_memorize_build_response")
+
+ assert "relations = [self._model_dump_without_embeddings(rel)" in function_source
+ assert "rel.model_dump()" not in function_source
+
+
+def test_tool_call_history_uses_json_safe_model_dump() -> None:
+ source = (ROOT / "src/memu/utils/tool.py").read_text(encoding="utf-8")
+ function_source = _function_source(source, "add_tool_call")
+
+ assert 'tool_call.model_dump(mode="json")' in function_source
+ assert "tool_call.model_dump())" not in function_source
+
+
+def test_llm_usage_breakdown_is_json_safe() -> None:
+ raw_response = RawLLMResponse(
+ UsageRecord(
+ prompt_tokens=10,
+ completion_tokens=4,
+ total_tokens=14,
+ completion_tokens_details=CompletionTokenDetails(
+ reasoning_tokens=3,
+ generated_at=datetime(2026, 6, 5, 2, 30, tzinfo=timezone.utc),
+ ),
+ prompt_tokens_details=PromptTokenDetails(cached_tokens=6),
+ )
+ )
+
+ usage = _extract_usage_from_raw_response(kind="chat", raw_response=raw_response)
+
+ assert usage["finish_reason"] == "stop"
+ assert usage["input_tokens"] == 10
+ assert usage["output_tokens"] == 4
+ assert usage["total_tokens"] == 14
+ assert usage["cached_input_tokens"] == 6
+ assert usage["reasoning_tokens"] == 3
+ assert usage["tokens_breakdown"] == {
+ "reasoning_tokens": 3,
+ "generated_at": "2026-06-05T02:30:00Z",
+ }
+ json.dumps(usage)
+
+
+def test_llm_usage_breakdown_accepts_legacy_model_dump_signature() -> None:
+ raw_response = RawLLMResponse(LegacyUsageRecord())
+
+ usage = _extract_usage_from_raw_response(kind="chat", raw_response=raw_response)
+
+ assert usage["cached_input_tokens"] == 4
+ assert usage["tokens_breakdown"] == {
+ "reasoning_tokens": 2,
+ "generated_at": "2026-06-05T03:00:00+00:00",
+ }
+ json.dumps(usage)
+
+
+def test_llm_usage_extraction_accepts_responses_style_token_names() -> None:
+ raw_response = {
+ "choices": [{"finish_reason": "length"}],
+ "usage": {
+ "input_tokens": 11,
+ "output_tokens": 7,
+ "total_tokens": 18,
+ "input_tokens_details": {"cached_tokens": 5},
+ "output_tokens_details": {
+ "reasoning_tokens": 2,
+ "accepted_prediction_tokens": 1,
+ },
+ },
+ }
+
+ usage = _extract_usage_from_raw_response(kind="chat", raw_response=raw_response)
+
+ assert usage["finish_reason"] == "length"
+ assert usage["input_tokens"] == 11
+ assert usage["output_tokens"] == 7
+ assert usage["total_tokens"] == 18
+ assert usage["cached_input_tokens"] == 5
+ assert usage["reasoning_tokens"] == 2
+ assert usage["tokens_breakdown"] == {
+ "reasoning_tokens": 2,
+ "accepted_prediction_tokens": 1,
+ }
+ json.dumps(usage)
+
+
+def test_memory_item_extra_defaults_are_per_record_factories() -> None:
+ checked = [
+ ("src/memu/database/models.py", "MemoryItem"),
+ ("src/memu/database/sqlite/models.py", "SQLiteMemoryItemModel"),
+ ("src/memu/database/postgres/models.py", "MemoryItemModel"),
+ ]
+
+ for relative_path, class_name in checked:
+ source = (ROOT / relative_path).read_text(encoding="utf-8")
+ assignment = _class_assignment(source, class_name, "extra")
+
+ assert isinstance(assignment, ast.Call), f"{relative_path}:{class_name}.extra must call Field"
+ assert getattr(assignment.func, "id", "") == "Field"
+ assert any(
+ keyword.arg == "default_factory"
+ and getattr(keyword.value, "id", None) == "dict"
+ for keyword in assignment.keywords
+ ), f"{relative_path}:{class_name}.extra must use Field(default_factory=dict)"
+
+
+def _function_source(source: str, name: str) -> str:
+ module = ast.parse(source)
+ for node in ast.walk(module):
+ if isinstance(node, ast.FunctionDef) and node.name == name:
+ segment = ast.get_source_segment(source, node)
+ assert segment is not None
+ return segment
+ raise AssertionError(f"function {name!r} not found")
+
+
+def _class_assignment(source: str, class_name: str, field_name: str) -> ast.expr:
+ module = ast.parse(source)
+ for node in ast.walk(module):
+ if not isinstance(node, ast.ClassDef) or node.name != class_name:
+ continue
+ for statement in node.body:
+ if not isinstance(statement, ast.AnnAssign):
+ continue
+ if isinstance(statement.target, ast.Name) and statement.target.id == field_name:
+ assert statement.value is not None
+ return statement.value
+ raise AssertionError(f"{class_name}.{field_name} assignment not found")
diff --git a/tests/test_settings.py b/tests/test_settings.py
new file mode 100644
index 00000000..b3dbd0c3
--- /dev/null
+++ b/tests/test_settings.py
@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+from unittest.mock import patch
+
+from pydantic import ValidationError
+
+from memu.app.settings import (
+ CategoryConfig,
+ DatabaseConfig,
+ LLMConfig,
+ LLMProfilesConfig,
+ MemorizeConfig,
+ RetrieveConfig,
+ default_api_key_env,
+ resolve_api_key,
+)
+
+
+@patch.dict("os.environ", {"OPENAI_API_KEY": "resolved-openai-key"})
+def test_resolve_api_key_environment_variable_names() -> None:
+ assert resolve_api_key("OPENAI_API_KEY") == "resolved-openai-key"
+
+
+@patch.dict("os.environ", {"OPENAI_API_KEY": " resolved-openai-key "})
+def test_resolve_api_key_trims_environment_variable_values() -> None:
+ assert resolve_api_key("OPENAI_API_KEY") == "resolved-openai-key"
+
+
+@patch.dict("os.environ", {"OPENAI_API_KEY": "resolved-openai-key"})
+def test_resolve_api_key_preserves_literal_api_keys() -> None:
+ assert resolve_api_key("sk-literal-key") == "sk-literal-key"
+
+
+def test_resolve_api_key_normalizes_missing_api_key_to_empty_string() -> None:
+ assert resolve_api_key(None) == ""
+
+
+def test_default_api_key_env_matches_provider_defaults() -> None:
+ assert default_api_key_env("openai") == "OPENAI_API_KEY"
+ assert default_api_key_env(" GROK ") == "XAI_API_KEY"
+
+
+def test_llm_config_normalizes_provider_before_defaults() -> None:
+ config = LLMConfig(provider=" GROK ")
+
+ assert config.provider == "grok"
+ assert config.base_url == "https://api.x.ai/v1"
+ assert config.api_key == "XAI_API_KEY"
+ assert config.chat_model == "grok-2-latest"
+
+
+def test_llm_config_normalizes_client_backend() -> None:
+ config = LLMConfig(client_backend=" HTTPX ")
+
+ assert config.client_backend == "httpx"
+
+
+def test_llm_config_rejects_unknown_client_backend() -> None:
+ try:
+ LLMConfig(client_backend="http")
+ except ValidationError as exc:
+ assert "client_backend" in str(exc)
+ else:
+ raise AssertionError("LLMConfig should reject unknown client_backend values")
+
+
+def test_llm_config_rejects_non_positive_embed_batch_size() -> None:
+ try:
+ LLMConfig(embed_batch_size=0)
+ except ValidationError as exc:
+ assert "embed_batch_size" in str(exc)
+ else:
+ raise AssertionError("LLMConfig should reject non-positive embed_batch_size")
+
+
+def test_retrieve_numeric_bounds_reject_invalid_values() -> None:
+ invalid_configs = [
+ {"category": {"top_k": 0}},
+ {"item": {"top_k": 0}},
+ {"item": {"recency_decay_days": 0}},
+ {"resource": {"top_k": 0}},
+ ]
+
+ for config in invalid_configs:
+ try:
+ RetrieveConfig(**config)
+ except ValidationError:
+ pass
+ else:
+ raise AssertionError(f"RetrieveConfig should reject invalid numeric bounds: {config}")
+
+
+def test_memorize_numeric_bounds_reject_invalid_values() -> None:
+ invalid_configs = [
+ {"category_assign_threshold": -0.01},
+ {"category_assign_threshold": 1.01},
+ {"default_category_summary_target_length": 0},
+ ]
+
+ for config in invalid_configs:
+ try:
+ MemorizeConfig(**config)
+ except ValidationError:
+ pass
+ else:
+ raise AssertionError(f"MemorizeConfig should reject invalid numeric bounds: {config}")
+
+ try:
+ CategoryConfig(name="facts", target_length=0)
+ except ValidationError:
+ pass
+ else:
+ raise AssertionError("CategoryConfig should reject non-positive target_length")
+
+
+def test_database_config_allows_sqlite_without_explicit_dsn() -> None:
+ config = DatabaseConfig(metadata_store={"provider": "sqlite"})
+
+ assert config.metadata_store.dsn is None
+ assert config.vector_index is not None
+ assert config.vector_index.provider == "bruteforce"
+
+
+def test_retrieve_config_has_independent_route_intention_profile() -> None:
+ config = RetrieveConfig(route_intention_llm_profile="router", sufficiency_check_llm_profile="judge")
+
+ assert config.route_intention_llm_profile == "router"
+ assert config.sufficiency_check_llm_profile == "judge"
+
+
+def test_workflow_profile_names_are_trimmed_and_reject_blank_values() -> None:
+ retrieve_config = RetrieveConfig(
+ route_intention_llm_profile=" router ",
+ sufficiency_check_llm_profile=" judge ",
+ llm_ranking_llm_profile=" ranker ",
+ )
+ memorize_config = MemorizeConfig(
+ preprocess_llm_profile=" preprocess ",
+ memory_extract_llm_profile=" extract ",
+ category_update_llm_profile=" summarize ",
+ )
+
+ assert retrieve_config.route_intention_llm_profile == "router"
+ assert retrieve_config.sufficiency_check_llm_profile == "judge"
+ assert retrieve_config.llm_ranking_llm_profile == "ranker"
+ assert memorize_config.preprocess_llm_profile == "preprocess"
+ assert memorize_config.memory_extract_llm_profile == "extract"
+ assert memorize_config.category_update_llm_profile == "summarize"
+
+ try:
+ RetrieveConfig(route_intention_llm_profile=" ")
+ except ValidationError as exc:
+ assert "route_intention_llm_profile" in str(exc)
+ else:
+ raise AssertionError("RetrieveConfig should reject blank route_intention_llm_profile")
+
+
+def test_llm_profile_names_are_trimmed_in_profile_map_keys() -> None:
+ config = LLMProfilesConfig.model_validate({" default ": {"api_key": "A"}})
+
+ assert "default" in config.profiles
+ assert config.profiles["default"].api_key == "A"
+ assert "embedding" in config.profiles
diff --git a/tests/test_sqlite.py b/tests/test_sqlite.py
index 3031c56b..02f08ec0 100644
--- a/tests/test_sqlite.py
+++ b/tests/test_sqlite.py
@@ -1,42 +1,44 @@
-"""Test SQLite database backend for MemU."""
+#!/usr/bin/env python3
+"""Opt-in live LLM smoke test for the SQLite backend."""
+from __future__ import annotations
+
+import asyncio
import os
+import sys
import tempfile
+from pathlib import Path
+from typing import Any
-from memu.app import MemoryService
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+RUN_LIVE_LLM_TESTS_ENV = "MEMU_RUN_LIVE_LLM_TESTS"
+# Add src to sys.path before importing memu from a source checkout.
+src_path = str(PROJECT_ROOT / "src")
+if src_path not in sys.path:
+ sys.path.insert(0, src_path)
-def _print_results(title: str, result: dict) -> None:
- print(f"\n[SQLITE] RETRIEVED - {title}")
- print(" Categories:")
- for cat in result.get("categories", [])[:3]:
- print(f" - {cat.get('name')}: {(cat.get('summary') or cat.get('description', ''))[:80]}...")
- print(" Items:")
- for item in result.get("items", [])[:3]:
- print(f" - [{item.get('memory_type')}] {item.get('summary', '')[:100]}...")
- if result.get("resources"):
- print(" Resources:")
- for res in result.get("resources", [])[:3]:
- print(f" - [{res.get('modality')}] {res.get('url', '')[:80]}...")
+async def run_sqlite_workflow() -> None:
+ """Run the SQLite-backed memorize/retrieve smoke workflow against a real LLM."""
+ from memu import MemoryService
-async def main():
- """Test with SQLite storage."""
api_key = os.environ.get("OPENAI_API_KEY")
- file_path = os.path.abspath(os.path.join(os.path.dirname(__file__), "example", "example_conversation.json"))
+ if not api_key:
+ msg = "OPENAI_API_KEY is required for the SQLite live LLM workflow"
+ raise RuntimeError(msg)
- # Create a temporary SQLite database file
- with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as tmp:
- sqlite_path = tmp.name
+ file_path = Path(__file__).resolve().parent / "example" / "example_conversation.json"
- sqlite_dsn = f"sqlite:///{sqlite_path}"
+ with tempfile.TemporaryDirectory() as tmpdir:
+ sqlite_path = Path(tmpdir) / "memu.db"
+ sqlite_dsn = f"sqlite:///{sqlite_path.as_posix()}"
- print("\n" + "=" * 60)
- print("[SQLITE] Starting test...")
- print(f"[SQLITE] DSN: {sqlite_dsn}")
- print("=" * 60)
+ print("\n" + "=" * 60)
+ print("[SQLITE] Starting test...")
+ print(f"[SQLITE] DSN: {sqlite_dsn}")
+ print("=" * 60)
- try:
service = MemoryService(
llm_profiles={"default": {"api_key": api_key}},
database_config={
@@ -44,47 +46,67 @@ async def main():
"provider": "sqlite",
"dsn": sqlite_dsn,
},
- # SQLite uses brute-force vector search
"vector_index": {"provider": "bruteforce"},
},
retrieve_config={"method": "rag"},
)
- # Memorize
print("\n[SQLITE] Memorizing...")
- memory = await service.memorize(resource_url=file_path, modality="conversation", user={"user_id": "123"})
+ memory = await service.memorize(resource_url=str(file_path), modality="conversation", user={"user_id": "123"})
for cat in memory.get("categories", []):
print(f" - {cat.get('name')}: {(cat.get('summary') or '')[:80]}...")
- queries = [
- {"role": "user", "content": {"text": "Tell me about preferences"}},
- {"role": "assistant", "content": {"text": "Sure, I'll tell you about their preferences"}},
- {
- "role": "user",
- "content": {"text": "What are they"},
- }, # This is the query that will be used to retrieve the memory
- ]
+ queries = _sample_queries()
- # RAG-based retrieval
service.retrieve_config.method = "rag"
result_rag = await service.retrieve(queries=queries, where={"user_id": "123"})
_print_results("RAG", result_rag)
- # LLM-based retrieval
service.retrieve_config.method = "llm"
result_llm = await service.retrieve(queries=queries, where={"user_id": "123"})
_print_results("LLM", result_llm)
print("\n[SQLITE] Test completed!")
- finally:
- # Clean up the temporary database file
- if os.path.exists(sqlite_path):
- os.unlink(sqlite_path)
- print(f"[SQLITE] Cleaned up temporary database: {sqlite_path}")
+async def test_sqlite_full_workflow() -> None:
+ """Opt-in pytest integration check for the SQLite backend and a real LLM."""
+ import pytest
+
+ if os.environ.get(RUN_LIVE_LLM_TESTS_ENV) != "1":
+ pytest.skip(f"Set {RUN_LIVE_LLM_TESTS_ENV}=1 to run live LLM storage workflows")
+ if not os.environ.get("OPENAI_API_KEY"):
+ pytest.skip("OPENAI_API_KEY is required for live LLM storage workflows")
+
+ await run_sqlite_workflow()
+
+
+def _sample_queries() -> list[dict[str, dict[str, str] | str]]:
+ return [
+ {"role": "user", "content": {"text": "Tell me about preferences"}},
+ {"role": "assistant", "content": {"text": "Sure, I'll tell you about their preferences"}},
+ {"role": "user", "content": {"text": "What are they"}},
+ ]
-if __name__ == "__main__":
- import asyncio
- asyncio.run(main())
+def _print_results(title: str, result: dict[str, Any]) -> None:
+ print(f"\n[SQLITE] RETRIEVED - {title}")
+ print(" Categories:")
+ for cat in result.get("categories", [])[:3]:
+ print(f" - {cat.get('name')}: {(cat.get('summary') or cat.get('description', ''))[:80]}...")
+ print(" Items:")
+ for item in result.get("items", [])[:3]:
+ print(f" - [{item.get('memory_type')}] {item.get('summary', '')[:100]}...")
+ if result.get("resources"):
+ print(" Resources:")
+ for res in result.get("resources", [])[:3]:
+ print(f" - [{res.get('modality')}] {res.get('url', '')[:80]}...")
+
+
+def main() -> int:
+ asyncio.run(run_sqlite_workflow())
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/tests/test_workflow_contracts.py b/tests/test_workflow_contracts.py
new file mode 100644
index 00000000..a83cd086
--- /dev/null
+++ b/tests/test_workflow_contracts.py
@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from memu.workflow.pipeline import PipelineManager
+from memu.workflow.step import WorkflowStep
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def _noop_step(state: dict[str, object], context: object) -> dict[str, object]:
+ return state
+
+
+def test_pipeline_manager_validates_all_llm_profile_config_keys() -> None:
+ manager = PipelineManager(available_capabilities={"llm"}, llm_profiles={"default"})
+
+ for profile_key in ("llm_profile", "chat_llm_profile", "embed_llm_profile"):
+ try:
+ manager.register(
+ f"pipeline_{profile_key}",
+ [
+ WorkflowStep(
+ step_id="step",
+ role="test",
+ handler=_noop_step,
+ capabilities={"llm"},
+ config={profile_key: "missing"},
+ )
+ ],
+ )
+ except ValueError as exc:
+ assert f"unknown {profile_key} 'missing'" in str(exc)
+ else:
+ raise AssertionError(f"PipelineManager should reject unknown {profile_key}")
+
+
+def test_pipeline_manager_rejects_blank_and_non_string_llm_profile_references() -> None:
+ manager = PipelineManager(available_capabilities={"llm"}, llm_profiles={"default"})
+
+ for value in ("", " ", 123):
+ try:
+ manager.register(
+ f"pipeline_{value!r}",
+ [
+ WorkflowStep(
+ step_id="step",
+ role="test",
+ handler=_noop_step,
+ capabilities={"llm"},
+ config={"chat_llm_profile": value},
+ )
+ ],
+ )
+ except ValueError as exc:
+ assert "profile name must be non-empty" in str(exc)
+ else:
+ raise AssertionError("PipelineManager should reject invalid profile references")
+
+
+def test_pipeline_manager_revalidates_profile_references_on_config_mutation() -> None:
+ manager = PipelineManager(available_capabilities={"llm"}, llm_profiles={"default"})
+ manager.register(
+ "pipeline",
+ [
+ WorkflowStep(
+ step_id="step",
+ role="test",
+ handler=_noop_step,
+ capabilities={"llm"},
+ config={"chat_llm_profile": "default"},
+ )
+ ],
+ )
+
+ try:
+ manager.config_step("pipeline", "step", {"chat_llm_profile": " "})
+ except ValueError as exc:
+ assert "profile name must be non-empty" in str(exc)
+ else:
+ raise AssertionError("PipelineManager should reject invalid profile references during mutation")
+
+
+def test_llm_retrieve_route_intention_step_declares_route_intention_dependency() -> None:
+ source = (ROOT / "src/memu/app/retrieve.py").read_text(encoding="utf-8")
+ workflow_source = _function_source(source, "_build_llm_retrieve_workflow")
+ route_step_source = workflow_source.split('step_id="route_category"', 1)[0]
+
+ assert 'requires={"route_intention", "original_query", "context_queries", "skip_rewrite"}' in route_step_source
+
+
+def _function_source(source: str, name: str) -> str:
+ module = ast.parse(source)
+ for node in ast.walk(module):
+ if isinstance(node, ast.FunctionDef) and node.name == name:
+ segment = ast.get_source_segment(source, node)
+ assert segment is not None
+ return segment
+ raise AssertionError(f"function {name!r} not found")
From 29632ed0697723ebab4001957f096a7ee610436d Mon Sep 17 00:00:00 2001
From: sairin1202 <952141617@qq.com>
Date: Fri, 5 Jun 2026 17:52:54 +0800
Subject: [PATCH 2/3] feat(self-evolve): gate markdown memory updates
---
...005-self-evolve-instruction-review-gate.md | 75 +++
src/memu/app/self_evolve.py | 621 ++++++++++++++++++
2 files changed, 696 insertions(+)
create mode 100644 docs/adr/0005-self-evolve-instruction-review-gate.md
create mode 100644 src/memu/app/self_evolve.py
diff --git a/docs/adr/0005-self-evolve-instruction-review-gate.md b/docs/adr/0005-self-evolve-instruction-review-gate.md
new file mode 100644
index 00000000..ef998a4e
--- /dev/null
+++ b/docs/adr/0005-self-evolve-instruction-review-gate.md
@@ -0,0 +1,75 @@
+# ADR 0005: Gate Self-Evolution Through Instructions and Reviewed Patches
+
+- Status: Accepted
+- Date: 2026-06-04
+
+## Context
+
+Markdown-backed context harnesses can ingest agent logs, creator feedback,
+uploaded files, observations, sidecars, and skill traces. Those raw sources are
+valuable evidence, but letting them rewrite `memory.md`, `soul.md`, or
+`skill.md` directly creates a self-contamination risk: noisy execution logs or
+unreviewed model output can become durable context and then influence the next
+context pack.
+
+The self-evolve path needs traceability and review without breaking the
+existing folder compiler ergonomics.
+
+## Decision
+
+Raw evidence must pass through this chain before it can update long-term
+Markdown context:
+
+```text
+raw_data/
+ agent logs
+ creator feedback
+ uploaded files
+ observations
+ -> Evidence extraction
+ -> EvolutionInstruction
+ -> PatchProposal
+ -> ReviewDecision
+ -> approved patches update memory.md, soul.md, skill.md
+```
+
+An `EvolutionInstruction` records the structured intent:
+
+- `target`: `memory`, `soul`, or `skill`
+- `operation`: `add`, `update`, or `delete`
+- `reason`
+- `evidence`
+- `priority`
+- `confidence`
+
+Each instruction becomes a `PatchProposal`. The review gate evaluates
+traceability, confidence, conflict markers, and patch safety. Approved proposals
+are applied to generated Markdown blocks and manifest entries. Proposals that
+need creator review remain auditable and do not update long-term context.
+
+The compiler writes audit artifacts under `.memu/evolution/`:
+
+- `instructions.jsonl`
+- `patch_proposals.jsonl`
+- `review_decisions.jsonl`
+- `latest.json`
+
+`FolderMemoryCompilerConfig.evolution_review` controls whether the review gate
+auto-approves safe proposals or requires creator review. The CLI exposes this
+with `--require-creator-review` and `--min-evolution-confidence`.
+
+## Consequences
+
+Positive:
+
+- raw logs and feedback cannot directly pollute durable context
+- every generated memory/soul/skill update has a structured provenance chain
+- creator-review workflows can block writes while preserving proposals
+- deleted sources also produce traceable delete proposals
+- existing folder compiler calls still work because safe proposals auto-approve by default
+
+Negative:
+
+- manifest records are larger because they include per-source evolution audits
+- manual-review mode can leave sources pending and therefore re-propose changes
+- lightweight local conflict detection is heuristic until an LLM-backed reviewer is added
diff --git a/src/memu/app/self_evolve.py b/src/memu/app/self_evolve.py
new file mode 100644
index 00000000..006e04c1
--- /dev/null
+++ b/src/memu/app/self_evolve.py
@@ -0,0 +1,621 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Literal, cast
+
+
+EvolutionTarget = Literal["memory", "soul", "skill"]
+EvolutionOperation = Literal["add", "update", "delete"]
+EvolutionPriority = Literal["low", "medium", "high"]
+EvolutionSourceKind = Literal["agent_log", "creator_feedback", "user_upload", "observation", "unknown"]
+ReviewStatus = Literal["approved", "needs_review", "rejected"]
+
+
+@dataclass(frozen=True)
+class EvolutionReviewConfig:
+ """Policy used by the review gate before patches update long-term context."""
+
+ auto_approve: bool = True
+ min_confidence: float = 0.0
+ require_traceable_evidence: bool = True
+ require_conflict_review: bool = True
+
+
+@dataclass(frozen=True)
+class EvidenceRecord:
+ """Traceable evidence summary used by an evolution instruction."""
+
+ source: str
+ evidence_path: str
+ source_kind: EvolutionSourceKind
+ attribution: str
+ summary: str
+ conflicts: list[str] = field(default_factory=list)
+
+ def to_dict(self) -> dict[str, Any]:
+ return {
+ "source": self.source,
+ "evidence_path": self.evidence_path,
+ "source_kind": self.source_kind,
+ "attribution": self.attribution,
+ "summary": self.summary,
+ "conflicts": list(self.conflicts),
+ }
+
+ @classmethod
+ def from_dict(cls, data: Mapping[str, Any]) -> EvidenceRecord:
+ return cls(
+ source=str(data.get("source", "")),
+ evidence_path=str(data.get("evidence_path", "")),
+ source_kind=cast(EvolutionSourceKind, data.get("source_kind", "unknown")),
+ attribution=str(data.get("attribution", "")),
+ summary=str(data.get("summary", "")),
+ conflicts=[str(item) for item in data.get("conflicts", [])],
+ )
+
+
+@dataclass(frozen=True)
+class EvolutionInstruction:
+ """Structured instruction distilled from raw evidence before any patch is proposed."""
+
+ id: str
+ target: EvolutionTarget
+ operation: EvolutionOperation
+ reason: str
+ evidence: EvidenceRecord
+ priority: EvolutionPriority
+ confidence: float
+ content: dict[str, Any]
+ created_at: str = field(default_factory=lambda: _utc_now())
+
+ def to_dict(self) -> dict[str, Any]:
+ return {
+ "id": self.id,
+ "target": self.target,
+ "operation": self.operation,
+ "reason": self.reason,
+ "evidence": self.evidence.to_dict(),
+ "priority": self.priority,
+ "confidence": self.confidence,
+ "content": dict(self.content),
+ "created_at": self.created_at,
+ }
+
+ @classmethod
+ def from_dict(cls, data: Mapping[str, Any]) -> EvolutionInstruction:
+ evidence = data.get("evidence", {})
+ return cls(
+ id=str(data.get("id", "")),
+ target=cast(EvolutionTarget, data.get("target", "memory")),
+ operation=cast(EvolutionOperation, data.get("operation", "add")),
+ reason=str(data.get("reason", "")),
+ evidence=EvidenceRecord.from_dict(evidence if isinstance(evidence, Mapping) else {}),
+ priority=cast(EvolutionPriority, data.get("priority", "medium")),
+ confidence=float(data.get("confidence", 0.0)),
+ content=dict(data.get("content", {})) if isinstance(data.get("content", {}), Mapping) else {},
+ created_at=str(data.get("created_at") or _utc_now()),
+ )
+
+
+@dataclass(frozen=True)
+class PatchProposal:
+ """A proposed change to memory.md, soul.md, or skill.md derived from an instruction."""
+
+ id: str
+ instruction_id: str
+ target: EvolutionTarget
+ operation: EvolutionOperation
+ target_path: str
+ summary: str
+ patch: dict[str, Any]
+ reason: str
+ evidence: EvidenceRecord
+ priority: EvolutionPriority
+ confidence: float
+ created_at: str = field(default_factory=lambda: _utc_now())
+
+ def to_dict(self) -> dict[str, Any]:
+ return {
+ "id": self.id,
+ "instruction_id": self.instruction_id,
+ "target": self.target,
+ "operation": self.operation,
+ "target_path": self.target_path,
+ "summary": self.summary,
+ "patch": dict(self.patch),
+ "reason": self.reason,
+ "evidence": self.evidence.to_dict(),
+ "priority": self.priority,
+ "confidence": self.confidence,
+ "created_at": self.created_at,
+ }
+
+ @classmethod
+ def from_dict(cls, data: Mapping[str, Any]) -> PatchProposal:
+ evidence = data.get("evidence", {})
+ return cls(
+ id=str(data.get("id", "")),
+ instruction_id=str(data.get("instruction_id", "")),
+ target=cast(EvolutionTarget, data.get("target", "memory")),
+ operation=cast(EvolutionOperation, data.get("operation", "add")),
+ target_path=str(data.get("target_path", "memory.md")),
+ summary=str(data.get("summary", "")),
+ patch=dict(data.get("patch", {})) if isinstance(data.get("patch", {}), Mapping) else {},
+ reason=str(data.get("reason", "")),
+ evidence=EvidenceRecord.from_dict(evidence if isinstance(evidence, Mapping) else {}),
+ priority=cast(EvolutionPriority, data.get("priority", "medium")),
+ confidence=float(data.get("confidence", 0.0)),
+ created_at=str(data.get("created_at") or _utc_now()),
+ )
+
+
+@dataclass(frozen=True)
+class ReviewDecision:
+ """Review-gate decision for a patch proposal."""
+
+ proposal_id: str
+ status: ReviewStatus
+ reviewer: str
+ reason: str
+ confidence: float
+ safety_flags: list[str] = field(default_factory=list)
+ reviewed_at: str = field(default_factory=lambda: _utc_now())
+
+ @property
+ def approved(self) -> bool:
+ return self.status == "approved"
+
+ def to_dict(self) -> dict[str, Any]:
+ return {
+ "proposal_id": self.proposal_id,
+ "status": self.status,
+ "reviewer": self.reviewer,
+ "reason": self.reason,
+ "confidence": self.confidence,
+ "safety_flags": list(self.safety_flags),
+ "reviewed_at": self.reviewed_at,
+ }
+
+ @classmethod
+ def from_dict(cls, data: Mapping[str, Any]) -> ReviewDecision:
+ return cls(
+ proposal_id=str(data.get("proposal_id", "")),
+ status=cast(ReviewStatus, data.get("status", "needs_review")),
+ reviewer=str(data.get("reviewer", "")),
+ reason=str(data.get("reason", "")),
+ confidence=float(data.get("confidence", 0.0)),
+ safety_flags=[str(flag) for flag in data.get("safety_flags", [])],
+ reviewed_at=str(data.get("reviewed_at") or _utc_now()),
+ )
+
+
+@dataclass(frozen=True)
+class EvolutionReviewBundle:
+ """The auditable self-evolve chain for one source or removal."""
+
+ instructions: list[EvolutionInstruction]
+ proposals: list[PatchProposal]
+ reviews: list[ReviewDecision]
+
+ def to_dict(self) -> dict[str, Any]:
+ return {
+ "instructions": [instruction.to_dict() for instruction in self.instructions],
+ "patch_proposals": [proposal.to_dict() for proposal in self.proposals],
+ "review_decisions": [review.to_dict() for review in self.reviews],
+ }
+
+
+class SelfEvolveEngine:
+ """Convert evidence-backed candidates into reviewed long-term context patches."""
+
+ def __init__(self, review_config: EvolutionReviewConfig | None = None) -> None:
+ self.review_config = review_config or EvolutionReviewConfig()
+
+ def build_for_source(
+ self,
+ *,
+ source: str,
+ evidence_path: str,
+ evidence_text: str,
+ candidates: Sequence[Mapping[str, Any]],
+ previous_entries: Sequence[Mapping[str, Any]] = (),
+ ) -> EvolutionReviewBundle:
+ source_kind = classify_evolution_source(source, evidence_text)
+ instructions = self.extract_instructions(
+ source=source,
+ evidence_path=evidence_path,
+ evidence_text=evidence_text,
+ source_kind=source_kind,
+ candidates=candidates,
+ previous_entries=previous_entries,
+ )
+ return self._review_instructions(instructions)
+
+ def build_for_removed_source(
+ self,
+ *,
+ source: str,
+ evidence_path: str,
+ previous_entries: Sequence[Mapping[str, Any]],
+ ) -> EvolutionReviewBundle:
+ instructions: list[EvolutionInstruction] = []
+ source_kind = classify_evolution_source(source, "")
+ for entry in previous_entries:
+ target = cast(EvolutionTarget, str(entry.get("bucket", "memory")))
+ evidence = EvidenceRecord(
+ source=source,
+ evidence_path=evidence_path,
+ source_kind=source_kind,
+ attribution="Manifest entry generated from a source that is no longer present.",
+ summary=_entry_summary(entry),
+ conflicts=[],
+ )
+ content = {
+ "entry_id": str(entry.get("id", "")),
+ "previous_entry": dict(entry),
+ }
+ instructions.append(
+ EvolutionInstruction(
+ id=_stable_id("evi", source, target, "delete", str(entry.get("id", ""))),
+ target=target,
+ operation="delete",
+ reason="Remove long-term context that was generated from a deleted raw source.",
+ evidence=evidence,
+ priority="medium",
+ confidence=1.0,
+ content=content,
+ )
+ )
+ return self._review_instructions(instructions)
+
+ def extract_instructions(
+ self,
+ *,
+ source: str,
+ evidence_path: str,
+ evidence_text: str,
+ source_kind: EvolutionSourceKind,
+ candidates: Sequence[Mapping[str, Any]],
+ previous_entries: Sequence[Mapping[str, Any]] = (),
+ ) -> list[EvolutionInstruction]:
+ previous_by_id = {str(entry.get("id", "")): dict(entry) for entry in previous_entries if entry.get("id")}
+ candidate_ids: set[str] = set()
+ instructions: list[EvolutionInstruction] = []
+
+ for candidate in candidates:
+ entry_id = str(candidate.get("id", ""))
+ if not entry_id:
+ continue
+ candidate_ids.add(entry_id)
+ operation: EvolutionOperation = "update" if entry_id in previous_by_id else "add"
+ target = cast(EvolutionTarget, str(candidate.get("bucket", "memory")))
+ conflicts = detect_evidence_conflicts(evidence_text)
+ evidence = EvidenceRecord(
+ source=source,
+ evidence_path=evidence_path,
+ source_kind=source_kind,
+ attribution=self._attribution_for(source_kind, source),
+ summary=_entry_summary(candidate),
+ conflicts=conflicts,
+ )
+ content = {
+ "entry": dict(candidate),
+ "previous_entry": previous_by_id.get(entry_id),
+ }
+ instructions.append(
+ EvolutionInstruction(
+ id=_stable_id("evi", source, target, operation, entry_id, _entry_summary(candidate)),
+ target=target,
+ operation=operation,
+ reason=self._reason_for(operation, target, source_kind),
+ evidence=evidence,
+ priority=self._priority_for(source_kind, conflicts, candidate),
+ confidence=confidence_score(candidate.get("confidence")),
+ content=content,
+ )
+ )
+
+ for entry_id, previous in previous_by_id.items():
+ if entry_id in candidate_ids:
+ continue
+ target = cast(EvolutionTarget, str(previous.get("bucket", "memory")))
+ evidence = EvidenceRecord(
+ source=source,
+ evidence_path=evidence_path,
+ source_kind=source_kind,
+ attribution=self._attribution_for(source_kind, source),
+ summary=_entry_summary(previous),
+ conflicts=[],
+ )
+ instructions.append(
+ EvolutionInstruction(
+ id=_stable_id("evi", source, target, "delete", entry_id),
+ target=target,
+ operation="delete",
+ reason="Remove stale generated context that is no longer supported by current evidence.",
+ evidence=evidence,
+ priority="medium",
+ confidence=1.0,
+ content={
+ "entry_id": entry_id,
+ "previous_entry": dict(previous),
+ },
+ )
+ )
+
+ return instructions
+
+ def _review_instructions(self, instructions: Sequence[EvolutionInstruction]) -> EvolutionReviewBundle:
+ proposals = [self.build_patch_proposal(instruction) for instruction in instructions]
+ reviews = [self.review_patch_proposal(proposal) for proposal in proposals]
+ return EvolutionReviewBundle(instructions=list(instructions), proposals=proposals, reviews=reviews)
+
+ def build_patch_proposal(self, instruction: EvolutionInstruction) -> PatchProposal:
+ target_path = f"{instruction.target}.md"
+ entry = instruction.content.get("entry")
+ entry_id = instruction.content.get("entry_id")
+ if instruction.operation in {"add", "update"} and isinstance(entry, Mapping):
+ patch: dict[str, Any] = {"entry": dict(entry)}
+ summary = _entry_summary(entry)
+ else:
+ patch = {"entry_id": str(entry_id or "")}
+ summary = f"Remove generated entry {entry_id}"
+ return PatchProposal(
+ id=_stable_id("patch", instruction.id, instruction.operation, target_path),
+ instruction_id=instruction.id,
+ target=instruction.target,
+ operation=instruction.operation,
+ target_path=target_path,
+ summary=summary,
+ patch=patch,
+ reason=instruction.reason,
+ evidence=instruction.evidence,
+ priority=instruction.priority,
+ confidence=instruction.confidence,
+ )
+
+ def review_patch_proposal(self, proposal: PatchProposal) -> ReviewDecision:
+ flags = self._safety_flags(proposal)
+ if proposal.confidence < self.review_config.min_confidence:
+ flags.append("below_min_confidence")
+ if proposal.evidence.conflicts and self.review_config.require_conflict_review:
+ flags.append("conflict_detected")
+
+ if not self.review_config.auto_approve:
+ return ReviewDecision(
+ proposal_id=proposal.id,
+ status="needs_review",
+ reviewer="creator",
+ reason="Creator review is required before this patch can update long-term context.",
+ confidence=proposal.confidence,
+ safety_flags=flags,
+ )
+ if flags:
+ return ReviewDecision(
+ proposal_id=proposal.id,
+ status="needs_review",
+ reviewer="auto-review",
+ reason="Patch requires review because one or more safety checks did not pass.",
+ confidence=proposal.confidence,
+ safety_flags=flags,
+ )
+ return ReviewDecision(
+ proposal_id=proposal.id,
+ status="approved",
+ reviewer="auto-review",
+ reason="Patch passed traceability, confidence, and safety checks.",
+ confidence=proposal.confidence,
+ safety_flags=[],
+ )
+
+ def _safety_flags(self, proposal: PatchProposal) -> list[str]:
+ flags: list[str] = []
+ if proposal.target not in {"memory", "soul", "skill"}:
+ flags.append("invalid_target")
+ if proposal.operation not in {"add", "update", "delete"}:
+ flags.append("invalid_operation")
+ if self.review_config.require_traceable_evidence:
+ if not proposal.evidence.source:
+ flags.append("missing_evidence_source")
+ if not proposal.evidence.evidence_path:
+ flags.append("missing_evidence_path")
+ if proposal.operation in {"add", "update"} and not isinstance(proposal.patch.get("entry"), Mapping):
+ flags.append("missing_patch_entry")
+ if proposal.operation == "delete" and not proposal.patch.get("entry_id"):
+ flags.append("missing_delete_entry_id")
+ return flags
+
+ def _attribution_for(self, source_kind: EvolutionSourceKind, source: str) -> str:
+ if source_kind == "agent_log":
+ return f"Agent execution evidence from {source}."
+ if source_kind == "creator_feedback":
+ return f"Creator-authored feedback from {source}."
+ if source_kind == "observation":
+ return f"New observation evidence from {source}."
+ if source_kind == "user_upload":
+ return f"User-uploaded evidence from {source}."
+ return f"Evidence from {source}."
+
+ def _reason_for(
+ self,
+ operation: EvolutionOperation,
+ target: EvolutionTarget,
+ source_kind: EvolutionSourceKind,
+ ) -> str:
+ source_phrase = source_kind.replace("_", " ")
+ if operation == "delete":
+ return f"Delete stale {target} context because the source evidence no longer supports it."
+ if operation == "update":
+ return f"Update {target} context using structured evidence extracted from {source_phrase}."
+ return f"Add {target} context using structured evidence extracted from {source_phrase}."
+
+ def _priority_for(
+ self,
+ source_kind: EvolutionSourceKind,
+ conflicts: Sequence[str],
+ candidate: Mapping[str, Any],
+ ) -> EvolutionPriority:
+ if conflicts or source_kind == "creator_feedback":
+ return "high"
+ if str(candidate.get("bucket", "")) == "skill" or source_kind == "agent_log":
+ return "medium"
+ return "low"
+
+
+def apply_reviewed_proposals(
+ previous_entries: Sequence[Mapping[str, Any]],
+ proposals: Sequence[PatchProposal],
+ reviews: Sequence[ReviewDecision],
+) -> list[dict[str, Any]]:
+ """Apply only approved proposals to a source's existing generated entries."""
+
+ entries_by_id = {str(entry.get("id", "")): dict(entry) for entry in previous_entries if entry.get("id")}
+ order = [str(entry.get("id", "")) for entry in previous_entries if entry.get("id")]
+ review_by_proposal = {review.proposal_id: review for review in reviews}
+ for proposal in proposals:
+ review = review_by_proposal.get(proposal.id)
+ if review is None or not review.approved:
+ continue
+ if proposal.operation in {"add", "update"}:
+ entry = proposal.patch.get("entry")
+ if not isinstance(entry, Mapping):
+ continue
+ entry_id = str(entry.get("id", ""))
+ if not entry_id:
+ continue
+ entries_by_id[entry_id] = dict(entry)
+ if entry_id not in order:
+ order.append(entry_id)
+ elif proposal.operation == "delete":
+ entry_id = str(proposal.patch.get("entry_id", ""))
+ entries_by_id.pop(entry_id, None)
+ order = [item for item in order if item != entry_id]
+ return [entries_by_id[entry_id] for entry_id in order if entry_id in entries_by_id]
+
+
+def classify_evolution_source(source: str, evidence_text: str) -> EvolutionSourceKind:
+ lowered_source = source.lower()
+ lowered_evidence = evidence_text.lower()
+ if "skill_traces/" in lowered_source or "agent_log" in lowered_source or "agent-log" in lowered_source:
+ return "agent_log"
+ if "skill evolution trace" in lowered_evidence:
+ return "agent_log"
+ if "creator" in lowered_source or "feedback" in lowered_source:
+ return "creator_feedback"
+ if "observation" in lowered_source or "new_observation" in lowered_source:
+ return "observation"
+ if source:
+ return "user_upload"
+ return "unknown"
+
+
+def detect_evidence_conflicts(evidence_text: str) -> list[str]:
+ lowered = evidence_text.lower()
+ markers = (
+ "conflict",
+ "contradict",
+ "correction",
+ "instead of",
+ "replace previous",
+ "actually",
+ )
+ if any(marker in lowered for marker in markers):
+ return ["Evidence contains language that may conflict with existing long-term context."]
+ return []
+
+
+def confidence_score(value: Any) -> float:
+ if isinstance(value, int | float) and not isinstance(value, bool):
+ return max(0.0, min(float(value), 1.0))
+ lowered = str(value or "").strip().lower()
+ if lowered == "high":
+ return 0.9
+ if lowered == "medium":
+ return 0.65
+ if lowered == "low":
+ return 0.35
+ return 0.5
+
+
+def write_evolution_audit(
+ metadata_dir: str | Path,
+ *,
+ instructions: Sequence[EvolutionInstruction],
+ proposals: Sequence[PatchProposal],
+ reviews: Sequence[ReviewDecision],
+) -> None:
+ if not instructions and not proposals and not reviews:
+ return
+ evolution_dir = Path(metadata_dir) / "evolution"
+ evolution_dir.mkdir(parents=True, exist_ok=True)
+ _append_jsonl(evolution_dir / "instructions.jsonl", [instruction.to_dict() for instruction in instructions])
+ _append_jsonl(evolution_dir / "patch_proposals.jsonl", [proposal.to_dict() for proposal in proposals])
+ _append_jsonl(evolution_dir / "review_decisions.jsonl", [review.to_dict() for review in reviews])
+ latest = {
+ "updated_at": _utc_now(),
+ "instructions": [instruction.to_dict() for instruction in instructions],
+ "patch_proposals": [proposal.to_dict() for proposal in proposals],
+ "review_decisions": [review.to_dict() for review in reviews],
+ }
+ (evolution_dir / "latest.json").write_text(
+ json.dumps(latest, indent=2, ensure_ascii=False, sort_keys=True),
+ encoding="utf-8",
+ )
+
+
+def _append_jsonl(path: Path, records: Sequence[Mapping[str, Any]]) -> None:
+ if not records:
+ return
+ with path.open("a", encoding="utf-8") as handle:
+ for record in records:
+ handle.write(json.dumps(record, ensure_ascii=False, sort_keys=True))
+ handle.write("\n")
+
+
+def _entry_summary(entry: Mapping[str, Any]) -> str:
+ title = str(entry.get("title", "")).strip()
+ body = str(entry.get("body", "")).strip()
+ summary = title or body
+ if "\n" in summary:
+ summary = summary.splitlines()[0].strip()
+ if len(summary) > 180:
+ return summary[:177].rstrip() + "..."
+ return summary
+
+
+def _stable_id(prefix: str, *parts: object) -> str:
+ digest = hashlib.sha256()
+ for part in parts:
+ digest.update(str(part).encode("utf-8"))
+ digest.update(b"\0")
+ return f"{prefix}_{digest.hexdigest()[:16]}"
+
+
+def _utc_now() -> str:
+ return datetime.now(UTC).isoformat().replace("+00:00", "Z")
+
+
+__all__ = [
+ "EvidenceRecord",
+ "EvolutionInstruction",
+ "EvolutionOperation",
+ "EvolutionPriority",
+ "EvolutionReviewBundle",
+ "EvolutionReviewConfig",
+ "EvolutionSourceKind",
+ "EvolutionTarget",
+ "PatchProposal",
+ "ReviewDecision",
+ "ReviewStatus",
+ "SelfEvolveEngine",
+ "apply_reviewed_proposals",
+ "classify_evolution_source",
+ "confidence_score",
+ "detect_evidence_conflicts",
+ "write_evolution_audit",
+]
From eefb7f0e0cb7439f441d29b32e9db6cb27fe8b10 Mon Sep 17 00:00:00 2001
From: sairin1202 <952141617@qq.com>
Date: Fri, 5 Jun 2026 17:54:06 +0800
Subject: [PATCH 3/3] feat(harness): add markdown context repository
---
MANIFEST.in | 31 +-
README.md | 207 +-
assets/memu-overall-algorithm-flow.png | Bin 0 -> 1519861 bytes
.../memu-overall-engineering-architecture.png | Bin 0 -> 1419826 bytes
assets/memu-self-evolve-algorithm.png | Bin 0 -> 1370627 bytes
assets/memu-self-evolve-architecture.png | Bin 0 -> 1214106 bytes
...own-context-harness-and-skill-evolution.md | 78 +
docs/adr/README.md | 2 +
docs/architecture.md | 215 +-
docs/folder_memory_compiler.md | 554 ++++
docs/index.md | 27 +
examples/context_harness_demo.py | 79 +
mkdocs.yml | 50 +
pyproject.toml | 24 +-
src/memu/__init__.py | 214 +-
src/memu/_version.py | 5 +
src/memu/app/__init__.py | 185 +-
src/memu/app/cli_args.py | 36 +
src/memu/app/context_cli.py | 162 ++
src/memu/app/context_harness.py | 600 +++++
src/memu/app/context_harness_cli.py | 761 ++++++
src/memu/app/folder.py | 2256 +++++++++++++++++
src/memu/app/folder_cli.py | 270 ++
src/memu/app/harness_config.py | 233 ++
src/memu/app/markdown_context.py | 501 ++++
src/memu/app/skill_trace.py | 710 ++++++
src/memu/app/skill_trace_cli.py | 128 +
src/memu/py.typed | 1 +
tests/test_folder_compiler.py | 1840 ++++++++++++++
tests/test_repository_docs.py | 1592 ++++++++++++
uv.lock | 18 +-
31 files changed, 10684 insertions(+), 95 deletions(-)
create mode 100644 assets/memu-overall-algorithm-flow.png
create mode 100644 assets/memu-overall-engineering-architecture.png
create mode 100644 assets/memu-self-evolve-algorithm.png
create mode 100644 assets/memu-self-evolve-architecture.png
create mode 100644 docs/adr/0004-markdown-context-harness-and-skill-evolution.md
create mode 100644 docs/folder_memory_compiler.md
create mode 100644 docs/index.md
create mode 100644 examples/context_harness_demo.py
create mode 100644 mkdocs.yml
create mode 100644 src/memu/_version.py
create mode 100644 src/memu/app/cli_args.py
create mode 100644 src/memu/app/context_cli.py
create mode 100644 src/memu/app/context_harness.py
create mode 100644 src/memu/app/context_harness_cli.py
create mode 100644 src/memu/app/folder.py
create mode 100644 src/memu/app/folder_cli.py
create mode 100644 src/memu/app/harness_config.py
create mode 100644 src/memu/app/markdown_context.py
create mode 100644 src/memu/app/skill_trace.py
create mode 100644 src/memu/app/skill_trace_cli.py
create mode 100644 src/memu/py.typed
create mode 100644 tests/test_folder_compiler.py
create mode 100644 tests/test_repository_docs.py
diff --git a/MANIFEST.in b/MANIFEST.in
index 988fe526..bceab991 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,21 +1,28 @@
include README.md
-recursive-include memu *.py
-prune example
-include setup_postgres_env.sh
+include LICENSE.txt
+include CODE_OF_CONDUCT.md
+include CONTRIBUTING.md
+include SECURITY.md
+include SUPPORT.md
+include pyproject.toml
+include Cargo.toml
+include Cargo.lock
+include mkdocs.yml
+recursive-include src/memu *.py *.pyi py.typed
+recursive-include assets *.png *.gif *.jpg *.jpeg
+recursive-include readme *.md
+recursive-include docs *.md
+recursive-include examples *.py *.md *.json *.txt *.png *.jpg *.jpeg *.sh .env.example
exclude .env
-exclude .env.example
exclude setup.py.backup
-exclude */__pycache__/*
-exclude *.pyc
-exclude *.pyo
-exclude .git/*
-exclude .github/*
-exclude server/*
-exclude docs/*
-exclude scripts/*
exclude docker-compose.yml
exclude Dockerfile
exclude .dockerignore
exclude PROJECT_RELEASE_SUMMARY.md
exclude Makefile
exclude .pre-commit-config.yaml
+prune .git
+prune .github
+prune tmp
+global-exclude __pycache__
+global-exclude *.py[cod]
diff --git a/README.md b/README.md
index c0d2e36d..6460d346 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
[](https://badge.fury.io/py/memu-py)
[](https://opensource.org/licenses/Apache-2.0)
-[](https://www.python.org/downloads/)
+[](https://www.python.org/downloads/)
[](https://discord.com/invite/hQZntfGsbJ)
[](https://x.com/memU_ai)
@@ -28,7 +28,7 @@ memU **continuously captures and understands user intent**. Even without a comma
## 🤖 [OpenClaw Alternative](https://github.com/NevaMind-AI/memUBot)
-
+
**[memU Bot](https://github.com/NevaMind-AI/memUBot)** — Now open source. The enterprise-ready OpenClaw. Your proactive AI assistant that remembers everything.
@@ -79,7 +79,7 @@ Just as a file system turns raw bytes into organized data, memU transforms raw i
## ⭐️ Star the repository
-
+
If you find memU useful or interesting, a GitHub Star ⭐️ would be greatly appreciated.
---
@@ -97,10 +97,14 @@ If you find memU useful or interesting, a GitHub Star ⭐️ would be greatly ap
## 🔄 How Proactive Memory Works
```bash
-
+pip install "memu-py[claude]"
+# From a source checkout, use: uv sync --extra claude
+export OPENAI_API_KEY="..."
+export ANTHROPIC_API_KEY="..."
+# Optional when using memory.platform instead of memory.local:
+export MEMU_API_KEY="..."
cd examples/proactive
python proactive.py
-
```
---
@@ -233,6 +237,8 @@ MemU's three-layer system enables both **reactive queries** and **proactive cont
+
+
| Layer | Reactive Use | Proactive Use |
|-------|--------------|---------------|
| **Resource** | Direct access to original data | Background monitoring for new patterns |
@@ -277,21 +283,34 @@ For enterprise deployment with custom proactive workflows, contact **info@nevami
#### Installation
```bash
-pip install -e .
+pip install memu-py
+```
+
+For local source development, clone this repository and install the editable
+workspace:
+
+```bash
+make install
```
#### Basic Example
-> **Requirements**: Python 3.13+ and an OpenAI API key
+> **Requirements**: Python 3.12+ and an OpenAI API key
+
+Run the getting-started example:
-**Test Continuous Learning** (in-memory):
```bash
export OPENAI_API_KEY=your_api_key
-cd tests
-python test_inmemory.py
+python examples/getting_started_robust.py
```
-**Test with Persistent Storage** (PostgreSQL):
+The example initializes `MemoryService`, creates a memory item, and retrieves it
+with a natural-language query. See
+[`examples/getting_started_robust.py`](examples/getting_started_robust.py) for
+the full script.
+
+**Optional PostgreSQL integration check**:
+
```bash
# Start PostgreSQL with pgvector
docker run -d \
@@ -302,18 +321,94 @@ docker run -d \
-p 5432:5432 \
pgvector/pgvector:pg16
-# Run continuous learning test
+# Run the opt-in PostgreSQL integration test
+uv sync --extra postgres
export OPENAI_API_KEY=your_api_key
-cd tests
-python test_postgres.py
+export MEMU_RUN_POSTGRES_TESTS=1
+uv run python -m pytest tests/test_postgres.py
```
-Both examples demonstrate **proactive memory workflows**:
+These flows demonstrate **proactive memory workflows**:
1. **Continuous Ingestion**: Process multiple files sequentially
2. **Auto-Extraction**: Immediate memory creation
3. **Proactive Retrieval**: Context-aware memory surfacing
-See [`tests/test_inmemory.py`](tests/test_inmemory.py) and [`tests/test_postgres.py`](tests/test_postgres.py) for implementation details.
+See [`tests/test_inmemory.py`](tests/test_inmemory.py), [`tests/test_sqlite.py`](tests/test_sqlite.py),
+and [`tests/test_postgres.py`](tests/test_postgres.py) for implementation details. The
+in-memory and SQLite live LLM checks are opt-in with `MEMU_RUN_LIVE_LLM_TESTS=1`.
+
+### Context Harness: Folder to Markdown Memory
+
+For local agents that need inspectable context files, memU can compile a folder
+of raw data into a Markdown-backed memory repository:
+
+
+
+```text
+memory_repo/
+ AGENTS.md
+ raw_data/
+ memory.md
+ memory/
+ soul.md
+ soul/
+ skill.md
+ skill/
+ .memu/
+ harness.json
+ evolution/
+```
+
+Quick CLI workflow:
+
+```bash
+memu-harness init memory_repo --source-folder path/to/uploaded-folder
+memu-harness doctor memory_repo --json
+memu-harness status memory_repo --json
+memu-harness refresh memory_repo --query "current agent task"
+memu-harness review-evolution memory_repo
+memu-harness refresh memory_repo --exclude "node_modules/**" --exclude "*.tmp"
+memu-harness promote-skill memory_repo \
+ --title "Validate Context Packs" \
+ --lesson "Inspect promoted skills before relying on generated context"
+memu-harness suggest-skills memory_repo --json
+memu-harness context memory_repo --query "current agent task"
+memu-harness context memory_repo --query "current agent task" --format summary
+memu-harness context memory_repo --query "current agent task" --format messages
+memu-harness context memory_repo --bucket-max soul=1000 --bucket-max skill=2000
+memu-harness context memory_repo --format system --output context.system.md
+```
+
+This flow preserves multimodal files in `raw_data/`, supports sidecar captions,
+summaries, notes, and transcripts such as `screenshot.caption.md` or
+`report.summary.md`, updates changed files incrementally, and keeps manual skill
+notes outside generated blocks. Raw logs, creator feedback, uploads, and new
+observations do not edit `memory.md`, `soul.md`, or `skill.md` directly; memU
+first turns them into Evolution Instructions, Patch Proposals, and review
+decisions, with audit records under `.memu/evolution/`. Exclude noisy files
+explicitly with `--exclude` or a `.memuignore` file. `init` also creates
+`.memu/harness.json`, where the
+repository can persist non-secret defaults such as exclude globs, text evidence
+limits, context budgets, and context output format. Both `memu-harness context`
+and standalone `memu-context` read those context defaults. Skill traces can be
+turned into promotion suggestions with `suggest-skills`; promoted skills are
+also stored as stable cards under `skill/promoted/`. New harness repositories
+include an `AGENTS.md` bootstrap file so local coding agents can discover the
+memory, soul, skill, raw data, and skill-evolution conventions directly from
+the repository. Python callers can use `ContextHarness.from_repo("memory_repo")`
+to refresh and build context from `memory_repo/raw_data` with the same repo
+defaults.
+
+
+
+Run the no-API-key demo:
+
+```bash
+python examples/context_harness_demo.py
+```
+
+See [`docs/folder_memory_compiler.md`](docs/folder_memory_compiler.md) for the
+full harness API, CLI, watcher, status report, and self-evolving skill workflow.
---
@@ -328,14 +423,14 @@ service = MemUService(
# Default profile for LLM operations
"default": {
"base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
- "api_key": "your_api_key",
+ "api_key": "MEMU_QWEN_API_KEY",
"chat_model": "qwen3-max",
- "client_backend": "sdk" # "sdk" or "http"
+ "client_backend": "sdk" # "sdk", "httpx", or "lazyllm_backend"
},
# Separate profile for embeddings
"embedding": {
"base_url": "https://api.voyageai.com/v1",
- "api_key": "your_voyage_api_key",
+ "api_key": "VOYAGE_API_KEY",
"embed_model": "voyage-3.5-lite"
}
},
@@ -343,6 +438,24 @@ service = MemUService(
)
```
+The `lazyllm_backend` adapter is optional. Install it with
+`pip install "memu-py[lazyllm]"` or, from a source checkout,
+`uv sync --extra lazyllm`.
+
+Optional LazyLLM live check:
+
+```bash
+uv sync --extra lazyllm
+export MEMU_QWEN_API_KEY=your_api_key
+export MEMU_RUN_LAZYLLM_TESTS=1
+uv run python -m pytest tests/test_lazyllm.py
+```
+
+Retrieve routing can also use distinct profiles: set
+`route_intention_llm_profile`, `sufficiency_check_llm_profile`, and
+`llm_ranking_llm_profile` in `retrieve_config` to split cheap routing from
+heavier ranking or judging models.
+
---
### OpenRouter Integration
@@ -359,7 +472,7 @@ service = MemoryService(
"provider": "openrouter",
"client_backend": "httpx",
"base_url": "https://openrouter.ai",
- "api_key": "your_openrouter_api_key",
+ "api_key": "OPENROUTER_API_KEY",
"chat_model": "anthropic/claude-3.5-sonnet", # Any OpenRouter model
"embed_model": "openai/text-embedding-3-small", # Embedding model
},
@@ -387,15 +500,10 @@ service = MemoryService(
#### Running OpenRouter Tests
```bash
export OPENROUTER_API_KEY=your_api_key
+export MEMU_RUN_OPENROUTER_TESTS=1
# Full workflow test (memorize + retrieve)
-python tests/test_openrouter.py
-
-# Embedding-specific tests
-python tests/test_openrouter_embedding.py
-
-# Vision-specific tests
-python tests/test_openrouter_vision.py
+uv run python -m pytest tests/test_openrouter.py
```
See [`examples/example_4_openrouter_memory.py`](examples/example_4_openrouter_memory.py) for a complete working example.
@@ -404,6 +512,8 @@ See [`examples/example_4_openrouter_memory.py`](examples/example_4_openrouter_me
## 📖 Core APIs
+
+
### `memorize()` - Continuous Learning Pipeline
Processes inputs in real-time and immediately updates memory:
@@ -466,11 +576,12 @@ Deep **anticipatory reasoning** for complex contexts:
# Proactive retrieval with context history
result = await service.retrieve(
queries=[
- {"role": "user", "content": {"text": "What are their preferences?"}},
- {"role": "user", "content": {"text": "Tell me about work habits"}}
+ {"role": "user", "content": "What are their preferences?"},
+ {"role": "user", "content": "Tell me about work habits"}
],
where={"user_id": "123"}, # Optional: scope filter
- method="rag" # or "llm" for deeper reasoning
+ method="rag", # or "llm" for deeper reasoning
+ ranking="salience", # or "similarity" for RAG item recall
)
# Returns context-aware results:
@@ -482,11 +593,15 @@ result = await service.retrieve(
}
```
+For a single user query, Python callers can also pass `queries=["What are their preferences?"]`; MemU normalizes it to a user message before retrieval.
+
**Proactive Filtering**: Use `where` to scope continuous monitoring:
- `where={"user_id": "123"}` - User-specific context
- `where={"agent_id__in": ["1", "2"]}` - Multi-agent coordination
- Omit `where` for global context awareness
+`where` keys must match fields on your configured `UserConfig.model`, and values are validated/normalized by that model before querying. Validation is field-level, so partial filters do not need to include every field required by the model. Supported filters are equality (`field`) and membership (`field__in`); unsupported operators are rejected before any backend query runs.
+
---
## 💡 Proactive Scenarios
@@ -559,7 +674,7 @@ View detailed experimental data: [memU-experiment](https://github.com/NevaMind-A
| Repository | Description | Proactive Features |
|------------|-------------|-------------------|
-| **[memU](https://github.com/NevaMind-AI/memU)** | Core proactive memory engine | 7×24 learning pipeline, auto-categorization |
+| **[memU](https://github.com/NevaMind-AI/MemU)** | Core proactive memory engine | 7×24 learning pipeline, auto-categorization |
| **[memU-server](https://github.com/NevaMind-AI/memU-server)** | Backend with continuous sync | Real-time memory updates, webhook triggers |
| **[memU-ui](https://github.com/NevaMind-AI/memU-ui)** | Visual memory dashboard | Live memory evolution monitoring |
@@ -597,7 +712,7 @@ We welcome contributions from the community! Whether you're fixing bugs, adding
To start contributing to MemU, you'll need to set up your development environment:
#### Prerequisites
-- Python 3.13+
+- Python 3.12+
- [uv](https://github.com/astral-sh/uv) (Python package manager)
- Git
@@ -621,14 +736,31 @@ The `make install` command will:
Before submitting your contribution, ensure your code passes all quality checks:
```bash
make check
+make test
```
The `make check` command runs:
- **Lock file verification**: Ensures `pyproject.toml` consistency
-- **Pre-commit hooks**: Lints code with Ruff, formats with Black
+- **Pre-commit hooks**: Lints and formats code with Ruff
- **Type checking**: Runs `mypy` for static type analysis
- **Dependency analysis**: Uses `deptry` to find obsolete dependencies
+The `make test` command runs the pytest suite with coverage enabled.
+
+#### Documentation Site
+
+Preview the documentation locally with MkDocs:
+
+```bash
+make docs
+```
+
+Build the documentation in strict mode:
+
+```bash
+make docs-build
+```
+
### Contributing Guidelines
For detailed contribution guidelines, code standards, and development practices, please see [CONTRIBUTING.md](CONTRIBUTING.md).
@@ -638,7 +770,7 @@ For detailed contribution guidelines, code standards, and development practices,
- Write clear commit messages
- Add tests for new functionality
- Update documentation as needed
-- Run `make check` before pushing
+- Run `make check` and `make test` before pushing
---
@@ -650,10 +782,13 @@ For detailed contribution guidelines, code standards, and development practices,
## 🌍 Community
-- **GitHub Issues**: [Report bugs & request features](https://github.com/NevaMind-AI/memU/issues)
+- **Support**: [Get help and choose the right channel](SUPPORT.md)
+- **Security**: [Report vulnerabilities privately](SECURITY.md)
+- **GitHub Issues**: [Report bugs & request features](https://github.com/NevaMind-AI/MemU/issues)
+- **GitHub Discussions**: [Ask questions and discuss ideas](https://github.com/NevaMind-AI/MemU/discussions)
- **Discord**: [Join the community](https://discord.com/invite/hQZntfGsbJ)
- **X (Twitter)**: [Follow @memU_ai](https://x.com/memU_ai)
-- **Contact**: info@nevamind.ai
+- **Contact**: contact@nevamind.ai
---
diff --git a/assets/memu-overall-algorithm-flow.png b/assets/memu-overall-algorithm-flow.png
new file mode 100644
index 0000000000000000000000000000000000000000..d8e2708182b4a05f06dc48b1413f52067f3f90ab
GIT binary patch
literal 1519861
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