KidMemory

把孩子成长素材沉淀成可搜索、可编辑、可导出的家庭作品集。
Local-first memory workspace for families, built for privacy and long-term ownership.

产品简介

KidMemory 是一个本地优先（Local-first）的亲子内容工作台：

• 把分散在本地文件夹里的图片素材，导入为结构化的”家庭记忆库”
• 用 metadata + embedding + pgvector 建立自然语言可搜索能力
• 将候选素材交给 Agent 生成可预览、可导出的高质量 PDF 作品集
• V1.5 新增：手机扫码上传，支持 Supabase Storage 公网中转和局域网直传

核心原则：

• 数据优先在本地可控
• 隐私先于增长
• 不依赖云端也能完成主要流程

🚀 快速开始

5 分钟快速体验 V1.5 Web Companion，请查看 QUICK_START.md

完整部署指南，请查看 DEPLOYMENT_CHECKLIST.md

产品图

全局流程

桌面端页面预览

Setup	素材库	生成与导出

本地启动方式

0) 环境要求

• macOS（Apple Silicon 优先）
• Node.js >=22
• Flutter（可运行 flutter doctor）
• Homebrew
• PostgreSQL + pgvector

1) 拉取代码并配置环境变量

git clone <your-repo-url>
cd kidmemory
cp .env.example .env

按 .env 填写本地数据库、Claude、可选 OpenAI readiness、workspace/export 路径。

V1.5 Web Companion 配置（手机扫码上传）：

# Supabase Storage（必需）
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_STORAGE_BUCKET=kidmemory-assets
SUPABASE_STORAGE_PUBLIC_BASE_URL=https://your-project.supabase.co/storage/v1/object/public
SUPABASE_STORAGE_SIGNED_URL_TTL_SECONDS=900

# Web Companion 前端 URL
WEB_COMPANION_BASE_URL=http://localhost:3000

可选 V1.3 Direct Upload 配置（已废弃，建议使用 V1.5）：

SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_DIRECT_UPLOAD_BUCKET=web-companion-uploads
WEB_COMPANION_DIRECT_PUBLIC_URL=https://kidmemory-companion.example.com
WEB_COMPANION_DIRECT_UPLOAD_ENABLED=false

也可以使用 Supabase 官方 S3 协议凭据：

SUPABASE_S3_ENDPOINT=https://<project-ref>.storage.supabase.co/storage/v1/s3
SUPABASE_S3_REGION=auto
SUPABASE_S3_ACCESS_KEY_ID=
SUPABASE_S3_SECRET_ACCESS_KEY=
SUPABASE_S3_BUCKET=

S3 模式不会使用 service role key。SUPABASE_S3_ACCESS_KEY_ID 和 SUPABASE_S3_SECRET_ACCESS_KEY 是认证凭据，还需要 endpoint 和 bucket；如果 .env 里只配置了 S3 key，设置页会提示补齐缺少项。

2) 启动 PostgreSQL + pgvector

brew install postgresql@16 pgvector
brew services start postgresql@16

创建数据库（名称请替换为你 .env 中的数据库名）并启用向量扩展：

createdb kidmemory
psql kidmemory -c "CREATE EXTENSION IF NOT EXISTS vector;"

连通性检查：

pg_isready

3) 启动 Sidecar

cd apps/sidecar
npm install
npm test
npm run dev

4) 启动 Flutter 桌面端

cd apps/desktop_flutter
flutter pub get
flutter test
flutter run -d macos

仓库结构

apps/
  desktop_flutter/   # macOS Flutter 桌面端
  sidecar/           # NestJS sidecar API 与任务编排
docs/                # PRD、设计稿、路线图、架构说明
openspec/            # 变更提案与规格
examples/            # 示例数据
templates/           # 模板资源

Roadmap

• V0.1：桌面 MVP（示例数据 -> Agent -> PDF）
• V0.2：本地素材管理增强
• V0.3：自然语言搜图 + pgvector 检索 + 候选素材池
• V0.4：导出与存储增强（本地 + Supabase Storage）
• V0.5：Agent 稳定性增强
• V1.0：macOS 开源稳定版
• V1.5：Web Companion 后端可信上传版（手机扫码上传） ✅

详细见 docs/roadmap.md。

📚 文档

核心文档

• 快速开始指南 - 5 分钟快速体验
• 部署检查清单 - 完整部署指南
• V1.5 PRD - Web Companion 产品需求文档

开发文档

• 代码审查报告 - V1.5 代码审查总结
• 修复详情 - 代码审查修复说明
• 完整报告 - 审查与修复完整报告
• 项目指导 - Claude Code 工作指导

🎯 V1.5 新特性

Web Companion 手机扫码上传

• ✅ 桌面端创建短效上传会话（3小时有效期）
• ✅ 手机扫码进入上传页面
• ✅ Supabase Storage 公网中转（Signed Upload URL）
• ✅ 自动回拉到本地素材库
• ✅ 支持局域网直传（可选）
• ✅ 完整的状态机和错误恢复
• ✅ 事务支持确保数据一致性
• ✅ 指数退避重试机制
• ✅ 内存泄漏防护

技术亮点

• 安全性：Token hash 存储，Service role key 只在后端
• 可靠性：事务保证原子性，重试机制处理网络故障
• 性能：定期清理过期会话，防止内存泄漏
• 可观测性：结构化日志，便于生产环境监控

详见 V1.5 PRD 和 代码审查报告。

License

本项目使用 MIT License，详见 LICENSE。