diff --git a/apps/memtrace-memos-integration/.gitignore b/apps/memtrace-memos-integration/.gitignore new file mode 100644 index 000000000..fd869f6c4 --- /dev/null +++ b/apps/memtrace-memos-integration/.gitignore @@ -0,0 +1,33 @@ +# Local runtime state and credentials +/.memos/ +/.env +/.env.* +/logs/ +/tmp/ +*.log + +# Python environments and generated packages +/.venv/ +/venv/ +/build/ +/dist/ +*.egg-info/ +__pycache__/ +*.py[cod] + +# Tests and tool output +*_test.py +conftest.py +.pytest_cache/ +.ruff_cache/ +.tests/ +.coverage +.coverage.* +htmlcov/ +.tox/ +.nox/ + +# Editor and operating system files +/.idea/ +/.vscode/ +.DS_Store diff --git a/apps/memtrace-memos-integration/README.md b/apps/memtrace-memos-integration/README.md new file mode 100644 index 000000000..0ecae280e --- /dev/null +++ b/apps/memtrace-memos-integration/README.md @@ -0,0 +1,201 @@ +# SmartComment for MemOS + +English | [简体中文](README_zh.md) + +SmartComment is an optional tracing plugin for MemOS that records memory creation, background processing, and retrieval as execution graphs. If a fact wasn't remembered or you need to trace the source of a search result, use the graphs to inspect message extraction, memory writes, and retrieval. They also help you reproduce failed cases, evaluate memory quality, and check changes to extraction or retrieval strategies. + +The graph format and visualization tools come from [smartcomment](https://pypi.org/project/smartcomment/). You can also analyze the graphs with [MemTrace](https://github.com/zjunlp/MemTrace), a separate project whose AI agent inspects them to investigate memory-system failures. + +The plugin is disabled by default, even after installation. Enable it as needed in your development or test environment. Normal MemOS usage does not require it. + +## What you can see + +| Capability | What you can inspect | +| --- | --- | +| Memory creation | The source messages, extracted content, and memory IDs returned by write operations. | +| Background processing | How MemRead enhanced memories, wrote the results, or deleted older memories. | +| Search stages | Whether a memory was retrieved or removed during filtering or deduplication, and the final result order and scores. | +| Search-to-Add history | The original messages and memory creation process behind final search results. Enable it with `MEMOS_SMARTCOMMENT_LINK_SEARCH_TO_ADD`. | +| Request browsing | Each user's `index.md` lists timestamps, request summaries, trace IDs, and links to the corresponding graphs. | + +The recorded memory flows are: + +```text +Add: messages → extracted memories → written memories → background enhancement +Search: query → memory type → memory cube → retrieval → filtering → deduplication → reranking +``` + +## Quick start + +### 1. Prepare your MemOS environment + +Use Python 3.12 or newer. Follow the [MemOS deployment instructions](../../README.md) to configure the service, models, and storage, then activate the same Python environment that runs MemOS. Run these commands from the MemOS repository root: + +```bash +# Skip this line if this MemOS checkout is already installed in the active environment. +python -m pip install -e . + +python -m pip install "smartcomment>=0.1.2" +python -m pip install -e apps/memtrace-memos-integration +``` + +### 2. Enable the plugin and start the service + +Set the environment variables before starting MemOS: + +```bash +export MEMOS_ENABLED_PLUGINS=smartcomment +export MEMOS_SMARTCOMMENT_OUTPUT_DIR="$PWD/.memos/memtrace" + +# Optional: include the origins of final search results. Disabled by default. +export MEMOS_SMARTCOMMENT_LINK_SEARCH_TO_ADD=true + +python -m uvicorn memos.api.server_api:app --host 127.0.0.1 --port 8000 --workers 1 +``` + +The startup log should contain `smartcomment plugin loaded`. If you use other opt-in plugins, keep their names in `MEMOS_ENABLED_PLUGINS`, separated by commas. Restart the service after changing plugin settings. + +This command starts one worker. Each writer process needs its own output directory, so use separate directories if you run multiple workers. + +### 3. Add a memory and search for it + +Call `/product/add` and `/product/search` through the [local API documentation](http://127.0.0.1:8000/docs) or your existing client. To try the commands below, open another terminal and replace `YOUR_USER_ID` and `YOUR_CUBE_ID` with an existing user and memory cube. The [MemOS README](../../README.md) explains how to create a cube if you need one. + +```bash +curl -X POST http://127.0.0.1:8000/product/add \ + -H 'Content-Type: application/json' \ + -d '{ + "user_id": "YOUR_USER_ID", + "writable_cube_ids": ["YOUR_CUBE_ID"], + "messages": [{"role": "user", "content": "I go swimming on Tuesdays and Thursdays."}], + "async_mode": "sync" + }' + +curl -X POST http://127.0.0.1:8000/product/search \ + -H 'Content-Type: application/json' \ + -d '{ + "user_id": "YOUR_USER_ID", + "readable_cube_ids": ["YOUR_CUBE_ID"], + "query": "When do I go swimming?" + }' +``` + +Wait for the Add request to succeed before searching. The plugin writes graph files asynchronously, so history linking also requires waiting for the Add graph to appear. Background enhancement may still be running. + +Supply an `x-trace-id` request header to match a graph with your application logs. Requests with the same user and trace ID share a graph, so use a unique trace ID for each request if you want separate graphs. History linking works across different Add and Search trace IDs. + +### 4. Find the recorded requests + +With the output directory above, run this from the repository root: + +```bash +find .memos/memtrace -type f -name index.md +``` + +Open your user's `index.md`. It lists requests newest first, with the request time and UTC offset, type, query or message summary, full trace ID, and a link to `graph.json`. + +Example directory layout: + +```text +.memos/memtrace/ +└── user--/ + ├── index.md + └── 2026-11-17/ + ├── add/ + │ └──