libp2p-mesh 2026.6.20 → 2026.6.21

package/README.md

@@ -161,7 +161,7 @@ openclaw libp2p-mesh prompt install
 openclaw libp2p-mesh profile
 ```
 
-`USER.md` 中的公开 tag 会在 gateway 启动时只读提取，不会写回 `USER.md`。用户手动新增的结构化属性会保存到：
+`USER.md` 中的公开 tag 由 gateway 使用 OpenClaw 已配置的 agent/API 模型异步提取，不会写回 `USER.md`。初始 announce 或日志可能先不携带属性；等待后续完整 `instance-announce` 快照发出后，再按属性发送或排查匹配结果。用户手动新增的结构化属性会保存到：
 
 ```text
 ~/.openclaw/libp2p/user-profile.json
@@ -205,9 +205,9 @@ openclaw libp2p-mesh labels
 
 Labels are private local notes for remote instances you have already discovered. Use them when you want your own grouping to drive sends without asking the remote user to publish that attribute.
 
-### 7. 重启 gateway
+### 7. 重启或启动 gateway
 
-完成 `setup`、`prompt install` 或 `profile` 后，重启 gateway 让配置和提示词生效：
+完成 `setup` 或 `prompt install` 后，重启 gateway 让配置和提示词生效：
 
 ```bash
 openclaw gateway restart
@@ -219,6 +219,8 @@ openclaw gateway restart
 openclaw gateway
 ```
 
+`profile` 保存后，如果 gateway 正在运行，会自动刷新并重新广播公开属性；只有 gateway 没有运行时，才需要启动或重启后生效。
+
 启动后可以观察日志：
 
 ```text
@@ -626,9 +628,11 @@ Tools are not configured in `openclaw.json`; they are registered automatically b
 
 There are two public sources:
 
-- `USER.md` tags are extracted read-only at gateway startup. The plugin never edits `USER.md`.
+- `USER.md` tags are produced asynchronously by the gateway. The gateway uses the OpenClaw-configured agent/API model to extract tags from `USER.md` without editing the file.
 - `user-profile.json` stores manually managed structured attributes such as group, project, role, skill, or a custom key.
 
+The initial base `instance-announce` may omit `userPublicAttributes`. After the gateway extracts `USER.md` tags and merges `user-profile.json`, it rebroadcasts a full `instance-announce` snapshot. If extraction is unavailable, `USER.md` tags are skipped; profile attributes still broadcast.
+
 By default, `USER.md` is read from:
 
 ```text
@@ -647,7 +651,7 @@ Run the profile wizard to manage structured attributes:
 openclaw libp2p-mesh profile
 ```
 
-The wizard previews read-only `USER.md` tags and lets you add, edit, or remove only structured profile attributes. Tags extracted from `USER.md` are not written to `user-profile.json`; they are merged in memory with profile attributes and broadcast only in instance announce messages.
+The wizard previews read-only `USER.md` tags and lets you add, edit, or remove only structured profile attributes. Tags extracted from `USER.md` are not written to `user-profile.json`; they are merged in memory with profile attributes and broadcast only in full instance announce snapshots after asynchronous extraction completes.
 
 The default profile path is:
 

package/dist/src/instance-peer-store.js

@@ -44,11 +44,13 @@ function sameRecord(record, payload) {
         return false;
     const recordAttributes = normalizeUserPublicAttributes(record.userPublicAttributes);
     const payloadAttributes = normalizeUserPublicAttributes(payload.userPublicAttributes);
+    const payloadIncludesAttributes = "userPublicAttributes" in payload;
     return (record.peerId === payload.peerId &&
         record.instanceName === payload.instanceName &&
         record.pubkey === payload.pubkey &&
         sameStringArray(record.multiaddrs, payload.multiaddrs) &&
-        sameUserPublicAttributes(recordAttributes, payloadAttributes) &&
+        (!payloadIncludesAttributes ||
+            sameUserPublicAttributes(recordAttributes, payloadAttributes)) &&
         record.lastAnnouncedAt === payload.announcedAt);
 }
 function normalizeRecord(value) {
@@ -135,7 +137,9 @@ export function createInstancePeerStore(options) {
             return runMutation(async () => {
                 const table = await load();
                 const existing = table.instances[payload.instanceId];
-                const userPublicAttributes = normalizeUserPublicAttributes(payload.userPublicAttributes);
+                const userPublicAttributes = "userPublicAttributes" in payload
+                    ? normalizeUserPublicAttributes(payload.userPublicAttributes)
+                    : normalizeUserPublicAttributes(existing?.userPublicAttributes);
                 const changed = !sameRecord(existing, payload);
                 const record = {
                     instanceId: payload.instanceId,

package/dist/src/instance-router.js

@@ -120,6 +120,8 @@ export function createInstanceRouter(options) {
     const pendingAcks = new Map();
     const deliveryCache = new Map();
     const unsubs = [];
+    const pendingAttributePeers = new Set();
+    let attributeRefreshPromise;
     function localInstanceId() {
         const identity = mesh.getInstanceIdentity();
         if (!identity) {
@@ -127,20 +129,24 @@ export function createInstanceRouter(options) {
         }
         return identity.id;
     }
-    async function loadUserPublicAttributes() {
+    async function loadUserPublicAttributes(loadOptions) {
+        const userMdPromise = loadOptions?.refreshUserMd && options.userAttributeSource?.refreshTags
+            ? options.userAttributeSource.refreshTags()
+            : options.userAttributeSource?.loadTags() ?? Promise.resolve([]);
+        const profilePromise = options.userProfileStore?.listAttributes().catch((error) => {
+            logger?.warn?.(`[libp2p-mesh] Failed to load profile public attributes: ${summarizeError(error)}`);
+            return [];
+        }) ?? Promise.resolve([]);
         const [userMdTags, profileAttributes] = await Promise.all([
-            options.userAttributeSource?.loadTags().catch((error) => {
+            userMdPromise.catch((error) => {
                 logger?.warn?.(`[libp2p-mesh] Failed to load USER.md public attributes: ${summarizeError(error)}`);
                 return [];
-            }) ?? Promise.resolve([]),
-            options.userProfileStore?.listAttributes().catch((error) => {
-                logger?.warn?.(`[libp2p-mesh] Failed to load profile public attributes: ${summarizeError(error)}`);
-                return [];
-            }) ?? Promise.resolve([]),
+            }),
+            profilePromise,
         ]);
         return mergeUserPublicAttributes(userMdTags, profileAttributes);
     }
-    async function buildAnnouncePayload() {
+    function buildBaseAnnouncePayload() {
         const identity = mesh.getInstanceIdentity();
         if (!identity) {
             throw new Error("Local instance identity is not initialized");
@@ -151,15 +157,87 @@ export function createInstanceRouter(options) {
             instanceName: identity.name,
             multiaddrs: mesh.getMultiaddrs(),
             pubkey: identity.pubkey,
-            userPublicAttributes: await loadUserPublicAttributes(),
             announcedAt: Date.now(),
         };
     }
+    async function buildAttributeAnnouncePayload() {
+        return {
+            ...buildBaseAnnouncePayload(),
+            userPublicAttributes: await loadUserPublicAttributes({ refreshUserMd: true }),
+        };
+    }
+    function attributeAnnouncePeers(extraPeerId) {
+        const peers = new Set();
+        for (const peerId of mesh.getConnectedPeers()) {
+            if (isNonEmptyString(peerId) && peerId !== mesh.getLocalPeerId()) {
+                peers.add(peerId);
+            }
+        }
+        for (const peerId of announcedPeers) {
+            if (isNonEmptyString(peerId) && peerId !== mesh.getLocalPeerId()) {
+                peers.add(peerId);
+            }
+        }
+        if (extraPeerId && extraPeerId !== mesh.getLocalPeerId()) {
+            peers.add(extraPeerId);
+        }
+        return [...peers];
+    }
+    async function sendAttributeAnnounceToPeers(peers) {
+        if (peers.length === 0) {
+            return;
+        }
+        const payload = await buildAttributeAnnouncePayload();
+        for (const peerId of peers) {
+            try {
+                await mesh.sendStructuredMessage(peerId, {
+                    id: crypto.randomUUID(),
+                    type: "instance-announce",
+                    to: peerId,
+                    payload: JSON.stringify(payload),
+                });
+                logAnnounce("Sent", peerId, payload);
+            }
+            catch (error) {
+                logger?.warn?.(`[libp2p-mesh] Failed to send attribute announce to ${peerId}: ${summarizeError(error)}`);
+            }
+        }
+    }
+    function queueAttributeRefresh(extraPeerId) {
+        const peers = extraPeerId === undefined
+            ? attributeAnnouncePeers()
+            : isNonEmptyString(extraPeerId) && extraPeerId !== mesh.getLocalPeerId()
+                ? [extraPeerId]
+                : [];
+        for (const peerId of peers) {
+            pendingAttributePeers.add(peerId);
+        }
+        if (pendingAttributePeers.size === 0 && !attributeRefreshPromise) {
+            return;
+        }
+        drainAttributeRefresh();
+    }
+    function drainAttributeRefresh() {
+        if (!attributeRefreshPromise) {
+            attributeRefreshPromise = (async () => {
+                while (pendingAttributePeers.size > 0) {
+                    const peers = [...pendingAttributePeers];
+                    pendingAttributePeers.clear();
+                    await sendAttributeAnnounceToPeers(peers).catch((error) => {
+                        logger?.warn?.(`[libp2p-mesh] Failed to refresh public attributes: ${summarizeError(error)}`);
+                    });
+                }
+            })().finally(() => {
+                attributeRefreshPromise = undefined;
+            });
+        }
+        return attributeRefreshPromise;
+    }
     async function announceToPeer(peerId) {
         if (!isNonEmptyString(peerId) || peerId === mesh.getLocalPeerId()) {
             return;
         }
-        const payload = await buildAnnouncePayload();
+        const payload = buildBaseAnnouncePayload();
         await mesh.sendStructuredMessage(peerId, {
             id: crypto.randomUUID(),
             type: "instance-announce",
@@ -168,6 +246,13 @@ export function createInstanceRouter(options) {
         });
         announcedPeers.add(peerId);
         logAnnounce("Sent", peerId, payload);
+        queueAttributeRefresh(peerId);
+    }
+    async function refreshPublicAttributes() {
+        for (const peerId of attributeAnnouncePeers()) {
+            pendingAttributePeers.add(peerId);
+        }
+        await drainAttributeRefresh();
     }
     function announceSummary(direction, peerId, payload, changed) {
         const changedDetail = changed === undefined ? "" : ` changed=${changed}`;
@@ -582,6 +667,7 @@ export function createInstanceRouter(options) {
         stop,
         handleMessage,
         announceToPeer,
+        refreshPublicAttributes,
         listInstances,
         resolveInstance,
         sendInstanceMessage,

package/dist/src/plugin.js

@@ -5,7 +5,7 @@ import { createInstancePeerStore } from "./instance-peer-store.js";
 import { createInstanceRouter } from "./instance-router.js";
 import { createMeshNetwork } from "./mesh.js";
 import { createPeerLabelStore } from "./peer-label-store.js";
-import { createUserMdAttributeSource } from "./user-md-attributes.js";
+import { createUserMdAgentAttributeSource } from "./user-md-agent-attributes.js";
 import { createUserProfileStore } from "./user-profile-store.js";
 import { buildP2PTools } from "./agent-tools.js";
 import { registerLibp2pMeshCli } from "./profile-cli.js";
@@ -13,7 +13,6 @@ export function registerLibp2pMesh(api) {
     registerLibp2pMeshWithDeps(api);
 }
 export function registerLibp2pMeshWithDeps(api, deps = {}) {
-    registerLibp2pMeshCli(api);
     const config = api.pluginConfig;
     let unsubscribeInbound;
     let serviceStarted = false;
@@ -24,7 +23,7 @@ export function registerLibp2pMeshWithDeps(api, deps = {}) {
     });
     const store = createInstancePeerStore({ logger: api.logger });
     const peerLabelStore = createPeerLabelStore({ logger: api.logger });
-    const userAttributeSource = createUserMdAttributeSource({ logger: api.logger });
+    const userAttributeSource = createUserMdAgentAttributeSource({ logger: api.logger });
     const userProfileStore = createUserProfileStore({ logger: api.logger });
     const delivery = createOpenClawRuntimeInboundDelivery({
         config: api.config,
@@ -48,6 +47,13 @@ export function registerLibp2pMeshWithDeps(api, deps = {}) {
         userProfileStore,
         peerLabelStore,
     });
+    registerLibp2pMeshCli(api, {
+        profile: {
+            async afterProfileSave() {
+                await router.refreshPublicAttributes();
+            },
+        },
+    });
     const channel = createLibp2pMeshChannel(mesh);
     function attachInboundHandlers() {
         return mesh.onMessage((msg) => {

package/dist/src/profile-cli.d.ts

@@ -19,6 +19,7 @@ export type ProfileCliDeps = {
     createUserMdAttributeSource?: (api: OpenClawPluginApi) => {
         loadTags(): Promise<Awaited<ReturnType<UserProfileStore["listAttributes"]>>>;
     };
+    afterProfileSave?: () => Promise<void>;
 };
 export type LabelsCliDeps = {
     createPrompter?: (ctx: OpenClawPluginCliContext) => SetupPrompter;

package/dist/src/profile-cli.js

@@ -43,6 +43,7 @@ export function registerLibp2pMeshProfileCommand(root, api, ctx, deps = {}) {
                 writer: {
                     async replaceAttributes(attributes) {
                         await profileStore.replaceAttributes(attributes);
+                        await deps.afterProfileSave?.();
                     },
                 },
             });

package/dist/src/prompt-config.js

@@ -36,19 +36,26 @@ export const LIBP2P_MESH_AGENT_PROMPT = `
 
 1. 必须使用 \`selector\` 参数，不要使用旧的 \`match.kind/key/value\` 参数。
 
-2. \`openclaw libp2p-mesh labels\` manages local labels for remote instances. These labels are stored in the local \`peer-labels.json\`, stay on this machine, and are used only when the send tool uses \`scope="local"\` or \`scope="all"\`.
+2. 公开属性来源：
 
-3. scope 规则：
+   - \`source="USER.md"\` 表示 gateway 使用 OpenClaw 已配置的 agent/API 模型，从 USER.md 异步提取并公开广播的 tag。
+   - \`source="profile"\` 表示用户通过 \`openclaw libp2p-mesh profile\` 手动配置的公开结构化属性。
+   - gateway 的基础 \`instance-announce\` 可能省略 \`userPublicAttributes\`；这表示本次 announce 没有携带属性，不一定表示该用户没有公开属性。按公开属性发送前先用 \`p2p_list_instances\` 查看当前实例记录。
+   - 普通对话 agent 不应自己读取 USER.md 来决定公开属性。USER.md 属性提取是 gateway 后台职责。
+
+3. \`openclaw libp2p-mesh labels\` manages local labels for remote instances. These labels are stored in the local \`peer-labels.json\`, stay on this machine, and are used only when the send tool uses \`scope="local"\` or \`scope="all"\`.
+
+4. scope 规则：
 
    - 默认是 \`scope="public"\`；default is scope="public"；省略 \`scope\` 时只匹配远端公开广播的 \`userPublicAttributes\`。
-   - \`scope="public"\` 匹配远端实例自己公开的属性，例如 USER.md tags 或 profile 属性。
+   - \`scope="public"\` 匹配远端公开广播的 \`userPublicAttributes\`，包括 USER.md 异步提取 tag 和 profile 属性。
    - \`scope="local"\` 只匹配本机通过 \`openclaw libp2p-mesh labels\` 给远端实例配置的本地标签。
-   - \`scope="all"\` 同时匹配 public 和 local 两个来源。
+   - \`scope="all"\` 同时匹配公开属性和本地标签。
    - 用户说“我归类”“我标记”或提到 labels/local labels/本地标签时，使用 \`scope="local"\`。
    - 用户说 public、公开、自己公开、对方公开时，使用 \`scope="public"\`。
    - 用户说 both、two sources、两个来源、公开和本地都算时，使用 \`scope="all"\`。
 
-4. selector 规则：
+5. selector 规则：
 
    - \`group=实验室\` 必须原样传入：
      - \`selector="group=实验室"\`
@@ -67,7 +74,7 @@ export const LIBP2P_MESH_AGENT_PROMPT = `
 
    - \`实验室\` 这种裸值是歧义表达，不要自行改成 \`tag=实验室\` 或 \`tag:实验室\`，直接调用工具会返回歧义错误，或提示用户必须写成 \`group=实验室\` 或 \`tag:实验室\`。
 
-5. 群发前必须先 dry run：
+6. 群发前必须先 dry run：
 
    - 第一次调用：
      - \`dryRun=true\`
@@ -75,7 +82,7 @@ export const LIBP2P_MESH_AGENT_PROMPT = `
      - \`scope\` 使用按上面规则判断出的 scope；如果没有明确本地或双来源意图，可省略，默认是 \`scope="public"\`
      - \`message\` 填用户要发送的原始消息内容
 
-6. 如果 dry run 匹配到目标，不需要再询问用户确认，立即再次调用同一个工具发送：
+7. 如果 dry run 匹配到目标，不需要再询问用户确认，立即再次调用同一个工具发送：
 
    - 第二次调用：
      - \`dryRun=false\`
@@ -84,11 +91,11 @@ export const LIBP2P_MESH_AGENT_PROMPT = `
      - \`message\` 必须和 dry run 时一致
    - In English: dry run then actual send must use the same selector/scope/message.
 
-7. 如果 dry run 没有匹配目标，直接输出工具返回结果，不要猜测网络中还有其他未发现实例。
+8. 如果 dry run 没有匹配目标，直接输出工具返回结果，不要猜测网络中还有其他未发现实例。
 
-8. 不要手动在 \`message\` 前面拼接发送方 instanceId；插件会在接收侧元数据和展示文本中携带发送方 instanceId。
+9. 不要手动在 \`message\` 前面拼接发送方 instanceId；插件会在接收侧元数据和展示文本中携带发送方 instanceId。
 
-9. 按属性发送只匹配本机 \`instance-peer.json\` 中已发现的实例，不代表全网搜索。
+10. 按属性发送只匹配本机 \`instance-peer.json\` 中已发现的实例，不代表全网搜索。
 
 ## 三、查询和排障
 

package/dist/src/types.d.ts

@@ -85,6 +85,10 @@ export type UserPublicAttribute = {
     label: string;
     source: "profile";
 };
+export type UserMdAttributeSource = {
+    loadTags(): Promise<UserPublicAttribute[]>;
+    refreshTags?(): Promise<UserPublicAttribute[]>;
+};
 export type LocalPeerLabel = {
     key: string;
     value: string;
@@ -205,9 +209,7 @@ export type InstanceRouterOptions = {
         warn?: (message: string) => void;
         error?: (message: string) => void;
     };
-    userAttributeSource?: {
-        loadTags(): Promise<UserPublicAttribute[]>;
-    };
+    userAttributeSource?: UserMdAttributeSource;
     userProfileStore?: {
         listAttributes(): Promise<UserPublicAttribute[]>;
     };
@@ -222,6 +224,7 @@ export interface InstanceRouter {
     stop(): Promise<void>;
     handleMessage(msg: P2PMessage): Promise<void>;
     announceToPeer(peerId: string): Promise<void>;
+    refreshPublicAttributes(): Promise<void>;
     listInstances(): Promise<InstancePeerRecord[]>;
     resolveInstance(instanceId: string): Promise<InstancePeerRecord | undefined>;
     sendInstanceMessage(instanceId: string, message: string): Promise<{

package/dist/src/user-md-agent-attributes.d.ts

@@ -0,0 +1,24 @@
+import type { UserMdAttributeSource, UserPublicAttribute } from "./types.js";
+type Logger = {
+    debug?: (message: string) => void;
+    warn?: (message: string) => void;
+};
+export type UserMdAttributeExtractionUnavailable = {
+    unavailable: true;
+    reason: string;
+};
+export type UserMdAttributeExtractor = {
+    extract(request: {
+        markdown: string;
+        sourcePath: string;
+    }): Promise<UserPublicAttribute[] | UserMdAttributeExtractionUnavailable>;
+};
+export declare function resolveUserMdAttributeCachePath(customPath?: string): string;
+export declare function validateExtractedUserMdTags(value: unknown): UserPublicAttribute[];
+export declare function createUserMdAgentAttributeSource(options?: {
+    path?: string;
+    cachePath?: string;
+    extractor?: UserMdAttributeExtractor;
+    logger?: Logger;
+}): UserMdAttributeSource;
+export {};

package/dist/src/user-md-agent-attributes.js

@@ -0,0 +1,180 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { normalizeAttributeValue } from "./user-attributes.js";
+import { resolveUserMdPath } from "./user-md-attributes.js";
+const CACHE_VERSION = 1;
+const MAX_AGENT_TAGS = 10;
+const MAX_AGENT_TAG_LENGTH = 40;
+const defaultExtractor = {
+    async extract() {
+        return {
+            unavailable: true,
+            reason: "USER.md agent extraction is unavailable in this runtime",
+        };
+    },
+};
+export function resolveUserMdAttributeCachePath(customPath) {
+    if (customPath) {
+        return customPath;
+    }
+    const stateDir = process.env.OPENCLAW_STATE_DIR;
+    if (stateDir) {
+        return path.join(stateDir, "libp2p", "user-md-attributes-cache.json");
+    }
+    return path.join(homedir(), ".openclaw", "libp2p", "user-md-attributes-cache.json");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function normalizeWhitespace(value) {
+    return value.trim().replace(/\s+/g, " ");
+}
+function looksLikeSentence(value) {
+    return /[。.!?！？]/.test(value) || value.split(/\s+/).filter(Boolean).length > 4;
+}
+function normalizeAgentTag(value) {
+    if (!isRecord(value) || value.kind !== "tag" || value.source !== "USER.md") {
+        return undefined;
+    }
+    if (typeof value.value !== "string" || typeof value.label !== "string") {
+        return undefined;
+    }
+    const tagValue = normalizeWhitespace(value.value);
+    const label = normalizeWhitespace(value.label);
+    if (!tagValue || !label || tagValue.length > MAX_AGENT_TAG_LENGTH || looksLikeSentence(tagValue)) {
+        return undefined;
+    }
+    return {
+        kind: "tag",
+        value: tagValue,
+        label,
+        source: "USER.md",
+    };
+}
+export function validateExtractedUserMdTags(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const attributes = [];
+    const seen = new Set();
+    for (const rawAttribute of value) {
+        const attribute = normalizeAgentTag(rawAttribute);
+        if (!attribute) {
+            continue;
+        }
+        const key = normalizeAttributeValue(attribute.value);
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        attributes.push(attribute);
+        if (attributes.length >= MAX_AGENT_TAGS) {
+            break;
+        }
+    }
+    return attributes;
+}
+function hashMarkdown(markdown) {
+    return createHash("sha256").update(markdown, "utf8").digest("hex");
+}
+function normalizeCacheFile(value) {
+    if (!isRecord(value) || value.version !== CACHE_VERSION || typeof value.userMdHash !== "string") {
+        return undefined;
+    }
+    const attributes = validateExtractedUserMdTags(value.attributes);
+    if (!Array.isArray(value.attributes) || attributes.length !== value.attributes.length) {
+        return undefined;
+    }
+    return {
+        version: CACHE_VERSION,
+        updatedAt: typeof value.updatedAt === "number" ? value.updatedAt : Date.now(),
+        userMdHash: value.userMdHash,
+        attributes,
+    };
+}
+async function readCache(cachePath) {
+    try {
+        return normalizeCacheFile(JSON.parse(await readFile(cachePath, "utf8")));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeCache(cachePath, userMdHash, attributes) {
+    const cache = {
+        version: CACHE_VERSION,
+        updatedAt: Date.now(),
+        userMdHash,
+        attributes: validateExtractedUserMdTags(attributes),
+    };
+    const dir = path.dirname(cachePath);
+    const tmpPath = `${cachePath}.tmp-${process.pid}-${Date.now()}-${randomUUID()}`;
+    await mkdir(dir, { recursive: true });
+    try {
+        await writeFile(tmpPath, `${JSON.stringify(cache, null, 2)}\n`, "utf8");
+        await rename(tmpPath, cachePath);
+    }
+    catch (error) {
+        await rm(tmpPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+function isExtractionUnavailable(value) {
+    return isRecord(value) && value.unavailable === true && typeof value.reason === "string";
+}
+export function createUserMdAgentAttributeSource(options) {
+    const filePath = resolveUserMdPath(options?.path);
+    const cachePath = resolveUserMdAttributeCachePath(options?.cachePath);
+    const extractor = options?.extractor ?? defaultExtractor;
+    const logger = options?.logger;
+    async function readUserMd() {
+        try {
+            const markdown = await readFile(filePath, "utf8");
+            return { markdown, userMdHash: hashMarkdown(markdown) };
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return undefined;
+            }
+            logger?.warn?.(`[libp2p-mesh] Failed to read USER.md at ${filePath}: ${error.message}`);
+            return undefined;
+        }
+    }
+    async function loadCachedTagsForCurrentHash() {
+        const userMd = await readUserMd();
+        if (!userMd) {
+            return [];
+        }
+        const cache = await readCache(cachePath);
+        return cache?.userMdHash === userMd.userMdHash ? [...cache.attributes] : [];
+    }
+    return {
+        async loadTags() {
+            return loadCachedTagsForCurrentHash();
+        },
+        async refreshTags() {
+            const userMd = await readUserMd();
+            if (!userMd) {
+                return [];
+            }
+            const cache = await readCache(cachePath);
+            if (cache?.userMdHash === userMd.userMdHash) {
+                return [...cache.attributes];
+            }
+            const extracted = await extractor.extract({
+                markdown: userMd.markdown,
+                sourcePath: filePath,
+            });
+            if (isExtractionUnavailable(extracted)) {
+                logger?.warn?.(`[libp2p-mesh] USER.md agent extraction unavailable: ${extracted.reason}`);
+                return [];
+            }
+            const attributes = validateExtractedUserMdTags(extracted);
+            await writeCache(cachePath, userMd.userMdHash, attributes);
+            logger?.debug?.(`[libp2p-mesh] Saved USER.md agent attribute cache to ${cachePath}`);
+            return attributes;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libp2p-mesh",
-  "version": "2026.6.20",
+  "version": "2026.6.21",
   "description": "OpenClaw libp2p P2P mesh network plugin for cross-instance agent communication",
   "type": "module",
   "main": "dist/index.js",

package/src/instance-peer-store.ts

@@ -66,13 +66,15 @@ function sameRecord(
 
   const recordAttributes = normalizeUserPublicAttributes(record.userPublicAttributes);
   const payloadAttributes = normalizeUserPublicAttributes(payload.userPublicAttributes);
+  const payloadIncludesAttributes = "userPublicAttributes" in payload;
 
   return (
     record.peerId === payload.peerId &&
     record.instanceName === payload.instanceName &&
     record.pubkey === payload.pubkey &&
     sameStringArray(record.multiaddrs, payload.multiaddrs) &&
-    sameUserPublicAttributes(recordAttributes, payloadAttributes) &&
+    (!payloadIncludesAttributes ||
+      sameUserPublicAttributes(recordAttributes, payloadAttributes)) &&
     record.lastAnnouncedAt === payload.announcedAt
   );
 }
@@ -187,7 +189,10 @@ export function createInstancePeerStore(options?: {
       return runMutation(async () => {
         const table = await load();
         const existing = table.instances[payload.instanceId];
-        const userPublicAttributes = normalizeUserPublicAttributes(payload.userPublicAttributes);
+        const userPublicAttributes =
+          "userPublicAttributes" in payload
+            ? normalizeUserPublicAttributes(payload.userPublicAttributes)
+            : normalizeUserPublicAttributes(existing?.userPublicAttributes);
         const changed = !sameRecord(existing, payload);
         const record: InstancePeerRecord = {
           instanceId: payload.instanceId,

package/src/instance-router.ts

@@ -217,6 +217,8 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
   const pendingAcks = new Map<string, PendingAck>();
   const deliveryCache = new Map<string, DeliveryCacheEntry>();
   const unsubs: Array<() => void> = [];
+  const pendingAttributePeers = new Set<string>();
+  let attributeRefreshPromise: Promise<void> | undefined;
 
   function localInstanceId(): string {
     const identity = mesh.getInstanceIdentity();
@@ -226,26 +228,35 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
     return identity.id;
   }
 
-  async function loadUserPublicAttributes(): Promise<UserPublicAttribute[]> {
-    const [userMdTags, profileAttributes] = await Promise.all([
-      options.userAttributeSource?.loadTags().catch((error) => {
+  async function loadUserPublicAttributes(loadOptions?: {
+    refreshUserMd?: boolean;
+  }): Promise<UserPublicAttribute[]> {
+    const userMdPromise = loadOptions?.refreshUserMd && options.userAttributeSource?.refreshTags
+      ? options.userAttributeSource.refreshTags()
+      : options.userAttributeSource?.loadTags() ?? Promise.resolve([]);
+
+    const profilePromise =
+      options.userProfileStore?.listAttributes().catch((error) => {
         logger?.warn?.(
-          `[libp2p-mesh] Failed to load USER.md public attributes: ${summarizeError(error)}`,
+          `[libp2p-mesh] Failed to load profile public attributes: ${summarizeError(error)}`,
         );
         return [];
-      }) ?? Promise.resolve([]),
-      options.userProfileStore?.listAttributes().catch((error) => {
+      }) ?? Promise.resolve([]);
+
+    const [userMdTags, profileAttributes] = await Promise.all([
+      userMdPromise.catch((error) => {
         logger?.warn?.(
-          `[libp2p-mesh] Failed to load profile public attributes: ${summarizeError(error)}`,
+          `[libp2p-mesh] Failed to load USER.md public attributes: ${summarizeError(error)}`,
         );
         return [];
-      }) ?? Promise.resolve([]),
+      }),
+      profilePromise,
     ]);
 
     return mergeUserPublicAttributes(userMdTags, profileAttributes);
   }
 
-  async function buildAnnouncePayload(): Promise<InstanceAnnouncePayload> {
+  function buildBaseAnnouncePayload(): InstanceAnnouncePayload {
     const identity = mesh.getInstanceIdentity();
     if (!identity) {
       throw new Error("Local instance identity is not initialized");
@@ -257,17 +268,102 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
       instanceName: identity.name,
       multiaddrs: mesh.getMultiaddrs(),
       pubkey: identity.pubkey,
-      userPublicAttributes: await loadUserPublicAttributes(),
       announcedAt: Date.now(),
     };
   }
 
+  async function buildAttributeAnnouncePayload(): Promise<InstanceAnnouncePayload> {
+    return {
+      ...buildBaseAnnouncePayload(),
+      userPublicAttributes: await loadUserPublicAttributes({ refreshUserMd: true }),
+    };
+  }
+
+  function attributeAnnouncePeers(extraPeerId?: string): string[] {
+    const peers = new Set<string>();
+    for (const peerId of mesh.getConnectedPeers()) {
+      if (isNonEmptyString(peerId) && peerId !== mesh.getLocalPeerId()) {
+        peers.add(peerId);
+      }
+    }
+    for (const peerId of announcedPeers) {
+      if (isNonEmptyString(peerId) && peerId !== mesh.getLocalPeerId()) {
+        peers.add(peerId);
+      }
+    }
+    if (extraPeerId && extraPeerId !== mesh.getLocalPeerId()) {
+      peers.add(extraPeerId);
+    }
+    return [...peers];
+  }
+
+  async function sendAttributeAnnounceToPeers(peers: string[]): Promise<void> {
+    if (peers.length === 0) {
+      return;
+    }
+
+    const payload = await buildAttributeAnnouncePayload();
+    for (const peerId of peers) {
+      try {
+        await mesh.sendStructuredMessage(peerId, {
+          id: crypto.randomUUID(),
+          type: "instance-announce",
+          to: peerId,
+          payload: JSON.stringify(payload),
+        });
+        logAnnounce("Sent", peerId, payload);
+      } catch (error) {
+        logger?.warn?.(
+          `[libp2p-mesh] Failed to send attribute announce to ${peerId}: ${summarizeError(error)}`,
+        );
+      }
+    }
+  }
+
+  function queueAttributeRefresh(extraPeerId?: string): void {
+    const peers =
+      extraPeerId === undefined
+        ? attributeAnnouncePeers()
+        : isNonEmptyString(extraPeerId) && extraPeerId !== mesh.getLocalPeerId()
+          ? [extraPeerId]
+          : [];
+    for (const peerId of peers) {
+      pendingAttributePeers.add(peerId);
+    }
+
+    if (pendingAttributePeers.size === 0 && !attributeRefreshPromise) {
+      return;
+    }
+
+    drainAttributeRefresh();
+  }
+
+  function drainAttributeRefresh(): Promise<void> {
+    if (!attributeRefreshPromise) {
+      attributeRefreshPromise = (async () => {
+        while (pendingAttributePeers.size > 0) {
+          const peers = [...pendingAttributePeers];
+          pendingAttributePeers.clear();
+          await sendAttributeAnnounceToPeers(peers).catch((error) => {
+            logger?.warn?.(
+              `[libp2p-mesh] Failed to refresh public attributes: ${summarizeError(error)}`,
+            );
+          });
+        }
+      })().finally(() => {
+        attributeRefreshPromise = undefined;
+      });
+    }
+
+    return attributeRefreshPromise;
+  }
+
   async function announceToPeer(peerId: string): Promise<void> {
     if (!isNonEmptyString(peerId) || peerId === mesh.getLocalPeerId()) {
       return;
     }
 
-    const payload = await buildAnnouncePayload();
+    const payload = buildBaseAnnouncePayload();
     await mesh.sendStructuredMessage(peerId, {
       id: crypto.randomUUID(),
       type: "instance-announce",
@@ -276,6 +372,15 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
     });
     announcedPeers.add(peerId);
     logAnnounce("Sent", peerId, payload);
+    queueAttributeRefresh(peerId);
+  }
+
+  async function refreshPublicAttributes(): Promise<void> {
+    for (const peerId of attributeAnnouncePeers()) {
+      pendingAttributePeers.add(peerId);
+    }
+
+    await drainAttributeRefresh();
   }
 
   function announceSummary(
@@ -791,6 +896,7 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
     stop,
     handleMessage,
     announceToPeer,
+    refreshPublicAttributes,
     listInstances,
     resolveInstance,
     sendInstanceMessage,

package/src/plugin.ts

@@ -6,7 +6,7 @@ import { createInstancePeerStore } from "./instance-peer-store.js";
 import { createInstanceRouter } from "./instance-router.js";
 import { createMeshNetwork } from "./mesh.js";
 import { createPeerLabelStore } from "./peer-label-store.js";
-import { createUserMdAttributeSource } from "./user-md-attributes.js";
+import { createUserMdAgentAttributeSource } from "./user-md-agent-attributes.js";
 import { createUserProfileStore } from "./user-profile-store.js";
 import { buildP2PTools } from "./agent-tools.js";
 import { registerLibp2pMeshCli } from "./profile-cli.js";
@@ -26,8 +26,6 @@ export function registerLibp2pMeshWithDeps(
   api: OpenClawPluginApi,
   deps: Libp2pMeshPluginDeps = {},
 ) {
-  registerLibp2pMeshCli(api);
-
   const config = api.pluginConfig as MeshConfig | undefined;
   let unsubscribeInbound: (() => void) | undefined;
   let serviceStarted = false;
@@ -38,7 +36,7 @@ export function registerLibp2pMeshWithDeps(
   });
   const store = createInstancePeerStore({ logger: api.logger });
   const peerLabelStore = createPeerLabelStore({ logger: api.logger });
-  const userAttributeSource = createUserMdAttributeSource({ logger: api.logger });
+  const userAttributeSource = createUserMdAgentAttributeSource({ logger: api.logger });
   const userProfileStore = createUserProfileStore({ logger: api.logger });
   const delivery = createOpenClawRuntimeInboundDelivery({
     config: api.config,
@@ -65,6 +63,14 @@ export function registerLibp2pMeshWithDeps(
     peerLabelStore,
   });
 
+  registerLibp2pMeshCli(api, {
+    profile: {
+      async afterProfileSave() {
+        await router.refreshPublicAttributes();
+      },
+    },
+  });
+
   const channel = createLibp2pMeshChannel(mesh);
 
   function attachInboundHandlers(): () => void {

package/src/profile-cli.ts

@@ -30,6 +30,7 @@ export type ProfileCliDeps = {
   createPrompter?: (ctx: OpenClawPluginCliContext) => SetupPrompter;
   createProfileStore?: (api: OpenClawPluginApi) => Pick<UserProfileStore, "listAttributes" | "replaceAttributes">;
   createUserMdAttributeSource?: (api: OpenClawPluginApi) => { loadTags(): Promise<Awaited<ReturnType<UserProfileStore["listAttributes"]>>> };
+  afterProfileSave?: () => Promise<void>;
 };
 
 export type LabelsCliDeps = {
@@ -92,6 +93,7 @@ export function registerLibp2pMeshProfileCommand(
           writer: {
             async replaceAttributes(attributes) {
               await profileStore.replaceAttributes(attributes);
+              await deps.afterProfileSave?.();
             },
           },
         });

package/src/prompt-config.ts

@@ -38,19 +38,26 @@ export const LIBP2P_MESH_AGENT_PROMPT = `
 
 1. 必须使用 \`selector\` 参数，不要使用旧的 \`match.kind/key/value\` 参数。
 
-2. \`openclaw libp2p-mesh labels\` manages local labels for remote instances. These labels are stored in the local \`peer-labels.json\`, stay on this machine, and are used only when the send tool uses \`scope="local"\` or \`scope="all"\`.
+2. 公开属性来源：
 
-3. scope 规则：
+   - \`source="USER.md"\` 表示 gateway 使用 OpenClaw 已配置的 agent/API 模型，从 USER.md 异步提取并公开广播的 tag。
+   - \`source="profile"\` 表示用户通过 \`openclaw libp2p-mesh profile\` 手动配置的公开结构化属性。
+   - gateway 的基础 \`instance-announce\` 可能省略 \`userPublicAttributes\`；这表示本次 announce 没有携带属性，不一定表示该用户没有公开属性。按公开属性发送前先用 \`p2p_list_instances\` 查看当前实例记录。
+   - 普通对话 agent 不应自己读取 USER.md 来决定公开属性。USER.md 属性提取是 gateway 后台职责。
+
+3. \`openclaw libp2p-mesh labels\` manages local labels for remote instances. These labels are stored in the local \`peer-labels.json\`, stay on this machine, and are used only when the send tool uses \`scope="local"\` or \`scope="all"\`.
+
+4. scope 规则：
 
    - 默认是 \`scope="public"\`；default is scope="public"；省略 \`scope\` 时只匹配远端公开广播的 \`userPublicAttributes\`。
-   - \`scope="public"\` 匹配远端实例自己公开的属性，例如 USER.md tags 或 profile 属性。
+   - \`scope="public"\` 匹配远端公开广播的 \`userPublicAttributes\`，包括 USER.md 异步提取 tag 和 profile 属性。
    - \`scope="local"\` 只匹配本机通过 \`openclaw libp2p-mesh labels\` 给远端实例配置的本地标签。
-   - \`scope="all"\` 同时匹配 public 和 local 两个来源。
+   - \`scope="all"\` 同时匹配公开属性和本地标签。
    - 用户说“我归类”“我标记”或提到 labels/local labels/本地标签时，使用 \`scope="local"\`。
    - 用户说 public、公开、自己公开、对方公开时，使用 \`scope="public"\`。
    - 用户说 both、two sources、两个来源、公开和本地都算时，使用 \`scope="all"\`。
 
-4. selector 规则：
+5. selector 规则：
 
    - \`group=实验室\` 必须原样传入：
      - \`selector="group=实验室"\`
@@ -69,7 +76,7 @@ export const LIBP2P_MESH_AGENT_PROMPT = `
 
    - \`实验室\` 这种裸值是歧义表达，不要自行改成 \`tag=实验室\` 或 \`tag:实验室\`，直接调用工具会返回歧义错误，或提示用户必须写成 \`group=实验室\` 或 \`tag:实验室\`。
 
-5. 群发前必须先 dry run：
+6. 群发前必须先 dry run：
 
    - 第一次调用：
      - \`dryRun=true\`
@@ -77,7 +84,7 @@ export const LIBP2P_MESH_AGENT_PROMPT = `
      - \`scope\` 使用按上面规则判断出的 scope；如果没有明确本地或双来源意图，可省略，默认是 \`scope="public"\`
      - \`message\` 填用户要发送的原始消息内容
 
-6. 如果 dry run 匹配到目标，不需要再询问用户确认，立即再次调用同一个工具发送：
+7. 如果 dry run 匹配到目标，不需要再询问用户确认，立即再次调用同一个工具发送：
 
    - 第二次调用：
      - \`dryRun=false\`
@@ -86,11 +93,11 @@ export const LIBP2P_MESH_AGENT_PROMPT = `
      - \`message\` 必须和 dry run 时一致
    - In English: dry run then actual send must use the same selector/scope/message.
 
-7. 如果 dry run 没有匹配目标，直接输出工具返回结果，不要猜测网络中还有其他未发现实例。
+8. 如果 dry run 没有匹配目标，直接输出工具返回结果，不要猜测网络中还有其他未发现实例。
 
-8. 不要手动在 \`message\` 前面拼接发送方 instanceId；插件会在接收侧元数据和展示文本中携带发送方 instanceId。
+9. 不要手动在 \`message\` 前面拼接发送方 instanceId；插件会在接收侧元数据和展示文本中携带发送方 instanceId。
 
-9. 按属性发送只匹配本机 \`instance-peer.json\` 中已发现的实例，不代表全网搜索。
+10. 按属性发送只匹配本机 \`instance-peer.json\` 中已发现的实例，不代表全网搜索。
 
 ## 三、查询和排障
 

package/src/types.ts

@@ -102,6 +102,11 @@ export type UserPublicAttribute =
       source: "profile";
     };
 
+export type UserMdAttributeSource = {
+  loadTags(): Promise<UserPublicAttribute[]>;
+  refreshTags?(): Promise<UserPublicAttribute[]>;
+};
+
 export type LocalPeerLabel = {
   key: string;
   value: string;
@@ -232,9 +237,7 @@ export type InstanceRouterOptions = {
     warn?: (message: string) => void;
     error?: (message: string) => void;
   };
-  userAttributeSource?: {
-    loadTags(): Promise<UserPublicAttribute[]>;
-  };
+  userAttributeSource?: UserMdAttributeSource;
   userProfileStore?: {
     listAttributes(): Promise<UserPublicAttribute[]>;
   };
@@ -250,6 +253,7 @@ export interface InstanceRouter {
   stop(): Promise<void>;
   handleMessage(msg: P2PMessage): Promise<void>;
   announceToPeer(peerId: string): Promise<void>;
+  refreshPublicAttributes(): Promise<void>;
   listInstances(): Promise<InstancePeerRecord[]>;
   resolveInstance(instanceId: string): Promise<InstancePeerRecord | undefined>;
   sendInstanceMessage(instanceId: string, message: string): Promise<{

package/src/user-md-agent-attributes.ts

@@ -0,0 +1,243 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+
+import type { UserMdAttributeSource, UserPublicAttribute } from "./types.js";
+import { normalizeAttributeValue } from "./user-attributes.js";
+import { resolveUserMdPath } from "./user-md-attributes.js";
+
+const CACHE_VERSION = 1;
+const MAX_AGENT_TAGS = 10;
+const MAX_AGENT_TAG_LENGTH = 40;
+
+type Logger = {
+  debug?: (message: string) => void;
+  warn?: (message: string) => void;
+};
+
+type UserMdAttributeCacheFile = {
+  version: 1;
+  updatedAt: number;
+  userMdHash: string;
+  attributes: UserPublicAttribute[];
+};
+
+export type UserMdAttributeExtractionUnavailable = {
+  unavailable: true;
+  reason: string;
+};
+
+export type UserMdAttributeExtractor = {
+  extract(request: {
+    markdown: string;
+    sourcePath: string;
+  }): Promise<UserPublicAttribute[] | UserMdAttributeExtractionUnavailable>;
+};
+
+const defaultExtractor: UserMdAttributeExtractor = {
+  async extract() {
+    return {
+      unavailable: true,
+      reason: "USER.md agent extraction is unavailable in this runtime",
+    };
+  },
+};
+
+export function resolveUserMdAttributeCachePath(customPath?: string): string {
+  if (customPath) {
+    return customPath;
+  }
+
+  const stateDir = process.env.OPENCLAW_STATE_DIR;
+  if (stateDir) {
+    return path.join(stateDir, "libp2p", "user-md-attributes-cache.json");
+  }
+
+  return path.join(homedir(), ".openclaw", "libp2p", "user-md-attributes-cache.json");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function normalizeWhitespace(value: string): string {
+  return value.trim().replace(/\s+/g, " ");
+}
+
+function looksLikeSentence(value: string): boolean {
+  return /[。.!?！？]/.test(value) || value.split(/\s+/).filter(Boolean).length > 4;
+}
+
+function normalizeAgentTag(value: unknown): UserPublicAttribute | undefined {
+  if (!isRecord(value) || value.kind !== "tag" || value.source !== "USER.md") {
+    return undefined;
+  }
+
+  if (typeof value.value !== "string" || typeof value.label !== "string") {
+    return undefined;
+  }
+
+  const tagValue = normalizeWhitespace(value.value);
+  const label = normalizeWhitespace(value.label);
+  if (!tagValue || !label || tagValue.length > MAX_AGENT_TAG_LENGTH || looksLikeSentence(tagValue)) {
+    return undefined;
+  }
+
+  return {
+    kind: "tag",
+    value: tagValue,
+    label,
+    source: "USER.md",
+  };
+}
+
+export function validateExtractedUserMdTags(value: unknown): UserPublicAttribute[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  const attributes: UserPublicAttribute[] = [];
+  const seen = new Set<string>();
+
+  for (const rawAttribute of value) {
+    const attribute = normalizeAgentTag(rawAttribute);
+    if (!attribute) {
+      continue;
+    }
+
+    const key = normalizeAttributeValue(attribute.value);
+    if (seen.has(key)) {
+      continue;
+    }
+
+    seen.add(key);
+    attributes.push(attribute);
+    if (attributes.length >= MAX_AGENT_TAGS) {
+      break;
+    }
+  }
+
+  return attributes;
+}
+
+function hashMarkdown(markdown: string): string {
+  return createHash("sha256").update(markdown, "utf8").digest("hex");
+}
+
+function normalizeCacheFile(value: unknown): UserMdAttributeCacheFile | undefined {
+  if (!isRecord(value) || value.version !== CACHE_VERSION || typeof value.userMdHash !== "string") {
+    return undefined;
+  }
+
+  const attributes = validateExtractedUserMdTags(value.attributes);
+  if (!Array.isArray(value.attributes) || attributes.length !== value.attributes.length) {
+    return undefined;
+  }
+
+  return {
+    version: CACHE_VERSION,
+    updatedAt: typeof value.updatedAt === "number" ? value.updatedAt : Date.now(),
+    userMdHash: value.userMdHash,
+    attributes,
+  };
+}
+
+async function readCache(cachePath: string): Promise<UserMdAttributeCacheFile | undefined> {
+  try {
+    return normalizeCacheFile(JSON.parse(await readFile(cachePath, "utf8")));
+  } catch {
+    return undefined;
+  }
+}
+
+async function writeCache(cachePath: string, userMdHash: string, attributes: UserPublicAttribute[]): Promise<void> {
+  const cache: UserMdAttributeCacheFile = {
+    version: CACHE_VERSION,
+    updatedAt: Date.now(),
+    userMdHash,
+    attributes: validateExtractedUserMdTags(attributes),
+  };
+  const dir = path.dirname(cachePath);
+  const tmpPath = `${cachePath}.tmp-${process.pid}-${Date.now()}-${randomUUID()}`;
+
+  await mkdir(dir, { recursive: true });
+  try {
+    await writeFile(tmpPath, `${JSON.stringify(cache, null, 2)}\n`, "utf8");
+    await rename(tmpPath, cachePath);
+  } catch (error) {
+    await rm(tmpPath, { force: true }).catch(() => undefined);
+    throw error;
+  }
+}
+
+function isExtractionUnavailable(value: unknown): value is UserMdAttributeExtractionUnavailable {
+  return isRecord(value) && value.unavailable === true && typeof value.reason === "string";
+}
+
+export function createUserMdAgentAttributeSource(options?: {
+  path?: string;
+  cachePath?: string;
+  extractor?: UserMdAttributeExtractor;
+  logger?: Logger;
+}): UserMdAttributeSource {
+  const filePath = resolveUserMdPath(options?.path);
+  const cachePath = resolveUserMdAttributeCachePath(options?.cachePath);
+  const extractor = options?.extractor ?? defaultExtractor;
+  const logger = options?.logger;
+
+  async function readUserMd(): Promise<{ markdown: string; userMdHash: string } | undefined> {
+    try {
+      const markdown = await readFile(filePath, "utf8");
+      return { markdown, userMdHash: hashMarkdown(markdown) };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        return undefined;
+      }
+
+      logger?.warn?.(`[libp2p-mesh] Failed to read USER.md at ${filePath}: ${(error as Error).message}`);
+      return undefined;
+    }
+  }
+
+  async function loadCachedTagsForCurrentHash(): Promise<UserPublicAttribute[]> {
+    const userMd = await readUserMd();
+    if (!userMd) {
+      return [];
+    }
+
+    const cache = await readCache(cachePath);
+    return cache?.userMdHash === userMd.userMdHash ? [...cache.attributes] : [];
+  }
+
+  return {
+    async loadTags(): Promise<UserPublicAttribute[]> {
+      return loadCachedTagsForCurrentHash();
+    },
+    async refreshTags(): Promise<UserPublicAttribute[]> {
+      const userMd = await readUserMd();
+      if (!userMd) {
+        return [];
+      }
+
+      const cache = await readCache(cachePath);
+      if (cache?.userMdHash === userMd.userMdHash) {
+        return [...cache.attributes];
+      }
+
+      const extracted = await extractor.extract({
+        markdown: userMd.markdown,
+        sourcePath: filePath,
+      });
+      if (isExtractionUnavailable(extracted)) {
+        logger?.warn?.(`[libp2p-mesh] USER.md agent extraction unavailable: ${extracted.reason}`);
+        return [];
+      }
+
+      const attributes = validateExtractedUserMdTags(extracted);
+      await writeCache(cachePath, userMd.userMdHash, attributes);
+      logger?.debug?.(`[libp2p-mesh] Saved USER.md agent attribute cache to ${cachePath}`);
+      return attributes;
+    },
+  };
+}