Ameki

Knowledge base manager with Agent kernel

Ameki 是一个 CLI 工具，内置 pi-mono Agent 作为知识提取引擎。人类写 raw/*.md，Agent 维护 wiki/。

核心特性

• Agent 自主探索 — Agent 自己决定如何读取和理解文档，不被预设流程束缚
• 交互式 TUI — 运行 ameki 启动终端 UI，多轮对话、流式输出、Markdown 渲染
• 状态最小化 — Agent 会话状态是临时的，只有知识库文件是持久状态
• 写入安全 — 所有写操作通过 Writer 模块，失败自动回滚
• 可配置 — 通过 settings.json 配置语言、模型等参数

快速开始

bun install
bun run dev init my-kb

# 创建 .env 文件（API key 等配置）
cp .env.example .env
# 编辑 .env 填入 AMEKI_API_KEY 等

# 放入原始资料
cp data/raw/*.md my-kb/raw/

# Agent 驱动摄入
cd my-kb
bun --env-file=../.env run ../src/cli.ts ingest agent_project.md

# 询问知识库（交互式 TUI，支持多轮对话）
bun --env-file=../.env run ../src/cli.ts

# 或非交互式单次问答
bun --env-file=../.env run ../src/cli.ts ask "agent有哪些能力？"

# 重建索引
bun --env-file=../.env run ../src/cli.ts rebuild-index

命令

| 命令 | 说明 | |------|------| | ameki | 启动交互式 TUI，多轮对话问答（流式输出） | | ameki init [path] | 初始化知识库 | | ameki ingest <file> | 摄入 raw 文件，Agent 分析并写入 wiki | | ameki reingest <file> | 增量更新：对比内容变化，只修改受影响的部分；无缓存时自动全量重摄入 | | ameki ask <question> | 基于知识库回答问题（非交互式，单次问答） | | ameki feedback <page> <feedback> | 对已有 wiki 页面应用人类反馈 | | ameki lint [--links] [--freshness] [--conflicts] | 验证（默认全部）；--links 只检查链接（broken links + source refs + backlinks）；--freshness 只检查时间敏感性；--conflicts 只检查冲突 | | ameki rebuild-index | 从 wiki 页面重建 index.md | | ameki status | 显示知识库状态 | | ameki log [--limit N] [--since <date>] [--page <path>] | 查看操作历史 |

配置

~/.ameki/settings.json（用户级配置，不会被 git 上传）:

{
  "language": "bilingual",
  "model": {
    "name": "qwen-plus",
    "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
    "contextWindow": 128000,
    "maxTokens": 8192,
    "reasoning": false
  },
  "ingest": {
    "maxTopics": 5
  },
  "webSearch": {
    "provider": "searxng",
    "apiKey": "",
    "baseUrl": "https://your-searxng-instance.com"
  }
}

环境变量覆盖 file 设置：AMEKI_MODEL, AMEKI_BASE_URL 等。

language 支持：zh, en, ja, ko, es, fr, de, pt, ru, ar, hi, id, vi, th, bilingual

目录结构

~/.ameki/settings.json       # 用户配置（API key、模型偏好）
raw/                         # 原始资料（只读）
wiki/                        # Agent 维护的知识库
│   ├── sources/             # 每篇 raw 的摘要
│   └── topics/             # 知识主题（深入解释）
.ameki/                      # 系统文件（运行时数据）
│   ├── backup/             # 写操作备份
│   ├── cache/              # 分块缓存（支持增量更新）
│   └── logs/
│       └── history.jsonl   # 操作历史

Agent 工具

在 ask 模式下，Agent 可用：

• read_document — 读取文件
• ls — 列目录
• grep — 搜索文件内容
• find — 查找文件
• glob — 模式匹配文件
• search_wiki — 搜索 wiki 内容
• web_search — 网络搜索
• web_fetch — 获取网页内容

在 ingest/feedback 模式下，Agent 额外可用：

• write_page — 创建或更新 wiki 页面
• remove_page — 删除 wiki 页面

安全限制：路径遍历保护、禁止符号链接逃逸。

安装

bun install
bun run build   # 构建二进制到 dist/ameki

开发

bun run dev <command>   # 推荐：自动加载项目根目录的 .env

架构

CLI 命令
  └── Agent (pi-mono)
        └── tools (read_document, ls, grep, find, glob, search_wiki, web_search, write_page, ...)

核心模块
  ├── Reader           — 纯读文件
  ├── Writer           — 唯一写入口（带验证和回滚）
  ├── Chunks           — 文档分块（按 header 切分，支持增量更新）
  ├── BacklinksIndex   — 双向链接索引
  ├── Settings         — 配置管理（env > file > defaults）
  └── validators/
        ├── basic       — frontmatter 验证
        ├── links       — 链接完整性验证
        ├── backlinks   — 反向链接索引一致性验证
        └── source      — 来源引用验证

设计来源

• Karpathy 的 LLM Wiki 模式
• pi-mono — Agent 内核