Content
# Memo
> V0.9-alpha · Memory + Persona + Todo + Context Space + Cross Agent Bridge
## 1. What is Memo
Memo is a locally running AI Context Space that does four things:
1. **Memory**: Use a SQLite file to precipitate long-term context in various AI Agents.
2. **Space**: Organize memory, to-do, and conversations by project, matter, customer, and product line using Context Space.
3. **Persona**: Distill who you are, how you think, and what you prefer from all memories to form a "digital twin".
4. **Action**: Precipitate the next step in memory as to-do, risk, and project promotion clues.
Any Agent supporting MCP (WorkBuddy / HanaAgent / QoderWork / Claude / Cursor) can share the same memory, space, persona, and to-do after installation.
## 2. System Requirements
- Windows 10+ / macOS 12+
- Python 3.10+
- DeepSeek API Key (or other OpenAI compatible API)
- 4GB disk space (including embedded model)
## 3. Installation
If the installation object is a colleague unfamiliar with commands, please refer to:
```text
docs/non-developer-install-guide.md
```
On Windows, you can also directly double-click:
```text
install.bat
```
Below is the developer/manual installation process.
### 3.1 Unzip
Unzip `Memo_V0.7.0.zip` to any directory (recommended `D:\Memo` or `~/Memo`).
### 3.2 Configuration
Edit the `.env` file:
```
LLM_API_KEY=sk-your-deepseek-key
LLM_BASE_URL=https://api.deepseek.com/v1
MEMO_DB_PATH=data/memo.db
```
If using your own API, modify `LLM_BASE_URL` and model name accordingly.
### 3.3 Install Dependencies
```bash
pip install -r requirements.txt
```
The first run will automatically download the embedded model (`BAAI/bge-small-zh-v1.5`, about 100MB), requiring a network connection. For domestic users, set the mirror:
```bash
set HF_ENDPOINT=https://hf-mirror.com
```
### 3.4 Initialize Database
```bash
python -c "from memo.core.engine import engine; engine.init(); print('OK')"
```
### 3.5 Start Service
```bash
start_all.bat # Windows
# or
python scripts/memo_dashboard.py # Dashboard (http://localhost:9120)
python scripts/memo_watcher.py # Watcher (Bridge inbox monitoring + persona refresh)
```
## 4. Connect to Agent
### 4.1 Install MCP (required)
Add the following configuration to the Agent's MCP configuration file:
```json
{
"mcpServers": {
"memo": {
"command": "python",
"args": ["<project_path>/scripts/run_mcp.py"]
}
}
}
```
> Replace `<project_path>` with the absolute path of the Memo unzipped directory (e.g., `D:/Memo` or `~/Memo`).
| Agent | Configuration File Path |
|-------|-------------------------|
| **WorkBuddy** | `~/.workbuddy/mcp.json` |
| **HanaAgent** | Settings → MCP Connector |
| **QoderWork** | Settings → MCP; also available for manual import using `install_output/qoder_mcp_ready_to_paste.json` |
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Cursor** | `.cursor/mcp.json` |
### 4.2 Install Skill (recommended, let Agent run automatically)
Copy `SKILL.md` to the Agent's skills directory:
| Agent | Installation Directory |
|-------|-------------------------|
| **WorkBuddy** | `~/.workbuddy/skills/memo/SKILL.md` |
| **HanaAgent** | `~/.hanako/skills/memo/SKILL.md` |
| **QoderWork** | Skills Market import; if local `~/.qoder` / `~/.qoderwork` exists, the installer will attempt to copy to the corresponding skills directory |
After installation, the Agent will:
- **Before each conversation**, automatically retrieve relevant memories.
- **After each conversation**, silently write conversation memories.
- **When involving decisions/preferences**, automatically call the persona engine.
### 4.3 Inject Agent Prompt
Append the content of `AGENT_PROMPT.md` to the Agent's System Prompt, and the Agent will automatically execute the three-stage linkage of retrieval + memory + persona.
### 4.4 Build Initial Persona Baseline
```bash
python -c "from memo.core.engine import engine; engine.init(); r=engine.build_persona_baseline(); print(r)"
```
## 5. Agent Behavior (automatically executed after connection)
| Stage | Timing | Tool | Description |
|------|------|------|------|
| **Recall** | Before each response | `memo_recall` | Automatically extract keywords to retrieve past memories and integrate into responses |
| **Remember** | After each response | `memo_remember` | Silently write this conversation, without disturbing the user |
| **Persona** | Decision/preference questions | `persona_ask` | Match persona profile, provide stance-based responses |
## 6. MCP Tool List (core tools)
| Tool | Purpose | Example |
|------|------|------|
| `memo_remember` | Write memory | `memo_remember({conversation:"...", agent_name:"WorkBuddy"})` |
| `memo_recall` | Retrieve memory | `memo_recall({query:"data governance rules"})` |
| `memo_export` | Bridge export (file transfer) | `memo_export({conversation:"...", agent_name:"Qoder"})` |
| `memo_start_session` | Start memory session | |
| `memo_end_session` | End memory session | |
| `memo_stats` | View statistics | |
| `memo_hot_tags` | High-frequency feature words | |
| `memo_maintain` | Lifecycle maintenance | |
| `memo_snapshot` | Global snapshot | |
| `persona_ask` | Persona routing Q&A | `persona_ask({question:"How should I promote this project?"})` |
| `persona_profile` | View persona profile | `persona_profile({dimension:"value"})` |
| `todo_add` | Create to-do | `todo_add({title:"Finish report",priority:"high",due_date:"2026-07-20"})` |
| `todo_list` | List to-do | `todo_list({status:"todo+doing"})` |
| `todo_close` | Complete to-do | `todo_close({ids:["abc123"]})` |
| `todo_check_risk` | Risk detection | Return overdue/urgent/warning |
| `space_create` | Create Context Space | `space_create({name:"Memo"})` |
| `space_list` | List Space | |
| `space_activate` / `space_deactivate` | Activate/exit current Space | |
| `space_profile` | View Space briefing | |
| `space_recall` | Retrieve within Space | |
| `space_detect` | Detect which Space text may belong to | |
| `memory_govern` | Memory governance: mark importance/error/expire/silent/soft delete | |
## 7. Dashboard
Open `http://localhost:9120` in a browser.
| Tab | Content |
|-----|------|
| Overview | Memory, conversations, relationships, to-do, and active feature words |
| Memory Governance | Search memory, mark importance/error/expire/silent/soft delete |
| Context Space | Space creation, editing, archiving, briefing, memory unbinding |
| To-do | Create, complete, reopen to-do, support binding Space |
| Persona Profile | 10-dimension persona assertion management |
| Graph View | Currently a placeholder for entry, next stage to connect Canvas graph |
## 8. Architecture
```
┌─────────────────────────────────────────┐
│ MCP Server (11 tools) │ ← Any Agent connection
│ memo_remember / recall / export / ... │
├─────────────────────────────────────────┤
│ Persona Router │ ← Domain matching → Persona/hybrid/experience channel
├──────────────────┬──────────────────────┤
│ Persona Engine │ Memory Engine │
│ 10-dimension profile·incremental update │ Retrieval·gating·CAS·graph │
├──────────────────┴──────────────────────┤
│ SQLite (memo.db) │
│ memory_units · persona_assertions · ... │
└─────────────────────────────────────────┘
```
## 9. Operations
| Operation | Command |
|------|------|
| Start all | `start_all.bat` |
| Stop all | `stop_all.bat` |
| Manual lifecycle | `python -c "from memo.core.engine import engine; engine.init(); engine.run_lifecycle()"` |
| Incremental persona refresh | `python -c "from memo.core.engine import engine; engine.init(); engine.update_persona()"` |
| Database backup | Copy `data/memo.db` |
| Security upgrade | `upgrade.bat` or first `python scripts/init_db.py` then `start_all.bat` |
| Environment self-test | `python scripts/doctor.py` |
| Secure packaging | `python scripts/build_release.py --include-dist` |
## 10. Test Steps
1. Unzip to local directory, modify `.env` and fill in API Key
2. `pip install -r requirements.txt`
3. Initialize: `python -c "from memo.core.engine import engine; engine.init(); print('OK')"`
4. Start: Double-click `start_all.bat`
5. Open `http://localhost:9120` to confirm dashboard is normal
6. Add memo to Agent's MCP configuration
7. Restart Agent, let it "remember this conversation"
8. Refresh dashboard, confirm memory count increases
9. Run `build_persona_baseline()` to build persona baseline
10. Switch to persona profile tab, view 10-dimension assertions
