Mem-Skill: Self-Evolving Knowledge System

Initialization

When the user runs /mem-skill init, execute the following setup:

1. Determine the current workspace root directory.
Create the directory structure:

   <workspace>/
   ├── knowledge-base/
   │   └── _index.json
   ├── experience/
   │   └── _index.json
   └── log.md

3. Populate knowledge-base/_index.json with the starter template (see "Knowledge Base Index Format" below).
Populate experience/_index.json with the starter template (see "Experience Index Format" below).
Create log.md with the starter template (see "Log Format" below).
Append to log.md: INLINECODE5
Confirm to the user: "mem-skill initialized. Knowledge base, experience, and log created."

Engine Selection

When the user runs /mem-skill init --mem-engine=qmd, optionally with extra --qmd-* flags:

Supported flags (all optional):

Flag	Values	Default
INLINECODE8	INLINECODE9, INLINECODE10	(ask user)
INLINECODE11

any string | (ask user) |
| --qmd-experience=<name> | any string | (ask user) |
| --qmd-mask=<pattern> | glob pattern | **/*.md |

Examples:
CODEBLOCK1

Init procedure:

1. Perform all standard init steps above.
Check if QMD is installed: run which qmd or npx @tobilu/qmd status.
If QMD is not installed, prompt:

> "QMD is not installed. Install it now with npm install -g @tobilu/qmd? (QMD requires Node.js >= 22)"

4. Determine collection scope:

- If --qmd-scope was provided, use that value. - Otherwise, you MUST ask the user (do NOT guess or auto-choose): > "Where should QMD collections be stored? > 1. Project — scoped to this workspace (recommended for multi-project setups) > 2. Global — shared across all workspaces" - If project: default collection name prefix is the sanitized workspace folder name (e.g., folder my-app → prefix my-app). - If global: default collection name prefix is mem.

5. Determine collection names:

- If --qmd-knowledge was provided, use that value. - If --qmd-experience was provided, use that value. - For any name NOT provided via flags, you MUST ask the user (do NOT auto-generate): > "What name for the knowledge collection? (default: <prefix>-knowledge)" > "What name for the experience collection? (default: <prefix>-experience)" - Accept user input or use the defaults if the user confirms.

6. Determine file mask:

- If --qmd-mask was provided, use that value. - Otherwise use **/*.md.

7. After all values are confirmed, create the QMD collections:

   qmd collection add <workspace>/knowledge-base --name <knowledge-name> --mask "<mask>"
   qmd collection add <workspace>/experience --name <experience-name> --mask "<mask>"
   qmd context add qmd://<knowledge-name> "General knowledge base: reusable workflows, preferences, best practices"
   qmd context add qmd://<experience-name> "Skill-specific experience: pitfalls, parameters, solutions"
   qmd embed

8. Create a .mem-skill.config.json at the workspace root:

   {
     "engine": "qmd",
     "version": "1.0.0",
     "scope": "<project|global>",
     "mask": "<mask>",
     "collections": {
       "knowledge": "<knowledge-name>",
       "experience": "<experience-name>"
     }
   }

9. Append to log.md: INLINECODE30
Confirm: "mem-skill initialized with QMD memory engine. Collections created and embeddings generated."

IMPORTANT: Never silently create QMD collections without confirming scope and names with the user. If no --qmd-* flags were provided, every question above MUST be asked interactively.

For the default engine (no --mem-engine flag), create .mem-skill.config.json with:
CODEBLOCK4

For detailed engine-specific behavior, see references/qmd-engine.md and references/engines.md.

Upgrade Command

When the user runs /mem-skill upgrade, migrate an existing mem-skill workspace to the latest version. This is safe to run multiple times — it only adds what's missing.

Procedure:

1. Check prerequisites:

- Verify knowledge-base/_index.json and experience/_index.json exist. If not, tell the user to run /mem-skill init instead. - Read .mem-skill.config.json to determine current engine and version.

2. Create log.md if it doesn't exist:

   # mem-skill Activity Log

   Chronological record of all mem-skill operations. Each entry is parseable with `grep "^## \[" log.md`.

   ## [YYYY-MM-DD] upgrade | Migrated from v<old> to v1.2.0

If log.md already exists, just append the upgrade log entry.

3. Backfill **Source:** field on existing entries:

- Scan all .md files in knowledge-base/ and experience/. - For each entry (identified by ## [Title]) that is missing **Source:**, insert **Source:** conversation after the **Date:** line. - Report: "Backfilled Source field on entries."

4. Backfill **Related:** field on existing entries:

- For each entry missing **Related:**, insert an empty **Related:** line before **Keywords:**. - These will be populated naturally by future writes and by running /mem-skill lint. - Report: "Added Related field placeholder to entries."

5. Update .mem-skill.config.json version to 1.2.0.

6. QMD engine post-upgrade (if engine is qmd):

- Run qmd update && qmd embed to re-index the backfilled entries.

7. Confirm:

> "Upgrade complete (v → v1.2.0): > - Created log.md ✓ (or: log.md already existed) > - Backfilled Source on entries ✓ > - Added Related placeholder to entries ✓ > - Updated config version ✓ > > Run /mem-skill lint to discover cross-reference opportunities between your existing entries."

Manual Recording Command

When the user runs /mem-skill recordnow, immediately trigger the recording flow for the current conversation — even if Step 5 was not triggered automatically.

This is useful when:

- Multiple tasks were completed in one session and the agent forgot to ask.
The user wants to record something that didn't trigger the satisfaction keywords.
The user remembers later that a solution was worth saving.

Procedure:

1. Review the full conversation history for completed tasks.
For each completed task, summarize it into a one-line essence.
Evaluate: "Will this save time next time?"
Present all recordable items to the user as a numbered list:

> "I found these completed tasks worth recording:
> 1. [summary of task 1] → knowledge-base
> 2. [summary of task 2] → knowledge-base
> 3. [summary of skill usage] → experience
>
> Which ones should I record? (all / 1,2 / none)"

5. On approval, write each selected item following the same write procedure as Step 5 (including compounding checks, cross-references, source fields, and QMD post-write sync if applicable).
Append to log.md: INLINECODE61
If no recordable tasks are found, respond: "I reviewed the conversation but didn't find any completed tasks worth recording. Is there something specific you'd like me to save?"

Health-Check Command

When the user runs /mem-skill lint, perform a comprehensive health-check of the knowledge base and experience store.

Checks performed:

1. Duplicate detection — Scan all entries for similar titles, overlapping keywords (>= 70% overlap), or near-identical content. Flag entries that should be merged.

2. Stale entries — Flag entries older than 6 months (based on **Date:** field) that have no **Updated:** timestamp. These may contain outdated practices.

3. Contradiction detection — Within the same category, look for entries that give conflicting advice on the same topic. Flag with both entries quoted.

4. Orphan detection:

- Categories in _index.json with no corresponding .md file. - .md files in knowledge-base/ or experience/ with no _index.json entry. - Broken **Related:** links pointing to non-existent entries.

5. Missing cross-references — Entries in the same category or with overlapping keywords that have no **Related:** links between them.

6. Knowledge gaps — Categories with fewer than 2 entries. Suggest whether to merge into a broader category or to actively build out.

7. Index consistency — Verify totalEntries and per-category count values match the actual entry count in each .md file.

Output format:
CODEBLOCK6

After lint:

- Ask the user which issues to fix.
For merges: combine entries, update cross-references, update index counts.
For stale entries: ask whether to update, archive, or delete.
For missing cross-references: add **Related:** links.
Append to log.md: INLINECODE78

QMD engine: After any fixes that modify .md files, run qmd update && qmd embed.

Ingest Command

When the user runs /mem-skill ingest <source>, process an external source into knowledge base entries.

Source types:

Source	Example
Local file	INLINECODE82
URL

/mem-skill ingest https://example.com/best-practices |
| Directory | /mem-skill ingest ./docs/ (processes all markdown files) |

Procedure:

1. Read the source:

- Local file: Read the file contents. - URL: Fetch the webpage and extract main content. - Directory: List all .md files and process each.

2. Extract key knowledge points:

- Identify 3-10 distinct, reusable insights from the source. - Each insight should pass the recording criteria: "Will this save time next time?" - Discard pure theory, one-off context, and non-actionable content.

3. Match against existing categories:

- For each extracted insight, find the best matching category in knowledge-base/_index.json. - If no category matches, follow the Dynamic Category flow.

4. Check for compounding opportunities:

- For each insight, search existing entries for related content (same as Step 5, step 3). - If a related entry exists, offer to update/merge rather than duplicate.

5. Present to the user:

> "I extracted these knowledge points from [source]: > 1. [insight 1] → knowledge-base/.md (new) > 2. [insight 2] → knowledge-base/.md (update existing: '') > 3. [insight 3] → knowledge-base/.md (new) > > Which ones should I record? (all / 1,3 / none)"

6. Write on approval:

- Create new entries or update existing ones. - Set **Source:** to file:<path> or url:<link>. - Add **Related:** cross-references between related entries. - Update _index.json counts and timestamps.

7. Log: Append to log.md: INLINECODE93

8. QMD engine post-write: Run qmd update && qmd embed.

IMPORTANT: Ingest does NOT blindly copy source content. It extracts actionable knowledge that fits the recording criteria, re-formats it into the standard entry format, and integrates it with existing knowledge.

Core Loop (Mandatory Every Turn)

Execute these steps on every conversation turn. Do not display internal cache state to the user.

Step 0: In-Conversation Cache (Internal)

Maintain these variables silently within the conversation:

- last_keywords — keywords from the previous turn
INLINECODE96 — top 3 keywords as a fingerprint
INLINECODE97 — timestamp of last index read
INLINECODE98 — categories matched on last read
INLINECODE99 — non-mem-skill skills used this turn
INLINECODE100 — skills with no experience entry
INLINECODE101 — skills whose experience has been loaded this session

Step 1: Extract Keywords (No File I/O)

- Extract 3–8 core nouns/phrases from the user's current message.
Deduplicate and normalize casing.
Generate topic_fingerprint from the top 3 keywords.

Step 2: Detect Topic Switch (No File I/O)

A topic switch occurs when any of these conditions are met:

- Explicit transition words: "also", "switch to", "by the way", "next", "instead"
Current keywords differ from last_keywords by >= 40%
User explicitly requests a new category or topic

Step 3: Cross-Skill Experience Read (Forced — Ignores Topic Switch)

Whenever a non-mem-skill skill is used this turn:

- If the skill-id is already in loaded_experience_skills, skip (do not re-read or re-announce).
Otherwise:

1. Read experience/_index.json.
2. If a matching skill-id entry exists, load experience/skill-<skill-id>.md.
3. Add the skill-id to loaded_experience_skills.
4. Include in response: "Loaded experience: skill-<skill-id>.md"
5. Log (first read per session only): Append to log.md: ## [YYYY-MM-DD] read | Retrieved experience: skill-<skill-id>.md
6. If no entry exists, add to missing_experience_skills.

Engine-specific retrieval:

- Default engine: Read experience/_index.json and match by skillId.
QMD engine: Read collection names from .mem-skill.config.json, then run qmd search "<skill-id>" -c <experience-collection> --json -n 5 for keyword match, or qmd query "<skill-id> <context>" -c <experience-collection> --json -n 5 for deeper retrieval.

Step 4: Knowledge Base Read (Only on Topic Switch)

Execute only on the first turn of the conversation or when a topic switch is detected:

Default engine:

1. Read knowledge-base/_index.json.
Match current keywords against all category keywords arrays.
Load every matched category file (no priority ranking — load all matches).
If no category matches, follow the "Dynamic Category" flow (see below).
If any files were loaded, include in response: INLINECODE122
Log (first read per session only): Append to log.md: INLINECODE124

If no topic switch occurred, reuse last_matched_categories without re-reading.

QMD engine:

1. Read collection names from .mem-skill.config.json.
Run qmd query "<keywords joined by space>" -c <knowledge-collection> --json -n 10 --min-score 0.3.
Load top results as context.
Include in response: INLINECODE128

Step 5: Proactive Recording (Most Important)

Trigger conditions:

- The current task is clearly completed at high quality.
The user expresses satisfaction ("great", "perfect", "that works", etc.).
The agent synthesizes a particularly valuable answer (comparison, deep analysis, connection discovery) that would be useful beyond this conversation.

Recording procedure:

1. Summarize: Distill the solution into a one-line essence.
Evaluate value: "Will this save time next time?"
Check for existing related entries (compounding update):

- Search knowledge-base/_index.json and relevant .md files for entries with overlapping keywords or similar topics.
- QMD engine: Run qmd query "<summary>" -c <knowledge-collection> --json -n 3 --min-score 0.5 to find related entries.
- If a closely related entry exists, offer to update/merge instead of creating a duplicate:
> "I found an existing entry '[[#]]' that's related. Should I update it with the new information, or create a separate entry?"
- Update = append new points to the existing entry, add **Updated:** YYYY-MM-DD below the original date, and add cross-references.
- Separate = create a new entry with **Related:** links to the existing one (and update the existing entry's **Related:** too).

4. Ask permission: Always say something like:

> "We solved [problem description]. I'd like to record this experience so I can reference it next time. Is that okay?"

5. Write on approval:

- Skill experience (if a non-mem-skill skill was used and the skill has no entry or has new techniques): Write to experience/skill-<skill-id>.md and update experience/_index.json.
- General knowledge (if it's a reusable workflow, preference, or solution): Write to knowledge-base/<category>.md and update knowledge-base/_index.json.
- Include **Source:** field (default: conversation).
- Include **Related:** cross-references to any related entries found in step 3.

6. Log the operation: Append to log.md:

- For new entries: ## [YYYY-MM-DD] write | Recorded to <path>: "<title>"
- For updates: INLINECODE144

Filing valuable answers back:
If the agent produces a valuable synthesis (comparison table, analysis, architectural decision) during a query — not just task completion — proactively offer:

"This [comparison/analysis/summary] seems valuable beyond this conversation. Want me to save it to the knowledge base?"

This ensures knowledge is captured from exploration and research, not just from building things.

QMD engine post-write:
After writing any .md file, run:
CODEBLOCK7

Forced rule — always ask when experience is missing:
If a non-mem-skill skill was used this turn and that skill has no entry in experience/_index.json, you must ask at task completion:

"We used this time, but there's no experience record yet. Can I record this session's approach for future reference?"

If Step 5 was not triggered (e.g., multi-task sessions where satisfaction signals were missed), the user can run /mem-skill recordnow at any time to manually trigger recording. See "Manual Recording Command" above.

Index Formats

Knowledge Base Index Format

INLINECODE148:
CODEBLOCK8

Experience Index Format

INLINECODE149:
CODEBLOCK9

Log Format

INLINECODE150:
CODEBLOCK10

Logging rules:

- Append to log.md on every write, update, lint, ingest, and recordnow operation.
Read operations: log only on first read per session (not every turn).
Keep entries on a single line for parseability.
Do NOT log keyword extraction or topic detection (internal-only).

Entry Formats

Knowledge Base Entry

CODEBLOCK11

Experience Entry

CODEBLOCK12

Source Field Values

Value	When to Use
INLINECODE152	Learned from a chat session (default)
INLINECODE153

Ingested from a local file | | url:<link> | Ingested from a web URL |

Related Field

Cross-references use [[file#heading]] format (compatible with Obsidian-style wikilinks):

- Link to knowledge entries: INLINECODE156
Link to experience entries: INLINECODE157
When writing a new entry, search existing entries for related content and add bidirectional links (update the related entry's **Related:** field too).

Dynamic Category (Knowledge Base Only)

When user keywords do not match any existing category:

1. Suggest creating a new category.
Ask the user for a category name and keywords.
Create a new <category-id>.md file and update knowledge-base/_index.json.

Recording Criteria

Core question: Will this save the user time next time?

Knowledge Base — Should Record:

- Reusable workflows and decision steps (cross-domain procedures)
High-cost mistakes and their correction paths
Critical parameters, settings, or prerequisites
User preferences and style rules (tone, format, design)
Multi-attempt solutions (include failure reasons and success conditions)
Reusable templates, checklists, and output formats
External dependencies or resource locations

Knowledge Base — Should NOT Record:

- Single Q&A with no reusable process
Pure conceptual explanations without concrete steps
Context-free, non-reusable conclusions

Experience — Should Record:

- Pitfalls and their fixes when using a specific skill (include error messages)
Critical parameters or configurations that affect outcomes
Reusable templates, prompts, or workflows for that skill
Dependency or asset paths (fonts, images, project entry points)
Steps requiring a specific order or technique to succeed

Experience — Should NOT Record:

- Pure theory or conceptual explanations (those belong in knowledge-base)
Conclusions without reproducible steps
One-off, non-reusable operations

Storage Paths

- Knowledge index: INLINECODE161
Knowledge content: INLINECODE162
Experience index: INLINECODE163
Experience content: INLINECODE164
Config: INLINECODE165

QMD Upgrade Suggestion

When the knowledge base exceeds 50 entries, proactively suggest upgrading to QMD:

"Your knowledge base has grown to [N] entries. For faster semantic search, consider upgrading to QMD: run /mem-skill init --mem-engine=qmd."

For full QMD engine details, see references/qmd-engine.md.
For the engine abstraction and adding new engines, see references/engines.md.

Mem-Skill：自进化知识系统

初始化

当用户运行 /mem-skill init 时，执行以下设置：

/
├── knowledge-base/
│ └── _index.json
├── experience/
│ └── _index.json
└── log.md

3. 使用初始模板填充 knowledge-base/index.json（参见下方的知识库索引格式）。
使用初始模板填充 experience/index.json（参见下方的经验索引格式）。
使用初始模板创建 log.md（参见下方的日志格式）。
追加到 log.md：## [YYYY-MM-DD] init | mem-skill initialized (engine: default)
向用户确认：mem-skill 已初始化。知识库、经验和日志已创建。

引擎选择

当用户运行 /mem-skill init --mem-engine=qmd 时，可选择性地附带额外的 --qmd-* 标志：

支持的标志（均为可选）：

标志	值	默认值
--qmd-scope=<scope>	project, global	（询问用户）
--qmd-knowledge=<name>

任意字符串 | （询问用户） |
| --qmd-experience= | 任意字符串 | （询问用户） |
| --qmd-mask= | glob 模式 | /*.md |

示例：

/mem-skill init --mem-engine=qmd
/mem-skill init --mem-engine=qmd --qmd-scope=project
/mem-skill init --mem-engine=qmd --qmd-scope=global --qmd-knowledge=my-kb --qmd-experience=my-exp
/mem-skill init --mem-engine=qmd --qmd-mask=/.md,/.txt

初始化流程：

1. 执行上述所有标准初始化步骤。
检查 QMD 是否已安装：运行 which qmd 或 npx @tobilu/qmd status。
如果 QMD 未安装，提示：

> QMD 未安装。现在使用 npm install -g @tobilu/qmd 安装它吗？（QMD 需要 Node.js >= 22）

4. 确定集合范围：

- 如果提供了 --qmd-scope，则使用该值。 - 否则，你必须询问用户（不要猜测或自动选择）： > QMD 集合应存储在哪里？ > 1. 项目 — 限定在此工作空间内（推荐用于多项目设置） > 2. 全局 — 在所有工作空间之间共享 - 如果为项目：默认集合名称前缀是经过清理的工作空间文件夹名称（例如，文件夹 my-app → 前缀 my-app）。 - 如果为全局：默认集合名称前缀是 mem。

5. 确定集合名称：

- 如果提供了 --qmd-knowledge，则使用该值。 - 如果提供了 --qmd-experience，则使用该值。 - 对于任何未通过标志提供的名称，你必须询问用户（不要自动生成）： > 知识集合的名称是什么？（默认：-knowledge） > 经验集合的名称是什么？（默认：-experience） - 接受用户输入，如果用户确认则使用默认值。

6. 确定文件掩码：

- 如果提供了 --qmd-mask，则使用该值。 - 否则使用 /*.md。

7. 在所有值确认后，创建 QMD 集合：

bash qmd collection add /knowledge-base --name --mask qmd collection add /experience --name --mask qmd context add qmd:// 通用知识库：可重用工作流、偏好、最佳实践 qmd context add qmd:// 技能特定经验：陷阱、参数、解决方案 qmd embed

8. 在工作空间根目录创建 .mem-skill.config.json：

json { engine: qmd, version: 1.0.0, scope: , mask: , collections: { knowledge: , experience: } }

9. 追加到 log.md：## [YYYY-MM-DD] init | mem-skill initialized (engine: qmd, scope: , collections: , )
确认：mem-skill 已使用 QMD 记忆引擎初始化。集合已创建，嵌入已生成。

重要提示： 在未与用户确认范围和名称的情况下，切勿静默创建 QMD 集合。如果未提供任何 --qmd-* 标志，则上述每个问题都必须以交互方式询问。

对于默认引擎（无 --mem-engine 标志），创建 .mem-skill.config.json，内容为：
json
{
engine: default,
version: 1.0.0
}

有关引擎特定行为的详细信息，请参见 references/qmd-engine.md 和 references/engines.md。

升级命令

当用户运行 /mem-skill upgrade 时，将现有 mem-skill 工作空间迁移到最新版本。可以安全地多次运行——它只会添加缺失的内容。

流程：

1. 检查先决条件：

- 验证 knowledge-base/index.json 和 experience/index.json 是否存在。如果不存在，告知用户改为运行 /mem-skill init。 - 读取 .mem-skill.config.json 以确定当前引擎和版本。

2. 创建 log.md（如果不存在）：

markdown # mem-skill Activity Log

Chronological record of all mem-skill operations. Each entry is parseable with grep ^## \[ log.md.

## [YYYY-MM-DD] upgrade | Migrated from v to v1.2.0

如果 log.md 已存在，则仅追加升级日志条目。

3. 回填现有条目的 Source: 字段：

- 扫描 knowledge-base/ 和 experience/ 中的所有 .md 文件。 - 对于每个缺少 Source: 的条目（由 ## [Title] 标识），在 Date: 行之后插入 Source: conversation。 - 报告：已回填个条目的 Source 字段。

4. 回填现有条目的 Related: 字段：

- 对于每个缺少 Related: 的条目，在 Keywords: 之前插入一个空的 Related: 行。 - 这些将由未来的写入和运行 /mem-skill lint 自然填充。 - 报告：已为个条目添加 Related 字段占位符。

5. 将 .mem-skill.config.json 版本更新 为 1.2.0。

6. QMD 引擎升级后（如果引擎是 qmd）：

- 运行 qmd update && qmd embed 以重新索引回填的条目。

7. 确认：

> 升级完成（v → v1.2.0）： > - 已创建 log.md ✓（或：log.md 已存在） > - 已回填个条目的 Source ✓ > - 已为个条目添加 Related 占位符 ✓ > - 已更新配置版本 ✓ > > 运行 /mem-skill lint 以发现现有条目之间的交叉引用机会。

手动记录命令

当用户运行 /mem-skill recordnow 时，立即触发当前对话的记录流程——即使步骤 5 未自动触发。

这在以下情况下很有用：

- 在一次会话中完成了多个任务，但代理忘记询问。
用户想要记录一些未触发满意度关键词的内容。
用户后来想起某个解决方案值得保存。

流程：

1. 查看完整的对话历史以查找已完成的任务。
对于每个已完成的任务，将其总结为一句话精华。
评估：下次会节省时间吗？
将所有可记录的项目以编号列表形式呈现给用户：

> 我发现这些已完成的任务值得

mem-skill自进化记忆系统

mem-skill

Mem-Skill: Self-Evolving Knowledge System

Initialization

Engine Selection

Upgrade Command

Manual Recording Command

Health-Check Command

Ingest Command

Core Loop (Mandatory Every Turn)

Step 0: In-Conversation Cache (Internal)

Step 1: Extract Keywords (No File I/O)

Step 2: Detect Topic Switch (No File I/O)

Step 3: Cross-Skill Experience Read (Forced — Ignores Topic Switch)

Step 4: Knowledge Base Read (Only on Topic Switch)

Step 5: Proactive Recording (Most Important)

Index Formats

Knowledge Base Index Format

Experience Index Format

Log Format

Entry Formats

Knowledge Base Entry

Experience Entry

Source Field Values

Related Field

Dynamic Category (Knowledge Base Only)

Recording Criteria

Knowledge Base — Should Record:

Knowledge Base — Should NOT Record:

Experience — Should Record:

Experience — Should NOT Record:

Storage Paths

QMD Upgrade Suggestion

Mem-Skill：自进化知识系统

初始化

引擎选择

升级命令

手动记录命令

标签

通过对话安装

方式一：安装 SkillHub 和技能

方式二：设置 SkillHub 为优先技能安装源

通过命令行安装

下载

相关推荐

self-improvement

self-improvement

self-improvement

self-improvement