pinecone-memory

将 OpenClaw 记忆系统接入 Pinecone 向量数据库，用于语义检索与记忆持久化。Use when: 用户要求同步记忆到 Pinecone、执行语义搜索、为记忆做云端备份、对大规模记忆进行高效检索。

Security Scan

The skill mostly does what its description says (sync/query Pinecone), but there are mismatches between its declared requirements and what the files actually need/run, and the runtime instructions read/write local files and perform index operations (including destructive cleanup) — so review before installing and avoid giving production secrets until you approve it.

Purpose & Capability

The skill's stated purpose (persist OpenClaw memory to Pinecone and perform semantic search) aligns with the code and CLI commands: it reads local markdown memory, chunks/redacts text, and upserts/queries a Pinecone index. However the registry metadata provided earlier shows no required env vars or binaries while the SKILL.md (and the code) require Node and PINECONE_API_KEY — that metadata mismatch is an incoherence you should resolve before trusting the skill.

Instruction Scope

Runtime instructions (SKILL.md) explicitly tell the agent to run node tools/pinecone-memory.mjs with paths like MEMORY.md and 'memory' (a directory). The tool will read arbitrary markdown files under given paths, write a local state file (.pinecone-memory-state.json), write backup JSONL files, and can perform destructive operations (cleanup). Reading local files is expected for a memory-sync tool, but that means the skill will process any files in the supplied paths — if those contain secrets the tool may see them (it tries to redact API keys/tokens/passwords, but redaction is heuristic). The instructions are prescriptive (explicit commands) but grant broad file-read scope via default paths and recursive directory walk; that increases risk if the agent or user accidentally points it to sensitive locations.

Install Mechanism

Registry shows no install spec (instruction-only), which is lower risk for automatic writes. But the package.json declares a dependency on @pinecone-database/pinecone and Node.js is required; the README/SETUP instructs running npm install. That means installing this skill in practice will fetch an npm package from the public registry — a moderate-risk action (normal for such a tool). There is no remote arbitrary archive download or obscure URL usage in the files provided.

Credentials

The SKILL.md metadata and code require PINECONE_API_KEY (primary credential) and the code uses it to construct a Pinecone client. That is proportionate to the described purpose. However the registry metadata supplied with the skill bundle incorrectly lists no required env vars — this discrepancy is important to surface: the skill will fail without PINECONE_API_KEY and you should not rely on the registry's empty 'required env' claim. No other secrets (AWS keys, DB creds) are requested in the files provided.

Persistence & Privilege

The skill is not always-enabled and does not request special platform-level privileges. It writes its own state file (.pinecone-memory-state.json), backup JSONL, and suggests cron/heartbeat jobs (user-run). It can perform destructive operations on the target Pinecone namespace (cleanup) which is expected for an index management tool but means you should avoid running cleanup in production namespaces/with production API keys without explicit confirmation.

What to consider before installing

What to check before installing and running this skill: - Metadata mismatch: the registry metadata claims no required env vars, but the SKILL.md and code require PINECONE_API_KEY and Node.js. Assume PINECONE_API_KEY is required until the registry entry is corrected. - Install safely: run npm install in an isolated environment if you need to install dependencies. Review package.json (it depends on @pinecone-database/pinecone) and prefer installing in a controlled environment (container, VM) first. - Test with non-production credentials: use a throwaway Pinecone API key and a non-production index/namespace when you first run check/sync/heartbeat/cleanup. - Inspect default paths: by default the tool reads MEMORY.md and recursively reads the 'memory' folder — ensure these paths don't include sensitive files. If you pass custom paths, validate them carefully. - Be careful with destructive commands: cleanup deletes namespace data; restore/write operations modify your index. Don’t run cleanup/restore against production namespaces without backups and explicit confirmation. - Local artifacts: the tool writes .pinecone-memory-state.json and JSONL backups. Ensure these files are stored securely (they may contain excerpts of your memories) and exclude them from public repos. - Review code if you need higher assurance: the included tools/pinecone-memory.mjs is readable; if you are not comfortable, have a developer audit network calls and confirm there are no hidden endpoints beyond the Pinecone SDK usage. If you want, I can: - Summarize the remainder of tools/pinecone-memory.mjs (file was truncated in the manifest) and look specifically for network calls or surprising behavior, or - Produce a short checklist/command sequence to safely try this skill in a sandboxed environment.

Pinecone Memory Skill

这个 skill 提供一个最小可运行的 Pinecone 记忆工具链：

• check：检查环境变量与索引可用性。
• sync：把本地 markdown 记忆切片后写入 Pinecone。
• query：按文本做语义检索（优先走 Integrated Embedding 搜索接口）。
• stats：查看索引和命名空间统计。
• heartbeat：写入探针并验证写入可见性，用于健康检查与定时巡检。
• cleanup：清理指定 namespace 的数据。
• backup / restore：本地 JSONL 备份与恢复。

本 skill 采用 Integrated Embedding 索引（记录里必须有 chunk_text），默认不手动传向量。

触发时机

• 用户说“把记忆同步到 Pinecone”。
• 用户说“查一下以前关于 X 的记忆”。
• 用户说“看下 Pinecone 是否正常 / 有多少数据”。

执行流程（必须按顺序）

1. 先跑环境检查：

node {baseDir}/tools/pinecone-memory.mjs check --index openclaw-memory

2. 再做同步：

node {baseDir}/tools/pinecone-memory.mjs sync --index openclaw-memory --namespace default --path MEMORY.md --path memory

默认开启增量同步（基于本地状态文件比对 source hash，仅写入变化文件）。

3. 再做查询验证：

node {baseDir}/tools/pinecone-memory.mjs query --index openclaw-memory --namespace default --text "用户偏好"

4. 最后看统计：

node {baseDir}/tools/pinecone-memory.mjs stats --index openclaw-memory --namespace default

5. 健康巡检（验证“真的写入”）：

node {baseDir}/tools/pinecone-memory.mjs heartbeat --index openclaw-memory --namespace default --write-probe true

6. 管理命令：

node {baseDir}/tools/pinecone-memory.mjs cleanup --index openclaw-memory --namespace default --confirm yes
node {baseDir}/tools/pinecone-memory.mjs backup --path MEMORY.md --path memory --output backup/pinecone-memory-backup.jsonl
node {baseDir}/tools/pinecone-memory.mjs restore --input backup/pinecone-memory-backup.jsonl --index openclaw-memory --namespace default --verify-write true

存储信息模型（必须覆盖）

1. 核心内容（向量主体）

• 文档/知识库分块、网页分块、书籍/报告/论文分块、代码片段与 API 文档。
• 写入字段：chunk_text（Integrated Embedding 主字段）。

2. 元数据（过滤与追溯）

• 来源：source、source_url。
• 时间：created_at、updated_at。
• 作者与部门：author、department。
• 标签与分类：tags、source_kind。
• 权限：acl_scope。
• 版本：doc_version。

3. 结构化知识块

• 记录类型通过 record_type 区分：core_content、qa_knowledge、summary、entity_relation、conversation_history、agent_action、external_knowledge、heartbeat。

4. 对话与交互历史

• 历史对话、Agent 行动日志可作为 record_type 写入同一索引，按 namespace 隔离。

5. 外部与实时信息

• API 返回摘要、用户临时上传文件解析文本可作为短时记忆写入，建议使用单独 namespace 并定期清理。

行为规则

1. 同步前先过滤明显敏感内容（如 API key、token、密码字段）。
2. 统一使用结构化 _id，格式为 source#chunk-<n>#<hash8>。
3. 命名空间默认 default，生产与测试必须分离。
4. 查询返回只保留高相关结果，默认 topK=5。
5. sync 默认开启写后可见性校验，输出 writeVerification。
6. sync 默认开启增量同步，状态保存在 .pinecone-memory-state.json。
7. 若 Pinecone SDK 方法不兼容，必须给出明确报错与降级建议，不可静默失败。

已知约束

• Integrated Embedding 场景下，写入记录必须包含 chunk_text。
• Pinecone 为最终一致性，写后立刻查询可能短暂不可见。
• 不同 SDK 版本方法可能不同，本 skill 已做能力探测与兼容分支。

目录约定

• 执行脚本：{baseDir}/tools/pinecone-memory.mjs
• 安装说明：{baseDir}/SETUP.md
• 使用反馈：{baseDir}/USAGE_FEEDBACK.md

官方参考

• https://docs.openclaw.ai/tools/skills
• https://docs.openclaw.ai/tools/creating-skills
• https://docs.openclaw.ai/tools/clawhub