智能体记忆源码 Liyuan1992/memdsl

memdsl

Agent memory as source code the agent reads itself.

0.9 release line with experimental Edges

Version 0.9.0 adds an opt-in memdsl.workspace.v3 first-class explicit Edge
experiment. It does not rewrite the frozen 0.8 contract: legacy relations and
authority remain compatible, explicit Edge proposals always require a human,
and explicit supersedes is graph-only. Source remains runtime authority;
review/audit is a workflow contract, not a non-bypassable grant ledger. See
the Phase 6 design and risk matrix and
the release-scope evidence freeze.

Stable 0.8 compatibility contract

The 0.8 contract combines the previously unpublished navigation and View work
now shipped by 0.9.0; neither 0.7.0 nor 0.8.0 was released separately. Stable
public contracts include the v1 compatibility/authority surfaces, Catalog v1,
Trace v1, indexed
query/search trace, report diagnostics, public rebuildable CompiledWorkspace
/ compile_workspace, memdsl.workspace.v2, exact use, the generic
dialect_mapping capability, ViewContext/ResolvedView, and the explicit
opt-in v2 read schemas. Map v1 remains supported throughout the 0.8 line and
will not be reconsidered for removal before 1.0.

The software release is 0.9.2, anchored by tag v0.9.2. It adds official
MCP Registry metadata and a UV-based MCPB installer for the default-read-only
memdsl-mcp server. Parser, schema, review, query, authority, and MCP tool
contracts are unchanged from 0.9.1. Neither patch nor package-level release
promotes the opt-in Edge surface to stable or makes automatic Edge generation
authoritative.

The real-world rollout quality of quarantine/strict, dialect-candidate
learning, and host-attested principal integration is still experimental and
opt-in. Their safety invariants are not experimental: authorization happens
before aggregation, incomplete hard-rule evaluation never becomes ALLOW,
non-authoritative edges never gain authority, and repair paths remain open.
CompiledWorkspace is a public rebuildable handle; its cache/index layout,
compiler contract strings, and synthetic timing constants remain implementation
details. Workspace-v3 first-class Edges are experimental. Automatic dialect
learning, automatic Edge candidates, inferred authority, and cold-history/
incremental compilation are not shipped. Host extraction/sanitization and
private schemas/policies/samples remain outside memdsl and are not release
gates.

memdsl started with a retrieval failure. A memory system built on RAG failed
to recall a memory it certainly had; a coding agent pointed at the same raw
memory files traced it down in a few steps. Same model — the difference was the context contract. The agent knew the memory existed and could keep reading toward it; the retriever got exactly one similarity guess, and a 缺失看起来与不存在完全相同。

memdsl 将这种差异转化为产品。长期记忆存放在可读、可 lint、可审查的 .mem 源文件中，而每个运行时界面都是为自行读取记忆的 agent 而构建的：

- 有界记忆 Catalog（memdsl catalog、MCP memory_catalog / memdsl://catalog、Python build_memory_catalog）：分页的模块/类型/主题/ 状态导航，带有条目和字节预算、绑定修订的游标，并且没有重复的结构化/文本表示。它是大型工作区推荐的会话启动界面。
- 兼容的记忆 map（memdsl map、MCP memory_map / memdsl://map）：现有的 v1 完整索引仍然可供较旧的客户端使用，并且不会被悄悄改为 Catalog。
- 能解释其未命中原因的索引查询（每个序列化 pack 中的 search_trace）：确定性的词法倒排索引保留 v1 EvidencePack 排序和权威通道，同时暴露 View/来源身份、候选池计数、被过滤器隐藏的匹配、有界词汇建议以及安全的重试查询。建议从不写入别名，也不让候选符号重定向检索。
- 有界关系 Trace（memdsl trace、MCP memory_trace、Python trace_memory）：确定性的入向/出向/双向 BFS 导航，带有关系过滤器、显式的循环/回退/交叉边、硬性深度/节点/边/字节预算以及绑定修订的游标。连通性是导航，不是证明。
- 仅报告的链接诊断（memdsl lint、MCP memory_lint 和 memdsl://status）：重复 id、歧义/错误前缀/悬空目标、未知关系、修订循环和 supersede 分叉都会被明确显示。循环边不能让所有参与者都消失，分叉从不选择胜者，并且默认 Map/查询权威保持 v1 兼容。
- 原始源作为底线（memdsl://file/{file_id}）：agent 可以随时下探并阅读实际声明，就像编码 agent 阅读代码一样。

启动这个项目的失败模式现在会大声失败——记忆存在，某个过滤器隐藏了它，而 trace 正是这样说的：

$ memdsl query examples/domains/coding -q "force push main" \
--type coding.bug_pattern --json
"missing": [
"no active declarations matched query terms: ['force', 'push', 'main']",
"1 active declaration(s) matched the query but were excluded by type/subject filters"
],
"search_trace": {
"excluded_by_filters": [
{"id": "coding.project_rule:git.no_force_push", ...}
], ...
}

$ memdsl query examples/domains/coding -q "force push main"
MUST
- [coding.project_rule:git.no_force_push] Never force-push the main branch. (exceptions: []) [status=active; runtime_role=constraint; lifecycle={"status":"active"}]

用 Claude Code 在两分钟内试用

核心库和 CLI 支持 Python 3.9+。MCP 附加组件和 memdsl-mcp 服务器需要 Python 3.10+，因为上游 MCP SDK 需要。

Python 3.10+
pip install "memdsl[mcp]"
claude mcp add memdsl -- memdsl-mcp --workspace ~/memory # 或 examples/ 目录

服务器指示代理首先读取 memory_catalog，仅使用绑定到相同 Source/View 和过滤器的游标继续操作，将 no_match 视为重试信号，仅将 memory_trace 用于有界的显式关系导航，并使用 memory_check 针对 MUST 约束对重要草稿进行预检。旧版 memory_map 仍为兼容客户端注册。

DeepSeek Harness

DeepSeek Harness 可以通过其官方 MCP 客户端挂载相同的 stdio MCP 服务器。推荐的 overlay 仅授予 read:summary,read:search，因此模型可以对已批准的源记忆进行编目、查询、追踪、解释和检查，但无法创建提案。请参阅DeepSeek Harness 集成指南中经过测试的 overlay 和验证步骤。

memdsl DeepSeek Harness 演示

受治理的类型化记忆

第二根支柱：你可以像审查代码一样审查记忆，而无需将某位作者的本体强加给每一位用户。0.8 版本保留了 0.5 中引入的两层类型架构以及 0.6 中的生命周期安全审查契约，并新增了有界编译导航和显式 workspace-v2 Views：

core memory record claim / evidence / scope / confidence / lifecycle /
access policy / relations

domain type system coding.project_rule / assistant.commitment /
writing.voice_preference / your own memory types

核心层拥有稳定的行为契约。工作区拥有自己的词汇表。编程代理、个人助理和写作系统不应仅仅因为 memdsl 的作者选择了 preference、boundary 或 fact 这些词，就必须用相同的词来称呼同一事物。

两层

核心层提供通用字段和五种稳定的运行时角色：

| 运行时角色 | EvidencePack 行为 |
| symbol | 定义其他记忆可以引用的主体 |
| constraint | 活跃声明出现在 MUST 中并参与合规性检查 |
| guidance | 活跃声明出现在 SHOULD 中 |
| assertion | 活跃声明在相关时出现在 CONTEXT 中 |
| question | 活跃声明出现在 MISSING 中，而非作为事实 |

每个可搜索的非活跃命中项都隔离在 PROVISIONAL 下，无论其运行时角色如何。候选符号无法重定向查询，候选约束无法进入 MUST 或合规性检查。

相同的权限边界适用于关系。supersedes 关系仅当其源为活跃状态且其完整 ID 或唯一裸目标能够精确解析时，才能隐藏目标。候选、已撤回、已归档、有歧义、重复或前缀错误的替代者无法更改查询、MUST 或合规性。这是 0.8 保留的 v1 兼容性权限规则。可选的 ResolvedView 路径使用相同的故障安全基础，并仅添加显式的 v2 隔离执行。

核心还理解诸如 requires_evidence、 searchable、temporal、enforceable、guardable、 exceptions_recommended 等能力，以及显式审查选择加入的 auto_approvable。

领域层定义了有意义的记忆类型，并将每一种编译为运行时角色。随附的示例包括：

- 编码：coding.project_rule、coding.bug_pattern、coding.tool_preference
- 个人助理：assistant.routine、assistant.commitment、 assistant.relationship_context
- 写作：writing.voice_preference、writing.taboo_topic、 writing.style_example

内置的 memdsl.standard@1 包使现有的 entity、fact、 preference、boundary、principle、decision、state 和 open_issue 工作区继续可用。这些名称是兼容性默认值，并非人类记忆的通用本体。

定义领域词汇表

工作区通过 memdsl.json 选择加入模式：

{
"schema_version": "memdsl.workspace.v1",
"schemas": ["coding.memschema.json"]
}

模式定义领域类型、字段、角色和能力：

{
"name": "coding",
"version": "1",
"types": {
"project_rule": {
"runtime_role": "constraint",
"required_fields": ["claim", "evidence", "scope"],
"optional_fields": ["rationale", "owner"],
"search_fields": ["rationale", "owner"],
"capabilities": [
"requires_evidence",
"searchable",
"enforceable",
"guardable",
"exceptions_recommended"
],
"defaults": {"force": "hard", "status": "active"},
"allowed_forces": ["hard"],
"allow_extra_fields": false
}
}
}

project_rule 成为命名空间类型 coding.project_rule：

module coding.memory

entity Repository.Memdsl {
canonical_name: "memdsl"
status: active
}

coding.project_rule git.no_force_push {
subject: Repository.Memdsl
claim: "Never force-push the main branch."
scope: repository("memdsl")
confidence: high
exceptions: []
rationale: "Published history must remain auditable."
guard {
when_any: ["push", "git", "main"]
deny_any: ["force-push", "--force", "--force-with-lease"]
}
lifecycle { status: active }
access_policy {
readers: [developer, coding_agent]
writers: [maintainer]
reviewers: [maintainer]
export: internal
}
evidence {
source: AGENTS.md
quote: "Do not force-push unless the user explicitly asks."
}
}

严格模式会拒绝未声明的字段。未知记忆类型会导致 lint 失败，并报出 unknown_memory_type；它们不会静默地获得临时行为。

精确导入与工作区自有方言

现有工作区保持兼容：无清单和 memdsl.workspace.v1 保留旧版全局链接。工作区可以通过 v2 显式审计或强制执行导入：

{
"schema_version": "memdsl.workspace.v2",
"schemas": ["workspace-dialect.memschema.json"],
"linking": {"visibility": "report"}
}
use X 在整个工作区完成索引后才会解析，因此声明顺序无关紧要。X 是一个确切的模块或一个确切的活动符号名称。不存在通配符、前缀、别名或模块优先于符号的优先级。报告模式保留旧式链接并发出迁移诊断；严格模式移除未导入的关系、主题路由和方言路由效果。对于 v1 工作区，绝不会推断为严格模式。

方言仍然是工作区拥有的 Source。模式类型通过通用 dialect_mapping 能力选择启用；虚构的可运行示例是 examples/dialect/。只有活动的、公开的、有效的、无歧义的正向映射才会进行路由。候选、待定、私有、有歧义和负向映射不会。无匹配可能返回 search_trace.dialect_candidate 模板，但它不会写入任何内容：证据、提案、审查、批准和重新编译仍然是必需的。

选择启用隔离强制执行

工作区 v2 可以独立启用 v2 读取门控：

{
"schema_version": "memdsl.workspace.v2",
"schemas": ["workspace-dialect.memschema.json"],
"linking": {"visibility": "report"},
"enforcement": {"mode": "quarantine"}
}

省略 enforcement，或选择 report，会保留 v1 读取行为。quarantine 和 strict 是显式选择启用；它们将 Source 分类为权威、临时、隔离或排除，并使用新的 v2 query/list/explain/check/Catalog/Trace 信封。空结果会区分 no_match、quarantined、unauthorized、compiler_error 和预算限制。身份关键错误会故障关闭，而关系/use/方言/类型错误会在最小的安全声明、文件或修订族范围内被隔离。Lint、源编辑、提案、审查和审计仍可用于修复。

Map 仍然是 v1 兼容表面，并在显式强制执行下返回 unsupported_view。请改用 Catalog、query、list、explain 或 Trace。待定提案仍然不会进入持久 View，候选/私有/有歧义的方言映射也绝不会通过隔离获得路由权限。

安装和检查

基础包支持 Python 3.9+：

pip install memdsl # or: pip install -e . from a checkout
memdsl --version
memdsl types examples/domains/coding
memdsl lint examples/domains/coding --json
memdsl catalog examples/domains/coding --json
memdsl map examples/domains/coding
memdsl query examples/domains/coding -q "force push main"
memdsl trace examples/alex decision:aurora.pricing_free_tier --both --depth 2 --json
memdsl check examples/domains/coding \
-t "push main" \
-c "git push --force origin main"

memdsl types 会显示每个已加载的标准类型和领域类型，以及其运行时角色、必需字段、能力、模式版本和来源。当其他工具需要发现类型系统时，请使用 --json。

memdsl lint --json 会以 memdsl.lint.v1 信封：每个诊断都带有其代码、严重级别、文件、行号和声明 id，以及计数和一个与退出码匹配的 status，取值为 ok、errors 或 strict_warnings。

自定义编码规则的行为与 MUST 约束完全一致，而无需任何 Python 代码知道 coding.project_rule 这个名称：

MUST
- [coding.project_rule:git.no_force_push] Never force-push the main branch. [status=active; runtime_role=constraint; lifecycle={"status":"active"}]

合规检查返回 BLOCK 并引用同一个领域声明。未受保护或不可强制执行的约束会安全地失败为 NEEDS_REVIEW，而不是被猜测处理。

分层查询契约

查询返回的是 EvidencePack，而不是扁平的命中列表：

- MUST：适用的 constraint 声明
- SHOULD：相关的 guidance 声明
- CONTEXT：相关的 assertion 声明
- PROVISIONAL：经过评分的非活跃可搜索声明
- CONFLICT：所选记忆之间声明的冲突
- MISSING：相关的 question 声明和已知缺口

每个条目都带有稳定的声明 id、类型、运行时角色、能力、主张、主体、范围、置信度、生命周期、访问策略、证据和源位置。领域语义保持富有表现力，而运行时行为保持可预测。

JSON 输出仍为 memdsl.evidence_pack.v1；0.6 中新增的 provisional 字段在 0.8 中保持增量添加。经过评分的 CONTEXT 和 PROVISIONAL 条目包含 score 和 matched_terms，并且每个声明条目都带有显式的生命周期状态和运行时角色。

参考检索器有意采用词法方式，并使用可重建的倒排词项索引。生产系统可以在同一 EvidencePack 契约背后放置 BM25、嵌入、图或数据库索引。

导航：先有界 Catalog，再查询并下钻

memdsl 的存在是因为由智能体驱动的阅读胜过盲目的相似度匹配：知道某个记忆存在的智能体可以下钻到它，而漏掉它的检索器只会返回空。四个表面支持这一循环：

- 有界 Catalog（memdsl catalog、MCP memory_catalog / memdsl://catalog、Python build_memory_catalog）：按模块/类型/主体/状态过滤的模块摘要。默认页为 20 个条目 / 8192 个规范紧凑 UTF-8 JSON 字节。truncated、next_cursor、returned_items、精确总数以及词汇表总数/截断元数据都是显式的。游标绑定 Source 指纹、仅报告 View、过滤器、排序和表示形式；Source 发生变化会返回 cursor_stale。
- Map v1 兼容性（memdsl map、MCP memory_map / memdsl://map、Python build_memory_map）：仍为现有客户端返回完整的可服务声明索引。它不是推荐的大型工作区会话启动表面。在显式的 workspace-v2 强制执行下，它会返回 unsupported_view；Map 和 Catalog 是导航，而不是引用。
- 搜索轨迹（序列化包中的 search_trace）：查询是如何被解释的、运行了哪些索引、过滤前后的候选池，以及类型/主题过滤器排除了哪些匹配的声明。无匹配时可能会添加有界的词汇 vocabulary_suggestions 和 retry_queries；候选、歧义或访问受限的词汇永远不会成为自动路由。
- 有界轨迹（memdsl trace、MCP memory_trace、Python trace_memory）：使用确定性 BFS 跟随显式解析的关系。
默认值为深度 3、20 个节点、40 条边和 8192 字节。无状态游标绑定 Source/View、锚点、方向、关系过滤器、深度和临时可见性。反向/循环/交叉边是显式的；图连通性不是证据或证明。

预检约束

任何 schema 定义的 constraint 都可以参与 memdsl check。要运行确定性守卫，其类型必须同时声明 enforceable 和 guardable。
短语和正则守卫产生 ALLOW 或 BLOCK；仅自然语言的约束产生 NEEDS_REVIEW。声明的例外必须使用 --exception 显式断言。

标准 v0.4 boundary 类型遵循同样的通用路径。其旧的 JSON 别名（如 boundary_id 和 applicable_must）仍然可用，以保持客户端兼容性。

运行可复现的标准或自定义域套件：

memdsl eval compliance examples/compliance \
--cases examples/compliance/cases.jsonl --json

memdsl eval compliance examples/domains/coding \
--cases examples/domains/coding/cases.jsonl --json

用作 MCP 服务器

MCP 服务器需要 Python 3.10+：

Python 3.10+
pip install "memdsl[mcp]"
memdsl-mcp --workspace examples/domains/coding --inspect
memdsl-mcp --workspace ~/memory

MCP 服务器暴露：

- 工具：memory_catalog、memory_map、memory_types、memory_query、memory_trace、memory_check、 memory_explain、memory_list、memory_lint、memory_propose、 memory_review_list
- 资源：memdsl://status、memdsl://catalog、memdsl://map、memdsl://types、
memdsl://files、memdsl://file/{file_id}

代理应在会话开始时读取 memory_catalog，以便随着工作区增长，导航保持有界，然后使用 memory_query 和有界的 memory_trace 进行本地深入探查。memory_map 仍保留供 v1 客户端使用。在提议声明之前，调用 memory_types 或读取 memdsl://types。这会发现工作区的词汇，而不是发明一个类型或假设标准包是唯一有效的世界观。

访问可以通过 --scopes 或 MEMDSL_MCP_SCOPES 收窄（默认： read:summary,read:search,write:candidate）。核心表示并传输声明级 access_policy。对于强制执行的 View，嵌入宿主可以仅在构造 MemdslMCPService 时注入受信任的主体和角色； MCP 工具参数不能自我断言身份。过滤发生在计数、词汇表、诊断、图遍历和原始文件资源之前。memdsl 不提供身份提供程序，因此宿主必须对主体进行身份验证并映射角色。

门控写入

每次 MCP 写入仍然是一个提案。它必须使用已加载的类型、解析，并通过针对实时工作区的 lint。无效提案会被拒绝；完全相同的待处理/已批准重复项返回 no_op；其他所有内容要么排队，要么由宿主证明的策略进行窄范围自动批准。

默认仍然是全人工。初始化一个有效但已禁用的策略：

memdsl review policy init memory
memdsl review policy show memory
memdsl review policy validate memory

生成的 JSON 具有空的 clients/rules 和零每日限制。要启用自动化，工作区所有者必须显式地向一个候选断言类型添加 auto_approvable，配置精确类型规则和受信任的宿主客户端，设置正数每日限制，并授予非默认的 write:auto 作用域：

memdsl-mcp --workspace memory \
--scopes read:summary,read:search,write:candidate,write:auto

内置的 workspace_file_quote 验证器要求 evidence.source 解析到已加载的工作区根目录内，并且 evidence.quote 必须精确出现在该 UTF-8 文件中。问题、指导、约束、符号、活动、全局、警告、破坏性或未验证的提案始终留在队列中。没有 write:auto 时，有效策略以影子姿态运行：写入保持待处理，而 eligible_route 记录策略本会执行的操作。

人工操作和质量反馈保持显式：

memdsl review list memory
memdsl review approve memory PROPOSAL_ID --into memory/approved.mem
memdsl review reject memory PROPOSAL_ID --reason "not durable"
memdsl review digest memory
memdsl review stats memory
memdsl review audit memory PROPOSAL_ID --verdict confirm

review list、review show 和 review audit 除了现有的 policy show、digest 和 stats JSON 输出外，还接受 --json，因此队列仪表板或 CI 作业可以读取队列而无需解析人类可读文本。批准和拒绝仍然是纯文本决策。

进程内宿主使用权威路径：

from memdsl import (
ProposalContext,
ReviewStore,
Workspace,
load_policy,
staging_dir_for,
)

workspace = Workspace.load(["memory"])
store = ReviewStore(staging_dir_for(["memory"]))
policy = load_policy(store.staging_dir, registry=workspace.registry)
assert policy is not None
context = ProposalContext(client_id="mcp-client")

result = store.submit(
["memory"],
proposal_source,
policy=policy,
context=context,
write_auto_granted=True,
)

自动批准会重新加载并指纹化 memory、manifest 和 schema 输入，重新验证证据，强制执行有限的 UTC 每日限制，仅写入主工作区根目录内非符号链接的 .mem 目标，并且从不使用 force。路由评估、决策、审查后结果、摘要游标和空操作事件保持仅追加。

审查后的 flag 不会静默删除记忆。提升、修订和撤回需要一份新的人工审查声明，带有新的 id 和指向旧声明的 supersedes（可选 revision_of）。在关系具有权威性之前，后继者必须处于生命周期 active 状态；旧声明不需要就地重写 status: superseded。ReviewStore 不创建 Git 提交；宿主可以添加 Git 集成，而不让核心正确性依赖于它。

包含内容

- 一个领域中立的 .mem 记录，包含来源、范围、置信度、生命周期、访问策略、关系和稳定 id。
- 一个可扩展、带命名空间的 .memschema.json 类型系统和工作区清单。
- 一个向后兼容的标准类型包，用于 v0.5 之前的工作区。
- 一个模式驱动的 linter、分层查询执行器、解释器和确定性合规门。
- 通过 CLI 和 MCP 进行类型发现。
- 一个默认安全、宿主证明的审查流水线，具有人工排队、确定性窄范围自动批准、空操作检测、摘要/统计和仅追加审计。
- 可复现的合规基准以及编码/助手/写作领域包。
- 面向 Alex 和 Mira 的虚构标准示例，以及一个故意损坏的 linter 工作区。

完整语法和语义见 docs/SPEC.md。进程内宿主还应阅读 docs/PUBLIC_API.md 和 docs/UPGRADING.md。审查策略安全契约见 docs/DESIGN_review_policy.md。文档索引将软件契约、实现设计、发布边界和可复现性材料汇集在一起。

memdsl 不是什么

- 它不是 Mem0、Zep、Graphiti 或 LangMem 等检索/提取系统的替代品。它是这些系统之上的受治理源格式和行为契约。
- 它不是人或记忆的通用分类法。领域所有者定义自己的类型。
- 它不是语义策略预言机。无法确定性评估的约束保持为 NEEDS_REVIEW。
- 它不是不受限制的自动记忆写入器。只有具有可信身份和已验证证据的显式选择加入的候选断言才能被自动批准；每一个更高风险或不确定的提案仍由人工审查。

当前证据和局限

从提取该项目的私有单用户系统获得的早期证据显示，在其内部评估中，检索精度高于该系统调优后的 RAG 基线。这一结果令人鼓舞，但它并不能证明某一种本体可以推广到所有人。v0.8 架构明确说明了这一局限：memdsl 标准化记录和运行时契约，同时让每个领域拥有自己的词汇表。

捆绑的测试套件是契约级、确定性的测试。跨模型行为性声明仍需要单独记录的模型运行。

路线图

- 双层核心 + 可扩展领域类型系统 — 已在 v0.5 发布
- 生命周期安全的临时服务 + 分层审查策略 — 已在 v0.6 发布
- 公共可重建 CompiledWorkspace + 有界 Catalog 分页/预算— stable/public 0.8 合同已由 0.9.0 发布
- 索引查询 + 有界 Trace + 精确 use/report/strict + 经审查的 Dialect — stable/public 0.8 合同已由 0.9.0 发布
- 带显式 v2 envelope 的 opt-in quarantine 强制执行 — stable/public schema/safety 合同；真实 rollout 质量仍为实验性
- Opt-in 一等经审查 Edge 实验 — 在匿名探索性 Pilot 之后作为实验性功能在 0.9.0 发布；relation/evidence 收窄仍为 ADJUST，而非正式经验验证
- 冷历史/增量编译 — 推迟至存在代表性规模、SLO 和生产瓶颈证据之后
- Schema 包分发、依赖/版本约束与迁移
- 更丰富的字段验证器与领域定义的诊断规则
- EvidencePack 合同之后的可插拔检索后端
- 用于强制执行所表示访问策略的身份提供方适配器
- 语义冲突审查器与按客户端/按规则配额，以经测量的 shadow/sample/post-review 证据为门控

许可证

代码：MIT。规范（docs/SPEC.md）：CC-BY-4.0。

0.9 正式软件版本中的实验 Edge

0.9.0 新增显式 opt-in 的 memdsl.workspace.v3 一等 Edge 实验，不改写已经冻结的 0.8 合同：legacy relation 与 authority 保持兼容，Edge proposal 永远进入人工审核，显式 supersedes 在本阶段仅进入 graph。当前 runtime authority 仍来自 Source；review/audit 只是 workflow contract，不是不可绕过的授权账本。详见 Phase 6 设计与风险矩阵 与发布范围证据冻结。

把 Agent 记忆写成 agent 自己会去读的源代码。

Stable 0.8 兼容合同

0.8 合同把此前未单独发布的导航能力与 View 能力统一后由 0.9.0 承载；0.7.0 与 0.8.0 均未单独发布。正式公共合同包括 Source/review authority、公共且可重建的 CompiledWorkspace / compile_workspace、v1 兼容 surface、Catalog v1、Trace v1、indexed query/search trace、report diagnostics、memdsl.workspace.v2、 exact use、通用 dialect_mapping capability、ViewContext/ResolvedView 与显式 opt-in 的 v2 read schemas。Map v1 在整个 0.8 line 继续保留，不早于 1.0 才重新评估删除。

正式软件版本为 0.9.2，由 tag v0.9.2 锚定。它增加官方 MCP Registry 元数据和用于安装默认只读 memdsl-mcp 服务的 UV MCPB 包；parser、schema、review、 query、authority 与 MCP tool 合同均与 0.9.1 相同。无论 patch 还是软件版本发布，都不会把 opt-in Edge 提升为 stable，也不会让自动 Edge 生成获得 authority。

quarantine/strict 的真实 rollout 质量、dialect candidate 学习闭环和宿主证明 principal 的集成仍是 experimental/opt-in；但 authorization-before-aggregation、 hard rule 不完整时不得 ALLOW、非权威 edge 不得获得 authority、repair lane 必须可用等安全不变量不是实验性的。CompiledWorkspace 是公共、可重建 handle；其 cache/index 布局、compiler contract 字符串和 synthetic timing 仍是内部事实。
workspace-v3 一等 Edge 保持 experimental；自动方言学习、自动 Edge 候选、inferred authority 与冷历史/增量编译尚未发布。宿主 extractor/sanitizer、私人 schema/policy/ 样本不属于 memdsl，也不构成 release gate。
memdsl 起源于一次召回失败。一个基于 RAG 的记忆系统没能召回一条确实存在的记忆；而一个 coding agent 拿到同样的原始记忆文件，几步就把它找了出来。
同一个模型——差别在上下文契约：agent 知道那条记忆存在，可以一层层读过去；检索器只有一次相似度猜测，而且“没命中”和“不存在”看起来一模一样。

memdsl 把这个差别做成了产品。长期记忆保存在可读、可 lint、可审查的 .mem 源文件里，每个运行时 surface 都为“agent 自己读记忆”而设计：

- 有界记忆目录 Catalog（memdsl catalog、MCP memory_catalog / memdsl://catalog、Python build_memory_catalog）：按 module/type/subject/ status 分页导航，具备 item/byte 硬预算、绑定 revision 的稳定 cursor，并避免 structured/text 双份返回；这是大型 workspace 推荐的会话起始 surface。
- 兼容记忆地图（memdsl map、MCP memory_map / memdsl://map）：旧的 v1 全量索引继续保留，不会被原地改成 Catalog。
- 带倒排索引、会解释 miss 的查询（序列化 pack 中的 search_trace）：确定性的词法 postings 保持 v1 EvidencePack 排序与 authority lane，同时返回 View/source、候选池、filter-hidden match、受限词汇建议和安全 retry query；建议不会写 alias，也不会让 candidate symbol 改写路由。
- 有界关系 Trace（memdsl trace、MCP memory_trace、Python trace_memory）：确定性的 incoming/outgoing/both BFS、relation filter、显式 cycle/back/cross edge、depth/node/edge/byte 硬预算与 revision-bound cursor。
连通性只是导航，不是证明。
- 原始源码兜底（memdsl://file/{file_id}）：agent 随时可以下钻去读真正的声明，就像 coding agent 读代码一样。

当年启动这个项目的那种失败，现在会大声报错——记忆存在，是过滤器藏了它， trace 会把话说明白：

$ memdsl query examples/domains/coding -q "force push main" \
--type coding.bug_pattern --json
"missing": [
"no active declarations matched query terms: ['force', 'push', 'main']",
"1 active declaration(s) matched the query but were excluded by type/subject filters"
],
"search_trace": {
"excluded_by_filters": [
{"id": "coding.project_rule:git.no_force_push", ...}
], ...
}

$ memdsl query examples/domains/coding -q "force push main"
MUST
- [coding.project_rule:git.no_force_push] Never force-push the main branch. (exceptions: []) [status=active; runtime_role=constraint; lifecycle={"status":"active"}]

两分钟在 Claude Code 里跑起来

底层库和 CLI 支持 Python 3.9+。由于上游 MCP SDK 的要求，MCP extra 和 memdsl-mcp server 需要 Python 3.10+。

Python 3.10+
pip install "memdsl[mcp]"
claude mcp add memdsl -- memdsl-mcp --workspace ~/memory # 或任意 examples/ 目录

server 会指示 agent 先读 memory_catalog，只在 Source/View 和过滤条件不变时继续 cursor，把 no_match 当作重试信号，只用 memory_trace 做有界的显式关系导航，并在产出重要草稿前用 memory_check 对照 MUST 约束做预检。旧客户端仍可调用 memory_map。

受治理的类型化记忆

第二根支柱：像审代码一样审记忆，但不要求所有用户接受作者的一套世界观。
v0.8 保留 v0.5 引入的两层类型架构与 v0.6 的 lifecycle 安全审核合同，并加入有界编译导航与显式 workspace-v2 View：

底层通用记录 claim / evidence / scope / confidence / lifecycle / access policy / relations

上层领域类型系统 coding.project_rule / assistant.commitment / writing.voice_preference / 用户自定义类型

底层负责稳定的行为契约，workspace 负责自己的词汇。编程 Agent、个人助理和写作系统不应该仅仅因为 memdsl 作者选择了 preference、boundary、fact 这些词，就被迫用同一套分类描述自己的记忆。

两层架构

底层提供通用字段和五种稳定的 runtime role：

| Runtime role | 在 EvidencePack 中的行为 |
| symbol | 定义其他记忆可以引用的主体 |
| constraint | 只有 active 声明进入 MUST 并参与合规检查 |
| guidance | 只有 active 声明进入 SHOULD |
| assertion | Only enters CONTEXT when the active declaration is relevant |
| question | Only the active declaration enters MISSING, rather than being disguised as a fact |

Any searchable non-active hit only enters PROVISIONAL, regardless of runtime role.
Candidate symbols cannot redirect queries, and candidate constraints cannot enter MUST or
compliance.

The same authority boundary also applies to relationships. Only when the source is active and the full id matches exactly or the
bare ref resolves uniquely can supersedes hide the target. Candidate, retracted,
archived, ambiguous, duplicate, or wrong-kind-prefixed superseders cannot change the query, MUST, or
compliance. This is the v1 correctness/security authority rule that 0.8 continues to retain.
ResolvedView reuses this security foundation and only adds quarantine enforcement on explicit v2 opt-in.

The underlying layer also recognizes capabilities such as requires_evidence, searchable, temporal,
enforceable, guardable, exceptions_recommended, and the explicitly reviewed
opt-in auto_approvable.

The upper layer defines the memory types that the domain truly cares about, and compiles each type into a stable role.
The repository ships with three example domains:

- Programming: coding.project_rule, coding.bug_pattern,
coding.tool_preference
- Personal assistant: assistant.routine, assistant.commitment,
assistant.relationship_context
- Writing: writing.voice_preference, writing.taboo_topic,
writing.style_example

The built-in memdsl.standard@1 compatibility package continues to load legacy types such as entity, fact,
preference, boundary, principle, decision, state,
and open_issue. They are backward-compatible default vocabulary, not the only taxonomy of human memory.

Defining Your Own Domain Vocabulary

A workspace introduces schemas through memdsl.json:

{
"schema_version": "memdsl.workspace.v1",
"schemas": ["coding.memschema.json"]
}

A .memschema.json defines the fields, roles, and capabilities of a type:

{
"name": "coding",
"version": "1",
"types": {
"project_rule": {
"runtime_role": "constraint",
"required_fields": ["claim", "evidence", "scope"],
"optional_fields": ["rationale", "owner"],
"search_fields": ["rationale", "owner"],
"capabilities": [
"requires_evidence",
"searchable",
"enforceable",
"guardable",
"exceptions_recommended"
],
"defaults": {"force": "hard", "status": "active"},
"allowed_forces": ["hard"],
"allow_extra_fields": false
}
}
}

After loading, the full name of project_rule is coding.project_rule:

coding.project_rule git.no_force_push {
subject: Repository.Memdsl
claim: "Never force-push to the main branch."
scope: repository("memdsl")
confidence: high
exceptions: []
rationale: "Published history must remain auditable."
guard {
when_any: ["push", "git", "main"]
deny_any: ["force-push", "--force", "--force-with-lease"]
}
lifecycle { status: active }
access_policy {
readers: [developer, coding_agent]
writers: [maintainer]
reviewers: [maintainer]
export: internal
}
evidence {
source: AGENTS.md
quote: "Do not force-push unless the user explicitly requests it."
}
}

A strict schema rejects undeclared fields. Unknown types produce an unknown_memory_type lint
error and do not silently acquire a set of ad hoc behaviors.

Precise use and workspace-owned dialects

Legacy workspaces remain compatible: when there is no manifest or when memdsl.workspace.v1 is used, it is still
legacy global linking. Only explicit use of v2 enters report or strict:

{
"schema_version": "memdsl.workspace.v2",
"schemas": ["workspace-dialect.memschema.json"],
"linking": {"visibility": "report"}
}

The compiler first builds the module/symbol table for the entire repository, then resolves use X, so declaration order does not affect the result.
X can only match exactly one module or one active symbol name; wildcards, prefixes,
alias，也不设置 module 优先或 symbol 优先。report 保留 legacy 链接并给迁移诊断； strict 会去掉未导入 relation、subject 路由和 dialect 路由的效果。v1 绝不会因为出现了 use 就被暗中切成 strict。

方言仍是 workspace 自己拥有、可版本化、可审核的 Source。schema type 通过通用 dialect_mapping capability opt in，仓库提供了完全虚构、可运行的 examples/dialect/。只有 active、公开、结构有效、无歧义的 positive mapping 才会路由；candidate、pending、private、ambiguous 和 negative mapping 都不会。
no-match 可以返回 search_trace.dialect_candidate 模板，但不会自动写 Source；仍需 evidence、proposal、人工审核、批准和重新编译。

显式 opt-in 的 quarantine enforcement

workspace v2 可以独立开启 v2 读取 gate：

{
"schema_version": "memdsl.workspace.v2",
"schemas": ["workspace-dialect.memschema.json"],
"linking": {"visibility": "report"},
"enforcement": {"mode": "quarantine"}
}

省略 enforcement 或选择 report，仍保持 v1 读取行为。quarantine 与 strict 必须显式 opt in；它们把 Source 分成 authoritative、provisional、 quarantined、excluded，并使用新的 query/list/explain/check/Catalog/Trace v2 envelope。空结果会明确区分 no_match、quarantined、unauthorized、 compiler_error 与预算不足。identity-critical 错误 fail closed，relation/use/ dialect/type 错误则尽量只隔离最小安全的 declaration、文件或 revision family。
lint、直接编辑 Source、proposal、review 和 audit 修复通道仍然开放。

Map 保持 v1 兼容面，在显式 enforcement 下返回 unsupported_view；应改用 Catalog、query、list、explain 或 Trace。pending proposal 仍不会进入 durable View，candidate/private/ambiguous dialect 也不会借 quarantine 获得路由权。

安装与类型发现

基础包支持 Python 3.9+：

pip install memdsl # 或在 checkout 中运行 pip install -e .
memdsl --version
memdsl types examples/domains/coding
memdsl lint examples/domains/coding --json
memdsl catalog examples/domains/coding --json
memdsl map examples/domains/coding
memdsl query examples/domains/coding -q "force push main"
memdsl trace examples/alex decision:aurora.pricing_free_tier --both --depth 2 --json
memdsl check examples/domains/coding \
-t "push main" \
-c "git push --force origin main"

memdsl types 会列出已加载的标准类型和领域类型，以及各自的 runtime role、必填字段、capability、schema 版本和来源。需要给其他工具消费时可加 --json。

memdsl lint --json 输出与文本模式完全相同的诊断，包在 memdsl.lint.v1 信封里：每条诊断的 code、severity、文件、行号、声明 id，加上计数和与退出码一致的 status（ok、errors 或 strict_warnings）。

上面的自定义类型不需要在 Python 代码里写死 coding.project_rule，依然会作为 MUST 约束出现：

MUST
- [coding.project_rule:git.no_force_push] Never force-push the main branch. [status=active; runtime_role=constraint; lifecycle={"status":"active"}]

合规检查会返回 BLOCK 并引用同一个领域声明。没有 guard 或不具备执行能力的约束会安全返回 NEEDS_REVIEW，不会假装已经理解。

分层查询契约

查询返回的是 EvidencePack，而不是扁平命中列表：

- MUST：适用的 constraint
- SHOULD：相关的 guidance
- CONTEXT：相关的 assertion
- PROVISIONAL：带分数的非 active searchable 声明
- CONFLICT：已声明的冲突
- MISSING：相关的 question 和已知信息缺口

每一项都携带稳定 id、类型、runtime role、capability、claim、subject、scope、 confidence、lifecycle、access policy、evidence 和源码位置。这样领域语义可以扩展，运行时行为仍然稳定。

JSON 输出仍为 memdsl.evidence_pack.v1；v0.6 加入的 provisional 在 v0.8 继续保持 additive。带分数的 CONTEXT 和 PROVISIONAL 条目都包含 score、 matched_terms，每个 declaration item 还明确携带 lifecycle status 和运行时角色。

参考实现使用可重建的词法倒排索引。生产系统可以在同一个 EvidencePack 契约后面替换成 BM25、embedding、图或数据库索引。

导航：先读有界 Catalog，再查询和下钻

memdsl 的出发点是“让 agent 自己读记忆”胜过“让相似度匹配替 agent 决定”：知道某条记忆存在的 agent 可以一层层钻下去，而检索器一旦没命中就什么都没有。
四个 surface 支撑这个闭环：

- 有界 Catalog（memdsl catalog、MCP memory_catalog / memdsl://catalog、Python build_memory_catalog）：按 module 汇总，并可按 module/type/subject/status 过滤。默认 20 items / 8192 canonical compact UTF-8 JSON bytes；truncated、next_cursor、returned_items、精确 total 和词表 total/truncated metadata 都显式返回。cursor 绑定 Source fingerprint、 report-only View、过滤条件、顺序和 representation；Source 改变会返回 cursor_stale。
- Map v1 兼容面（memdsl map、MCP memory_map / memdsl://map、Python build_memory_map）：继续为旧客户端返回全量可服务声明索引，但不再推荐作为大型 workspace 的会话起始 surface。显式 workspace-v2 enforcement 下会返回 unsupported_view。Map 与 Catalog 都只是导航，不是引用来源。
- 检索痕迹（序列化 pack 中的 search_trace）：记录查询被如何解释，以及使用了哪些 index、过滤前后候选池，以及 type/subject filter 排除了哪些本来匹配的声明。no-match 可返回有界 vocabulary_suggestions 与 retry_queries；candidate、歧义或 access-restricted 词汇不会成为自动路由。
- 有界 Trace（memdsl trace、MCP memory_trace、Python trace_memory）：沿已解析的显式关系做确定性 BFS。默认 depth 3、20 nodes、 40 edges、8192 bytes；cursor 绑定 Source/View、anchor、direction、relation、 depth 与 provisional visibility。back/cycle/cross edge 显式返回，但连通性不是 evidence 或 proof。
- 只报告、不隔离的链接诊断（memdsl lint、MCP memory_lint 与 memdsl://status）：duplicate id、歧义/错误前缀/dangling target、未知 relation、 revision cycle 和 supersede fork 都会显式出现。cycle edge 不会让参与节点全部消失，fork 不会暗选 winner，而默认 Map/query authority 仍保持 v1 兼容。

执行前约束检查

任何被 schema 编译为 constraint 的类型都可以参与 memdsl check。要执行确定性的 guard，该类型必须同时声明 enforceable 和 guardable。短语与正则 guard 返回 ALLOW 或 BLOCK；只有自然语言的约束返回 NEEDS_REVIEW。
例外必须由调用方通过 --exception 显式声明。

v0.4 的标准 boundary 也走同一条通用链路。boundary_id、 applicable_must 等旧 JSON 字段仍作为兼容别名保留。

memdsl eval compliance examples/compliance \
--cases examples/compliance/cases.jsonl --json

memdsl eval compliance examples/domains/coding \
--cases examples/domains/coding/cases.jsonl --json

作为 MCP server 使用

MCP server 需要 Python 3.10+：

Python 3.10+
pip install "memdsl[mcp]"
memdsl-mcp --workspace examples/domains/coding --inspect
memdsl-mcp --workspace ~/memory

MCP server 提供：

- tools：memory_catalog、memory_map、memory_types、memory_query、memory_trace、memory_check、 memory_explain、memory_list、memory_lint、memory_propose、 memory_review_list
- resources：memdsl://status、memdsl://catalog、memdsl://map、memdsl://types、
memdsl://files、memdsl://file/{file_id}

Agent 应该在会话开始时读取 memory_catalog，让导航成本不随 workspace 总量线性膨胀，再用 memory_query 与有界 memory_trace 局部下钻；memory_map 继续服务 v1 客户端。在提出新声明前，应该先调用 memory_types 或读取 memdsl://types，发现当前 workspace 的词汇，而不是自己发明类型，也不是默认标准兼容包就是唯一世界观。

可通过 --scopes 或 MEMDSL_MCP_SCOPES 缩小 MCP 权限范围，默认值为 read:summary,read:search,write:candidate。底层会表示、验证并传输声明级 access_policy。在 enforced View 中，嵌入式宿主只能在构造 MemdslMCPService 时注入可信 principal 与 roles；MCP tool 参数不能自报身份。
过滤发生在 count、vocabulary、diagnostics、graph traversal 和 raw-file resource 之前。memdsl 不提供身份提供商；宿主仍需认证 principal 并映射 roles。

受审查的写入

每次 MCP 写入仍然先成为 proposal。新声明必须使用已加载类型，能够解析，并通过当前 workspace 的 lint。非法 proposal 会被拒绝；与 pending/approved 内容完全相同的提交返回 no_op；其余 proposal 要么排队，要么由宿主证明过的窄策略自动批准。

默认仍然全部人审。先生成一份合法但禁用自动批准的 policy：

memdsl review policy init memory
memdsl review policy show memory
memdsl review policy validate memory

生成的 JSON 里 trusted clients 和 rules 都为空，日限额为 0。要开启自动化， workspace owner 必须给一个 candidate assertion 类型显式加入 auto_approvable，配置精确 kind 规则和可信宿主 client，设置正数日限额，再授予默认不包含的 write:auto scope：

memdsl-mcp --workspace memory \
--scopes read:summary,read:search,write:candidate,write:auto

内置 workspace_file_quote verifier 要求 evidence.source 解析到已加载 workspace root 内，且 evidence.quote 必须逐字出现在该 UTF-8 文件中。
question、guidance、constraint、symbol、active、global、带 warning、带破坏性关系或证据未验证的 proposal 始终排队。没有 write:auto 时，合法 policy 处于 shadow 姿态：写入仍 pending，但 eligible_route 会记录策略原本会怎么做。

人工操作与质量反馈保持显式：

memdsl review list memory
memdsl review approve memory PROPOSAL_ID --into memory/approved.mem
memdsl review reject memory PROPOSAL_ID --reason "not durable"
memdsl review digest memory
memdsl review stats memory
memdsl review audit memory PROPOSAL_ID --verdict confirm

review list、review show、review audit 与已有的 policy show、digest、 stats 一样支持 --json，队列面板或 CI 任务不必再解析给人看的文本。approve 与 reject 仍然只有文本输出，保持决策动作显式。

进程内宿主应传入权威 workspace paths：

from memdsl import (
ProposalContext,
ReviewStore,
Workspace,
load_policy,
staging_dir_for,
)

workspace = Workspace.load(["memory"])
store = ReviewStore(staging_dir_for(["memory"]))
policy = load_policy(store.staging_dir, registry=workspace.registry)
assert policy is not None
context = ProposalContext(client_id="mcp-client")

result = store.submit(
["memory"],
proposal_source,
policy=policy,
context=context,
write_auto_granted=True,
)

自动批准前会重新加载并 fingerprint 记忆、manifest 和 schema，重新验证证据，执行有限 UTC 日配额，只写入主 workspace root 内的非 symlink .mem 目标，且绝不使用 force。路由 assessment、decision、post-review 结果、digest cursor 和 no-op 事件都保持 append-only。

post-review flag 不会静默删除记忆。晋升、修订和撤销都要提交一条新 id 的人工审核声明，用 supersedes（可同时用 revision_of）指向旧声明。successor 必须是 lifecycle active 才获得关系 authority；旧声明不需要原地改成 status: superseded。
ReviewStore 不创建 Git commit；宿主可以增加 Git 集成，但核心正确性不依赖 Git。

包里有什么

- 与领域无关的 .mem 通用记录：来源、scope、confidence、lifecycle、 access policy、relations 和稳定 id。
- 可扩展、带 namespace 的 .memschema.json 类型系统和 workspace manifest。
- 面向 v0.5 之前 workspace 的标准兼容类型包。
- schema 驱动的 linter、分层查询、explain 和确定性 Compliance Gate。
- CLI 与 MCP 的类型发现能力。
- 默认安全、宿主证明的审核链路：人工队列、确定性的窄范围自动批准、no-op 检测、digest/stats 和 append-only audit。
- 可复现合规 benchmark，以及 coding、assistant、writing 三个领域包。
- Alex、Mira 两个虚构标准示例和一个故意损坏的 lint 示例。
完整语法与语义见 docs/SPEC.md。进程内宿主还应阅读 docs/PUBLIC_API.md 和 docs/UPGRADING.md。
审核策略的安全合同见 docs/DESIGN_review_policy.md。
文档索引 把软件合同、实现设计、发布边界和可复现材料集中在一起。

memdsl 不是什么

- 它不是 Mem0、Zep、Graphiti、LangMem 等检索/抽取系统的替代品，而是位于这些系统之上的受治理源格式和行为契约。
- 它不是人或记忆的通用分类法；领域所有者定义自己的类型。
- 它不是语义策略裁判；无法确定性执行的约束会保持 NEEDS_REVIEW。
- 它不是不受限制的自动记忆写入器。只有显式 opt-in、身份可信且证据已验证的 candidate assertion 才可能自动批准；所有高风险或不确定 proposal 仍由人审。

当前证据与边界

这个项目来自一个私有的单用户系统。该系统的内部评测曾显示，DSL 结构化检索的 precision 高于它自己的调优 RAG baseline。这个结果值得继续验证，但不能证明一套 ontology 对所有人都通用。v0.8 正面承认这个限制：memdsl 标准化记录结构和运行契约，把领域词汇的所有权交还给使用者。

仓库内置的是确定性的契约级测试。跨模型行为结论仍需单独记录真实模型运行。

Roadmap

- 两层 core + 可扩展领域类型系统 — v0.5 已完成
- lifecycle 安全的 provisional 服务 + 分级审核策略 — v0.6 已完成
- 公共可重建 CompiledWorkspace + 有界 Catalog 分页/预算— 0.9.0 已发布的 stable/public 0.8 合同
- 倒排查询 + 有界 Trace + exact use/report/strict + 受审核 Dialect — 0.9.0 已发布的 stable/public 0.8 合同
- 显式 v2 envelope 下的 opt-in quarantine enforcement — schema/安全合同 stable/public，真实 rollout 质量仍为 experimental
- 显式 opt-in 的一等可审核 Edge 实验 — 0.9.0 以 experimental 状态承载该能力，依据匿名探索性 Pilot 开启；relation/evidence 收窄结论仍为 ADJUST，不是正式实证验证
- 冷历史/增量编译 — 等待代表性规模、SLO 与生产瓶颈证据
- Schema 包分发、依赖/版本约束和迁移机制
- 更丰富的字段验证器和领域诊断规则
- EvidencePack 后面的可插拔检索后端
- 执行 access policy 的身份提供商适配器
- 基于 shadow/sample/post-review 数据的语义冲突 reviewer 与 per-client/per-rule 配额

许可证

代码：MIT。规范（docs/SPEC.md）：CC-BY-4.0。