企业官网建设流程全解析

ai-memory init 详解：wiki/db/raw/logs 数据目录结构大起底

【免费下载链接】ai-memorySolution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors项目地址: https://gitcode.com/GitHub_Trending/ai/ai-memory

一分钟看懂：ai-memory init 是干什么的

ai-memory是一个面向编码 Agent CLI（如 Claude Code、Codex、Cursor 等）的AI 长期记忆系统，帮你的 Agent 跨会话、跨厂商保留项目知识。而ai-memory init是安装后要执行的第一步命令：它会一次性创建wiki、raw、db、logs等数据目录，并生成默认配置文件，是整个记忆系统的"地基"。

这一篇文章带你起底这套数据目录结构：每个目录存什么、谁可读、能不能手改，以及新手最常问的几个问题。

一键初始化步骤：30 秒完成

在终端执行：

ai-memory init

这条命令做了三件事（源码见crates/ai-memory-cli/src/commands/init.rs）：

1. 创建数据根目录（默认~/.local/share/ai-memory/），权限自动设为仅属主可读写；
2. 创建 4 个子目录：wiki、raw、db、models；
3. 生成默认配置config.toml（模板来自crates/ai-memory-cli/templates/config.default.toml），并自动写入一个随机token_pepper用于多用户场景的令牌加盐。

💡幂等设计：重复执行init是安全的——已存在的目录和配置不会被覆盖。确需重置配置时才加--force。

初始化后的目录结构如下：

~/.local/share/ai-memory/ ├── config.toml # 服务配置（绑定地址、衰减参数、认证等） ├── wiki/ # Markdown 知识库（长期记忆的"真相源"） ├── raw/ # 不可变的原始观测数据（JSONL 分段） ├── db/ │ └── memory.sqlite # SQLite 派生索引（全文/向量检索） ├── models/ # 预留目录，放本地嵌入模型 └── logs/ # 按天滚动的运行日志

wiki 目录：唯一"真相源"，可以手改

wiki/是整个系统最重要的目录，存放由 LLM 从你的 Agent 会话中提炼出来的 Markdown 知识页面，按工作区/项目组织，例如concepts/、decisions/、gotchas/等子目录。

它的几个关键特性：

• Git 版本化：wiki 本身是一个 Git 仓库，每次记忆整合、每次会话结束都会产生一次提交，改错了可以直接回滚；
• 可人工编辑：用 Obsidian 或 vim 直接改 Markdown 即可，文件监听器会自动把外部修改同步回索引；
• 持久可靠：SQLite 索引丢了可以重建，但 wiki 里的 Markdown 才是不会丢的"源数据"。

下面这张图就是 wiki 内容通过 Web 界面浏览的效果（ai-memory 的 wiki 项目视图）：

db 目录：可随时重建的"派生索引"

db/memory.sqlite是一个 SQLite 数据库，存放的是派生索引而不是源数据：页面全文检索（FTS5）、链接图谱、会话记录、嵌入向量等。所有搜索命令（ai-memory search、MCP 的memory_query）都走这里。

📌 新手记住一句话：wiki 是书，db 是书签索引。索引损坏或升级出问题时，重建索引即可，不会损失 wiki 里的知识。

raw 与 logs：两个"兜底"目录

• raw/：存放经过清洗（sanitize）的、不可变的观测数据（JSONL 分段），是 wiki 页面背后的"原始证据"。Agent 可以回溯某条记忆最初来自哪次会话，但正常情况下你不用碰它；
• logs/：CLI 和服务器写入按天滚动的日志（默认为~/.local/share/ai-memory/logs/）。排障时优先看这里。值得注意的是，如果该位置不可写（例如只读沙箱环境），ai-memory 会降级到系统临时目录或仅输出到 stderr，命令依然可用，而不是直接报错。

config.toml 里的安全细节，值得一看

init生成的配置文件默认权限为600（仅属主可读写），数据目录为700，属于"防御默认"式设计：

• token_pepper自动生成：每次全新安装都会产生不同的随机值，用于让窃取的用户令牌哈希在离线环境下失效；
• 多用户可选：配置里预留了root_username等多用户归因字段，单机单人场景保持默认即可；
• 配置可分离存放：init支持--config /etc/ai-memory/config.toml把配置放到数据目录之外，数据根目录不变，方便 systemd 等系统服务部署。

初始化之后：打开 Web 界面验证效果

服务跑起来后（ai-memory serve），浏览器访问默认端口49374就能看到你所有工作区和项目的 wiki 概览——每个项目卡片显示页面数量与最近活跃时间，这是验证 init 是否成功的直观方式：

新手常见问题（FAQ）

Q1：重复执行ai-memory init会破坏数据吗？不会。目录创建是幂等的，已有config.toml时默认跳过写入，只有显式--force才会覆盖。

Q2：数据目录能放到别的位置吗？可以。通过--data-dir参数或环境变量AI_MEMORY_DATA_DIR指定，init会在你指定的位置创建同样的结构。

Q3：raw 和 wiki 到底哪个是"真"的？两者分工不同：wiki 是提炼后的长期知识（真相源），raw 是不可变的原始观测证据。前者面向检索与阅读，后者面向审计与回溯。

小结

跑完ai-memory init后，建议定期备份wiki/（它是 Git 仓库，天然适合版本管理），其余目录基本可以"设置后忘了它"。更多细节可参考项目文档docs/ARCHITECTURE.md与docs/install.md。

【免费下载链接】ai-memorySolution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors项目地址: https://gitcode.com/GitHub_Trending/ai/ai-memory