内存管理选项

SkillFlaw 提供灵活的内存与存储管理能力，用于保存和检索与你的流程及 SkillFlaw 服务相关的数据。 这既包括 SkillFlaw 的核心数据库表、文件管理与缓存，也包括聊天记忆。

存储选项与路径

SkillFlaw 支持以 PostgreSQL 作为应用级存储，并允许针对特定记忆模式使用外部系统。

SkillFlaw 会把结构化应用数据存储在 PostgreSQL 中。

SkillFlaw 支持以下存储模式：

• PostgreSQL 数据库：你可以把所有 SkillFlaw 存储统一放到 PostgreSQL 中。 更多说明请参阅 配置外部 memory。

  当你需要持久化数据、多实例部署，或希望把状态与应用主机隔离开时，共享 PostgreSQL 存储会很有帮助。

• 独立聊天记忆：你也可以只把聊天记忆单独存放到外部系统中，而把其他 SkillFlaw 存储仍保留在默认路径中。 更多说明请参阅 存储聊天记忆。

• 无数据库模式：如果你想关闭所有数据库操作并运行一个 no-op 会话，可在 环境变量 中设置 SKILLFLAW_USE_NOOP_DATABASE=True。 这种模式适合测试场景，尤其是你不希望任何数据被持久化时。

SkillFlaw 数据库表

以下表会存储在你的 SkillFlaw PostgreSQL 数据库中：

• ApiKey：管理 SkillFlaw API 鉴权 Key。组件 API Key 则存储在 Variables 表中。详见 API keys and authentication。

• File：保存上传到 SkillFlaw 文件管理中的文件元数据，包括文件名、路径、大小和存储提供方。详见 管理文件。

• Flow：保存流程定义，包括节点、边和组件配置，形式可能是 JSON 或数据库记录。详见 构建流程。

提示

如果你希望在流程保存到数据库前自动去除 API Key 与 token，可在 环境变量 中设置 SKILLFLAW_REMOVE_API_KEYS=True。 当该值为 true 时，所有既是密码字段、且字段名中包含 api、key 或 token 的字段，都会在保存前被设为 null。 这有助于避免敏感凭据落库。

• Folder：提供流程存储结构，包括单用户文件夹与多用户共享文件夹。详见 在项目中管理流程。

• Message：保存组件之间产生的聊天消息与交互。详见 Message 对象 与 存储聊天记忆。

• Transactions：记录流程运行的执行历史与结果，该信息也被用于 日志。

• User：保存用户账户信息，包括凭据、权限、用户资料与管理设置。详见 API keys and authentication。

• Variables：保存全局加密值与凭据。详见 全局变量 与 组件 API Key。

• VertexBuild：跟踪流程中单个节点的构建状态。详见 在 Playground 中测试流程。

更多实现细节可查阅源码中的数据库模型：source code。

配置外部 memory

设置 SKILLFLAW_DATABASE_URL 指向你的 PostgreSQL 地址，然后使用 .env 启动 SkillFlaw。 更多示例请参阅 配置外部 PostgreSQL 数据库。

_10

SKILLFLAW_DATABASE_URL=postgresql://user:password@localhost:5432/skillflaw

如果你还需要细调数据库连接池与超时设置，可以继续配置以下环境变量：

• SKILLFLAW_DATABASE_CONNECTION_RETRY：是否在数据库连接丢失后自动重试。若设为 true，当连接失败时 SkillFlaw 会尝试重新连接。默认 false。

• SKILLFLAW_DB_CONNECT_TIMEOUT：在放弃等待锁释放或建立数据库连接前等待的秒数。这个值可能与 SKILLFLAW_DB_CONNECTION_SETTINGS 里的 pool_timeout 分开生效。默认 30。

• SKILLFLAW_MIGRATION_LOCK_NAMESPACE：迁移期间 PostgreSQL advisory lock 的可选命名空间标识。若未提供，将使用数据库 URL 的哈希。对于多个 SkillFlaw 实例共享同一数据库、需要协调迁移锁时非常有用。

• SKILLFLAW_DB_CONNECTION_SETTINGS：一个 JSON 字典，用于配置连接池参数：

  • pool_size：连接池中长期保持的基础连接数。默认 20。
  • max_overflow：在 pool_size 基础上允许额外创建的最大连接数。默认 30。
  • pool_timeout：从连接池获取连接时的超时秒数。默认 30。
  • pool_pre_ping：若为 true，每次借出连接前先做存活检查。默认 true。
  • pool_recycle：连接自动回收前的秒数。默认 1800（30 分钟）。
  • echo：若为 true，会输出 SQL 以供调试。默认 false。

  示例：

  
  

  _10

  SKILLFLAW_DB_CONNECTION_SETTINGS='{"pool_size": 20, "max_overflow": 30, "pool_timeout": 30, "pool_pre_ping": true, "pool_recycle": 1800, "echo": false}'

  
  

  不要再使用已弃用的 SKILLFLAW_DB_POOL_SIZE 与 SKILLFLAW_DB_MAX_OVERFLOW。 请改为在 SKILLFLAW_DB_CONNECTION_SETTINGS 中使用 pool_size 与 max_overflow。

• SKILLFLAW_MIGRATION_LOCK_NAMESPACE：用于数据库迁移期间 PostgreSQL advisory lock 的可选命名空间。对于多个 SkillFlaw 实例共享同一个 PostgreSQL 的场景很有用。未设置时会使用默认命名空间。该设置仅在 PostgreSQL 作为数据库后端时生效。

配置缓存 memory

SkillFlaw 默认使用异步内存缓存：

_10

SKILLFLAW_LANGCHAIN_CACHE=InMemoryCache

_10

SKILLFLAW_CACHE_TYPE=async

官方正式支持的只有这个默认异步内存缓存，它已足够覆盖大多数场景。 其他缓存方式（例如 Redis）仍然是实验性能力，未来可能变更。 如果你确实要使用非默认缓存，可使用以下环境变量：

变量	类型	默认值	说明
SKILLFLAW_CACHE_TYPE	String	async	设置 SkillFlaw 内部缓存类型。可选 async、redis、memory、disk。如果设为 redis，则必须同时配置 SKILLFLAW_REDIS_*。
SKILLFLAW_LANGCHAIN_CACHE	String	InMemoryCache	设置 LangChain 缓存存储类型。当前支持的默认值是 InMemoryCache。
SKILLFLAW_REDIS_HOST	String	localhost	当 SKILLFLAW_CACHE_TYPE=redis 时的 Redis 主机名。
SKILLFLAW_REDIS_PORT	Integer	6379	当 SKILLFLAW_CACHE_TYPE=redis 时的 Redis 端口。
SKILLFLAW_REDIS_DB	Integer	0	当 SKILLFLAW_CACHE_TYPE=redis 时的 Redis 数据库编号。
SKILLFLAW_REDIS_CACHE_EXPIRE	Integer	3600	当 SKILLFLAW_CACHE_TYPE=redis 时的缓存过期时间（秒）。
SKILLFLAW_REDIS_PASSWORD	String	未设置	当 SKILLFLAW_CACHE_TYPE=redis 时，Redis 的可选认证密码。

存储聊天记忆

带有 Chat Input 或 Chat Output 组件的聊天型流程，会产生聊天历史，并存储到 SkillFlaw 的 messages 表中。 至少从功能上看，这相当于一份聊天日志；但它不等同于真正为 LLM 提供上下文召回能力的聊天记忆。

如果你想在流程中真正存储并检索聊天记忆，可以使用 Message History 组件，或者使用 Agent 组件内建的聊天记忆能力。

聊天记忆是怎么工作的？

聊天记忆本质上是一种为 LLM 或 agent 保留历史对话的缓存，以便它们在未来交互中继续引用这些上下文。 例如，如果用户之前已经告诉模型自己的名字，模型就可以从聊天记忆中取回这个信息，而不需要每次都重新询问。

聊天记忆与向量存储记忆不同，它专门针对聊天消息的保存与检索而设计。

支持聊天记忆的组件（如 Agent 和 Message History）是把各自数据库以“记忆”的方式暴露给 LLM 或 agent。 这种“按记忆方式检索”很关键，因为它的目标是召回历史对话上下文，而不是像向量存储那样做语义检索与文本块召回。

Session ID 与聊天记忆

聊天历史与聊天记忆都是按 session ID (session_id) 分组的。

默认 session ID 为 flow ID，这意味着同一个流程中的所有聊天消息都会被视为同一个大聊天会话。

如果你的流程要面向多个用户使用，建议使用自定义 session ID，以便更好地隔离记忆。 例如，如果你把用户 ID 当作 session ID，那么每个用户的聊天历史就会分别存储，彼此上下文不会串扰。

聊天记忆选项

聊天记忆存储在哪里、如何读取，取决于你在流程中使用的组件：

• Agent 组件：内建聊天记忆，并且默认开启。 它可以自动读取并引用同一 session ID 下的历史消息。 所有消息都存储在 SkillFlaw 存储 中，该组件只提供少量记忆参数，例如要读取多少条消息。

  对大多数场景来说，Agent 内建记忆已经足够。

  如果你要使用外部聊天记忆存储、在非聊天场景中读取记忆，或你使用的是语言模型组件而不是 agent，则需要使用 Message History 组件（单独使用，或配合第三方聊天记忆组件）。

• Message History 组件：默认会从 SkillFlaw 存储中保存与读取记忆，除非你额外挂了第三方聊天记忆组件。 它比 Agent 提供更多排序与过滤选项，不过其中不少能力其实 Agent 也已有内建支持。

  Message History 可以单独使用，也可以配合语言模型或 agent 使用。 例如，如果你希望在非聊天流程里直接查询聊天记忆中的数据，而不是把它喂给聊天组件，就可以直接使用 Message History。

• 第三方聊天记忆组件：只有当你确实需要把聊天记忆保存到专门的外部聊天数据库中时，才需要使用它们。 一般来说，只有 SkillFlaw 默认存储无法满足你的特殊要求时，才值得这样做。 例如，你希望直接对聊天记忆数据库做管理，或者你就是想使用 SkillFlaw 默认存储之外的数据库。

更多示例请参阅 Message History 组件 与 Agent memory。

另请参阅

• SkillFlaw 文件管理
• SkillFlaw 日志
• SkillFlaw 环境变量