历史扫描和实时接入是两件事
“同步新增”读取 Agent 已写入本地的数据；Hook 或插件负责新对话中的自动召回、自动采集和任务接续。只扫描不会修改 Agent 配置；安装 Hook、插件或 Skill 才会写入下文列出的配置和文件。
Cursor 当前的 Hook 重点负责自动采集和
普通请求需要额外记忆时，由随 Hook 安装的 Skill 执行按需搜索；其他五个接入会在普通请求前自动注入召回结果。
/memmy-resume
` | 配对码 | 批准配对请求 |
| `/pairing deny ` | 配对码 | 拒绝配对请求 |
| `/pairing revoke ` | 用户 ID | 撤销用户配对 |
`/history-dag` 是否可用，取决于对应功能是否在配置中启用。
## 七、常见问题 [#七常见问题]
### `memmy: command not found` [#memmy-command-not-found]
* macOS：确认 Memmy 已拖入 `/Applications` 并启动过一次，然后打开新终端或执行 `source ~/.zshrc`。
* Windows：打开新的 PowerShell 或 Windows Terminal。
* Linux：确认安装器执行成功，并检查 `~/.local/bin` 是否在 PATH 中。
### 没有可用模型 [#没有可用模型]
```plaintext
memmy onboard
memmy status
```
确认模型、Provider 和凭据已保存后，再执行 `memmy`。
### Gateway 不可用 [#gateway-不可用]
* 使用桌面端：确认 Memmy 桌面端正在运行。
* 使用 Linux CLI：检查 `memmy-gateway.service`。
* 使用源码或手动运行的 CLI：在另一个终端执行 `memmy gateway`。
默认 Gateway WebSocket 端口是 `18980`。Linux 用户可以查看日志：
```plaintext
journalctl --user -u memmy-gateway.service
```
### 为什么 `memmy agent` 没有打开全屏界面 [#为什么-memmy-agent-没有打开全屏界面]
这是正常的。`memmy agent` 是单轮或传统终端入口；需要全屏 TUI 时执行：
```plaintext
memmy
```
# 托管工具集成 (/docs/cn/tools/integrations)
工具页的普通集成来自托管目录（Composio），包括 GitHub、GitLab、Gmail、Google Calendar/Docs/Drive/Sheets/Slides、Notion、Slack、Linear、Jira、Confluence、Figma、Dropbox、Airtable、Trello、Salesforce、HubSpot、Stripe、Zoom 等。
## 授权流程 [#授权流程]
1. 点击工具卡片，查看权限范围后点击连接，获取授权 URL。
2. 在外部浏览器完成 OAuth；弹窗每 4 秒轮询，最长等待 5 分钟。
3. 连接成功后，工具通过 Composio MCP bridge 暴露给 Agent Runtime，桌面后端自动写入 `tools.mcpServers.composio`。
# 自定义 MCP Server (/docs/cn/tools/mcp)
Memmy 支持 `stdio`、`sse`、`streamableHttp` 三种 MCP server：
```yaml
tools:
mcpServers:
example:
type: stdio
command: npx
args:
- "-y"
- "your-mcp-server"
toolTimeout: 30
enabledTools:
- "*"
```
## 内置工具开关 [#内置工具开关]
```yaml
tools:
web:
enabled: true
search:
provider: duckduckgo
maxResults: 5
fetch:
timeoutS: 30
maxChars: 60000
exec:
enabled: true
timeout: 60
imageGeneration:
enabled: false
```
内置工具覆盖文件系统、shell、Web 搜索与抓取、MCP、定时任务、消息发送、图像生成、长任务、自省、运行时状态和上下文管理。
# Memmy changelog (/docs/changelog)
The latest updates to Memmy Desktop, Agent, Memory, and CLI
## Core Capabilities [#core-capabilities]
* Scan conversation history from Cursor, Claude Code, Codex, and more; dedupe, ingest, and search it in one place.
* Config lives in `~/.memmy/config.yaml`, memory in local SQLite, and every endpoint is token-protected.
* Multi-session tasks, streaming output, attachments, voice input, and slash commands.
* A transparent always-on-top mini window that takes text or voice tasks anytime and syncs with the main workbench.
* Channels like Telegram, WeChat, Feishu, and DingTalk, plus managed integrations such as GitHub, Notion, and Slack.
* Many providers including OpenAI-compatible, Anthropic, Gemini, DeepSeek, and Ollama.
## Quick Start [#quick-start]
1. Download and launch the Memmy desktop app, or build `App/memmy-agent` and use the CLI.
2. Choose account mode or API Key mode, configure your primary model, and pass a connection test. CLI users run:
```bash
memmy onboard
```
3. Send your first task from the main workbench, or in the terminal:
```bash
memmy agent --message "Hi, introduce the current workspace"
```
Keep your first milestone small: get one normal reply working in the desktop app or CLI first, then move on to tools, channels, MCP, memory scanning, and the desktop pet.
## Configuration [#configuration]
The main config defaults to `~/.memmy/config.yaml` and supports `${ENV_NAME}` environment variable references:
```yaml
agents:
defaults:
model: openai/gpt-4.1
provider: openai
timezone: "+08:00"
providers:
openai:
apiKey: ${OPENAI_API_KEY}
```
## Next Steps [#next-steps]
Full installation and first-run setup · Overview, entries, policies, world model, and logs · Connect Memmy to your IM · memmy and memmy-memory commands · Processes, ports, and data flow · FAQ and troubleshooting entry points
# Messaging Channels (/docs/channels)
Memmy plugs into the IMs you already use, so you can command your Agent right from your chat apps. Currently supported:
**Telegram · Discord · iMessage · WeChat · Feishu · DingTalk**
## How to Connect [#how-to-connect]
| Channel | Method |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------- |
| WeChat | QR code sign-in; the dialog polls for the scan result |
| Feishu | `appId` + `appSecret` form; on insufficient permissions, missing scopes are parsed out with an application link |
| DingTalk | `clientId` + `clientSecret` form |
| Telegram / Discord / iMessage | Follow the dialog instructions on the Tools page |
Connection status refreshes every 5 seconds; connected channels can be disconnected anytime. Channel configuration is written into the runtime by the local backend via the memmy-agent admin client.
# Local Architecture (/docs/concepts/architecture)
## Core Concepts [#core-concepts]
| Concept | Description |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Workspace | The Agent's working directory, default `~/.memmy/workspace`; the runtime syncs templates, built-in skills, and memory files here |
| Config | `~/.memmy/config.yaml`, overridable via `MEMMY_CONFIG` or `--config` |
| Agent Runtime | Model calls, message loop, tool registration, MCP, sessions, long tasks, skills, auto-compaction, memory hooks |
| Memory Service | The local-first memory foundation; entry point `Memory/src/server/index.ts`, default `:18960` |
| Local Backend | Backend for the desktop local API: SQLite app state, permissions, Cloud/Memory clients, source scanning, Skill writing, Fastify routes |
| Agent Source | Read adapter for external Agent history + optional Skill install target |
| Dream | Memory consolidation mechanism, triggered manually or on a schedule |
# Full Feature List (/docs/concepts/features)
## Highlights [#highlights]
* Nine external Agent sources — scanned, deduped, ingested
* Multi-session, attachments, voice, slash commands
* A transparent always-on-top mini window, on call anytime
* 20+ managed integrations + custom MCP
* 6 IM channels
* 15+ providers with your own quota
## Full List [#full-list]
### Memory [#memory]
* External source scanning: Cursor, Claude Code, Codex, OpenCode, OpenClaw, Hermes, WorkBuddy, Pi, qwenwork
* Memory panel: overview, entries, tasks, policies, world model, skills, analytics, logs
* Dream consolidation: manual / scheduled, with logs and rollback
* memmy-memory CLI and the Memory Runtime HTTP API
* External Agent Skill installation (active memory read/write)
### Desktop [#desktop]
* Multi-session task list: grouping, pinning, archiving, search, unread indicators
* Streaming output, stop / restart, Agent status panel
* Attachments (images + common office documents), voice input (ASR)
* Slash commands, Agent artifact preview
* Pet mode: input bubble, multi-task badge, answer preview, session continuation
### Models & Auth [#models--auth]
* Account mode (platform tokens) and API Key mode (BYOK)
* Six independently configurable model slots: primary, Embedding, memory summary, skill evolution, ASR, image generation
* 15+ providers, including OAuth sign-in
### Tools & Automation [#tools--automation]
* Built-in tools: files, shell, web search and fetching, scheduled tasks, long tasks, image generation, and more
* Composio managed integrations + custom MCP servers (stdio / sse / streamableHttp)
* 6 messaging channels
### APIs [#apis]
* OpenAI-compatible API (`memmy serve`)
* Memory Runtime API, desktop local API, SSE event stream
# Desktop Pet Mode (/docs/desktop/pet)
The desktop pet is a transparent, always-on-top mini window — perfect for firing off tasks without interrupting your current work.
## Interactions [#interactions]
* Single-click to expand the input bubble; `Enter` to send; voice recording with transcription is supported.
* Double-click to leave pet mode and open the full workbench.
* Drag with the left mouse button to move the window; the right-click menu can open full mode.
* When tasks are running or there are unread completions, a numeric badge appears; click it to expand a mini task list (up to 6).
## Session Continuation [#session-continuation]
* If a task is running, new messages continue the same session; tasks completed within the last 5 minutes also continue their session.
* After clicking "New session", the next message creates a new session.
* The pet and full mode share the WebUI thread, so context survives switching.
# Settings (/docs/desktop/settings)
| Section | Contents |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Account | Nickname editing, full contact info, sign out / exit local mode |
| Models | Switch between platform mode and own-model mode; configure primary / memory summary / skill evolution / Embedding / ASR / image generation models |
| Tokens | Platform-granted token or BYOK usage stats, low-balance alerts, request more |
| General | Simplified Chinese / English |
| Window | Default launch mode (pet / full / last used), close behavior, menu bar icon |
| Notifications | Update notifications, task completion notifications, sounds |
| Privacy | Memory improvement program toggle, data agreement |
| Developer | Log level, open log directory, export redacted diagnostic report |
| About | Version, check for updates, terms of service |
Diagnostic reports contain no secrets, tokens, account identifiers, prompts, or task messages.
# Main Workbench (/docs/desktop/workbench)
`/main` is the full Agent workbench: task list on the left, message stream in the middle, input box at the bottom.
## Input & Sending [#input--sending]
* `Enter` to send, `Shift + Enter` for a new line; IME composition (e.g. Chinese input) is handled correctly.
* The `+` button adds attachments: up to 4, 10MB each, supporting images and common formats like `.pdf`, `.docx`, `.xlsx`, `.pptx`, `.md`, `.csv`, `.json`.
* The microphone button enables voice input (requires an ASR model); transcriptions merge into the input box.
* While a task is running, the send button becomes a stop button.
## Slash Commands [#slash-commands]
Type `/` to open the command panel:
| Command | Purpose |
| ---------------- | ------------------------------------- |
| `/new` | Start a new task |
| `/stop` | Stop the current task |
| `/restart` | Re-run the current task |
| `/status` | Check the Agent's runtime status |
| `/model` | View the current model configuration |
| `/goal` | View or manage goal state |
| `/dream` | Manually trigger memory consolidation |
| `/dream-log` | View consolidation records |
| `/dream-restore` | Restore the pre-consolidation state |
| `/help` | Help |
## Task List [#task-list]
Grouped by Pinned, Today, Yesterday, Last 7 Days, Older, and Archived. Supports rename, pin, archive, restore, and delete; running tasks show a spinner, and completed-but-unread tasks show an unread dot. `Cmd/Ctrl + K` opens task search.
# Local Development & Packaging (/docs/development/local-dev)
## One-Command Start [#one-command-start]
Get running in three steps:
```bash
git clone https://github.com/MemTensor/memmy-agent.git && cd memmy-agent
cp .env.example .env # Cloud address is pre-filled — works out of the box
bash scripts/dev-start.sh # Install deps → build → start the full stack
```
`scripts/dev-start.sh` does everything in one command: it installs dependencies, builds Memory and memmy-agent, installs the `memmy` / `memmy-memory` CLIs into `~/.local/bin`, and starts the full stack (Memory, Agent API, Gateway, frontend, and desktop backend). Once the desktop app opens, finish account sign-in or BYOK setup — the script waits for the model config and then starts the agent services automatically.
> `MEMMY_CLOUD_SERVICE` in `.env` defaults to `https://api.memmy.cn (use the origin only; clients append /api/... paths)`, so copying it connects you to the official cloud — no self-hosted backend or API key required. On Windows, run it in Git Bash; the script adds `~/.local/bin` to your PATH.
## Requirements [#requirements]
Node.js `>=22` + npm. Root workspaces include `Memory`, `App/backend/local-api-contracts`, `App/backend`, `App/frontend/*`, `App/shell/desktop/interface`, and `App/shell/*`.
## Common Commands [#common-commands]
```bash
npm install # Install dependencies at the repo root
npm run dev:desktop # Start the desktop frontend Vite server and Electron shell together
npm run build # Build Memory and all workspaces
npm run lint
npm run typecheck
npm run test
npm run db:migrate # Run backend database migrations
npm run package:mac # Package the macOS DMG
npm run package:win:x64
```
## Developing Memory Standalone [#developing-memory-standalone]
```bash
npm run memory:serve:dev -- \
--host 127.0.0.1 \
--port 18960 \
--db ~/.memmy/memory-service/memory.sqlite \
--config ~/.memmy/config.yaml
```
## memmy-agent from Source [#memmy-agent-from-source]
```bash
cd App/memmy-agent
npm install && npm run build
node dist/main.js onboard
node dist/main.js agent --message "Hi, introduce the current workspace"
node dist/main.js serve
```
# FAQ (/docs/help/faq)
**How is Memmy different from a regular chatbot?**
A regular chatbot only handles the current conversation. Memmy maintains local memory, scans external Agent history, installs Agent Skills, and puts the desktop app, CLI, Memory service, and tool connections in one runtime environment.
**Do I have to register an account?**
Not necessarily. The desktop app supports both account mode and API Key mode; API Key mode uses your own model quota, and data is still stored local-first.
**Can I use Memmy without configuring ASR or an image generation model?**
Yes. They only affect voice input and Agent image generation — both optional capabilities that never block normal chat or memory features.
**How do external Agents use Memmy's memory?**
First run the Memory service, then install the CLI, and finally install the corresponding Skill for Codex, Cursor, Claude Code, Opencode, OpenClaw, or Hermes.
**Where is my data stored? Does scanning upload it?**
Everything defaults to `~/.memmy`, including config, workspace, the Memory SQLite database, and runtime files. Scanning and ingestion happen entirely locally, with memories written to local SQLite. Participation in the "memory improvement program" is explicitly controlled by a toggle in privacy settings.
# memmy-memory CLI (/docs/memory/memory-cli)
Gives external Agents or scripts access to the Memory service:
```bash
memmy-memory init
memmy-memory health
memmy-memory search "memory policies in this project"
memmy-memory add "a piece of knowledge worth saving"
memmy-memory get
memmy-memory delete
```
Connects to `http://127.0.0.1:18960` by default. Use `--url`, `--token`, `--config`, `--source`, and `--user-id` to specify the target service, authentication, calling source, and user namespace.
Also supports reload-config, session open/close, turn start/complete, and raw calls.
# How Memory Works (/docs/memory/overview)
Memmy memory is hosted by the local Memory service. The default endpoint is `http://127.0.0.1:18960`, and data is stored in `~/.memmy/memory-service/memory.sqlite`. Hooks, plugins, the `memmy-memory` CLI, and the desktop app all read and write this service, so different Agents share the same memory store.
## The Complete Path of One Request [#the-complete-path-of-one-request]
The path has seven stages:
1. Before a request reaches the Agent, a Hook or plugin opens or reuses a Memmy session and calls `turn.start`.
2. On the first turn of a new episode, the Memory service classifies intent and decides whether to recall memory and which layers are allowed.
3. The request is converted into a semantic query, keywords, short-pattern terms, and structural error fragments.
4. Recall channels run in parallel, then candidates are fused using memory layer, channel rank, quality, and time decay.
5. Candidates pass a relative threshold, deduplication, MMR diversity selection, and an optional LLM filter.
6. Hits are rendered as historical context and injected into the Agent. The current user request always remains authoritative.
7. At the end of the turn, `turn.complete` stores the raw turn and L1 traces. Background jobs then summarize, reflect, score, embed, and evolve higher-level memory.
## Four Memory Layers [#four-memory-layers]
| Memory layer | What it stores | How it is produced |
| -------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| L1 Trace | User request, Agent response, tool calls, results, reflections, error signatures, and source | `turn.complete`, history scanning, or explicit `memory.add` |
| L2 Policy | Triggers, procedures, boundaries, verification, and failure-avoidance guidance induced from similar valuable L1 traces | L2 induction after reward |
| L3 World Model | Stable knowledge about a project, environment, and constraints rather than a procedure | Abstraction from clusters of L2 policies |
| Skill | A callable SOP with a name, invocation guide, steps, and verification conditions | Crystallized and verified from eligible L2 Policies |
## Capture, Indexing, and Evolution [#capture-indexing-and-evolution]
### Automatic turn capture [#automatic-turn-capture]
`turn.complete` first stores a Raw Turn and then writes one L1 item for each captured step. By default it retains:
* up to 4,000 characters of user or Agent text;
* up to 2,000 characters from each tool output;
* up to 8 derived tags;
* tool name, input, result, error signatures, turn status, and source Agent;
* a heuristic summary that can later be rewritten asynchronously by the summary model;
* quality signals such as `value`, `alpha`, and `priority`.
Reflection synthesis and embedding after capture are enabled by default. L1 uses the summary text to create `vec_summary`; L2, L3, and Skill use `vec`. An embedding failure enters a retry queue and does not block the active Agent turn.
### Explicit writes and history imports [#explicit-writes-and-history-imports]
`memory.add` writes L1 by default, although callers can select another layer. A normal manual write enters the text index immediately and receives an embedding asynchronously.
An L1 imported by an Agent history scan enters the `summary_queued` pipeline first. It becomes recallable only after summary and vector indexing complete, preventing partially processed history from being injected.
### Episodes, feedback, and higher-level memory [#episodes-feedback-and-higher-level-memory]
* Consecutive follow-ups are merged into one episode by default, with a maximum gap of 2 hours.
* When an episode closes because of a topic boundary, session close, or 2 hours of inactivity, Memmy generates and scores reflections first.
* It waits through a default 30-second feedback window, then computes task reward and propagates it back through the episode's L1 traces.
* Eligible L1 traces enter a candidate pool and are induced into L2. A new L2 triggers L3 abstraction and Skill crystallization.
* Explicit user feedback, repeated tool failures, and divergent success/failure distributions can also adjust value and create failure-avoidance experience or decision repair.
Key evolution defaults:
| Setting | Default | Effect |
| ----------------------------------------- | ------: | ------------------------------------------------------------------------------------------- |
| `capture.synthReflection` | `true` | Synthesizes and scores reflection after an episode closes |
| `capture.embedAfterCapture` | `true` | Creates embeddings asynchronously after capture or evolution |
| `capture.batchThreshold` | `12` | Step threshold for batched reflection on long episodes |
| `reward.gamma` | `0.9` | Positional discount applied to earlier steps in the trace |
| `reward.lambda` | `0.5` | Blends uniform weighting with gamma-based positional weighting |
| `reward.delta` | `0.1` | Extra weight for a step that recovers from an irrelevant previous step |
| `reward.decayHalfLifeDays` | `30` | Time-decay half-life for L1 priority |
| `reward.feedbackWindowSec` | `30` | Time to wait for explicit feedback after episode close |
| `l2Induction.minTraceValue` | `0.005` | Minimum value for the L2 pool; the L1 trace must also have a vector |
| `l2Induction.minEpisodesForInduction` | `1` | Distinct episodes required to induce L2 |
| `l2Induction.minSimilarity` | `0.65` | Minimum similarity for associating L1 with an existing L2 |
| `l2Induction.candidateTtlDays` | `30` | Retention period for L2 candidate evidence |
| `l2Induction.minGain` | `0.02` | Minimum gain for activating an L2 Policy |
| `l2Induction.archiveGain` | `-0.05` | Gain threshold for archiving an L2 Policy |
| `l3Abstraction.clusterMinSimilarity` | `0.3` | Minimum similarity for clustering L2 into one world model |
| `l3Abstraction.minConfidenceForRetrieval` | `0.2` | Minimum L3 confidence for recall |
| `skill.minEtaForRetrieval` | `0.1` | Eta threshold used during Skill crystallization; recall also checks `retrieval.minSkillEta` |
| `skill.minSupport` | `1` | Minimum evidence count for Skill crystallization |
| `skill.minGain` | `0.02` | Minimum gain for Skill crystallization |
## When Recall Runs [#when-recall-runs]
Each retrieval entry point allows different layers:
| Retrieval mode | Layers allowed by default | Purpose |
| ---------------------------------- | ------------------------- | ------------------------------------------------------------------- |
| `turn_start` / `search` | Skill, L2, L1, L3 | Automatic recall before a normal request or manual search |
| `tool_driven` / `sub_agent` | L2, L1, L3 | Tool decisions or sub-Agent missions without automatic Skill recall |
| `skill_invoke` / `decision_repair` | Skill, L2, L1 | Invoking a target Skill or repairing a failed decision |
| `world_model` | L3 | World-model-only lookup |
The first turn of a new episode also passes an intent gate:
| Intent | Layers recalled |
| --------------------------------------- | -------------------- |
| Task or unknown | Skill, L2, L1, L3 |
| Asking what Memmy remembers from before | Skill, L2, L1; no L3 |
| Chitchat or a Memmy meta-command | Recall is skipped |
`turn_start` excludes L1 from the current session to prevent a just-observed turn from echoing back through the long-term-memory path. L2, L3, and Skill are not excluded by this rule.
`readOnlyInjectionProfile` narrows layers only when `domain: research`. It can be `experience` (L2 only), `skill`, `skill_experience`, or `all`. Outside the research domain, the effective profile is always `all`.
## How the Query Is Prepared [#how-the-query-is-prepared]
1. When an evolution model is configured, the service extracts one embedding-oriented semantic query and up to 5 keywords from the full request. If extraction fails, it falls back to the original request and rule-based keywords.
2. Chinese phrases produce additional two-character patterns, while code, paths, and error text produce structural fragments.
3. A query vector is created only when the database contains eligible vectors. If vectorization times out or fails, full-text, short-pattern, and structural channels continue.
4. `enableQueryRewrite` is off by default. When enabled, the evolution model generates 3 complementary queries, each recalls independently, and a separate RRF merge combines their results.
## How Many Recall Paths Are There? [#how-many-recall-paths-are-there]
There are **4 retrieval families**, represented by **6 ranker channel names**:
`vec`, `vec_summary`, `vec_action`, `fts`, `pattern`, and `structural`.
| Family | Channel | Scope | Default pool and threshold |
| ------------------- | ------------------------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------- |
| Semantic vector | L1 uses `vec_summary` / `vec_action`; other layers use `vec` | All layers | Skill 12, L1 20, L2 20, L3 8; minimum similarity is 0.25 for L1/L2/Skill and 0.15 for L3 |
| SQLite FTS5 | `fts` | All layers | Up to 20 per layer; up to 5 full-text terms, combined in groups of three when more than two terms exist |
| Short/CJK pattern | `pattern` | All layers | Up to 20 per layer; covers two-character CJK fragments and two-character ASCII terms using field substring matching |
| Structural fragment | `structural` | L1 only | Up to 10; matches distinctive error signatures, paths, and error codes |
Pool sizes follow these formulas:
* vector pool: `tierTopK × candidatePoolFactor`;
* the defaults are Tier 1 `3 × 4 = 12`, Tier 2 `5 × 4 = 20`, and Tier 3 `2 × 4 = 8`;
* FTS and pattern: `max(tierTopK, keywordTopK)`, which is 20 by default;
* after all channels are merged, each Tier is capped again at 12 / 20 / 8.
For local SQLite retrieval, the service first builds a search window from the latest 2,000 vector rows matching the layer and vector field, then asks sqlite-vec for Top K. The 2,000-row window is currently a fixed constant, not a `config.yaml` option.
## Candidate Filtering, Fusion, and Ranking [#candidate-filtering-fusion-and-ranking]
### Before the ranker [#before-the-ranker]
* Only `activated` and `resolving` records are read. `archived`, `deleted`, and unfinished history imports are excluded.
* A Skill must be `active` or `candidate` and have `eta >= minSkillEta`, which defaults to 0.1.
* L3 confidence must reach `l3Abstraction.minConfidenceForRetrieval`, which defaults to 0.2.
* `tagFilter: auto` applies only to the L1 vector route. It first uses tags inferred from the query; if no tagged vector matches, it relaxes to an untagged summary-vector search. `on` stays strict, while `off` disables this tag gate.
### Relevance fusion [#relevance-fusion]
Each candidate starts with its best channel score, then receives a layer-quality bonus:
```text
L1 bonus = min(weightPriority, 0.3) × max(value, 0) × time decay
Skill bonus = skillEtaBlend × eta
L2 bonus = 0.2 × clamp01(gain, or feedback salience / confidence)
RRF bonus = 0.4 × Σ 1 / (rrfConstant + channelRank + 1)
relevance = max(channelScore) + layer bonus + RRF bonus
```
### Thresholds, episode rollups, and MMR [#thresholds-episode-rollups-and-mmr]
1. Each Tier's pre-pool is ordered by relevance, channel count, and vector score.
2. When at least 2 high-ranking L1 traces share an episode, the representative vector similarity reaches 0.45, and its value is not negative, Memmy creates an episode rollup containing up to 6 steps.
3. Candidates below 20% of the highest relevance are dropped. Multi-channel bypass is on by default, so a candidate that hits at least 2 channels can survive.
4. Queries containing long identifiers or error-code-like tokens require keyword confirmation from FTS, pattern, or structural channels for L1/L2. Skill and L3 are exempt.
5. MMR selects using `0.7 × relevance - 0.3 × redundancy`. Smart seed requires the first candidate from a Tier to reach at least 70% of the global top relevance.
6. The final pass deduplicates individual L1 traces against an episode rollup and suppresses duplicate L2 Policies already covered by a Skill.
`tier1TopK=3`, `tier2TopK=5`, and `tier3TopK=2` size candidate pools and also produce the default global result limit of `3 + 5 + 2 = 10`. They are not hard per-Tier quotas in the final result. When a request supplies `limit`, final MMR selection uses that request value.
### Final LLM filter [#final-llm-filter]
After mechanical ranking, Memmy prefers the evolution model for relevance filtering and falls back to the summary model when evolution is not configured:
| Setting | Default | Effect |
| ----------------------------- | ------: | ------------------------------------------------------------------------------ |
| `llmFilterEnabled` | `true` | Enables final semantic filtering |
| `llmFilterMinCandidates` | `1` | Minimum mechanical candidates required before calling the LLM |
| `llmFilterMaxKeep` | `8` | Maximum kept after a successful LLM call |
| `llmFilterFallbackMaxKeep` | `6` | Fallback cap when no LLM is configured, the call fails, or output is malformed |
| `llmFilterCandidateBodyChars` | `500` | Candidate body characters shown to the filter model |
The LLM may intentionally drop every candidate. If its output is invalid or the call fails, the top 6 mechanically ranked candidates are retained.
## How Context Is Injected [#how-context-is-injected]
Hits are rendered in this order:
1. L1 traces and similar episodes;
2. L2 Policy;
3. L3 Environment Knowledge;
4. Skills;
5. decision guidance distilled from experience.
A normal snippet is capped at 640 characters. Skills use `summary` mode by default, injecting the name and up to 200 characters of description. `full` mode injects the guide but still obeys the 640-character per-snippet cap. The final Markdown explicitly labels the content as historical memory that must be checked against the current request and current repository state.
## Tuning config.yaml [#tuning-configyaml]
The main configuration file is `~/.memmy/config.yaml` unless `MEMMY_CONFIG` points elsewhere. The following block lists the effective core settings and their defaults. You only need to keep fields you want to override:
```yaml
memmyMemory:
version: 1
domain: ""
algorithm:
enableMemoryAdd: true
enableMemorySearch: true
enableQueryRewrite: false
capture:
maxTextChars: 4000
maxToolOutputChars: 2000
synthReflection: true
embedAfterCapture: true
batchThreshold: 12
reward:
gamma: 0.9
lambda: 0.5
delta: 0.1
decayHalfLifeDays: 30
feedbackWindowSec: 30
l2Induction:
minEpisodesForInduction: 1
minSimilarity: 0.65
candidateTtlDays: 30
minTraceValue: 0.005
minGain: 0.02
archiveGain: -0.05
l3Abstraction:
minPolicies: 1
minPolicyGain: 0.02
minPolicySupport: 1
clusterMinSimilarity: 0.3
minConfidenceForRetrieval: 0.2
skill:
minEtaForRetrieval: 0.1
minSupport: 1
minGain: 0.02
candidateTrials: 1
session:
followUpMode: merge_follow_ups
mergeMaxGapMs: 7200000
retrieval:
tier1TopK: 3
tier2TopK: 5
tier3TopK: 2
candidatePoolFactor: 4
weightPriority: 0.4
mmrLambda: 0.7
rrfConstant: 60
relativeThresholdFloor: 0.2
minSkillEta: 0.1
minTraceSim: 0.25
episodeGoalMinSim: 0.45
tagFilter: auto
keywordTopK: 20
skillEtaBlend: 0.15
smartSeed: true
smartSeedRatio: 0.7
multiChannelBypass: true
skillInjectionMode: summary
skillSummaryChars: 200
llmFilterEnabled: true
llmFilterMaxKeep: 8
llmFilterFallbackMaxKeep: 6
llmFilterMinCandidates: 1
llmFilterCandidateBodyChars: 500
readOnlyInjectionProfile: all
```
After saving the file, run:
```bash
memmy-memory reload-config
```
Retrieval, evolution, and model settings can be hot-reloaded. A `storage` change makes the reload response return `requiresRestart: true`, in which case the Memory service must be restarted. Algorithm settings are centralized in the service, so Agent Hooks and plugins usually do not need to be reinstalled.
### Common tuning directions [#common-tuning-directions]
* **Increase recall:** raise `candidatePoolFactor` or `keywordTopK`, or lower `relativeThresholdFloor` or `minTraceSim`.
* **Reduce noise:** raise `minTraceSim`, `relativeThresholdFloor`, or `minSkillEta`, or lower `llmFilterMaxKeep`.
* **Increase diversity:** lower `mmrLambda`. Raising it favors the highest relevance more strongly.
* **Handle multi-fact or indirect questions:** enable `enableQueryRewrite`, at the cost of extra evolution-model calls and latency.
* **Disable memory reads or writes independently:** set `enableMemorySearch: false` or `enableMemoryAdd: false`.
## Inspecting a Recall [#inspecting-a-recall]
```bash
memmy-memory search "your query" --verbose
```
For debugging, inspect:
* `candidateMemoryIds`: raw candidates merged from the underlying channels;
* `hits`: candidates after fusion, thresholding, and MMR;
* `sourceMemoryIds`: memories actually rendered into context;
* `status`: whether LLM filtering succeeded, was disabled, was skipped, or fell back;
* the Memory Logs page: `memory.search` candidates, filtered results, droppedByLlm entries, and statistics.
## The Memory Management Page [#the-memory-management-page]
The `/memory` sidebar is organized into three groups by purpose:
| Group | Sub-pages | Description |
| -------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Work | Overview / Memories / Tasks / Experiences / World models / Skills | View summary statistics and memory details, organized by task, experience, world model, and skill |
| Insights | Analytics / Logs | Review write and evolution analytics, plus Memory API search and write logs |
| System | Cross-Agent access | Manage Agent sources, history scanning, and Hook/plugin connection status |
The Logs page provides dedicated detail views for `memory.search` and `memory.add` (search candidates, written fields, result status), useful for explaining why a memory was matched or written.
# Install Memory Skills for External Agents (/docs/memory/skills)
Beyond passively scanning history, Memmy lets external Agents actively read and write memory.
The desktop app starts it automatically; or launch from source with `npm run memory:serve:dev`. The desktop "Memory Sources" page offers one-click installation to `~/.local/bin`. `bash memmy-memory init --agent ` Memmy writes the memory instruction file into the target Agent's rules directory, after which that Agent will actively call `memmy-memory` to retrieve and write memories.
# Agent Sources & Scanning (/docs/memory/sources)
Learn how Memmy scans local history from nine built-in Agents and which Hooks, plugins, Skills, and live-memory behaviors it installs.
An Agent Source is Memmy's adapter for reading local history from an external Agent. Source scanning imports conversations that already exist; supported live integrations use Hooks and plugins for automatic recall and capture in new conversations.
History scanning and live integration are separate
“Sync new” reads data the Agent has already written locally. A Hook or plugin handles automatic recall, automatic turn capture, and task resumption in new conversations. Scanning alone does not modify Agent configuration; installing a Hook, plugin, or Skill writes the files listed below.
## Built-in sources [#built-in-sources]
| Agent | Default history source | Live integration |
| ----------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------- |
| Cursor | `~/Library/Application Support/Cursor/User/workspaceStorage/**/state.vscdb` and `globalStorage/state.vscdb` | Hook |
| Claude Code | `~/.claude/projects/**/*.jsonl` | Hook |
| Codex | `~/.codex/sessions////rollout-*.jsonl` | Hook |
| OpenCode | `~/.local/share/opencode/opencode.db` | Native plugin |
| OpenClaw | Conversation and memory SQLite databases under `~/.openclaw` | Memory plugin |
| Hermes | `~/.hermes/sessions/**/*.jsonl` and `~/.hermes/state.db` | Memory Provider plugin |
| WorkBuddy | `~/.workbuddy/projects/**/*.jsonl` | Skill (on-demand memory access) |
| Pi | `~/.pi/agent/sessions/**/*.jsonl` | Skill (on-demand memory access) |
| qwenwork | `~/.qwenworkcn/projects/**/*.jsonl` | Skill (on-demand memory access) |
Cross-Agent access only shows built-in Agents whose local configuration or history source is currently detected. Undetected built-in Agents do not occupy space in the list.
## Incremental sync [#incremental-sync]
* **Sync new** scans every detected source; each source can also be synced individually.
* Scans can be paused, resumed, or stopped; progress streams in real time over SSE.
* **Deep scan** uses `full` mode to backfill older history and requires a second confirmation.
* Under **Advanced actions → Add another Agent**, you can select `kimi code`, `zcode`, `minimax code`, or `coder`, or enter another Agent name.
* Adding another Agent does not require a local path. Memmy starts a discovery task that locates the history directory, identifies the message format, installs the full `memmy-memory` Skill, imports the latest 500 complete conversation turns, and saves a rule for later syncs. This flow does not install a native Hook or plugin for an unknown Agent.
* The discovery task first verifies the Agent identity against an executable, `.app`, or installed package product name. During automatic discovery, matching only ignores case, spaces, hyphens, and underscores; it does not translate, infer aliases, or match semantically. If no installed product matches, Memmy reports that the Agent was not found and stops. The user can continue by supplying absolute paths to the installation artifact, native history file or directory, and optional Skill directory so Memmy can validate only those scoped paths. Memmy does not substitute another Agent or its own history.
* During discovery and validation, a custom Agent remains an internal draft and is not shown in the Cross-Agent list. It appears only after Memmy records a verified native history path. A name reported as not found therefore does not create a visible Agent card, while the original task can still accept paths and continue onboarding.
### Why scanned-message and added-memory counts differ [#why-scanned-message-and-added-memory-counts-differ]
The scan and “Adding” progress indicators count **messages**, while the memory pages count **memory records**. These values are not one-to-one. Memmy groups messages by source and conversation, then writes one L1 memory for each complete conversation turn:
* A user message starts a turn. Following tool, system, and Assistant messages are merged into that turn, which must start with non-empty user content and end with a non-empty Assistant message.
* One complete turn creates one L1 memory. For example, one user message, two tool messages, and one Assistant message are four processed messages but only one added memory.
* Messages reread at the watermark boundary and messages imported previously are deduplicated with conversation checkpoints, source message IDs, and stable turn IDs. A repeat sync updates or returns the same memory instead of creating a copy.
* A user-only turn, a turn without a final Assistant response, or a turn with empty boundary content is skipped until a later sync can complete it.
* An oversized turn is skipped, while a Memory service write error is counted as failed. Neither case adds a memory.
As a result, the current scan/processed-message count, the unique imported-message count, and the new-memory count can all differ. Before counting, built-in adapters also ignore non-message records, extract usable text, and redact common secrets and large Base64 payloads.
### How the date-time watermark works [#how-the-date-time-watermark-works]
Memmy maintains a separate date-time watermark for each source. This is not simply the “last scanned” time shown in the UI:
1. When the initial scan starts, Memmy stores its start time as a baseline and also records the newest message timestamp actually observed. The later of those values becomes the effective cursor for the next incremental scan.
2. On later **Sync new** runs, a built-in source selects a conversation when at least one of its messages has a timestamp **greater than or equal to** the cursor. Memmy rereads the entire selected conversation so a watermark cannot cut off the user request at the start of a turn.
3. The inclusive `>=` boundary intentionally allows the boundary message to be read again. Before import, a conversation checkpoint compares the last message timestamp, message ID, and content hash. Stable source message IDs and turn IDs then make the import itself idempotent.
4. The watermark advances to the newest observed timestamp only when scanning and import finish without errors and there are no incomplete or failed conversations. After a scan error or an unfinished turn, the watermark stays in place so the next run can retry. The displayed “last scanned” time may still change and is not the incremental cursor.
For an Agent connected through “Add another Agent” whose format Memmy discovers, the first import stores a sync boundary. Later syncs select complete turns whose starting user message is strictly later than that boundary, then use stable message and turn IDs to remove repeats.
### Images, files, and oversized turns [#images-files-and-oversized-turns]
An image or file attachment does not cause a turn to be skipped by itself. Built-in sources extract usable text from history and replace common inline Base64 image or file payloads with a redaction marker before import.
Attachment contents, file text, tool output, or other long text may still become part of a turn. Memmy measures the UTF-8 size of the complete memory-write request (`memory.add` JSON), including the user request, tool trace, Assistant response, and request metadata. If it exceeds **2 MiB**, Memmy skips the entire turn rather than truncating it or splitting it across memories, then continues with other turns in the same sync. This is recorded as skipped rather than as a sync failure, so the sync may still complete successfully. The size limit applies to the complete turn request, not only to the user request's character count.
## Scan preferences [#scan-preferences]
| Toggle | Effect |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Auto-sync conversations | Automatically collect new conversations from connected Agents (on startup and on a schedule)—no need to click Sync new |
| Auto-connect newly found Agents | Installs the integration for a newly detected built-in Agent; the compact Skill is installed with it |
When auto-install is disabled, a detected Agent still appears in the list and you can click **Install Hook**, **Install plugin**, or **Install Skill** manually.
## Data processing and local management [#data-processing-and-local-management]
* Each successfully written complete turn first becomes one raw L1 memory, then receives its summary and search index in the background.
* You can view the local data path (default `~/.memmy/memory-service`), open the directory, export `memory.sqlite`, or wipe local memory data after a second confirmation.
* Removing a Hook, plugin, or Skill does not delete imported history. Clearing local data is a separate explicit action.
## Hook and plugin integrations [#hook-and-plugin-integrations]
Memmy connects to live Agent conversations through each host's native **Hooks** or **plugin** system. Installing an integration also installs a compact `memmy-memory` Skill for on-demand search and retrieval when the automatically injected context is not enough.
### Integration overview [#integration-overview]
| Agent | Integration | Events or interfaces used | Main effect |
| ----------- | ---------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Cursor | Hook | `beforeSubmitPrompt`, `afterAgentResponse`, `stop` | Starts turns, records responses, captures completed turns, and supports `/memmy-resume` |
| Claude Code | Hook | `UserPromptSubmit`, `Stop` | Recalls and injects memory before a request, captures the completed turn, and supports `/memmy-resume` |
| Codex | Hook | `UserPromptSubmit`, `Stop` | Recalls and injects memory before a request, captures the completed turn, and supports `/memmy-resume` |
| OpenCode | Native plugin | Message, tool, text-completion, and session events | Recalls memory, captures responses and tool traces, and exposes native memory tools and `/memmy-resume` |
| OpenClaw | Memory plugin | `before_prompt_build`, `agent_end` | Injects memory while building the prompt, captures the completed turn, and exposes native memory tools |
| Hermes | Memory Provider plugin | Provider lifecycle methods such as `prefetch` and `sync_turn` | Recalls and captures automatically, mirrors explicit Hermes memory writes, and exposes native memory tools |
| WorkBuddy | Skill | Agent invokes `memmy-memory` | Searches, reads, and writes shared memory on demand |
| Pi | Skill | Agent invokes `memmy-memory` | Searches, reads, and writes shared memory on demand |
| qwenwork | Skill | Agent invokes `memmy-memory` | Searches, reads, and writes shared memory on demand |
### What happens during a turn [#what-happens-during-a-turn]
```mermaid
flowchart LR
Request["User request"] --> Entry["Hook / plugin"]
Entry --> Start["Open session and start turn"]
Start --> Recall["Retrieve relevant Memmy memory"]
Recall --> Context["Inject it as historical context"]
Context --> Agent["Agent performs the task"]
Agent --> Complete["Capture answer, status, and available tool traces"]
Complete --> Memory["Complete the turn in the local Memory service"]
```
Common results after installation:
* **Automatic recall:** Claude Code, Codex, OpenCode, OpenClaw, and Hermes retrieve and inject relevant memory before normal requests run.
* **Automatic capture:** the Hook or plugin submits the user request, Agent answer, and success/failure status at the end of a turn. The Agent does not need to run `memmy-memory add` manually.
* **Task resumption:** `/memmy-resume ` returns up to five L1 episode candidates. Enter `1`–`5` to load the complete episode and inject continuation context. Claude Code, OpenCode, OpenClaw, and Hermes use native command entry points; Cursor, Codex, and Skill-only integrations install an explicit `memmy-resume` Skill.
* **On-demand lookup:** the bundled Skill keeps `memmy-memory search` and `memmy-memory get` for cases where automatic context is insufficient.
* **Source attribution:** captured turns carry `cursor`, `claude_code`, `codex`, `opencode`, `openclaw`, or `hermes`, so you can filter and trace their origin.
Cursor's current Hook focuses on automatic capture and
/memmy-resume
When a normal Cursor request needs additional memory, the bundled Skill performs an on-demand lookup. The other five integrations inject recalled context before normal requests.
### Cursor: three Hooks [#cursor-three-hooks]
Memmy appends its own entries to `~/.cursor/hooks.json` without replacing other Hooks.
| Hook | When it runs | What Memmy does |
| -------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| `beforeSubmitPrompt` | Before the user request is submitted | Opens or reuses a Memmy session, starts a turn, stores the request, and handles `/memmy-resume` search and selection |
| `afterAgentResponse` | After the Agent produces a response | Stores the final response in the current turn state for the completion Hook |
| `stop` | When the Agent turn stops | Combines the request and response and calls turn-complete; failures are allowed through and do not block Cursor |
Written or updated by default:
* `~/.cursor/hooks.json`
* `~/.cursor/hooks/memmy-resume-hook.mjs`
* `~/.cursor/hooks/memmy-memory-config.json`
* `~/.cursor/skills/memmy-memory/SKILL.md`
* `~/.cursor/skills/memmy-resume/SKILL.md`
### Claude Code: `UserPromptSubmit` and `Stop` [#claude-code-userpromptsubmit-and-stop]
| Hook | When it runs | What Memmy does |
| ------------------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `UserPromptSubmit` | Before the user request reaches the model | Starts a Memmy turn, puts recalled memory into `additionalContext`, and handles `/memmy-resume` |
| `Stop` | When Claude Code completes or terminates a turn | Reads the request and answer from the Hook payload or transcript, then completes the turn as `succeeded`, `failed`, or `cancelled` |
Written or updated by default:
* `~/.claude/settings.json`
* `~/.claude/hooks/memmy-resume-hook.mjs`
* `~/.claude/hooks/memmy-memory-config.json`
* `~/.claude/commands/memmy-resume.md`
* `~/.claude/CLAUDE.md`
* `~/.claude/skills/memmy-memory/SKILL.md`
### Codex: `UserPromptSubmit` and `Stop` [#codex-userpromptsubmit-and-stop]
| Hook | When it runs | What Memmy does |
| ------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `UserPromptSubmit` | Before the user request is submitted | Starts a turn, injects recalled memory through Hook `additionalContext`, and handles `/memmy-resume` |
| `Stop` | When the Codex turn stops | Extracts the answer from the transcript or last Assistant message, completes the turn, and preserves failed or cancelled status |
Written or updated by default:
* `~/.codex/hooks.json`
* `~/.codex/hooks/memmy-resume-hook.mjs`
* `~/.codex/hooks/memmy-memory-config.json`
* `~/.codex/AGENTS.md`
* `~/.codex/skills/memmy-memory/SKILL.md`
* `~/.codex/skills/memmy-resume/SKILL.md`
### OpenCode: native plugin [#opencode-native-plugin]
| Callback | Effect |
| ----------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `chat.message` | Starts a turn, injects recalled memory automatically, and handles `/memmy-resume` |
| `tool.execute.before` / `tool.execute.after` | Captures non-Memmy tool arguments and results as part of the turn trace |
| `experimental.text.complete` / `message.part.updated` | Collects the complete Assistant text output |
| `session.error` | Marks the current turn failed and stores the error |
| `session.idle` | Completes and captures the current turn asynchronously |
| `dispose` | Flushes turns that have not yet been submitted before the plugin unloads or the process exits |
The plugin also registers the native `memmy_memory_search`, `memmy_memory_get`, and `memmy_memory_add` tools.
Written or updated under `~/.config/opencode` by default:
* `plugins/memmy-memory.js`
* `plugins/memmy-memory-config.json`
* `commands/memmy-resume.md`
* `../../../AGENTS.md`
* `skills/memmy-memory/SKILL.md`
If `OPENCODE_CONFIG_DIR` or `XDG_CONFIG_HOME` is set, Memmy writes to the corresponding configuration directory instead.
### OpenClaw: Memory plugin [#openclaw-memory-plugin]
| Interface | Effect |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `registerMemoryCapability` | Tells OpenClaw that Memmy is active and that injected content is historical context |
| `before_prompt_build` | Starts a turn before prompt construction and injects recalled memory or a selected episode through `prependContext` |
| `agent_end` | Extracts the request, answer, and tool trace and completes the turn synchronously so capture is not lost on process exit |
| `registerCommand` | Registers `/memmy-resume` |
| `registerTool` | Registers `memmy_memory_search`, `memmy_memory_get`, and `memmy_memory_add` |
Installation points `plugins.slots.memory` to `memmy-memory` and enables `allowPromptInjection` and `allowConversationAccess`.
Written or updated by default:
* `~/.openclaw/extensions/memmy-memory/`
* `~/.openclaw/openclaw.json`
* `~/.openclaw/skills/memmy-memory/SKILL.md`
* `../../../AGENTS.md` in the OpenClaw workspace (default `~/.openclaw/workspace/AGENTS.md`)
OpenClaw has one memory-provider slot. If another memory plugin is already active, Memmy asks whether to replace it or keep it and install only the Skill.
### Hermes: Memory Provider plugin [#hermes-memory-provider-plugin]
| Provider interface / Hook | Effect |
| --------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `system_prompt_block` | Declares that Memmy is active and that injected memory is historical context only |
| `prefetch` | Starts a turn before the user request and returns relevant memory context |
| `sync_turn` | Completes the turn in a background thread and captures the user request and Assistant answer |
| `on_memory_write` | Mirrors explicit memory writes from Hermes into Memmy |
| `on_session_switch` | Keeps the Memmy session aligned with the active Hermes session |
| `get_tool_schemas` / `handle_tool_call` | Exposes `memmy_memory_search`, `memmy_memory_get`, and `memmy_memory_add` |
| `pre_llm_call` / `pre_gateway_dispatch` | Recognizes a `/memmy-resume` candidate number and injects or rewrites it as full episode context |
Installation sets `memory.provider` to `memmy-memory`, enables the `memory` toolset, and enables the standalone `memmy-resume` command plugin.
Written or updated by default:
* `~/.hermes/plugins/memmy-memory/`
* `~/.hermes/plugins/memmy-resume/`
* `~/.hermes/config.yaml`
* `~/.hermes/SOUL.md`
* `~/.hermes/skills/memmy-memory/SKILL.md`
Hermes likewise allows one active Memory Provider. Memmy asks for confirmation before replacing another provider.
### Install, verify, and remove [#install-verify-and-remove]
1. Open **Memory → Cross-Agent access**.
2. For Cursor, Claude Code, and Codex, click **Install Hook**. For OpenCode, OpenClaw, and Hermes, click **Install plugin**. For WorkBuddy, Pi, and qwenwork, click **Install Skill**.
3. For another Agent, expand **Advanced actions → Add another Agent**, select a preset or enter its name, and let Memmy complete discovery and the first import.
4. If the Agent is already running, restart it or open a new session so it reloads its configuration.
5. Complete a normal turn, then confirm that the corresponding source appears in Memmy's memory or log views.
6. Enter `/memmy-resume `, confirm that candidates appear, and select an episode with `1`–`5`.
When you click **Remove Hook**, **Remove plugin**, or **Remove Skill**, Memmy cleans up the integration content it manages. Other configuration is preserved, and memories already stored in Memmy are not deleted.
### Local access and failure behavior [#local-access-and-failure-behavior]
* Hooks and plugins read the Memory service endpoint and token from `~/.memmy/config.yaml` and keep the runtime configuration they need in the Agent's local config directory. Do not publish these config files.
* Injected content is wrapped in `` as historical memory, while `` identifies the authoritative current request. This reduces the risk of treating old memory as a new instruction.
* Recall and capture are **fail-open**: errors are logged and the Agent continues its current task instead of being interrupted when the Memory service is temporarily unavailable.
* Host Hook commands have a 60-second timeout; individual Memory requests have a 45-second timeout.
# API Key Mode (BYOK) (/docs/models/byok)
Use your own model quota. Setup takes three steps, each with a real connection test.
1. Choose a provider (OpenAI, Anthropic, Gemini, DeepSeek, Zhipu, Tongyi Qianwen, Kimi, MiniMax, Baidu Qianfan, Doubao), then fill in the model ID, endpoint, and API Key; Embedding can run in local mode or custom mode.
2. The memory summary model (summarizes conversations and experience) and the skill evolution model (distills experience into skills) can both simply reuse the primary model.
3. ASR (voice input, currently fixed to Qwen ASR) and the image generation model are skippable — they never block normal chat or memory features.
## Provider Defaults [#provider-defaults]
| Provider | Default Endpoint | Default Model Placeholder |
| -------------- | --------------------------------------------------- | ------------------------- |
| OpenAI | `https://api.openai.com/v1` | `gpt-4o` |
| Anthropic | `https://api.anthropic.com` | `claude-sonnet-4` |
| Gemini | `https://generativelanguage.googleapis.com` | `gemini-2.5-pro` |
| DeepSeek | `https://api.deepseek.com/v1` | `deepseek-chat` |
| Zhipu | `https://open.bigmodel.cn/api/paas/v4` | `glm-4` |
| Tongyi Qianwen | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `qwen-max` |
| Kimi | `https://api.moonshot.ai/v1` | `moonshot-v1-128k` |
| MiniMax | `https://api.minimax.chat/v1` | `MiniMax-Text-01` |
| Baidu Qianfan | `https://qianfan.baidubce.com/v2` | `ernie-4.0-8k` |
| Doubao | `https://ark.cn-beijing.volces.com/api/v3` | `doubao-pro-256k` |
# Supported Providers (/docs/models/providers)
The Agent Runtime currently supports:
OpenAI-compatible APIs, Anthropic, Azure OpenAI, AWS Bedrock, OpenRouter, DeepSeek, Gemini, Zhipu, DashScope, Kimi, MiniMax, Ollama, LM Studio, GitHub Copilot, OpenAI Codex OAuth, and more.
OAuth-based providers can sign in via the CLI:
```bash
memmy provider login
```
# Desktop Local API (/docs/reference/local-api)
The desktop local API is built on Fastify and binds to a random port on `127.0.0.1`. Everything except `/api/health` is authenticated with `x-memmy-local-token`; due to EventSource limitations, SSE passes the same token via `?token=`.
## Main Endpoint Groups [#main-endpoint-groups]
| Group | Representative Endpoints |
| ----------------------- | --------------------------------------------------------------------------------------------------- |
| App configuration | `PATCH /api/app/settings`, `GET/PUT /api/app/model-config`, `POST /api/app/model-config/test` |
| Account | `POST /api/account/send-code`, `POST /api/account/verify-code`, `POST /api/account/logout` |
| Integrations & channels | `GET /api/v1/integrations/capabilities`, `POST /api/v1/channels/:provider/connect` |
| Agent Source | `GET /api/agent-sources`, `POST /api/agent-sources/scan`, `POST /api/agent-sources/:sourceId/skill` |
| Local data | `POST /api/local-data/reveal`, `POST /api/local-data/export`, `DELETE /api/local-data` |
| Memory proxy | `/api/v1/memory/*`, `/api/v1/panel/*` (proxied to the Memory Runtime) |
| MCP bridge | `GET/POST/DELETE /mcp/composio` (separate `x-memmy-mcp-token`) |
## SSE Events [#sse-events]
`/api/events` pushes: `app.connected`, `app.heartbeat`, `agent_source.scan_progress`, `agent_source.scan_completed`.
# Memory Runtime API (/docs/reference/memory-api)
Default address `http://127.0.0.1:18960`. Once `storage.token`, `MEMMY_MEMORY_TOKEN`, or `MEMORY_SERVICE_TOKEN` is set, all endpoints except the health check require a bearer token.
| Method | Path | Description |
| -------- | ----------------------------------- | ------------------------ |
| `GET` | `/api/v1/health` | Health check |
| `POST` | `/api/v1/sessions/open` | Open an Agent session |
| `POST` | `/api/v1/sessions/:sessionId/close` | Close a session |
| `POST` | `/api/v1/turns/start` | Record a turn start |
| `POST` | `/api/v1/turns/:turnId/complete` | Record a turn completion |
| `POST` | `/api/v1/memory/search` | Search memories |
| `POST` | `/api/v1/memory/add` | Write a memory |
| `GET` | `/api/v1/memory/:id` | Memory details |
| `DELETE` | `/api/v1/memory/:id` | Delete a memory |
| `GET` | `/api/v1/panel/overview` | Panel overview |
| `GET` | `/api/v1/panel/analysis` | Memory analytics |
| `GET` | `/api/v1/panel/items` | Entry list |
## Local Storage Configuration [#local-storage-configuration]
```yaml
memmyMemory:
version: 1
activeProfile: byok
storage:
mode: local
backend: sqlite
sqlitePath: ~/.memmy/memory-service/memory.sqlite
endpoint: http://127.0.0.1:18960
token: local-token
profiles:
byok:
embedding:
provider: local
```
# OpenAI-Compatible API (/docs/reference/openai-api)
`memmy serve` listens on `http://127.0.0.1:18990` by default:
| Method | Path |
| ------ | ---------------------- |
| `GET` | `/health` |
| `GET` | `/v1/models` |
| `POST` | `/v1/chat/completions` |
Any tool or script that speaks the OpenAI Chat Completions protocol can reuse Memmy directly.
# Default Ports (/docs/reference/ports)
| Service | Default Port |
| ------------------------------------- | --------------------------------- |
| Memory HTTP / memory foundation | `18960` |
| Gateway health | `18970` |
| WebUI / WebSocket / admin HTTP | `18980` |
| OpenAI-compatible API (`memmy serve`) | `18990` |
| Desktop frontend Vite dev server | `19000` |
| Vite HMR | `19010` |
| Desktop local API | Random port |
| Composio MCP bridge | Reuses the desktop local API port |
# Security & Privacy (/docs/security/security)
Memmy's security boundary is built on **local execution** and **explicit authentication**:
* The desktop local API only accepts requests from the local machine, `file://`, or controlled origins by default, verified with `x-memmy-local-token`.
* Due to EventSource limitations, SSE passes the same runtime token via a query parameter.
* The Composio MCP bridge uses a separate `x-memmy-mcp-token`.
* Memory HTTP can be protected with a bearer token (`MEMMY_MEMORY_TOKEN` / `MEMORY_SERVICE_TOKEN`).
* Config supports `${ENV_NAME}` environment variable references, keeping API Keys out of config files.
* The Memory client must connect to a real Memory Layer or discover a local SQLite source — otherwise startup fails rather than silently showing fake data.
## Where Your Data Lives [#where-your-data-lives]
Everything defaults to `~/.memmy`: config, workspace, the Memory SQLite database, and runtime files. Desktop app state is maintained by the local backend in a local SQLite database.
Scanning and ingestion happen entirely locally, with memories written to local SQLite. Participation in the "memory improvement program" is explicitly controlled by a toggle in privacy settings.
# Getting Started (/docs/start/getting-started)
This page walks you through installing Memmy, completing first-run setup, and having your first conversation — from zero.
## What You Need [#what-you-need]
* A macOS or Windows desktop environment (desktop path).
* Or Node.js `>=22` + npm (CLI / source path).
* API Key mode requires at least one model provider's API Key.
Not sure which mode to pick? Account mode works out of the box and comes with platform trial tokens; in API Key mode your data and quota stay fully under your control. Both modes store data local-first.
## Quick Setup [#quick-setup]
For a terminal-only installation on Linux x64 or arm64, install Node.js 22 or newer and make sure a systemd user session is available, then run:
```bash
curl -fsSL https://raw.githubusercontent.com/MemTensor/memmy-agent/main/scripts/install.sh | bash
memmy
```
The installer starts the local Memory Service as `memmy-memory.service`. If no usable model is configured, the first bare `memmy` command opens the existing wizard. After saving, it enables `memmy-gateway.service`, waits for readiness, and continues into the TUI. Both `systemd --user` services stay running when the TUI or terminal exits and start again on later logins; linger is not enabled. The installer launcher also refreshes a private `~/.memmy/systemd/gateway.env` file (mode `0600`) so configuration-referenced credentials and the terminal `PATH` remain available to the persistent Gateway.
Use `systemctl --user status memmy-memory.service` and `systemctl --user status memmy-gateway.service` to inspect them. The installer does not modify external agents. Run `memmy-memory init` or `memmy-memory init --agent ` explicitly to install Memory integration for an agent.
Download and install the Memmy desktop app. On first launch it automatically:
1. Sets `MEMMY_HOME` and `MEMMY_CONFIG`.
2. Installs the bundled CLI and prepares Hooks, plugins, and companion Skills for authorized Agents.
3. Prepares `~/.memmy/config.yaml`, the workspace, and the Memory SQLite database.
4. Starts the Memory service and the Agent gateway.
```bash
cd App/memmy-agent
npm install
npm run build
node dist/main.js --help
```
On the welcome page, choose:
* **Account mode**: sign in with a phone number or email verification code, using platform trial tokens.
* **API Key mode**: a three-step setup — primary model + Embedding, memory-related models, and optional ASR and image generation models — each step with a real connection test.
```bash
memmy onboard # Terminal menu for configuring models, providers, and tools
memmy onboard --defaults # Initialize config and workspace non-interactively
memmy status # Check configuration and runtime status
```
Enter the main workbench and send your first message from the input box. `Enter` to send, `Shift + Enter` for a new line, and type `/` to open the slash command panel.
```bash
memmy agent --message "Hi, introduce the current workspace"
# Or start an interactive chat directly
memmy
```
Open "Memory → Cross-Agent access" and scan conversation history from Cursor, Claude Code, Codex, OpenCode, OpenClaw, Hermes, WorkBuddy, Pi, and qwenwork into the memory store. First-run onboarding lets you scan only or also install the matching Hook, plugin, or Skill for detected Agents.
After connection, Hooks and plugins capture completed turns and inject relevant memory automatically; WorkBuddy, Pi, and qwenwork use the Skill for on-demand memory access. See [Agent Sources & Scanning](/docs/memory/sources) for details.
To connect an Agent outside the built-in list, open **Advanced actions → Add another Agent**. Select `kimi code`, `zcode`, `minimax code`, or `coder`, or enter another name; Memmy discovers its history location and format, installs the Skill, and completes the first import.
Open the "Tools" page:
* Messaging channels: Telegram, Discord, iMessage, WeChat, Feishu, DingTalk.
* Managed integrations: GitHub, Gmail, Notion, Slack, Linear, Jira, and more, via OAuth.
## Advanced: Use Memmy as a Local API [#advanced-use-memmy-as-a-local-api]
```bash
memmy serve
```
Listens on `http://127.0.0.1:18990` by default, exposing `GET /health`, `GET /v1/models`, and `POST /v1/chat/completions` — reusable by any tool that speaks the OpenAI Chat Completions protocol.
## Advanced: Environment Variables [#advanced-environment-variables]
| Variable | Purpose |
| --------------------------------------------- | ------------------------------------------------------ |
| `MEMMY_HOME` | Memmy data home directory (default `~/.memmy`) |
| `MEMMY_CONFIG` | Main config file path (default `~/.memmy/config.yaml`) |
| `MEMMY_MEMORY_TOKEN` / `MEMORY_SERVICE_TOKEN` | Bearer token for the Memory HTTP service |
`${ENV_NAME}` references in the config file are resolved automatically, so you never hard-code API Keys in config.
## What's Next [#whats-next]
Sessions, attachments, voice, and slash commands · Agent scanning and Hook/plugin integrations · The three-step setup in detail · The lightweight always-on-desktop entry point
## Related [#related]
* [Default Ports](/docs/reference/ports)
* [Security & Privacy](/docs/security/security)
* [FAQ](/docs/help/faq)
# CLI Command Reference (/docs/terminal/cli)
| Command | Description |
| --------------------------------- | --------------------------------------------------- |
| `memmy` | Start an interactive chat |
| `memmy onboard` | Terminal menu-driven setup |
| `memmy onboard --defaults` | Initialize config and workspace non-interactively |
| `memmy status` | Check config, workspace, model, and provider status |
| `memmy agent --message "..."` | Send a single-turn message |
| `memmy serve` | Start the OpenAI-compatible API |
| `memmy provider login ` | Provider OAuth sign-in |
# TUI User Guide (/docs/terminal/tui)
Memmy TUI is Memmy's full-screen terminal interface. Whether you install the desktop app or just the CLI, you can run `memmy` in your terminal to use it.
## Installing Memmy TUI [#installing-memmy-tui]
### Option 1: Install the Memmy desktop app [#option-1-install-the-memmy-desktop-app]
For macOS and Windows. The desktop app provides the `memmy` command and takes care of starting the local Memory and Agent Gateway services.
1. Download and install the desktop app from the [Memmy official website](https://memmy.cn/en/) or [GitHub Releases](https://github.com/MemTensor/memmy-agent/releases).
2. Launch Memmy and complete setup in either account mode or API key mode.
3. Open a new terminal and check that the command is available:
```bash
memmy --help
memmy --version
```
* **macOS:** drag the app into `/Applications` and launch it at least once. If your terminal reports that `memmy` cannot be found, open a new terminal or run:
```bash
source ~/.zshrc
```
* **Windows**: after installation, open a new PowerShell or Windows Terminal window.
When using the TUI provided by the desktop app, keep the Memmy desktop app running. Closing it also stops the Gateway it manages.
### Option 2: Install only the Memmy CLI [#option-2-install-only-the-memmy-cli]
For Linux x64 or arm64 environments that don't need the desktop app. Requires **Node.js 22** or later and a system with `systemd --user` support.
```bash
curl -fsSL https://raw.githubusercontent.com/MemTensor/memmy-agent/main/scripts/install.sh | bash
```
Once installation finishes, run:
```bash
memmy
```
On first run, if no model is available yet, Memmy opens the setup wizard. The CLI installer manages the Memory and Gateway services; they keep running after you exit the TUI or close the terminal.
Check service status:
```bash
systemctl --user status memmy-memory.service
systemctl --user status memmy-gateway.service
```
## First Time Setup [#first-time-setup]
If you already completed onboarding in the desktop app, you can skip this section. CLI users should run:
```bash
memmy onboard --defaults
memmy onboard
memmy status
```
* `memmy onboard --defaults` — creates or refreshes the config file and workspace, non-interactively.
* `memmy onboard` — configures models, providers, Gateway, Memory, and tools interactively.
* `memmy status` — checks the current configuration, workspace, model, and provider.
Default locations:
* Config file: `~/.memmy/config.yaml`
* Workspace: `~/.memmy/workspace`
## Opening the TUI [#opening-the-tui]
Run:
```bash
memmy
```
This opens the default `cli:direct` session. Type a message and press `Enter` to send it.
**Resuming or creating sessions:**
```bash
# Resume an existing session
memmy --session cli:work
# Create a new standalone session
memmy --standalone
# Create a session bound to a project directory
memmy --project /path/to/project
```
`--session`, `--standalone`, and `--project` are mutually exclusive — pick one.
List existing sessions:
```bash
memmy sessions list
```
### `memmy` vs. `memmy agent` [#memmy-vs-memmy-agent]
To open the full-screen TUI covered in this guide, use bare `memmy`.
`memmy agent` is for single-turn tasks or conventional terminal interaction:
```bash
# Single-turn task
memmy agent --message "Give me an overview of the current workspace"
# Send a single turn from stdin
echo "Summarize this project" | memmy agent
```
## Sending Tasks [#sending-tasks]
Type after the `❯` prompt and press `Enter` to send. The TUI does not currently support the desktop workbench's `Shift + Enter` newline; `Enter` always submits.
Long text wraps visually in the terminal, but you cannot insert multiple lines. To send multi-line text, use:
```bash
memmy agent --message $'first line\nsecond line'
```
or:
```bash
printf 'first line\nsecond line\n' | memmy agent
```
### Typing while a task is running [#typing-while-a-task-is-running]
* `Enter` — queue the next turn.
* `Tab` — append your input to the current turn, when that turn is being executed by this TUI.
If the current turn came from the desktop app or another IM channel, the TUI will not take it over; use `Enter` to queue instead.
When there are queued tasks, the interface shows the queue count, a message preview, and the message source.
## Keyboard Controls [#keyboard-controls]
Basic controls are the same on macOS, Windows, and Linux; the primary modifier for line-editing combinations differs:
| **Action** | **macOS** | **Windows** | **Linux** |
| --------------------------------------- | ----------------------------------------------------- | ------------------------------- | ------------------------------- |
| Send; queue next turn while running | `Enter` | `Enter` | `Enter` |
| Append to the current TUI executed turn | `Tab` | `Tab` | `Tab` |
| Move one character | `←` / `→` | `←` / `→` | `←` / `→` |
| Move by word | `⌘ + ←` / `⌘ + →` | `Ctrl + ←` / `Ctrl + →` | `Ctrl + ←` / `Ctrl + →` |
| Move to start of input | `Home` / `Ctrl + A` | `Home` / `Ctrl + A` | `Home` / `Ctrl + A` |
| Move to end of input | `End` / `Ctrl + E` / `⌘ + E` | `End` / `Ctrl + E` | `End` / `Ctrl + E` |
| Delete from cursor to start of line | `Ctrl + U` / `⌘ + U` / `⌘ + Backspace` / `⌘ + Delete` | `Ctrl + U` | `Ctrl + U` |
| Delete from cursor to end of line | `Ctrl + K` / `⌘ + K` | `Ctrl + K` | `Ctrl + K` |
| Delete previous word | `Ctrl + W` / `⌘ + W` | `Ctrl + W` / `Ctrl + Backspace` | `Ctrl + W` / `Ctrl + Backspace` |
| Delete a character | `Backspace` / `Delete` | `Backspace` / `Delete` | `Backspace` / `Delete` |
| Stop your own running turn and exit | `Ctrl + C` | `Ctrl + C` | `Ctrl + C` |
On macOS, `⌘` is the Command key; Windows and Linux use `Ctrl` as the primary modifier. `Shift + Enter` never inserts a newline on any platform — it submits the current message.
You can also exit by typing any of the following:
```bash
exit
quit
/exit
/quit
:q
```
If the task is being executed by another channel, `Ctrl + C` only exits the current TUI; it does not stop the task on that channel.
## Slash Commands [#slash-commands]
The TUI has a slash-command suggestion menu. Type `/` in the input area to open it, and keep typing a command name (for example `/go`) to filter the suggestions. The menu closes once you type a space to enter an argument or subcommand.
* `↑` / `↓` — move between suggestions.
* `Tab` — complete the selected command entry; it does not complete subcommands or arguments.
* `Enter` — if the current input is a command prefix, completes it first; if the command entry is already complete, runs the command.
* `Esc` — close the suggestion menu.
If `Enter` only completed the command, press `Enter` again to run it.
* The menu shows the commands currently available, along with hints for that command's arguments or subcommands.
* Arguments and subcommands do not get their own suggestions — for example, with `/model list` you complete `/model` first and then type `list` manually.
* `/stop` appears only when the current turn is being executed by this TUI.
* `/restart` is not shown and cannot be run from the TUI.
* `exit`, `quit`, `/exit`, `/quit`, and `:q` all exit, but only `/quit` appears in the menu.
* Whether `/history-dag` appears depends on whether the corresponding feature is enabled.
* Up to 8 suggestions are shown initially; keep typing a command prefix to filter down to others.
| **Command** | **Arguments** | **Purpose** |
| --------------------------- | ------------------ | ----------------------------------------------------------------------------------- |
| `/help` | none | Show help for the available commands |
| `/status` | none | Show runtime status, provider, and channel status |
| `/model` | none | Show the current model configuration |
| `/model list` | none | List model presets |
| `/model ` | model preset name | Switch model preset, e.g. `/model fast` |
| `/history` | none | Show session history |
| `/history ` | number of messages | Show the last `n` history messages |
| `/history-dag` | none | Show the session history DAG |
| `/new` | none | Stop the current task and start a new conversation |
| `/stop` | none | Stop the turn currently executed by this TUI; does not stop tasks on other channels |
| `/restart` | none | Not accepted by the TUI; exit and restart the Gateway instead |
| `/last-compaction` | none | Show the most recent context-compaction summary for this session |
| `/quit` | none | Exit the TUI without stopping turns running on other channels |
| `/goal` | none | Show the current persistent goal |
| `/goal status` | none | Show persistent goal status |
| `/goal help` | none | Show help for the goal subcommands |
| `/goal ` | goal text | Shorthand for creating a persistent goal |
| `/goal create ` | goal text | Create a persistent goal |
| `/goal pause` | none | Pause the goal |
| `/goal resume` | none | Resume the goal |
| `/goal edit ` | new goal text | Edit the goal |
| `/goal budget ` | a number or `none` | Set or clear the goal budget |
| `/goal clear` | none | Clear the goal |
| `/pairing` | none | View or manage channel pairings |
| `/pairing list` | none | List channel pairing requests |
| `/pairing approve ` | pairing code | Approve a pairing request |
| `/pairing deny ` | pairing code | Deny a pairing request |
| `/pairing revoke ` | user ID | Revoke a user's pairing |
Whether `/history-dag` is available depends on whether the corresponding feature is enabled in your configuration.
## FAQ [#faq]
### `memmy: command not found` [#memmy-command-not-found]
* **macOS**: make sure Memmy has been moved into `/Applications` and launched at least once, then open a new terminal or run `source ~/.zshrc`.
* **Windows**: open a new PowerShell or Windows Terminal window.
* **Linux**: confirm the installer completed successfully, and check that `~/.local/bin` is on your `PATH`.
### No model available [#no-model-available]
```bash
memmy onboard
memmy status
```
Confirm that the model, provider, and credentials have been saved, then run `memmy`.
### Gateway unavailable [#gateway-unavailable]
* **Desktop app**: make sure the Memmy desktop app is running.
* **Linux CLI**: check `memmy-gateway.service`.
* **Running the CLI from source or manually**: run `memmy gateway` in another terminal.
The default Gateway WebSocket port is `18980`. On Linux you can check the logs:
```bash
journalctl --user -u memmy-gateway.service
```
### Why doesn't `memmy agent` open the full-screen interface? [#why-doesnt-memmy-agent-open-the-full-screen-interface]
That's expected. `memmy agent` is the single-turn / conventional terminal entry point. For the full-screen TUI, run:
```bash
memmy
```
# Managed Tool Integrations (/docs/tools/integrations)
The standard integrations on the Tools page come from a managed catalog (Composio), including GitHub, GitLab, Gmail, Google Calendar/Docs/Drive/Sheets/Slides, Notion, Slack, Linear, Jira, Confluence, Figma, Dropbox, Airtable, Trello, Salesforce, HubSpot, Stripe, Zoom, and more.
## Authorization Flow [#authorization-flow]
1. Click a tool card, review the permission scopes, then click Connect to get an authorization URL.
2. Complete OAuth in your external browser; the dialog polls every 4 seconds for up to 5 minutes.
3. Once connected, the tool is exposed to the Agent Runtime through the Composio MCP bridge, and the desktop backend automatically writes `tools.mcpServers.composio`.
# Custom MCP Servers (/docs/tools/mcp)
Memmy supports three kinds of MCP servers: `stdio`, `sse`, and `streamableHttp`:
```yaml
tools:
mcpServers:
example:
type: stdio
command: npx
args:
- "-y"
- "your-mcp-server"
toolTimeout: 30
enabledTools:
- "*"
```
## Built-in Tool Toggles [#built-in-tool-toggles]
```yaml
tools:
web:
enabled: true
search:
provider: duckduckgo
maxResults: 5
fetch:
timeoutS: 30
maxChars: 60000
exec:
enabled: true
timeout: 60
imageGeneration:
enabled: false
```
Built-in tools cover the filesystem, shell, web search and fetching, MCP, scheduled tasks, message sending, image generation, long-running tasks, introspection, runtime status, and context management.