pattern (Loominal)

模式

MCP服务器为AI代理提供分层内存。

  

贝塔：核心功能测试稳定。部分 Loominal 多代理基础设施。

概述

Pattern是一个模型上下文协议（MCP）服务器，为AI代理提供分层内存功能。它使代理人能够：

• 记住 会话间的信息自动过期
• 分享 与同一项目中的其他代理一起学习
• 召回 会话启动时高效的上下文
• 隔离 基于项目和代理的安全记忆
• 统一身份 使用Warp进行一致的试剂识别

代理身份

Pattern v0.2.0与Warp的统一身份系统集成。Pattern不是生成临时ID，而是从Warp的NATS KV存储中读取代理身份。

运作原理

1. Warp初始化身份 启动时，将其储存在NATS KV桶中 loom-identity-{projectId}
2. 模式加载标识 具有重试逻辑（10次尝试，总等待时间约为5.5秒）
3. 同样的特工，同样的记忆：重新启动Claude Code，您的记忆将继续存在

多机器场景

对于在应共享相同身份和内存的多台机器上运行的代理，请设置 LOOMINAL_AGENT_ID 在Warp的配置中，覆盖自动ID推导。

子代理内存访问

子代理（由专门任务的根代理生成）可以访问其父代理的内存：

快速开始

先决条件

• Node.js>=18.0.0
• 启用JetStream的NATS服务器

安装

npm install @loominal/pattern

或者直接运行：

npx @loominal/pattern

配置

设置环境变量：

export NATS_URL="nats://localhost:4222"         # NATS server URL
export LOOMINAL_PROJECT_ID="my-project"         # Project isolation key (optional, derived from path)
export LOOMINAL_SUBAGENT_TYPE="specialized"     # Set by parent agent when spawning sub-agents
export DEBUG="true"                             # Enable debug logging (optional)

跑步

# Start the MCP server
pattern

# Or with npm
npm start

Claude代码集成

添加到您的Claude Code MCP设置中(~/.claude/settings.json):

{
  "mcpServers": {
    "pattern": {
      "command": "npx",
      "args": ["@loominal/pattern"],
      "env": {
        "NATS_URL": "nats://localhost:4222",
        "LOOMINAL_PROJECT_ID": "my-project"
      }
    }
  }
}

内存模型

统一范围系统

模式使用一个4值范围系统来确定可见性和存储位置：

私人/个人类别（特定于代理人）

团队/公共类别（共享）

MCP工具

remember

存储具有指定范围和类别的新内存。

{
  "content": "The API uses REST with JSON responses",
  "scope": "private",  // "private" | "personal" | "team" | "public"
  "category": "longterm",
  "metadata": {
    "tags": ["api", "architecture"],
    "priority": 1
  }
}

安全说明 （v0.3.1+）：扫描内容以查找常见的秘密模式（API密钥、密码等），如果检测到，将发出警告。切勿直接存储凭据。看 安全最佳实践.

remember-task

快速速记以记住任务（私人，24小时TTL）。

{
  "content": "Fix the authentication bug in login.ts"
}

remember-learning

快速速记以记住学习（私人，24小时TTL）。

{
  "content": "The database uses PostgreSQL with pgvector"
}

commit-insight

将临时内存升级为永久存储。

{
  "memoryId": "550e8400-e29b-41d4-a716-446655440000",
  "newContent": "Updated insight with more details"
}

core-memory

使用以下方式存储身份定义内存 personal 范围（跨项目跟踪用户，每个代理最多100个）。

{
  "content": "I am a coding assistant that prioritizes test coverage"
}

安全说明：核心记忆使用 personal 在所有项目中确定范围并跟随代理。切勿将项目特定的秘密存储在核心记忆中。子代理无法访问父核心内存以获得额外保护。

forget

按ID删除内存。

{
  "memoryId": "550e8400-e29b-41d4-a716-446655440000",
  "force": true  // Required for core memories
}

recall-context

在会话开始时检索内存上下文，具有强大的过滤和搜索功能。

基本参数：

{
  "scopes": ["private", "personal", "team"],  // Filter by scope
  "categories": ["core", "longterm", "decisions"],  // Filter by category
  "limit": 50,  // Max memories to return (default: 50, max: 200)
  "since": "2025-01-01T00:00:00Z"  // Only memories updated after this
}

高级过滤（v0.4.0+）：

{
  // Tag filtering (AND logic - memory must have all tags)
  "tags": ["api", "documentation"],

  // Priority filtering (1=high, 2=medium, 3=low)
  "minPriority": 1,  // Minimum priority
  "maxPriority": 2,  // Maximum priority

  // Date range filtering
  "createdAfter": "2025-01-01T00:00:00Z",   // Created after this date
  "createdBefore": "2025-01-31T00:00:00Z",  // Created before this date
  "updatedAfter": "2025-01-15T00:00:00Z",   // Updated after this date
  "updatedBefore": "2025-01-31T00:00:00Z",  // Updated before this date

  // Content search (case-insensitive)
  "search": "authentication"
}

示例：

查找本月创建的高优先级API文档：

{
  "tags": ["api", "docs"],
  "maxPriority": 1,
  "createdAfter": "2025-01-01T00:00:00Z",
  "search": "REST"
}

查找最近的架构决策：

{
  "scopes": ["team"],
  "categories": ["architecture", "decisions"],
  "updatedAfter": "2025-01-01T00:00:00Z"
}

退货：

{
  "private": [...],
  "personal": [...],
  "team": [...],
  "public": [...],
  "summary": "Key points from your memories...",
  "counts": {
    "private": 25,
    "personal": 5,
    "team": 10,
    "public": 0,
    "expired": 5
  }
}

过滤逻辑：

• 所有过滤器都作为AND条件应用（存储器必须与所有指定的过滤器匹配）
• 标签过滤使用AND逻辑（内存必须具有所有指定的标签）
• 没有优先级元数据的内存默认为优先级2（中等）
• 空的或未指定的过滤器被忽略（例如。， tags: [] 返回所有记忆）

share-learning

与所有项目代理共享私人/个人记忆（移至 team 范围）。

{
  "memoryId": "550e8400-e29b-41d4-a716-446655440000",
  "category": "learnings",
  "keepOriginal": false
}

安全说明：共享使内存对可见 项目中的所有代理。在共享之前，请查看内容中的敏感信息。一旦共享到团队范围，就不能取消共享（只能删除）。

cleanup

运行维护任务以使TTL内存过期并强制执行限制。

{
  "expireOnly": false
}

export-memories

将内存导出到JSON文件进行备份或传输。支持按范围、类别和日期范围进行筛选。

{
  "outputPath": "/path/to/backup.json",  // Optional, defaults to memories-backup-TIMESTAMP.json
  "scope": "private",                    // Optional: "private" | "personal" | "team" | "public"
  "category": "longterm",                 // Optional: filter by category
  "since": "2025-01-01T00:00:00Z",       // Optional: only export memories updated after this
  "includeExpired": false                 // Optional: include expired memories (default: false)
}

退货：

{
  "exported": 42,
  "filepath": "/absolute/path/to/backup.json",
  "bytes": 8192
}

用例:

• 在进行重大更改之前创建备份
• 导出特定类别以供共享或存档
• 在代理或项目之间转移记忆
• 使用导出最近的更改 since 参数

安全说明：导出的文件是未加密的JSON。安全地存储备份，并在共享前查看内容。切勿将包含敏感信息的备份文件提交给版本控制。

import-memories

从由创建的JSON备份文件导入内存 export-memories.

{
  "inputPath": "/path/to/backup.json",   // Required: path to backup file
  "overwriteExisting": false,             // Optional: overwrite if memory ID exists (default: false)
  "skipInvalid": true                     // Optional: skip invalid entries instead of failing (default: true)
}

退货：

{
  "imported": 40,
  "skipped": 2,
  "errors": [
    "Memory mem-123 already exists (use overwriteExisting to replace)",
    "Invalid memory structure: mem-456"
  ]
}

验证:

• 检查JSON格式和导出版本
• 验证内存结构和必填字段
• 验证范围/类别组合
• 检查是否存在重复的内存ID（除非 overwriteExisting 是真的）

错误处理:

• 随着 skipInvalid: true （默认）：继续导入有效内存，报告错误
• 随着 skipInvalid: false：在第一个错误时停止并抛出异常

安全说明：导入验证数据，但信任源文件。仅从可信来源导入。在导入之前，请检查备份文件内容，特别是从外部源还原时。

remember-bulk

通过验证和错误处理同时存储多个内存。通过可选的飞行前验证，高效地批量存储内存。

{
  "memories": [
    {
      "content": "First memory",
      "category": "longterm"
    },
    {
      "content": "Second memory",
      "scope": "team",
      "category": "decisions",
      "metadata": {
        "tags": ["important"],
        "priority": 1
      }
    },
    {
      "content": "Third memory",
      "scope": "personal",
      "category": "core"
    }
  ],
  "stopOnError": false,  // Optional: stop on first error vs continue (default: false)
  "validate": true       // Optional: validate all before storing any (default: true)
}

退货：

{
  "stored": 3,
  "failed": 0,
  "errors": [],
  "memoryIds": [
    "550e8400-e29b-41d4-a716-446655440000",
    "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  ]
}

参数:

• memories：内存对象数组，每个对象的字段与 remember 工具
• stopOnError：如果为真，则在第一个错误时停止；如果为false（默认），则继续并报告所有错误
• validate：如果为true（默认），则在存储任何内存之前验证所有内存；如果为false，则在存储期间进行验证

验证 （当 validate: true):

• 飞行前验证在存储之前检查所有记忆
• 验证内容大小（最大32KB）、范围/类别组合、元数据结构
• 如果发生任何验证错误，则不会存储任何内容，并抛出PatternError
• 所有验证错误都会与其数组索引一起报告

错误处理:

• 随着 stopOnError: false （默认）：继续存储有效内存，报告所有错误
• 随着 stopOnError: true：在第一个错误处停止，返回部分结果
• 错误包括数组索引和用于故障排除的错误消息

用例:

• 从外部源批量导入内存
• 正在使用多个条目初始化代理内存
• 批量创建项目文档或决策
• 在系统之间迁移内存

演出：不是原子-失败可能会留下部分结果。使用验证提前捕捉错误。

安全说明：每个内存都会单独扫描敏感内容（与 remember 工具）。查看日志中的警告。

forget-bulk

通过错误处理按ID删除多个内存。使用可选的核心内存强制标志高效批量删除内存。

{
  "memoryIds": [
    "550e8400-e29b-41d4-a716-446655440000",
    "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  ],
  "stopOnError": false,  // Optional: stop on first error vs continue (default: false)
  "force": false         // Optional: force delete core memories (default: false)
}

退货：

{
  "deleted": 3,
  "failed": 0,
  "errors": []
}

参数:

• memoryIds：要删除的内存ID（UUID）数组
• stopOnError：如果为真，则在第一个错误时停止；如果为false（默认），则继续并报告所有错误
• force如果为真，则允许删除核心记忆；如果为false（默认），则保护核心内存

错误处理:

• 随着 stopOnError: false （默认）：继续删除有效内存，报告所有错误
• 随着 stopOnError: true：在第一个错误处停止，返回部分结果
• 常见错误：找不到内存、核心内存没有强制标志、访问被拒绝（适用于其他人创建的团队/公共内存）
• 错误包括内存ID和故障排除错误消息

访问控制:

• 只能删除您自己的私人/个人记忆
• 只能删除您创建的团队/公共记忆
• 核心存储器需要 force: true 旗帜
• 规则与 forget 工具应用于每个内存

用例:

• 清理多个过时的内存
• 批量删除临时或过期条目
• 清除测试数据
• 重构过程中的内存管理

演出：不是原子-失败可能会留下部分结果。每个内存都是独立删除的。

pattern_health

检查服务器运行状况和连接状态。

认证

模式通过以下方式支持NATS身份验证：

1. URL凭据: nats://user:pass@host:port
2. 环境变量: NATS_USER 和 NATS_PASS

对于通过代理的WebSocket连接：

export NATS_URL="wss://user:pass@nats.example.com"

存储限制

安全最佳实践

什么不能存储

模式将数据存储在 纯文本 在NATS KV中。切勿储存：

• 🚫 凭证：密码、API密钥、令牌、证书
• 🚫 PII公司：社会安全号码、信用卡、医疗记录
• 🚫 秘密：数据库凭据、OAuth机密、私钥

内容扫描（v0.3.1+）

模式包括一个选择性内容扫描程序，用于检测常见的秘密模式（API密钥、密码、私钥等）并在存储前发出警告。必要时禁用：

export PATTERN_DISABLE_CONTENT_SCAN=true

保护您的NATS连接

使用TLS进行生产:

# WebSocket with TLS
export NATS_URL="wss://user:pass@nats.example.com"

# TCP with TLS
export NATS_URL="tls://user:pass@nats.example.com:4222"

客户端加密

对于必须存储的敏感内容，请使用客户端加密：

import { createCipheriv, randomBytes } from 'crypto';

// Encrypt before storing
const key = Buffer.from(process.env.PATTERN_ENCRYPTION_KEY!, 'hex');
const iv = randomBytes(16);
const cipher = createCipheriv('aes-256-cbc', key, iv);
const encrypted = cipher.update('sensitive data', 'utf8', 'base64') + cipher.final('base64');

await remember({
  content: iv.toString('base64') + ':' + encrypted,
  metadata: { tags: ['encrypted'] }
});

看 docs/SECURITY.md 全面的安全指导，包括：

• 威胁模型和保护模式
• 带有密钥管理的加密示例
• 访问控制最佳实践
• 事故响应程序

发展

# Clone the repository
git clone https://github.com/loominal/pattern.git
cd pattern

# Install dependencies
npm install

# Run tests
npm test
npm run test:coverage

# Build
npm run build

# Watch mode
npm run dev

# Lint and format
npm run lint
npm run format

建筑

flowchart TB
    subgraph Clients["MCP Clients"]
        CC["Claude Code"]
        OA["Other Agent"]
    end

    subgraph Server["MCP Server"]
        Pattern["Pattern
(Memory)"]
    end

    subgraph Storage["Storage Backend"]
        NATS["NATS KV
(JetStream)"]
    end

    CC  Pattern
    OA  Pattern
    Pattern  NATS

关键设计决策

• 统一身份：模式从Warp的NATS KV存储中读取标识，而不是生成临时UUID。同一台计算机+同一个文件夹=重启后的同一个代理。
• 统一范围模型：4值范围(private, personal, team, public)与Warp和Weft共享，以获得一致的语义
• 多桶存储：不同的作用域路由到不同的NATS KV bucket（项目bucket、用户bucket、全局bucket）
• 项目隔离：每个项目都有自己的NATS KV桶 private 和 team 范围
• 个人记忆：核心记忆使用 personal 范围，存储在用户bucket中，可在所有项目中访问
• 代理人隐私：由agentId键入的私人记忆，他人永远看不到
• TTL管理：应用程序级别过期（NATS KV不支持按密钥TTL）
• 摘要生成：优先内存中的最大4KB摘要

相关

• Loominal --多代理基础架构
• 曲速 --用于消息传递的MCP服务器
• 纬线 --工作协调员
• 航天飞机 --车队管理CLI

许可证

麻省理工学院-迈克尔·洛普雷斯蒂