name: project-memory
description: "Proactive project memory management via MemOS MCP. USE MCP TOOLS AUTOMATICALLY when: (1) Starting work - memos_search for context, (2) Completing tasks - memos_save as MILESTONE, (3) Fixing bugs - memos_save as ERROR_PATTERN, (4) Making decisions - memos_save as DECISION, (5) Encountering errors - memos_search for solutions, (6) User mentions '之前/上次/previously' - memos_search history, (7) Need to understand dependencies/causality - memos_get_graph or memos_trace_path for relationships, (8) Cube not found - memos_list_cubes to discover available cubes. Available MCP tools: memos_search, memos_search_context, memos_save, memos_list, memos_suggest, memos_list_cubes, memos_get_graph, memos_trace_path, memos_export_schema."

Project Memory (MCP Powered)

Intelligent project memory system powered by MemOS MCP Server. Use MCP tools directly - no scripts needed!

🚨 强制规则 (MUST/MUST NOT)

MUST (必须遵守)

1. 修复 Bug 后必须保存为 BUGFIX 或 ERROR_PATTERN，不得使用 PROGRESS
2. 做出技术决策后必须保存为 DECISION，包含理由和备选方案
3. 发现非显而易见的陷阱必须保存为 GOTCHA
4. 保存时必须显式指定 memory_type 参数，不依赖自动检测

MUST NOT (禁止)

1. 禁止将 PROGRESS 作为默认/万能类型
2. 禁止省略 memory_type 参数 (除非是纯进度汇报)
3. 禁止在 PROGRESS 中包含错误解决方案、技术决策、陷阱警告

类型选择决策树

是否解决了一个错误/Bug？
├─ 是 → 是否有通用价值？
│       ├─ 是 → ERROR_PATTERN (错误模式，可复用)
│       └─ 否 → BUGFIX (一次性修复)
└─ 否 → 是否做出了技术选择？
        ├─ 是 → DECISION
        └─ 否 → 是否发现了非显而易见的问题？
                ├─ 是 → GOTCHA
                └─ 否 → 是否是可复用的代码模板？
                        ├─ 是 → CODE_PATTERN
                        └─ 否 → 是否修改了配置？
                                ├─ 是 → CONFIG
                                └─ 否 → 是否完成了重大里程碑？
                                        ├─ 是 → MILESTONE
                                        └─ 否 → 是否新增了功能？
                                                ├─ 是 → FEATURE
                                                └─ 否 → PROGRESS (仅限纯进度)

错误示范 vs 正确示范

❌ 错误: memos_save(content="修复了模型路径问题") → 默认 PROGRESS
✅ 正确: memos_save(content="修复了模型路径问题...", memory_type="BUGFIX")

❌ 错误: memos_save(content="决定采用三轨架构") → 可能被误检测
✅ 正确: memos_save(content="决定采用三轨架构...", memory_type="DECISION")

❌ 错误: memos_save(content="注意: fallbacks会自动切换") → 可能落入 PROGRESS
✅ 正确: memos_save(content="注意: fallbacks会自动切换...", memory_type="GOTCHA")

Quick Reference: MCP Tools

Desktop Integration: Knowledge Graph Visualization

The desktop app now supports real-time Neo4j knowledge graph visualization.

Usage in Renderer

const accomplish = getAccomplish();
const graphData = await accomplish.getGraphData("ddsp-svc-6.3");

UI Component

The <KnowledgeGraph /> component (located in renderer/components/memory/KnowledgeGraph.tsx) provides:
- Force-directed graph layout
- Node color-coding by memory type
- Interactive tooltips with memory content
- Color coding by type:
- LongTermMemory: Blue (#3b82f6)
- WorkingMemory: Emerald (#10b981)
- ShortTermMemory: Amber (#f59e0b)
- Episodic/Semantic: Violet/Pink
- Zoom, pan, and center controls
- Automatic data fetching for a given projectId

Proactive Triggers (Use MCP Automatically!)

When to Search (memos_search)

When to Get Graph (memos_get_graph) - NEW!

Example Output:

[Neo4j需要Java 17+]
    ──CAUSE──>
[Neo4j启动失败, JAVA_HOME not set]

When to Trace Path (memos_trace_path) - NEW!

Example:

memos_trace_path(source_id="uuid1", target_id="uuid2", max_depth=5)
→ [决策A] ──CAUSE──> [变更B] ──CAUSE──> [问题C]

When to List Cubes (memos_list_cubes) - NEW!

When to Export Schema (memos_export_schema) - NEW!

When to Save (memos_save)

Memory Type Formats

[ERROR_PATTERN] - For Solved Errors

[ERROR_PATTERN] Error: {ErrorType}

## Signature
- Type: {ErrorType}
- Message: {Full error message}
- Context: {When this occurs}

## Root Cause
{Why this error happens}

## Solution
1. {Step 1}
2. {Step 2}

## Prevention
{How to avoid in future}

Tags: error, {error_type}, {category}

[DECISION] - For Choices Made

[DECISION] Topic: {topic}

## Decision
{What was decided}

## Options Considered
1. **{Option A}**: {pros/cons}
2. **{Option B}** (chosen): {pros/cons}

## Rationale
{Why this option was chosen}

## Impact
- Files affected: {list}
- Dependencies: {list}

Tags: decision, {topic}

[CODE_PATTERN] - For Reusable Code

[CODE_PATTERN] Pattern: {name}

## Purpose
{What this pattern does}

## Template
```{language}
{code template}

Usage

{When and how to use}

Tags: pattern, {language}, {category}

### [MILESTONE] - For Achievements

```markdown
[MILESTONE] {short description}

## Summary
{What was accomplished}

## Details
- {detail 1}
- {detail 2}

Tags: milestone, {category}

[GOTCHA] - For Traps and Workarounds

[GOTCHA] {short description}

## Issue
{The non-obvious problem}

## Context
{When/where this occurs}

## Workaround
{How to avoid or fix}

Tags: gotcha, {category}

Workflow with MCP

┌─────────────────────────────────────────────────────────────────┐
│                    PROJECT MEMORY WORKFLOW (MCP)                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  TRIGGER              MCP TOOL              ACTION              │
│  ───────              ────────              ──────              │
│                                                                 │
│  Start working   ───> memos_search    ───> Get project context  │
│                                                                 │
│  Hit error       ───> memos_search    ───> Find ERROR_PATTERN   │
│                       query: "ERROR_PATTERN {type}"             │
│                                                                 │
│  Need context    ───> memos_search_context ─> Smart search      │
│                       with conversation history                 │
│                                                                 │
│  Need root cause ───> memos_get_graph ───> View CAUSE chain     │
│                       query: "{error_keyword}"                  │
│                                                                 │
│  Trace path      ───> memos_trace_path ──> A→B→C chain          │
│                       source_id, target_id                      │
│                                                                 │
│  Check deps      ───> memos_get_graph ───> View relationships   │
│                       query: "{component}"                      │
│                                                                 │
│  Cube not found  ───> memos_list_cubes ──> Discover cubes       │
│                       include_status: true                      │
│                                                                 │
│  Graph health    ───> memos_export_schema > Stats & structure   │
│                                                                 │
│  Solved error    ───> memos_save      ───> Save ERROR_PATTERN   │
│                       memory_type: "ERROR_PATTERN"              │
│                                                                 │
│  Make decision   ───> memos_save      ───> Save DECISION        │
│                       memory_type: "DECISION"                   │
│                                                                 │
│  Complete task   ───> memos_save      ───> Save MILESTONE       │
│                       memory_type: "MILESTONE"                  │
│                                                                 │
│  "之前/上次"     ───> memos_search    ───> Find history         │
│                                                                 │
│  Unsure search   ───> memos_suggest   ───> Get suggestions      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Best Practices

1. Search Before Save - Check if similar memory exists
2. Be Specific - Include file paths, function names, error messages
3. Include Why - Don't just record what, explain the reasoning
4. Tag Consistently - Use standard tags for searchability
5. Save Immediately - Record while context is fresh

Legacy Scripts (Optional)

Note: With MCP, you rarely need these scripts. They're kept for backward compatibility.

The following scripts in scripts/ folder still work but MCP is preferred:

Environment Variables

Troubleshooting (MCP Tools Only)

Note: All error recovery uses MCP tools - no Bash/curl required. Works in isolated projects.

Cube Not Found Error

Error: Cube 'xxx' not found or Cube not registered

Recovery Steps (all via MCP):
1. memos_list_cubes() → See available cubes
2. If cube exists but not registered: memos_register_cube(cube_id="xxx")
3. If cube doesn't exist: Create cube directory with config.json, then register

Example:

memos_list_cubes(include_status=true)
→ Shows: dev_cube (registered), my_project (not registered)

memos_register_cube(cube_id="my_project")
→ "Cube 'my_project' registered successfully"

User Does Not Exist Error

Error: User 'xxx' does not exist

Recovery Steps (all via MCP):
1. memos_create_user(user_id="xxx") → Create the user
2. Retry the original operation

Example:

memos_save(content="...", cube_id="my_cube")
→ Error: User 'dev_user' does not exist

memos_create_user(user_id="dev_user")
→ "User 'dev_user' created successfully"

memos_save(content="...", cube_id="my_cube")
→ Success

MCP Connection Error

Error: MCP tools not responding or timeout

Recovery Steps:
1. Wait a moment and retry (API may be starting)
2. Try a simpler operation first: memos_list_cubes()
3. If persistent, the MemOS API service may need restart (outside MCP scope)

Memory Not Found

Error: Search returns empty results

Recovery Steps (all via MCP):
1. memos_list(cube_id="xxx", limit=20) → Check what memories exist
2. memos_list_cubes() → Verify using correct cube_id
3. memos_search_context(query="...", context=[...]) → Use context-aware search
4. Try broader search terms or different memory types

Save Failed

Error: Save operation failed

Recovery Steps (all via MCP):
1. memos_list_cubes(include_status=true) → Check cube status
2. If not registered: memos_register_cube(cube_id="xxx")
3. If user error: memos_create_user(user_id="xxx")
4. Retry save operation

Quick Recovery Flowchart

Error occurred
    │
    ├─ "Cube not found" ────────────> memos_list_cubes()
    │                                      │
    │                                      ├─ Found? → memos_register_cube()
    │                                      └─ Not found? → Create cube first
    │
    ├─ "User does not exist" ───────> memos_create_user(user_id="xxx")
    │
    ├─ "Save failed" ───────────────> memos_list_cubes(include_status=true)
    │                                      │
    │                                      └─ Check cube/user, then retry
    │
    └─ "No results" ────────────────> memos_list() to verify data exists