omnimemory-cli 0.1.0

package/README.md

@@ -0,0 +1,131 @@
+# OmniMemory
+
+OmniMemory 是一个可复用、低耦合、可迁移的 AI 分层记忆基础设施（MVP 起步），目标是让 Claude Code / Codex / Cursor 在跨设备、跨项目、跨账户场景下共享同一记忆体系。
+
+当前进度：`Phase D（WebUI 配置与管理）已落地`
+
+## 设计目标（与约束）
+
+- 跨工具一致：通过“文件协议 + CLI 协议”而不是绑定单一 MCP。
+- 跨设备/跨账户：以 GitHub 私有仓库为主同步层，工具只读写本地协议文件。
+- 低耦合/可拆卸：采用 2-4 文件接入原则，移除时不改业务代码。
+- 多层记忆：即时/短期/长期/归档四层，按重要性/置信度/复用度等信号提升或降级。
+- 人类+机器双视图：Markdown 负责人类可读（核心长期记忆）；JSONL + SQLite FTS 负责结构化检索与审计。
+- 安全：不在记忆正文存储密钥，只存凭据引用（credential reference）。
+- 轻依赖：核心默认仅依赖 `bash/sqlite3/git/curl`。
+
+## 目录结构
+
+- `docs/`：架构、决策记录、接入与流程规范。
+- `spec/`：协议与 JSON Schema。
+- `db/schema.sql`：SQLite 模式（含 FTS）。
+- `scripts/`：安装/卸载/接入/剥离/自检脚本。
+- `omnimemory/`：CLI 实现。
+- `bin/omnimemory`：CLI 入口。
+- `templates/project-minimal/`：任意项目最小接入模板（2-4 文件原则）。
+- `data/`：本地默认存储根（Markdown + JSONL，SQLite 将在 Phase B 初始化）。
+
+## 一行命令
+
+安装：
+
+```bash
+bash scripts/install.sh
+```
+
+本地 npm 风格启动：
+
+```bash
+npm run start
+```
+
+新设备一键 bootstrap（推荐）：
+
+```bash
+bash scripts/bootstrap.sh --repo <你的OmniMemory仓库URL> --remote-url <你的记忆私有仓库URL>
+```
+
+说明：后续发布到 npm 后可支持 `npx omnimemory-cli` 直接运行。
+
+发布后跨设备一键安装（无需复制仓库）：
+
+```bash
+npx -y omnimemory-cli
+```
+
+接入某项目：
+
+```bash
+bash scripts/attach_project.sh /path/to/target-project your-project-id
+```
+
+从某项目剥离：
+
+```bash
+bash scripts/detach_project.sh /path/to/target-project
+```
+
+卸载：
+
+```bash
+bash scripts/uninstall.sh
+```
+
+## 快速验证（Phase A）
+
+```bash
+bash scripts/verify_phase_a.sh
+```
+
+## 快速验证（Phase B）
+
+```bash
+bash scripts/verify_phase_b.sh
+```
+
+## 快速验证（Phase C）
+
+```bash
+bash scripts/verify_phase_c.sh
+```
+
+## 快速验证（Phase D）
+
+```bash
+bash scripts/verify_phase_d.sh
+```
+
+## CLI 命令
+
+```bash
+./bin/omnimemory write --summary "example" --body "hello"
+./bin/omnimemory find hello
+./bin/omnimemory checkpoint --summary "cp1"
+./bin/omnimemory brief
+./bin/omnimemory verify
+./bin/omnimemory sync --mode noop
+./bin/omnimemory sync --mode github-push
+./bin/omnimemory adapter cred-resolve --ref env://TOKEN --mask
+./bin/omnimemory adapter notion-write --database-id DB_ID --title "t" --content "c" --dry-run
+./bin/omnimemory adapter r2-put --file ./a.bin --url "https://example.com/presigned" --dry-run
+./bin/omnimemory config-path
+./bin/omnimemory start --host 127.0.0.1 --port 8765
+./bin/omnimemory uninstall --yes
+```
+
+详见：`docs/cli-mvp.md`、`docs/phase-c.md`、`docs/webui-config.md`
+详见：`docs/quickstart-10min.md`
+详见：`docs/publish-npm.md`
+
+## 阶段闭环流程（强制）
+
+每个阶段都按以下闭环执行：
+
+1. 阶段总结（目标、完成项、一致性）
+2. 自检（命令与关键输出）
+3. 人工验收步骤
+4. 收集反馈并修正
+5. 记录通过状态
+6. 再进入下一阶段
+
+详见：`docs/phase-workflow.md`

package/bin/omnimemory

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PYTHONPATH="$ROOT_DIR${PYTHONPATH:+:$PYTHONPATH}" exec python3 -m omnimemory.cli "$@"

package/db/schema.sql

@@ -0,0 +1,78 @@
+PRAGMA foreign_keys = ON;
+
+CREATE TABLE IF NOT EXISTS memories (
+  id TEXT PRIMARY KEY,
+  schema_version TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  layer TEXT NOT NULL CHECK (layer IN ('instant', 'short', 'long', 'archive')),
+  kind TEXT NOT NULL CHECK (kind IN ('note', 'decision', 'task', 'checkpoint', 'summary', 'evidence')),
+  summary TEXT NOT NULL,
+  body_md_path TEXT NOT NULL,
+  body_text TEXT NOT NULL DEFAULT '',
+  tags_json TEXT NOT NULL DEFAULT '[]',
+  importance_score REAL NOT NULL DEFAULT 0.5 CHECK (importance_score >= 0 AND importance_score <= 1),
+  confidence_score REAL NOT NULL DEFAULT 0.5 CHECK (confidence_score >= 0 AND confidence_score <= 1),
+  stability_score REAL NOT NULL DEFAULT 0.5 CHECK (stability_score >= 0 AND stability_score <= 1),
+  reuse_count INTEGER NOT NULL DEFAULT 0 CHECK (reuse_count >= 0),
+  volatility_score REAL NOT NULL DEFAULT 0.5 CHECK (volatility_score >= 0 AND volatility_score <= 1),
+  cred_refs_json TEXT NOT NULL DEFAULT '[]',
+  source_json TEXT NOT NULL,
+  scope_json TEXT NOT NULL,
+  integrity_json TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_memories_layer ON memories(layer);
+CREATE INDEX IF NOT EXISTS idx_memories_kind ON memories(kind);
+CREATE INDEX IF NOT EXISTS idx_memories_updated_at ON memories(updated_at);
+CREATE INDEX IF NOT EXISTS idx_memories_importance ON memories(importance_score);
+CREATE INDEX IF NOT EXISTS idx_memories_reuse_count ON memories(reuse_count);
+
+CREATE TABLE IF NOT EXISTS memory_refs (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  memory_id TEXT NOT NULL,
+  ref_type TEXT NOT NULL,
+  target TEXT NOT NULL,
+  note TEXT,
+  FOREIGN KEY (memory_id) REFERENCES memories(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_memory_refs_memory_id ON memory_refs(memory_id);
+CREATE INDEX IF NOT EXISTS idx_memory_refs_target ON memory_refs(target);
+
+CREATE TABLE IF NOT EXISTS memory_events (
+  event_id TEXT PRIMARY KEY,
+  event_type TEXT NOT NULL,
+  event_time TEXT NOT NULL,
+  memory_id TEXT NOT NULL,
+  payload_json TEXT NOT NULL,
+  FOREIGN KEY (memory_id) REFERENCES memories(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_memory_events_type_time ON memory_events(event_type, event_time);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+  id UNINDEXED,
+  summary,
+  body_text,
+  tags,
+  tokenize = 'unicode61'
+);
+
+CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories
+BEGIN
+  INSERT INTO memories_fts(id, summary, body_text, tags)
+  VALUES (new.id, new.summary, new.body_text, new.tags_json);
+END;
+
+CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories
+BEGIN
+  DELETE FROM memories_fts WHERE id = old.id;
+END;
+
+CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories
+BEGIN
+  DELETE FROM memories_fts WHERE id = old.id;
+  INSERT INTO memories_fts(id, summary, body_text, tags)
+  VALUES (new.id, new.summary, new.body_text, new.tags_json);
+END;

package/docs/quickstart-10min.md

@@ -0,0 +1,47 @@
+# 10 分钟上手（跨设备 / 跨项目）
+
+## A. 新设备一键安装
+
+在任意目录执行：
+
+```bash
+npx -y omnimemory-cli
+```
+
+若你未发布 npm 包，使用仓库脚本替代：
+
+```bash
+bash scripts/bootstrap.sh --repo <你的OmniMemory仓库URL>
+~/.omnimemory/bin/omnimemory start --host 127.0.0.1 --port 8765
+```
+
+打开：`http://127.0.0.1:8765`
+
+## B. 新项目接入（不污染业务代码）
+
+```bash
+~/.omnimemory/app/scripts/attach_project.sh /path/to/project my-project-id
+```
+
+只会新增 3 个文件：
+- `.omni-memory.json`
+- `.omni-memory-session.md`
+- `.omni-memory-ignore`
+
+## C. 首次设备同步
+
+在 WebUI 点击：`首次接入自动对齐`（pull -> reindex -> push）。
+
+之后后台 daemon 会准实时自动同步。
+
+## D. 卸载
+
+```bash
+~/.omnimemory/bin/omnimemory uninstall --yes
+```
+
+项目剥离：
+
+```bash
+~/.omnimemory/bin/omnimemory uninstall --yes --detach-project /path/to/project
+```

package/omnimemory/__init__.py

@@ -0,0 +1,2 @@
+__all__ = ["__version__"]
+__version__ = "0.1.0"

package/omnimemory/adapters.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+
+NOTION_API_BASE = "https://api.notion.com/v1"
+NOTION_VERSION = "2022-06-28"
+
+
+def resolve_cred_ref(ref: str) -> str:
+    if ref.startswith("env://"):
+        key = ref[len("env://") :]
+        val = os.getenv(key)
+        if val is None:
+            raise ValueError(f"environment variable not found: {key}")
+        return val
+
+    if ref.startswith("op://"):
+        proc = subprocess.run(["op", "read", ref], check=True, capture_output=True, text=True)
+        return proc.stdout.strip()
+
+    raise ValueError("unsupported cred ref, expected env:// or op://")
+
+
+def _http_json(method: str, url: str, headers: dict[str, str], payload: dict[str, Any] | None = None) -> dict[str, Any]:
+    data = None
+    if payload is not None:
+        data = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(url=url, method=method, headers=headers, data=data)
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"http {exc.code}: {body}") from exc
+
+
+def notion_write_page(
+    *,
+    token: str,
+    database_id: str,
+    title: str,
+    content: str,
+    title_property: str = "Name",
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    payload = {
+        "parent": {"database_id": database_id},
+        "properties": {
+            title_property: {
+                "title": [{"text": {"content": title}}]
+            }
+        },
+        "children": [
+            {
+                "object": "block",
+                "type": "paragraph",
+                "paragraph": {
+                    "rich_text": [{"type": "text", "text": {"content": content[:1900]}}]
+                },
+            }
+        ],
+    }
+    if dry_run:
+        return {"ok": True, "mode": "dry_run", "payload": payload}
+
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Notion-Version": NOTION_VERSION,
+        "Content-Type": "application/json",
+    }
+    data = _http_json("POST", f"{NOTION_API_BASE}/pages", headers, payload)
+    return {"ok": True, "id": data.get("id"), "url": data.get("url")}
+
+
+def notion_query_database(
+    *,
+    token: str,
+    database_id: str,
+    page_size: int = 5,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    payload = {"page_size": page_size}
+    if dry_run:
+        return {"ok": True, "mode": "dry_run", "payload": payload}
+
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Notion-Version": NOTION_VERSION,
+        "Content-Type": "application/json",
+    }
+    data = _http_json("POST", f"{NOTION_API_BASE}/databases/{database_id}/query", headers, payload)
+    results = data.get("results", [])
+    slim = [{"id": x.get("id"), "url": x.get("url")} for x in results]
+    return {"ok": True, "count": len(slim), "items": slim}
+
+
+def r2_put_presigned(*, file_path: Path, presigned_url: str, dry_run: bool = False) -> dict[str, Any]:
+    if dry_run:
+        return {"ok": True, "mode": "dry_run", "file": str(file_path), "url_prefix": presigned_url[:40]}
+
+    proc = subprocess.run(
+        ["curl", "-sS", "-X", "PUT", "--upload-file", str(file_path), presigned_url],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return {"ok": True, "response": proc.stdout.strip()}
+
+
+def r2_get_presigned(*, presigned_url: str, out_path: Path, dry_run: bool = False) -> dict[str, Any]:
+    if dry_run:
+        return {"ok": True, "mode": "dry_run", "out": str(out_path), "url_prefix": presigned_url[:40]}
+
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    subprocess.run(["curl", "-sS", "-L", "-o", str(out_path), presigned_url], check=True)
+    return {"ok": True, "out": str(out_path)}