kioku (Sanzoku Labs)

Kioku-面向开发人员的AI上下文记忆

版本2.0 |AI编码助手的持久、自我丰富的上下文管理

Kioku (記憶,日语中的“记忆”）是一个MCP（模型上下文协议）服务器，为Claude和Zed等AI编码助手提供智能上下文管理，帮助他们在会话中记住你的项目。

这解决了什么问题？

• 🧠 AI助手忘记 会话之间的项目
• ⏱️ 你浪费了10-15分钟 每次会话都会重新解释您的架构
• 💾 上下文窗口饱和 包含无关信息
• 📚 没有学习积累 跨编码会话

Kioku的承诺： 零手动上下文管理，同时您的AI对您的项目越来越聪明。

______________________________________________________________________

✨ v2.0中的新增功能

🚀 引导登机

• 带有API密钥验证的交互式设置向导
• Claude Desktop和Zed的自动配置
• 一个开始命令： kioku setup

🏥 健康诊断

• 系统健康检查 kioku doctor
• 常见问题的汽车维修
• 性能诊断和警告

📊 可视化仪表板

• 实时项目概述 localhost:3456
• 会话时间线和模块图
• 嵌入和上下文窗口统计信息

⚡ 高级上下文智能

• Git集成（日志、责备、差异）
• 利用人工智能优化发现提取
• 多项目工作空间支持
• 基于AST分析的智能组块

______________________________________________________________________

📦 Monorepo结构

Kioku被组织为一个包含4个包的monorepo：

packages/
├── shared/      # Shared utilities, types, error classes
├── api/         # Core business logic (MCP server, domain, application, infrastructure)
├── cli/         # Command-line interface (commands, logger)
└── ui/          # Dashboard web interface (React + Vite)

构建命令：

bun run build          # Build all packages (shared → api → cli → ui)
bun run build:api      # Build API package only
bun run build:cli      # Build CLI package only
bun run build:ui       # Build UI package only

质量门：

bun run quality-gate   # Type check + lint + tests
bun run type-check     # TypeScript strict mode
bun run lint           # ESLint with architecture boundaries
bun test:api           # Run API tests (338 passing)

文档：

• 📚 Monorepo使用指南 -日常开发工作流程
• 🏗️ 建筑 -包依赖关系和原则
• 🔄 回滚指南 -安全和回滚程序

______________________________________________________________________

快速开始

1.安装和设置（2分钟）

# Clone and build
git clone https://github.com/yourusername/kioku.git
cd kioku
bun install
bun run build

# Interactive setup wizard
kioku setup

安装向导将：

• ✅ 验证您的API密钥（OpenAI/Anthopic）
• ✅ 配置编辑器（Claude Desktop或Zed）
• ✅ 初始化您的项目
• ✅ 自动创建MCP配置

2.开始使用Kioku

# Check system health
kioku doctor

# View dashboard
kioku dashboard

# Show current context
kioku show

3.你的AI现在有超能力了！ 🦸

在Claude Desktop或Zed中打开您的项目。您的AI助手可以自动访问：

MCP资源：

• context://project -项目背景（架构、技术栈、模式）
• context://modules -模块文档
• context://session_history -最近的编码会话摘要

MCP工具：

• context_search -跨项目知识的语义搜索
• read_file -具有自动跟踪功能的文件访问
• grep_codebase -具有上下文感知的模式搜索
• git_log, git_blame, git_diff -Git历史分析

______________________________________________________________________

📚 CLI命令

核心命令

# 🚀 Setup & Initialization
kioku setup                    # Interactive setup wizard (recommended!)
kioku init                     # Initialize current project

# 🔌 Server
kioku serve                    # Start MCP server (auto-started by editor)

# 📊 Information
kioku show                     # Display context overview
kioku status                   # Show system health & statistics

# 🏥 Diagnostics
kioku doctor                   # Run health checks
kioku doctor --repair          # Auto-fix detected issues
kioku doctor --verbose         # Detailed diagnostics
kioku doctor --export report.json  # Export diagnostics report

# 📈 Dashboard
kioku dashboard                # Start visual dashboard (localhost:3456)
kioku dashboard --no-browser   # Start without opening browser
kioku dashboard --port 8080    # Use custom port

# 🧹 Maintenance
kioku cleanup-sessions         # Clean up orphaned sessions
kioku cleanup-sessions --dry-run    # Preview cleanup
kioku cleanup-sessions --force      # Skip confirmation

设置选项

# Non-interactive setup
kioku setup -y \
  --project-type web-app \
  --openai-key sk-xxx \
  --anthropic-key sk-ant-xxx \
  --editor claude

医生选项

kioku doctor --repair          # Auto-repair issues
kioku doctor --dry-run         # Preview repairs without applying
kioku doctor --quick           # Fast health check (skip expensive checks)
kioku doctor --check database  # Check specific component

______________________________________________________________________

🎯 主要特点

上下文管理

• 🧠 自动项目扫描 -检测技术栈、架构、模块
• 📝 自我丰富的环境 -从每次编码会话中学习
• 🔍 语义搜索 -ChromaDB的矢量嵌入
• 🎯 智能修剪 -保持上下文窗口最佳（80%阈值）
• 📊 使用情况跟踪 -监控文件访问和发现模式

开发者体验

• ⚡ 零配置设置 -交互式向导处理一切
• 🏥 自我修复 -汽车维修 kioku doctor --repair
• 📈 可视化仪表板 -实时项目洞察
• 🎨 漂亮的CLI -图标、颜色、进度指示器
• 📚 全面帮助 -工具文档中

AI集成

• 🔌 MCP协议 -适用于Claude Desktop、Zed等
• 🛠️ 丰富的工具 -搜索、读取、grep、git分析
• 📖 资源暴露 -项目、模块、会话历史
• 🔄 后台服务 -评分、修剪、充实
• 💡 进步学习 -AI每次会话都变得更聪明

技术卓越

• ✅ 90%+测试覆盖率 -全面的测试套件
• 🏗️ 洋葱建筑 -清晰地分离关注点
• 🔐 类型安全 -TypeScript严格模式无处不在
• 📦 依赖注入 -可测试和可维护
• 🚀 快速运行时间 -建在Bun上

______________________________________________________________________

🛠️ 技术栈

核心

• 运行时间： Bun（快速JavaScript运行时）
• 语言： TypeScript（严格模式）
• 架构： 洋葱架构+函数式编程

存储

• 关系型： SQLite（会话、发现、块）
• 矢量： ChromaDB（语义嵌入）
• 配置： YAML（项目上下文）

人工智能和API

• 嵌入： OpenAI文本嵌入3-small
• 发现优化： 人物克劳德（可选）
• 协议： 模型上下文协议（MCP）

前端（仪表板）

• 框架： React 18+Vite
• 造型： 顺风 CSS
• 国家： TanStack查询（React查询）
• 服务器： 禁食+CORS

开发运维

• 测试： Vitest
• Linting： ESLint（具有架构边界）
• 类型检查： TypeScript编译器
• 包管理器： 包子
• Git集成： 自定义git客户端

______________________________________________________________________

运作原理

第1节

1. 您初始化Kioku： kioku init
2. AI扫描你的项目结构
3. 可用的基本上下文（文件树、技术栈）

第2节+

1. 每节课后，Kioku都会提取发现：

- 您讨论的架构模式 - 您建立的编码惯例 - 您找到的解决方案和变通方法 - 您解释的业务规则

1. 这些发现丰富了 .context/project.yaml

1. 下一节课，AI会自动知道：

- 您的项目架构 - 您团队的惯例 - 过去的决定和背景 - 模块特定模式

结果

第10次会议： 你的人工智能助理回答问题的方式就像一个在这个项目上工作了几个月的高级团队成员。

您的手动上下文设置时间： 0分钟

______________________________________________________________________

建筑

Kioku如下 洋葱结构 随着 函数式编程 原则：

Infrastructure (🔴)  ← I/O, MCP Server, Storage
    ↓
Application (🟡)     ← Use Cases, Orchestration  
    ↓
Domain (🟢)          ← Pure Business Logic

关键原则：

• ✅ 域=100%纯函数（无I/O）
• ✅ 依赖关系仅指向内部
• ✅ 不可变的数据结构
• ✅ 全面测试覆盖率（90%+）

看 CLAUDE.md 获取完整的开发指南。

______________________________________________________________________

CLI命令

init

初始化当前项目的上下文

kioku init

serve

启动MCP服务器（编辑器自动使用）

kioku serve

show

显示当前项目上下文

kioku show

status

显示Kioku系统运行状况和诊断

kioku status

______________________________________________________________________

发展

运行测试

bun test                  # Run all tests
bun test --watch          # Watch mode
bun test --coverage       # With coverage report

质量门

bun run quality-gate      # Type check + lint + tests
bun run type-check        # TypeScript strict mode
bun run lint              # ESLint (includes architecture boundaries)
bun run lint:fix          # Auto-fix issues

构建

bun run build             # Compile TypeScript to dist/

______________________________________________________________________

项目结构

kioku/
├── src/
│   ├── domain/              # 🟢 Pure business logic
│   │   ├── models/          # Data structures
│   │   ├── calculations/    # Pure functions
│   │   └── rules/           # Business rules
│   │
│   ├── application/         # 🟡 Application logic
│   │   ├── use-cases/       # Feature workflows
│   │   ├── services/        # Application services
│   │   └── ports/           # Interfaces
│   │
│   └── infrastructure/      # 🔴 External world
│       ├── mcp/             # MCP server
│       ├── storage/         # Database, file I/O
│       ├── cli/             # Commands
│       └── external/        # OpenAI, Anthropic APIs
│
├── tests/
│   ├── unit/                # Unit tests (90%+ coverage)
│   └── integration/         # Integration tests
│
├── .specify/                # Spec-Driven Development
│   ├── memory/
│   │   └── constitution.md  # Project principles
│   └── specs/
│       └── 001-kioku-mvp/
│           ├── spec.md      # Feature requirements
│           ├── plan.md      # Technical design
│           └── tasks.md     # Implementation tasks
│
├── SETUP.md                 # Configuration guide
└── CLAUDE.md                # AI development guide

______________________________________________________________________

技术栈

运行时间： 包子\ 语言： TypeScript（严格模式）\ MCP-SDK： @模型上下文协议/sdk\ 储存： SQLite+YAML+ChromaDB（本地）\ 嵌入： OpenAI（文本嵌入3-small）\ 测试： Vitest\ Linting： ESLint（具有架构边界强制）

______________________________________________________________________

需求

• 包子 v1.1.29+（运行时）
• OpenAI API密钥 （用于嵌入）
• 无烟煤API密钥 （可选，用于未来的AI提取）
• 支持的编辑器：

- Zed编辑 - 克劳德代码（CLI）

______________________________________________________________________

MVP范围

范围：

• ✅ Types/JavaScript项目
• ✅ 基于规则的发现提取
• ✅ OpenAI嵌入
• ✅ 本地SQLite+ChromaDB
• ✅ 单用户、本地开发

超出范围（MVP后）：

• ❌ 多语言支持（Python、Go、Rust）
• ❌ 基于AI的提取（GPT-4细化）
• ❌ Git集成（Git_log、Git_blame）
• ❌ 实时文件查看
• ❌ Web仪表板UI
• ❌ 团队/协作功能

______________________________________________________________________

文档

• docs/setup-guide.md -Zed/Claude代码配置指南
• CLAUDE.md -人工智能开发指南（原理、架构、TDD）
• docs/project-overview.md -项目概况和架构
• docs/changelog.md -版本历史和更改
• .define/memory/constitution.md -项目原则
• .specific/specs/001上下文工具mvp/spec.md -功能规范（传统路径）

______________________________________________________________________

测试您的设置

1.手动服务器测试

cd ~/your-project-with-context
bun /path/to/kioku/dist/infrastructure/cli/index.js serve

您应该看到： Server running on stdio

2.查看上下文

cd ~/your-project-with-context
bun /path/to/kioku/dist/infrastructure/cli/index.js show

3.人工智能集成

在你的编辑器中，问你的AI：

What resources are available from the Kioku MCP server?

______________________________________________________________________

贡献

该项目如下 规范驱动开发:

1. 阅读 .specify/memory/constitution.md （原则）
2. 审查 .specify/specs/001-context-tool-mvp/spec.md （要求）
3. 跟随 测试驱动开发 （代码前测试）
4. 维持 90%+测试覆盖率
5. 尊重 洋葱结构 边界（由ESLint执行）

看 CLAUDE.md 用于完整的开发工作流程。

______________________________________________________________________

许可证

麻省理工学院（或您首选的许可证）

______________________________________________________________________

支持

问题： https://github.com/sanzoku-labs/kioku/issues\ 文档： 看 .specify/specs/001-context-tool-mvp/ 和项目README

______________________________________________________________________

内置于❤️ 使用Bun、TypeScript和MCP

让你的AI记住。专注于建筑。 🚀