crystalline

容器中运行 Crystalline 发布了一个多架构的 OCI 镜像（`linux/amd64` 和 `linux/arm64`），用于 Linux 服务器部署，每次发布都会推送到 GHCR。macOS 和 Windows 没有值得针对的 OCI 容器运行时，因此这些平台会运行原生二进制文件；容器仅涵盖 Linux 服务器场景。 有两个镜像变体以相同的名称、不同标签发布： | 标签 | 大小 | 嵌入模型 | 最适合 | | --- | --- | --- | --- | | `latest`（或固定的 `vX.Y.Z`） | 约 15 MB | 在后台下载模型（首次守护进程启动时需要） | 常见情况：具有正常互联网访问的主机，首次启动时短暂的模型下载时间可接受 | | `with-model`（或固定的 `vX.Y.Z-with-model`） | 约 145 MB | 模型嵌入在镜像中，无需下载 | 无网络访问的主机，或需要立即进行语义搜索的主机 | 选择 `with-model` 变体时，主机没有外部网络访问或不希望首次启动下载延迟；否则选择精简的 `latest` 变体，因为它是拉取和更新较小的镜像。 ```sh docker pull ghcr.io/jordiboehme/crystalline:latest # 或：docker pull ghcr.io/jordiboehme/crystalline:with-model docker run -d \ --name crystalline \ -p 7411:7411 \ -v "$(pwd)/knowledge:/knowledge" \ -v crystalline-data:/data \ ghcr.io/jordiboehme/crystalline:latest ``` 数据持久化位置： - `./knowledge`（绑定挂载）保存每个文件域的 engrams，一个域一个子文件夹 - 文件支持知识的持久状态，与原生二进制文件读取的 markdown-plus-frontmatter 文件完全相同。 - `crystalline-data`（命名卷，挂载在 `/data`）保存搜索索引和嵌入模型缓存。对于文件域，它可以完全重建：丢失它会花费 `crystalline reindex --full` 和模型重新下载（在 `with-model` 上跳过，因为其模型位于 `/data` 之外，不受卷影响），但不会丢失数据。如果运行虚拟域，它们的 engrams 是真实来源，也存储在这里，因此备份此卷或将它们导出到绑定挂载中以保留文件副本。 `with-model` 变体设置 `CRYSTALLINE_MODELS_DIR`（也可以在任何安装上直接设置，以将模型缓存重定位到其他位置）到 `/data` 之外的路径，因此嵌入的模型永远不会被 `/data` 卷挂载所遮蔽。捆绑的模型是 [BAAI/bge-small-en-v1.5](https://huggingface.co/BAAI/bge-small-en-v1.5)，MIT 许可。 三个示例 Compose 文件位于 [`examples/docker/`](examples/docker/) 下： - **`compose.yaml`** - 上述单容器设置，以及用于引导新域的注释过的 `domain init` / `domain add` 配方（`domain add` 立即索引它，通过共享的 `/data` 卷路由到正在运行的守护进程）。 - **`compose.git-sync.yaml`** - 可扩展部署变体，添加了一个 sidecar，每 60 秒将知识文件夹从 git 远程同步，挂载为只读到 Crystalline。这是团队管理 engrams 作为评审的 git 仓库而不是直接写入容器中的模式。 - **`compose.postgres.yaml`** - 上述共享数据库协作设置：Postgres 服务与 pgvector 以及通过挂载的配置文件指向它的 Crystalline 实例，以及注释的第二个实例，展示了第二个工作者如何共享同一个数据库。 ### 只读部署 在 `serve`（或 `mcp`）中传递 `--read-only`，配置文件中设置 `_only: true`只读模式提供内容四个内容变更工具（_engram`、`edit`、`move_engram` 和 `delete_engram`从 MCP 工具消失，如果客户端调用其中会拒绝，而 `search_eng、`read_engramlist_domains` 和工具保持不变。同步监视器和嵌入保持运行，因此索引仍然遵循外部编辑，如 git pull。`crystalline prompt system` 遵循相同的模式：它会删除写入指导，并指出知识是外部策划的，而 `--read-only` 强制按需变体。这是 `compose.git-sync.yaml` 中 git-sync 设置的自然配对，其中知识通过评审的到达，代理仅。模式在守护生命周期内固定，因此正在运行的的代理将获得该守护模式。主机上的工具（`verifyimport`、``/`add`/` `model download`）不受影响：边界是提供只读 API，而不是机器。 代理通过其 HTTP MCP 端点化的守护进程，从主机http://localhost:7411镜像的默认命令为 `serve --http 0.0.01`，因为绑定每个接口才能可访问 - 在容器内绑定 `0.0.1` 仅在同一容器访问）。来自上面的 Connect stdio ` mcp` 传输非容器化进程；ystalline 在容器中工具绑定到 HTTP 端点 会话接入 开始时运行 ` prompt system`，并作为上下文提供给代理每个已注册域MANIFEST.md`，一个紧凑的路由每行总结一个方法，以及行为规则（ -> 搜索该域查询 -> 扫描；写入始终显式域）。输出命名了引用的确ystalline MCP 工具（_engrams`、`write_engram` 等），因此具有多个 MCP 服务器连接的代理确在哪个服务器上调用哪个工具。`prompt接受一个子命令，生成的提示类型； 是目前唯一的类型sh crystalline prompt system --workspace . ``` 将其通用配方中的工具：在运行 `crystalline prompt system`在代理执行任何操作之前将标准为上下文。在 Claude Code 中 `settings.json` 中的 `SessionStart` ： ```json { "hooks": { Start": [ "matcher": " "hooks": [ ": " "command": "cr system" } } ] } 任何具有等效会话工具都可以以运行相同的命令。 ## 教学和学习 M暴露了 12 种工具；捕获知识是工作中的副产品，这是核心循环： - **`write_engram`** - 捕获新的 engram。始终需要 `domain`（写入没有默认域，因此代理永远不会写入错误的位置）。`permalink`、`status` 和 `recorded_at` 将为您填写。 search_engrams`** - 在编写之前搜索以回忆已经知道的内容。每个域的加语义排名；传递 `domains` 以缩小范围，或按 `type`、`tags`、`status` 或任意 `metadata_filters` 进行筛选，而不使用查询文本。 edit_engram`**原地完善 engramappend`、`prepend`、`find_replace`、`replace_section`、`insert_before_sectioninsert_after_section`），同一主题创建副本 **`build_context`** - 给crystalline://malink` 锚点，遵循其关系和跨域）以组周围的邻域深入研究。 观察是 engram 正文的原子单位级项目符号，如 `- [ 我们选择 Postgres路径 #database`。自由文本；有包括 `decision`、`、`pattern`、``、`convention`、`、`risk`idea`。关系连接 engrams：`- depends_on [[Other Engram]]` 或 `- "relates to" [[Other Engram]]` 表示多词关系类型。 时间字段是普通的，容易出错的：缺少的 `valid_from` 表示 engram 一直有效，缺少的 `valid_to` 表示它永远有效。永远不要编写一个哨兵式的远期日期 - 只需省略该字段。只有当事实时间限制时才设置它们（已知日期更改的临时解决方法）。` 和 `type` 的值集，在工具明确说明（状态：`current`、`draft`、`idea`、`deprecated`、`superseded` 等；类型：`engram`、`guide`、`decision`、`architecture`、`runbook`、`reference`）- 它们存在于代理可以区分想法和当前事实，并且是指导，而不是全局枚举，写入会被拒绝。 CLI 直接镜像变更和读取工具，用于脚本编写和快速编辑外部代理会话：`crystalline write`、`read``、`move`、`、`search`、` 和 `recent` MCP 对应工具。 ## 保持实 `cr` 静态检查一个或多个域的完整规则目录 - 格式错误的 frontmatter、损坏的链接、缺少的 MANIFEST 部分、模式漂移 - 无需数据库、服务或网络连接。 在 CI 中使用捆绑的 GitHub Action 运行： ```- uses: jordhme/crystalline@v1 with: paths: knowledge/ strictfalse' ``` 一个固定的发布二进制文件验证），运行 `crystalline verify`，注释运行，并在拉取请求上摘要注释，在原更新。 另外两个知识库值得信赖： - **`crystalline import> --domain <name>`** 将现有的 markdown-plus-frontmatter 知识库置于 Crystalline 之下化旧的 ` 值、补充 `status时间元数据、期日期以留空并添加缺少的 - 所有这些都是转换，具有 `--` 预览。 crystalline doctor`** 诊断索引、注册域和服务状态（孤立索引行、过锁），并使用 `--fix修复。 ## 技能 `skills/` 文件夹提供了三个与工具无关技能，教会代理使用 Crystalline： **`crystalline-routing`** -任务应使用、何时扫描每个域、何时回退到 MANIFEST。 - **`crapture`** -值得记录捕获的知识、搜索写入前避免重复、 engram 而不是分叉主题，以及保持 engram 有用的观察类别和约定。 - **`crystalline - 为需要结构的域编写 Picoschema engram、从的内容推断模式、性。 每个都是一个带有 `SKILL.md普通文件夹；通过将文件夹复制到工具链查找安装。对于 Claude是项目中的 `./skills/` 或 `~/.claude/sk： ```cp -r skillsystalline-routing skills/crystalline-capture skills/cr ~/.claude/sk``` 其他支持类似技能文件约定的可以直接指向相同的目录仅假设上述 12 个工具，从不工具链。 ## ``` crystalline 格式层：解析器、发射器、P验证、提示 | （无异步运行时、无数据库、无 ML - 保持静态） v crystalline-index 存储特征、嵌入式数据库、同步引擎、搜索、嵌入 | v crystalline-service 单实例守护进程、MCP 工具路由器、控制协议 | v crystalline (cli) 用户界面二进制文件 ``` 只有一个进程曾经打开过数据库：第一个 `crystalline mcp`ystalline serve` 获取一个咨询锁并成为守护进程；每个后续的 CLI 命令或 MCP 连接都通过接字附加到当没有运行时守护直接打开数据库进行简短操作。 ## 路 - 通过 git库进行版本控制和 为可选的传输提供身份验证绑定地址如何，都验证。在 `1270.1下，这是可以容器镜像绑定 `00.0`，因此主机上的代理它，因此将网络访问控制，直到此## 许可证ero 通用 v3.0阅 [LICENSE)。