使用说明

Cloudflare上的SHODH

版本2.0 -具有自然语言时态查询的AI驱动内存

当你切换设备时，你的人工智能的记忆不应该消失。

你在笔记本电脑上和克劳德一起工作。它会记住你的项目结构、编码风格和决策。然后你切换到手机，一切都消失了。你在解释同样的背景。 再一次。

Cloudflare上的SHODH解决了这个问题。 您的AI内存通过Cloudflare的边缘网络在您的所有设备上进行全局同步。全球范围内，相同的上下文始终可用，延迟<50ms。

内置于 SHODH记忆建筑by @瓦伦29ankuS

建筑

┌─────────────────────────────────────────────────┐
│              Cloudflare Edge                    │
│  ┌─────────────┐   ┌──────────┐   ┌──────────┐  │
│  │   Worker    │──▶│    D1    │   │Vectorize │  │
│  │  (API)      │   │(metadata)│   │(vectors) │  │
│  └──────┬──────┘   └──────────┘   └──────────┘  │
│         │                                       │
│         ▼                                       │
│  ┌─────────────┐                                │
│  │ Workers AI  │  (bge-small-en-v1.5 embeddings)│
│  └─────────────┘                                │
└─────────────────────────────────────────────────┘
          ▲
          │ HTTPS
          │
    ┌─────┴─────┐
    │  Devices  │  (laptop, phone, tablet...)
    └───────────┘

为什么多设备内存很重要

没有SHODH	有SHODH
❌ “你的技术栈是什么？”	✅ “我记得你在Prisma中使用Next.js”
❌ 切换设备时上下文丢失	✅ 笔记本电脑、手机、平板电脑上的上下文相同
❌ 每次重启后重新解释项目	✅ AI已经知道你的项目结构
❌ 记忆卡在一台机器上✅ 全局同步，任何地方<50ms

v2.0中的新增功能

🎯 自然语言时态查询 -65+英语和德语时态表达

“last week”，“last week”，“KW 49”，“since Monday”
语音听写支持：“KW eins”（数字字）
周范围：“从1千瓦到5千瓦”

🤖 AI总结 -获取你记忆的口头总结

非常适合Siri快捷键和Apple Watch
双语支持（德语/英语）

📅 日历周（KW）支持 -符合ISO 8601标准

德语：“KW 49”、“Kalenderwoche 3”
中文：“第52周”，“CW 49”

🎙️ 语音输入AI分类 -自动清理和标记

纠正听写错误
智能内存类型检测
自动生成相关标签

🔧 自定义时间戳 -历史导入的回溯记忆

🔌 Gemini客户支持 -适用于Claude和Gemini型号

运作原理

组件	技术	目的
Edge API	Cloudflare Workers	全球300多个城市的REST API
记忆存储	D1（SQLite）	内容、标签、时间戳
语义搜索	矢量化	按意义而不是关键字查找记忆
AI嵌入	工人AI	bge-small-en-v1.5（384个维度）
设备网桥	Node.js MCP	适用于Claude、Cursor和VS代码

文档

安装前:

📋 先决条件和要求 -开始前你需要什么
📚 安装指南 -完成分步设置
❓ 常见问题解答 -常见问题解答

如果你需要帮助:

🔧 故障排除 -常见问题和解决方案
🖥️ 多设备设置 -添加其他设备

发展与背景:

📖 发展历程 -我们是如何构建这个的
📝 更新日志 -版本历史

快速开始

首次设置？ 您只需部署一次Worker，然后随时添加设备。看完整指南.

快速设置（2分钟）

已经有一个Worker在运行了吗？ 添加此设备：

# Clone and setup
git clone https://github.com/YOUR_USER/shodh-cloudflare.git
cd shodh-cloudflare
./scripts/setup-client.sh

该脚本要求您提供Worker URL和API密钥，然后自动配置Claude Desktop。

需要先部署Worker吗？ 快速参考：

# 1. Create resources
wrangler d1 create shodh-memory
wrangler vectorize create shodh-vectors --dimensions=384 --metric=cosine

# 2. Deploy
cd worker && npm install && npm run deploy

# 3. Set API key
wrangler secret put API_KEY

📖 Detailed setup guide (first-time deployment, troubleshooting)

看完整的安装指南用于：

先决条件检查（Node.js 18+，Cloudflare帐户）
逐步进行带有验证的Worker部署
多设备设置说明
常见问题排查

客户端配置

该系统可以与支持以下功能的任何AI客户端集成模型上下文协议（MCP）或者可以用钩子和系统提示来定制其行为。

黑曜石融合

黑曜石Shodh同步插件 -使用分层文件夹组织（年/月）将Shodh记忆直接同步到黑曜石保管库中。可在黑曜石社区插件商店中找到。

克劳德桌面版

将以下内容添加到您的Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
窗户： %APPDATA%\Claude\claude_desktop_config.json
Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "shodh-cloudflare": {
      "command": "node",
      "args": ["/path/to/shodh-cloudflare/mcp-bridge/index.js"],
      "env": {
        "SHODH_CLOUDFLARE_URL": "https://your-worker-name.your-subdomain.workers.dev",
        "SHODH_CLOUDFLARE_API_KEY": "your-api-key"
      }
    }
  },
  "hooks": {
    "post_response": {
        "command": "/bin/bash",
        "args": ["/path/to/shodh-cloudflare/hooks/claude-code-ingest-smart.sh"]
    }
  }
}

编辑配置后：

重新启动克劳德桌面 （重要！）
MCP工具将可用 post_response 钩子会自动将有价值的对话保存到您的Shodh内存中。

Gemini CLI（或其他客户端）

对于Gemini或其他客户，您需要：

提供系统提示： 配置您的客户端以使用以下指令 skills/shodh-cloudflare/SKILL_GEMINI.md.此文件告诉Gemini模型如何使用可用的工具。
实施MCP桥接： 如果您的客户端支持MCP，请将其配置为连接到 mcp-bridge/index.js 服务器就像上面的Claude Desktop配置一样。
实施岗位响应挂钩： 要启用自动内存，请配置您的客户端以执行 hooks/gemini-code-ingest-smart.ps1 每次响应后的脚本。该脚本需要包含对话记录作为参数的JSON文件的路径。

Gemini客户端配置示例（假设）：

{
  "system_prompt_path": "/path/to/shodh-cloudflare/skills/SKILL_GEMINI.md",
  "mcp_servers": [
      { "name": "shodh-cloudflare", "command": ["node", "/path/to/shodh-cloudflare/mcp-bridge/index.js"] }
  ],
  "hooks": {
      "post_response": {
          "command": "pwsh",
          "args": ["/path/to/shodh-cloudflare/hooks/gemini-code-ingest-smart.ps1", "{transcript_path}"]
      }
  }
}

这是一个说明性的例子。实际实现取决于您特定的Gemini客户端的配置功能。

验证

安装后，验证一切正常：

自动验证（推荐）

cd shodh-cloudflare
./scripts/verify-installation.sh

这将测试：

✅ Node.js版本和npm
✅ 已安装MCP网桥依赖项
✅ Claude Desktop配置存在并且有效
✅ 工作URL可访问
✅ API认证工作

手动测试

在Claude Desktop中，尝试以下命令：

1. Show me my memory stats
   (Uses shodh-cloudflare:memory_stats)

2. Remember this: "Test memory for verification"
   (Uses shodh-cloudflare:remember)

3. Recall memories about "test"
   (Uses shodh-cloudflare:recall)

如果所有命令都有效，你就可以开始了！ 🎉

有问题吗？ 看故障排除指南.

API终点

符合 SHODH内存API规范（OpenAPI 3.1）。

端点	方法	描述
`/`	GET	健康检查（基本）
`/api/health`	GET	健康检查（详细）
`/api/remember`	POST	存储内存（具有语音输入的AI分类、自定义时间戳）
`/api/remember/batch`	POST	批量存储存储器（一次最多50个）
`/api/recall`	POST	语义搜索（质量提升、65+时间模式、范围查询、AI摘要）
`/api/recall/by-tags`	POST	基于标签的搜索
`/api/context`	POST	主动上下文浮出水面
`/api/memories`	GET	列出所有记忆
`/api/memories/:id`	GET	获取特定内存（支持ID前缀≥8个字符）
`/api/memories/:id`	PATCH	更新内存元数据（支持ID前缀）
`/api/memories/:id/reinforce`	POST	增强记忆（提高质量分数）
`/api/forget/:id`	DELETE	删除内存（支持ID前缀）
`/api/forget/by-tags`	POST	按标签删除
`/api/tags`	GET	列出所有标签
`/api/stats`	GET	内存统计信息
`/api/consolidate`	POST	触发内存整合
`/api/reindex`	POST	重新索引向量

MCP工具

配置后，这些工具在Claude中可用：

工具	说明
`remember`	使用元数据存储内存（支持自定义时间戳）
`batch_remember`	一次存储多个存储器（最多50个）
`recall`	语义搜索（质量提升，具有65种以上自然语言模式的时间范围查询）
`recall_by_tags`	基于标签的搜索
`proactive_context`	表面相关记忆
`list_memories`	列出所有回忆
`forget`	按ID删除（支持ID前缀≥8个字符）
`forget_by_tags`	按标签删除
`update_memory`	更新内存元数据（支持ID前缀）
`reinforce_memory`	强化重要记忆（提高质量分数）
`memory_stats`	获取统计数据
`context_summary`	最近的学习/决定
`consolidate`	触发内存整合

部署您自己的实例

首次部署Worker？ 查看完整安装指南-第1部分：Worker部署查看验证的详细步骤。

快速参考

# 1. Create D1 database
wrangler d1 create shodh-memory

# 2. Create Vectorize index
wrangler vectorize create shodh-vectors --dimensions=384 --metric=cosine

# 3. Configure wrangler.toml
cp worker/wrangler.toml.example worker/wrangler.toml
# Edit with your database ID

# 4. Initialize schema
cd worker
wrangler d1 execute shodh-memory --file=../schema.sql --remote

# 5. Set API key
wrangler secret put API_KEY

# 6. Deploy
npm install
npm run deploy

先决条件：Cloudflare帐户（免费层OK）、Node.js 18+、Wrangler CLI

有关Worker部署问题的疑难解答，请参阅故障排除-工作人员部署.

内存类型

Observation -一般性意见
Decision -作出的决定
Learning -学到的东西
Error -错误解决方案
Discovery -发现
Pattern -已识别的模式
Context -背景信息
Task -任务相关
Conversation -自动摄入对话

AI分类（语音输入）

当通过语音界面（Siri快捷键、Apple Watch）提交记忆时，Worker会自动：

纠正听写错误 -修复拼写、语法和识别错误
对内存类型进行分类 -确定这是学习、决策、任务等。
生成相关标签 -创建2-4个上下文标签

由...触发 source_type:

siri-shortcut -通过Siri的iOS快捷方式
siri-shortcut-ai -使用Apple Intelligence的iOS快捷方式
watch -Apple Watch语音输入

技术：

Cloudflare人工智能
型号： @cf/meta/llama-3.1-8b-instruct
JSON模式用于可靠的结构化输出

例子：

curl -X POST https://your-worker.workers.dev/api/remember \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"ich habe gelernt dass workars ai kostenlos ist","source_type":"siri-shortcut"}'

# Response includes:
# "ai_processed": true,
# "memory_type": "learning",
# "tags": ["learning", "cloudflare", "workers-ai"]
# Content corrected to: "Ich habe gelernt, dass Workers AI kostenlos ist"

注： AI分类仅对语音输入触发。常规API调用（MCP，直接）保留用户提供的类型和标记。

时态查询表达式

V2.0介绍 65+自然语言模式 用于按时间查询内存：

图案类别

基本关键词 （英语和德语）：

today / heute
yesterday / gestern
this week / diese woche

扩展模式:

last week / letzte woche
this month / diesen monat
last year / letztes jahr

灵活的N单元模式:

last 7 days / letzten 7 Tage
past 3 weeks / letzten 3 Wochen
vor 2 Monaten

工作日参考:

monday / montag （最近）
last friday / letzten freitag
seit dienstag

日历周（ISO 8601）:

德语： KW 49, KW 1 2024, Kalenderwoche 3
英语： week 52, week 1 2024, CW 49
语音听写： KW eins, week five

范围查询:

# Week ranges
{"from": "KW 1 2024", "to": "KW 5 2024"}

# Mixed ranges
{"from": "last month", "to": "yesterday"}

# Alias support
{"since": "monday", "until": "today"}

传统格式:

7d, 30d （N天前）
ISO日期字符串

所有图案都是 不区分大小写 并在两者中工作 英语和德语.

人工智能摘要（语音回忆）

这 /api/recall 端点支持基于AI的语音界面摘要：

参数：

summarize: true -启用搜索结果的AI摘要
language: "de" | "en" -摘要语言（默认：德语）
since: string -时间过滤器（支持65+种自然语言模式）
from / to -使用时态表达式的范围查询
before / until -上限过滤器

示例（Siri快捷方式用例）：

curl -X POST https://your-worker.workers.dev/api/recall \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"was habe ich heute gemacht","summarize":true,"since":"today","language":"de"}'

# Response includes:
# "summary": "Heute hast du an der Cloudflare Worker Integration gearbeitet...",
# "summarized": true,
# "since": "today",
# "since_parsed": "2026-01-31T00:00:00.000Z"

如何使用时间过滤器：

从D1数据库中按日期筛选记忆（最多50个候选）
根据查询的语义相似性对过滤后的记忆进行排名
人工智能总结了自然语言的最佳结果

OpenAPI规范合规性

此实施遵循 SHODH内存API规范v1.0.0，确保整个SHODH生态系统的兼容性。

✅ 完全符合要求的端点：

POST /api/remember -使用完整的元数据支持存储内存
POST /api/recall -基于向量嵌入的语义搜索
POST /api/recall/by-tags -基于标签的内存检索
POST /api/context -主动式上下文呈现
DELETE /api/forget/{id} -删除特定内存
POST /api/forget/by-tags -按标签批量删除
GET /api/memories -列出所有带分页的内存
GET /api/memory/{id} -获取特定内存
POST /api/consolidate -Hebbian联想的记忆巩固
GET /api/stats -内存统计
GET /api/tags -列出所有唯一标签

架构合规性： 支持规范中的所有统一字段：

核心: content, content_hash, type, tags
来源与信任: source_type, credibility
情感元数据: emotion, emotional_valence, emotional_arousal
情节记忆: episode_id, sequence_number, preceding_memory_id
质量与准入: quality_score, access_count, last_accessed_at

有关API的完整文档，请参阅 specs/openapi.yaml.

从v1.x迁移到v2.0

重大变更

无 -v2.0与v1.x API调用完全向后兼容。

建议的更新

MCP电桥 -更新依赖关系：
```
cd mcp-bridge
npm install
```
这将MCP SDK从1.0.0升级到>=1.8.0，以支持工具注释。
新功能 （选择加入）：
- 时态查询：使用增强型 since 自然语言参数
- AI总结：添加 summarize: true 到 /api/recall 电话
- 自定义时间戳：指定 created_at 创建记忆时
- 范围查询：使用 from/to 用于日期范围
无需重新部署工人 -API向后兼容

用户获得什么

更丰富的时态查询：“上周”而不是计算日期
语音友好：自然语言与Siri/听写配合使用
更好的语音回忆：人工智能口头回复摘要
历史数据：带有自定义时间戳的回溯记忆

致谢

该项目的灵感来自并兼容 SHODH记忆通过 @瓦伦29ankuS.SHODH对人工智能记忆的创新方法——包括情感元数据、情节结构和Hebbian风格的关联——为这种边缘实现提供了基础。

看 JOURNEY.md 从我们的开发过程中获得详细的见解。

获取帮助

文档

📋 先决条件和要求 -开始之前
📚 安装指南 -逐步设置
🔧 故障排除 -常见问题和解决方案
❓ 常见问题解答 -常见问题解答
🖥️ 多设备设置 -添加更多设备

快速检查

安装正确吗？

./scripts/verify-installation.sh

工人没有回应？

curl https://your-worker.your-subdomain.workers.dev/
# Should return: {"message":"SHODH Memory API is running"}

Claude Desktop看不到MCP工具？

检查操作系统的配置文件位置
重新启动克劳德桌面
看故障排除-MCP桥未启动

支持

错误报告: GitHub 问题
问题：检查常见问题解答第一
讨论：GitHub讨论

许可证

麻省理工学院