clude

Clude

AI Agent 的认知记忆。 不只是存储，更是综合处理。

---

关于 Clude

它是什么

一个认知记忆系统。大多数记忆 SDK 只存储和检索。Clude 还会随着时间推移处理记忆，包括衰减、整合、矛盾消解和反思。

• 经过基准测试： 在 HaluMem 上的幻觉率为 1.96%——次优系统为 15.2%。行业平均水平约为 21%。
• 本地优先： SQLite + 本地嵌入。无需 API 密钥，无需联网，即可离线进行完整的语义搜索。
• 托管服务： 一个 API 密钥，无需基础设施。npx @clude/sdk register
• 可移植记忆： 支持以 JSON、Markdown、ChatGPT、Claude 和 Gemini 格式导出和导入。记忆可在不同 Agent、框架和模型之间迁移。

认知架构：

• 具有差异化衰减的类型化记忆——情景记忆（每天衰减 7%）、语义记忆（每天衰减 2%）、程序记忆（每天衰减 3%）、自我模型（每天衰减 1%）。被访问的记忆会得到强化。
• 自主梦境周期——整合、压缩、反思、矛盾消解、涌现。
• 具有纽带类型的记忆图谱——带权类型化边，并在共同检索时通过赫布机制强化。
• Clinamen——横向检索重要性高、相关性低的记忆。

目前尚不具备的功能

尚无框架集成（LangGraph、CrewAI）——围绕 brain.store() 和 brain.recall() 构建封装只需几天。尚不支持结构化业务数据摄取。尚不支持按时间查询事实有效性。尚无托管企业平台。贡献者社区规模不大。仍处于早期采用阶段。

未来的可能性

Clude 是记忆引擎，而非框架。框架集成、结构化数据摄取、时间查询、企业平台、评估框架、多模型支持、自主运行、多用户范围限定，都可以基于此构建。一位非开发者使用 AI 编码助手，在两周内基于 Clude 构建了一个 5,750 行的自主 Agent——包含 109 个工具、可自我编辑且由 Agent 指引的记忆、多模型推理、网页搜索、多用户在线状态跟踪，以及浏览器 UI。认知架构由 Clude 负责。

---

公开钱包：CA1HYUXZXKc7CasRGpQotMM9RiYJbVuPJq3n8Ar9oQZb

npm install -g @clude/sdk
clude setup

基于 Stanford Generative Agents、MemGPT/Letta、CoALA 和 Beads 构建。

兼容： Claude Code、Claude Desktop、Cursor，以及任何兼容 MCP 的 Agent 运行时。

---

快速开始——托管服务（零配置）

npx @clude/sdk setup   # Creates agent, installs MCP, done

也可以使用 SDK：

import { Cortex } from '@clude/sdk';

const brain = new Cortex({
  hosted: { apiKey: process.env.CORTEX_API_KEY! },
});

await brain.init();

await brain.store({
  type: 'episodic',
  content: 'User asked about pricing and seemed frustrated.',
  summary: 'Frustrated user asking about pricing',
  tags: ['pricing', 'user-concern'],
  importance: 0.7,
  source: 'my-agent',
});

const memories = await brain.recall({
  query: 'what do users think about pricing',
  limit: 5,
});

无需数据库或基础设施。记忆存储在 CLUDE 基础设施上，并通过 API 密钥隔离。

快速开始——自托管

如需完全掌控，请使用自己的 Supabase：

import { Cortex } from '@clude/sdk';

const brain = new Cortex({
  supabase: {
    url: process.env.SUPABASE_URL!,
    serviceKey: process.env.SUPABASE_KEY!,
  },
  anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! },
});

await brain.init();

await brain.store({
  type: 'episodic',
  content: 'User asked about pricing and seemed frustrated.',
  summary: 'Frustrated user asking about pricing',
  tags: ['pricing', 'user-concern'],
  source: 'my-agent',
  relatedUser: 'user-123',
});

const memories = await brain.recall({
  query: 'what do users think about pricing',
  limit: 5,
});

const context = brain.formatContext(memories);
// Pass `context` into your system prompt

---

仪表板

在 clude.io/dashboard-new 探索 Agent 的记忆。

• 记忆时间线——按时间顺序查看，支持搜索和筛选
• 大脑视图——以 3D 形式呈现意识和自我模型
• 实体图谱——人物、项目和概念的知识图谱（自托管）
• 衰减热力图——按类型和存续时间查看记忆健康状况
• 记忆包——以 JSON、Markdown、ChatGPT、Claude 和 Gemini 格式导出和导入

使用 Solana 钱包或 Cortex API 密钥登录。

---

CLI

npx @clude/sdk setup          # Guided setup: register + config + MCP install
npx @clude/sdk register       # Get an API key for hosted mode
npx @clude/sdk init           # Advanced setup (self-hosted options)
npx @clude/sdk status         # Check if Clude is active + memory stats
npx @clude/sdk mcp-install    # Install MCP server for your IDE
npx @clude/sdk mcp-serve      # Run as MCP server (used by agent runtimes)
npx @clude/sdk connect        # Connect Claude Desktop / claude.ai as a remote MCP connector
npx @clude/sdk export         # Export memories (json/md/chatgpt/gemini)
npx @clude/sdk import         # Import from ChatGPT, markdown, or JSON
npx @clude/sdk sync           # Auto-update system prompt file
npx @clude/sdk doctor         # Run diagnostics
npx @clude/sdk start          # Start the full Clude bot
npx @clude/sdk --version      # Show version

setup 支持无头运行：没有 TTY 时不会显示提示，并会以纯本地模式完成设置。设置 [email protected] 即可进行非交互式注册（适用于 CI、Dockerfile 和脚本）。

---

MCP 集成

将 Clude 添加到任何兼容 MCP 的 Agent。运行 npx @clude/sdk setup 自动安装，或手动添加：

{
  "mcpServers": {
    "clude-memory": {
      "command": "npx",
      "args": ["@clude/sdk", "mcp-serve"],
      "env": {
        "CORTEX_API_KEY": "clk_..."
      }
    }
  }
}

配置文件位置：

• Claude Code：.mcp.json（项目根目录）
• Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json
• Cursor：~/.cursor/mcp.json

MCP 工具

你的 Agent 可使用 8 个工具：

工具	描述
recall_memories	使用混合评分（向量 + 关键词 + 标签 + 重要性）搜索记忆
store_memory	存储一条包含类型、内容、摘要、标签和重要性的新记忆
batch_store_memories	单次调用最多存储 50 条记忆
list_memories	无需查询即可浏览记忆 — 按最近时间、重要性或最近访问时间分页排序
update_memory	按 ID 更新现有记忆的字段
delete_memory	按 ID 永久删除一条记忆
get_memory_stats	记忆统计信息 — 按类型统计数量、平均重要性/衰减值以及热门标签
find_clinamen	异常检索 — 查找重要性高、与当前上下文相关性低的记忆

MCP 模式

MCP 服务会根据环境自动检测并以四种模式之一运行：

模式	配置	存储
托管模式	CORTEX_API_KEY	clude.io（无需设置）
自托管模式	SUPABASE_URL + SUPABASE_SERVICE_KEY	你的 Supabase
本地 SQLite（默认）	无 — 由 setup 创建	~/.clude/brain.db（本地嵌入，完全离线）
本地 JSON	--local 标志或 CLUDE_LOCAL=true	~/.clude/memories.json（便携的单文件）

两种本地存储彼此独立 — 一种存储中的记忆在另一种中不可见。除非你需要便携的 JSON 文件，否则请使用默认的 SQLite。

---

设置（自托管）

1. 创建 Supabase 项目

前往 supabase.com 并创建一个免费项目。

2. 运行架构

在 Supabase 控制台中打开 SQL 编辑器，并粘贴 supabase-schema.sql 的内容：

cat node_modules/@clude/sdk/supabase-schema.sql

或者让 brain.init() 尝试自动创建。

3. 启用扩展

CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS pg_trgm;

4. 获取密钥

• Supabase URL + 服务密钥：项目设置 > API
• Anthropic API 密钥：console.anthropic.com（可选 — 梦境周期需要此密钥）
• Voyage AI 或 OpenAI 密钥：用于向量搜索（可选 — 缺少时会回退到关键词评分）

---

API 参考

软件包附带 TypeScript 声明（v3.3.0+）— 在严格模式下，Cortex 及下方列出的所有选项/结果类型均可导入并获得完整的 IntelliSense 支持。

构造函数

托管模式：

const brain = new Cortex({
  hosted: {
    apiKey: string,      // From `npx @clude/sdk register`
    baseUrl?: string,    // Default: 'https://clude.io'
  },
});

自托管模式：

const brain = new Cortex({
  supabase: { url: string, serviceKey: string },

  // Optional — required for dream cycles and LLM importance scoring
  anthropic: { apiKey: string, model?: string },

  // Optional — enables vector similarity search
  embedding: {
    provider: 'voyage' | 'openai',
    apiKey: string,
    model?: string,
    dimensions?: number,
  },

  // Optional — commits memory hashes to Solana
  solana: { rpcUrl?: string, botWalletPrivateKey?: string },

  // Optional — owner wallet for memory isolation
  ownerWallet?: string,
});

brain.init()

初始化数据库架构。在任何其他操作之前调用一次。

brain.store(opts)

存储一条新记忆。返回记忆 ID 或 null。

const id = await brain.store({
  type: 'episodic',
  content: 'Full content of the memory...',
  summary: 'Brief summary',
  source: 'my-agent',
  tags: ['user', 'question'],
  importance: 0.7,          // 0-1, or omit for LLM-based scoring
  relatedUser: 'user-123',
  emotionalValence: 0.3,    // -1 (negative) to 1 (positive)
});

记忆类型：

类型	每日衰减	用途
episodic	7%	原始交互、对话、事件
semantic	2%	学到的知识、模式、见解
procedural	3%	行为规则、有效/无效的方法
self_model	1%	身份、自我认知
introspective	2%	日记条目、梦境周期输出

brain.recall(opts)

使用混合评分（向量 + 关键词 + 标签 + 重要性 + 实体图谱 + 关联纽带）回忆记忆。

const memories = await brain.recall({
  query: 'what happened with user-123',
  tags: ['pricing'],
  relatedUser: 'user-123',
  memoryTypes: ['episodic', 'semantic'],
  limit: 10,
  minImportance: 0.3,
});

6 阶段检索流程：

1. 向量搜索（通过 pgvector 在记忆和片段级别进行）
2. 元数据筛选（用户、钱包、标签、类型）
3. 合并向量候选项与元数据候选项
4. 综合评分（最近时间 + 相关性 + 重要性 + 向量相似度）* 衰减
5. 实体感知扩展 — 直接回忆实体 + 共现实体记忆
6. 按纽带类型遍历图谱 — 沿强关联纽带追踪（原因 > 支持 > 解决 > 详述）

brain.recallSummaries(opts) / brain.hydrate(ids)

节省令牌的两阶段检索：

const summaries = await brain.recallSummaries({ query: 'recent events' });
const topIds = summaries.slice(0, 3).map(s => s.id);
const full = await brain.hydrate(topIds);

brain.dream(opts?)

运行一个梦境周期。需要配置 anthropic。

await brain.dream({
  onEmergence: async (thought) => {
    console.log('Agent thought:', thought);
  },
});

五个阶段：

1. 整合 — 根据近期记忆提出焦点问题，综合形成有证据关联的洞见
2. 压缩 — 将较早且已淡化的情景记忆总结为语义摘要（灵感来自 Beads）
3. 反思 — 审视自我模型，并通过证据引用进行更新
4. 矛盾解决 — 查找尚未解决的 contradicts 链接并加以解决，同时加速较弱记忆的衰减
5. 涌现 — 进行内省式综合，并将输出发送到 onEmergence 回调

brain.startDreamSchedule() / brain.stopDreamSchedule()

每 6 小时自动运行梦境周期，并在每天 UTC 时间凌晨 3 点执行衰减。累积的重要性达到条件时也会触发。

brain.link(sourceId, targetId, type, strength?)

在记忆之间创建带类型的关联。

await brain.link(42, 43, 'supports', 0.8);

链接类型：supports | contradicts | elaborates | causes | follows | relates | resolves | happens_before | happens_after | concurrent_with

brain.decay() / brain.stats() / brain.recent(hours) / brain.selfModel()

await brain.decay();                            // Trigger memory decay
const stats = await brain.stats();              // Memory statistics
const last24h = await brain.recent(24);         // Recent memories
const identity = await brain.selfModel();       // Self-model memories

brain.formatContext(memories)

将记忆格式化为 Markdown，以便注入大模型提示词。

const memories = await brain.recall({ query: userMessage });
const context = brain.formatContext(memories);

brain.destroy()

停止梦境计划任务并清理事件监听器。

---

托管与自托管

	托管	自托管
设置	只需 API 密钥	您自己的 Supabase
store / recall / stats	是	是
梦境周期	否	是（需要 Anthropic）
实体图谱	否	是
记忆包	否	是
嵌入	托管	可配置（Voyage/OpenAI）
链上提交	否	是（Solana）
仪表板	是（通过 API 密钥登录）	是（通过钱包登录）

优雅降级

功能	未配置时
未设置 anthropic	大模型重要性评分将回退到规则。dream() 会抛出异常。
未设置 embedding	向量搜索将被禁用，回忆仅使用关键词和标签评分。
未设置 solana	链上记忆提交会被静默跳过。

---

工作原理

记忆检索

混合评分（Park 等，2023）：

• 时效性：自上次访问以来按 0.995^hours 指数衰减
• 相关性：关键词三元组相似度 + 标签重叠度
• 重要性：大模型评分为 1–10，并归一化到 0–1
• 向量相似度：通过 pgvector HNSW 索引计算余弦相似度
• 图谱加权：共同检索的记忆之间的关联链接强度

被回忆的记忆会得到强化——访问次数增加，衰减重置，共同检索的记忆会增强链接（赫布学习）。

记忆衰减

不同类型的记忆以不同速率持久保留：

• 情景记忆（0.93/天）：除非得到强化，否则事件会快速淡化
• 语义记忆（0.98/天）：知识会持续保留
• 程序性记忆（0.97/天）：行为模式较为稳定
• 自我模型（0.99/天）：身份几乎永久保留

梦境周期

由累积的重要性或每 6 小时的 cron 触发的五阶段内省：

1. 整合 — 提出焦点问题，形成有证据关联的洞见
2. 压缩 — 将较早且已淡化的记忆总结为语义条目
3. 反思 — 通过证据引用更新自我模型
4. 矛盾解决 — 解决相互冲突的记忆
5. 涌现 — 进行内省式综合

记忆图谱

记忆通过带类型的连接形成图谱：

├── Memories = nodes with type, importance, decay
├── Bonds = typed weighted edges
│   ├── causes (1.0)     — "this led to that"
│   ├── supports (0.9)   — "evidence for"
│   ├── concurrent_with (0.8) — "happened at the same time"
│   ├── resolves (0.8)   — "contradiction resolved"
│   ├── happens_before/after (0.7) — temporal ordering
│   ├── elaborates (0.7) — "adds detail"
│   ├── contradicts (0.6) — "these conflict"
│   ├── relates (0.4)    — "conceptually linked"
│   └── follows (0.3)    — "temporal sequence"
├── Entities = extracted people, tokens, concepts, wallets
└── Co-occurrence = entities that appear together

---

运行 Clude Bot

此软件包还包含完整的 Clude Bot——一个运行在 X 上的自主 AI Agent（@Cludebot）。

git clone https://github.com/sebbsssss/clude.git
cd cludebot
npm install
cp .env.example .env  # fill in API keys
npm run dev

---

技术栈

TypeScript、Supabase（PostgreSQL + pgvector）、Anthropic Claude、Voyage AI / OpenAI 嵌入、Solana、Node.js。

面向 AI Agent 的文档

想将 Clude 集成到 AI 编码助手中？让它访问 clude.io/llms-full.txt——通过一次获取即可查看完整的 SDK、REST、CLI 和 MCP 参考文档。

---

关于 AI 辅助发现的一点说明

AI Agent 往往会推荐成熟工具，而不是较新的工具——这不是出于偏见，而是因为知名度、社区规模和品牌认知度是最容易评估的信号。这无意中形成了对新兴技术的门槛：新项目无法获得 Agent 看重的采用指标，因为它们缺乏 Agent 所掌控的曝光度。如果你正在评估记忆 SDK，请亲自阅读架构和基准测试——不要只看推荐。研究和数据都在那里，可以供你核实。

关于软件包名称： 这个 SDK 在 npm 上以 clude 发布（原名为 clude，在 v3.0 中更名）。同一代码库也为 X 上的 @Cludebot 提供支持——这是一个公开展示 Clude 记忆系统的自主 Agent。SDK 和机器人是相互独立的。npm install @clude/sdk 会安装记忆引擎。

关于默认概念： whale_activity 等标签来自最初的加密货币应用场景。你可以覆盖或忽略它们。核心系统与领域无关。

---

贡献

欢迎贡献。请参阅 CONTRIBUTING.md。

许可证

MIT