docs: add search_filter + tags scoping guide and deployment/scaling notes (#386, follow-up to #402)

[RerankerGuo]

背景

代码已经在之前的两个 PR 中落地：

• feat(search): add containment-style tags filter for multi-user scoping (#368) #402 实现了 search_filter["tags"] containment-style AND filter 的完整代码逻辑 + 单元测试
• feat: support horizontal scaling / cluster deployment for production #386 中 maintainer 明确给出了 horizontal scaling 的官方立场声明

但目前用户/插件作者缺少一份结构化的使用说明：

1. Search filters 完整 API 文档缺失 — search_filter 是 ReMe 最核心的搜索过滤接口，包含 6 个 key，但 memory_search.md 只讲了打分逻辑，没有任何 filter 文档，导致用户只能看源码或 Issue 评论才能正确使用。
2. Tags scoping 实战指南缺失 — feat(search): add containment-style tags filter for multi-user scoping (#368) #402 的代码和测试都在，但缺少一份「写时 + 读时」的端到端 walk-through 示例，用户不知道 tags filter 是 AND 还是 OR，是否支持 CSV，如何在 MCP/HTTP 调用中传参数。
3. Scaling 立场声明散落在 Issue — feat: support horizontal scaling / cluster deployment for production #386 的评论里有 maintainer 的官方声明 + 设计原则约束，但新用户/新贡献者看不到这份声明，会不断重复提 scaling Issue 或 PR，浪费 maintainer 精力。

改动内容

1. docs/en/memory_search.md — 新增 Search Filters 章节（接 #402）

在原文末尾追加约 80 行文档：

• Search Filters (search_filter)：整体介绍 + YAML 示例
• Available filters 表格：列出 6 个 key (path/paths/prefix/date/metadata/tags)，逐一说明类型和语义
• Multi-user / multi-profile scoping with tags：端到端实战指南
  • 写时 frontmatter 示例 (tags: [user:alice, conv:xxx])
  • CLI 调用示例 (dot-notation 参数展开)
  • MCP/HTTP search 工具 JSON body 示例
  • 4 条语义规则（AND containment / CSV 支持 / scalar 兼容 / untagged 默认可见）
• 与现有插件家族关联：明确说明 Claude Code / Codex / OpenClaw / QwenPaw / Hermes Agent 的作者应使用此模式做 profile 隔离

2. docs/en/deployments_and_scaling.md — 新建部署与横向扩展指南（接 #386）

全新文档页，约 250 行，结构清晰分 6 节：

• Design Principles — Non-Negotiable：重申 Memory as File 两大不变式（文件是 source of truth / 文件可读可 diff 可 merge）
• Current Default Deployment：单进程单机拓扑 ASCII 图 + 启动命令
• Official Position on Horizontal Scaling：原文引用 maintainer 在 feat: support horizontal scaling / cluster deployment for production #386 中的官方立场声明 — "不在 maintainer roadmap，但欢迎社区贡献" + 不变式约束，使后续贡献者有稳定参考
• If You Want Multi-User Isolation Before Multi-Replica：3 种低运维成本方案
  • Option A: 每用户独立 workspace + 独立进程
  • Option B: 共享 workspace + tags scoping（与 feat(search): add containment-style tags filter for multi-user scoping (#368) #402 互文引用）
  • Option C: 混合方案（共享 digest + 私有 daily + tags）
• Community Backend Contributions 贡献指南：对想写 scalable backend 的社区贡献者给出 5 条硬性要求（明确边界 / 提供 rebuild CLI / 保持单进程默认 / Hydra 配置 / 先设计讨论）
• Failure Modes to Avoid：6 种 ReMe 特有的 scaling 坑点及原因表格（只写外部索引不写文件 / auto_memory 双写 / NFS 多写者 / SIGKILL 截断 / embedding namespace 泄露等）

验证方式

1. Pre-commit：pre_commit run --files docs/en/memory_search.md docs/en/deployments_and_scaling.md → 12/12 hooks 通过（trim-whitespace、private-key、pyroma 等）。
2. Unit tests 回归检查：pytest tests/unit -x -q → 858 passed，零回归（docs 改动不影响运行时）。
3. Markdown 可读性人工核对：
   • 表格列对齐、代码块标注语言正确 (yaml/json/markdown/bash/text)
   • 交叉引用链接有效（memory_search.md#search-filters、feat: support horizontal scaling / cluster deployment for production #386、各 sibling plugin 名）
   • ASCII 部署拓扑图列对齐无越界

影响范围

• 纯文档，零代码改动。不影响 ReMe 任何运行时行为、CI、测试套件。
• memory_search.md 是 ReMe 核心文档页之一，追加章节后读者可以原地理解 search_filters，无需跳转到源码。
• deployments_and_scaling.md 是全新文档页，后续可在 quick_start.md 的 "进一步阅读" 或框架总览中添加链接（本轮暂不加，避免大范围修改引起额外 review 负担 — 后续单独 tiny PR 跟进即可）。

Checklist

• 与 feat(search): add containment-style tags filter for multi-user scoping (#368) #402 的代码语义严格一致（AND containment / CSV / scalar 兼容 / untagged 默认可见）
• 逐字引用 maintainer 在 feat: support horizontal scaling / cluster deployment for production #386 中的官方立场声明，不添加主观推断
• 提供 3 种 user-isolation 方案的 Pros/Cons，不让读者猜测哪种适合自己
• Failure Modes 表格每条都解释 "为什么违反 invariant"，而不只是列风险
• 明确声明 "community components welcome" 但给出前置条件（pre-PR 设计讨论等），避免后续 PR 被拒造成 contributor 沮丧
• 858 个单元测试全通过，零回归

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.