+
**[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,197 @@ 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`.
+
+#### Built-in Self-Hosted API Server
+
+The package also installs a lightweight JSON API server:
+
+```bash
+export OPENAI_API_KEY=your_api_key
+export MEMU_SERVER_API_KEY=local-dev-token
+memu-server --host 127.0.0.1 --port 8765
+```
+
+Useful local endpoints:
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET`, `HEAD` | `/health` | Health check |
+| `GET`, `HEAD` | `/openapi.json` | Machine-readable OpenAPI contract |
+| `POST` | `/api/v3/memory/memorize` | Run `MemoryService.memorize` synchronously |
+| `POST` | `/api/v3/memory/retrieve` | Query memory with `queries` or a shorthand `query` string |
+| `POST` | `/api/v3/memory/categories` | List memory categories |
+| `POST` | `/api/v3/memory/items` | List memory items |
+| `POST` | `/api/v3/memory/items/create` | Create a source-less memory item |
+| `POST` | `/api/v3/memory/items/update` | Update a memory item by `memory_id` |
+| `POST` | `/api/v3/memory/items/delete` | Delete a memory item by `memory_id` |
+| `POST` | `/api/v3/memory/clear` | Clear memory for an optional `where` scope |
+| `DELETE` | `/api/v3/memory` | Clear memory for an optional `where` scope |
+
+`/api/v3/health` and `/api/v3/openapi.json` are also available as versioned
+aliases for clients that keep every endpoint under the API prefix. Health
+responses include the package version, configured providers, auth status, and
+request size limits for deployment checks.
+
+When `MEMU_SERVER_API_KEY` is set, memory endpoints require
+`Authorization: Bearer
+
+```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 +526,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 +541,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 +575,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 +603,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 +615,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 +679,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 +696,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 +777,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 +815,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 +839,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 +873,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 +885,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/SECURITY.md b/SECURITY.md
new file mode 100644
index 00000000..6a509929
--- /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
+- server endpoint 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/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
zcmeFZ1$0zN*Df4|009C7NYGC3gmj!Hhn93qlO5xOlzBbQ6_
z8*EHImmuR{)oc#VPT}bZ@{rHwce)isszZUxRr(?Zq?Jt2_!Vr6U1Xs8&=i-*BXSwd
z+Mv*A H>?La6Dd1;3i{d_W0MkFn9v%i@qCpuN^W-WMQ)e{Ita)yI
zb8TAS9wxPt<;5`72TRzY!ugouzE=d(!@$!zywhD}QP~v%k2PRPA!iaqCMhGiKn1zQ
zi+V{EqUa8Aq01s2zTZOimvYP&ez6>V9x+L+B$g{SQ;lM=v@
z&p+&_)c9#n`JY(#uW5Pp!ha(zaA=FXv&J?c*!0}aOF8`>v>d(k@^r+rt1a#ph3{eK
zmx&8fowgn${Fcm|xWXfohTa(B*l
GaFLEd*&
zt?;W{$D6uHUgQmCW+UE|Mwh=8c*IVNQ4nadx3d8bH*6FG|M;hpQ<6Zisv;(Z$PpLH
zE`r40%JPz(bAwbNAio$4b@?o5RkRkPw23`xd_Kzqjx;J2G}H#VOv84MXMha_1=zfW
zvs1~O*+emcoOLRi&iP6(WZ`EBs&d8AzYSLgv-+D&;uJTP`srjem*XPxzz$|7lwSlN#Jdl~(H~^3z0_NiwR6mAF#3Zg%
zR{n3`lEf_>MmagDkWX+CbLqhO15**6MuVDdD=mG5KKx~}!hwjUr<&IZMccL0T=)#f
zv-h+^Uw}Alr6m{YudYcewRmk|5~kCo@LT}Er*DMQB(gDOCZHm}4341Qn0XP*%8G~o
zFmiv0OcG2{TYOgFZ>7sKZ4ryRb=jDL9A(V!DF0p7Plhvxl@Hh~o<`Yn@Fnt+d>Fz5
zh{#qojclmCFeAb6KZNBfArY+!b3UCp2dG*djGi^)jx-P4=|f#RKi>9+M4A`3{iA2iLMe(@`}Jh*GLW%KGo55D3_
zPkz@cUw-`hMQcn?L`o5WwFE?DX|?N)+_>@Yf99ut{5|jg{yq23EiS;pmDTb1&wu`B
zfBhLxYk&?;#t5LnM-l*_x7PIiNH?!~;#u1^Zg~B_y#M
c3Es36H&=y)LXKtKRQ(Djp6>j(Gk
zx!{_s%*GAFu0L|?)_0uylH=Dej=SD9hv>HZfh7QhR_WEXwG%dN{*~uH`)wcp uT2)fD6hG%3<
z3dB7T>OGODSnBXH7gtb-$dY?xtyQYoar@n0`TE5$XeZY869R0AT(r?;ArK
b`V;Tc;Uo6D49;SP&SQ8vAO{x
zS%tOyLtH%ThdVONe+ba#lXuQGd7qwz3X0XoV=B~$94hJUhzj8cFH$qd;T2N>%vp6$
zc*r*@1n%-AIg|Ym7rxTBiOsnt_>;)oUgZgskzf<3vW8tO$(u{rF;CbjGzjO?sU2k8
zn_ZNcF-m+T9Wef`5(f%u<_wdKQIe71;Y?|lS+!V#dBqt3(}3fxg^i>lU9+eX`POr=
zXqf>k#+VQq02D(pZ5ADy=8Bq6`%?wK5S0{guHOlOT)GNtnM2Ctf$KE{8`EKYy-IRy
zy21pc(h+}}Sz}&>FL0L?1?{34cC#U3&j0{12C;&F6R1K_C&Z~rvaCEJ&a{IoQpTi(
znU_xko{@`?9ZdvbfRbNc7@eBJ