memsave 0.2.0__tar.gz

memsave-0.2.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

memsave-0.2.0/PKG-INFO

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: memsave
+Version: 0.2.0
+Summary: Read AI memories without spending credits — local, free hybrid retrieval
+Author: memsave contributors
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://memsave.app.workbuddy.host/?sharecode=5V43SCBI5Q
+Project-URL: Documentation, https://memsave.app.workbuddy.host/guide.html?sharecode=5V43SCBI5Q
+Project-URL: Funding, https://afdian.com/item/6f246044d49611f1b0a4525400c8052f
+Keywords: memory,mcp,rag,bm25,embeddings,llm,context,token
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: local
+Requires-Dist: onnxruntime>=1.16; extra == "local"
+Requires-Dist: numpy>=1.24; extra == "local"
+Requires-Dist: tokenizers>=0.15; extra == "local"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# memsave
+
+读回忆不花积分。
+
+大多数"记忆系统"贵在一个地方：它们把整座记忆库灌进上下文，然后让大模型自己去判断哪条相关。上下文是唯一稀缺资源，于是每想一次都要重新付一遍钱。
+
+memsave 反过来做：**检索全程跑在本地 CPU 上，一次模型调用都不发，只把真正命中的那一小段送进上下文。**
+
+## 核心方法
+
+**1. 检索不要过模型**
+- `SQLite FTS5` + BM25 做关键词召回。记忆这种命名实体密集的文本（人名、项目名、术语），关键词命中率高得离谱。
+- 中文没有空格，所以 CJK 串切成重叠 bigram 再索引 —— 零依赖，不需要分词库。
+- 可选 24MB 的 `bge-small-zh-v1.5` ONNX 模型做语义重排，CPU 单条 5–15ms。没装就退化成哈希向量，照样免费。
+
+**2. 三层分级，只加载最薄的一层**
+
+| 层 | 内容 | 体积 | 时机 |
+|---|---|---|---|
+| L0 | 标题 + 自动关键词 | ~17 token/条 | 常驻系统提示 |
+| L1 | 摘要 | ~80 token | 命中后加载 |
+| L2 | 原文 | 实际长度 | 显式请求才取 |
+
+L0 大小**恒定**：不管库里 300 条还是 5000 条，索引都是约 1000 token，因为只取 Top-N。
+
+**3. 成本从读取侧搬到写入侧**
+原始对话流水账不要存。存蒸馏后的事实：谁 / 做了什么 / 何时 / 决策 / 偏好。写一次花一次钱，之后读一万次都是零。
+
+**4. 文档只在写入时被处理一次**
+分词、关键词、向量、token 计数，全部在写入时算好存进表里。检索时唯一的计算是点积。
+
+## 实测数据
+
+300 条记忆库：
+
+| 查询 | 注入 | 全库基线 | 省下 | 耗时 |
+|---|---|---|---|---|
+| 老陈负责哪个项目 | 140 | 33,442 | 33,302 | 11.8ms |
+| Alpha 排期 | 145 | 33,442 | 32,297 | 13.3ms |
+| 预算上限 | 115 | 33,442 | 33,327 | 9.0ms |
+
+5000 条记忆库：压缩比 **0.02%**，检索 35–70ms，L0 索引仍是 1051 token。
+
+## 安装
+
+给**用户**装（对外分发用 wheel 直装，包名在 PyPI 尚未发布）：
+
+```bash
+pip install https://memsave.app.workbuddy.host/memsave-0.2.0-py3-none-any.whl?sharecode=5V43SCBI5Q
+python -m memsave stats          # 看到统计输出就装好了
+```
+
+给**开发者**装（从源码）：
+
+```bash
+pip install -e .                 # 零依赖核心，BM25 检索开箱可用
+pip install -e ".[local]"        # 可选：加上本地语义模型
+python -m memsave embedder install
+```
+
+完整上手步骤见 **[`site/guide.html`](site/guide.html)**（使用教程，已上线）。
+
+## 用法
+
+```bash
+# 手写摘要（推荐：你比启发式更清楚什么重要）
+python -m memsave add "Alpha 项目延期" \
+  --summary "Alpha 因 GPU 到货延迟推到 11 月 15 日" \
+  --body "2026-10-12 会议决定：上线时间从 10/30 推迟到 11/15…" \
+  --kind decision --tags "alpha,排期" --salience 0.9 --pinned
+
+# 丢原始文本进去自动蒸馏，--llm 用你自己的 key 蒸馏得更好
+python -m memsave add "会议决定：Alpha 上线时间推迟到 11/15，因 H800 到货延迟" --raw
+python -m memsave add "会议决定：Alpha 上线时间推迟到 11/15" --raw --llm
+
+python -m memsave search "Alpha 排期"
+python -m memsave index            # 输出 L0，粘进系统提示
+python -m memsave stats            # 省了多少 token / 多少钱
+```
+
+## 写入侧蒸馏：唯一该花钱的地方
+
+一条记忆写一次，读无数次。所以蒸馏是**唯一值得调用 LLM 的地方** —— 一次调用，永久摊销。
+
+```bash
+export OPENAI_API_KEY=sk-...          # 也支持任何 /chat/completions 兼容端点
+export OPENAI_BASE_URL=https://api.deepseek.com/v1
+export MEMSAVE_LLM_MODEL=deepseek-chat
+
+python -m memsave distill "会议开了两小时，最后老陈拍板说预算就卡在 80 万" --llm
+```
+
+不配 key 也能跑，走启发式：按句切分取首句、按提示词分类（`决定`→decision、`偏好`→preference）、按重要度给权重（偏好 0.85 > 决策 0.80 > 一次性事件 0.40）。
+
+**LLM 挂了就自动退回启发式，绝不丢记忆。**
+
+## 导出（免费版也有）
+
+```bash
+python -m memsave export ~/memories.md
+python -m memsave export ~/memories.json --format json
+python -m memsave import ~/memories.json        # 合并
+python -m memsave import ~/memories.json --replace
+```
+
+记忆是用户的资产，不是 lock-in 的筹码。**给不了干净导出的产品，用户就不敢往里放真正重要的东西。**
+
+## 授权
+
+```bash
+python -m memsave license status
+python -m memsave license activate MSV1-XXXX.XXXXXXXX
+```
+
+签发给客户：
+
+```bash
+export MEMSAVE_LICENSE_SECRET="<换成你自己的长随机串>"
+python -m memsave license issue --email a@b.com --tier pro        # 永久
+python -m memsave license issue --email a@b.com --tier team --days 365 --seats 20
+```
+
+看清楚这一点：**客户端授权是减速带，不是锁。** 任何客户端校验都能被提取密钥绕过。它的作用是让"付费"比"破解"更省事。真正的闸门在服务端 —— 同步、团队共享、更新，这些本来就要联网，校验应该放在那里。别在客户端 DRM 上烧工程时间。
+
+## 收款与自动发码
+
+从"有产品"到"有钱进账"，差的只是一个 HTTP 端点。`billing` 就是那个端点，标准库实现，不需要任何 web 框架。
+
+```bash
+export MEMSAVE_LICENSE_SECRET="<你自己的长随机串>"
+export STRIPE_WEBHOOK_SECRET="whsec_..."
+
+# SMTP，不配就落盘等待人工发送，绝不丢码
+export SMTP_HOST=smtp.resend.com SMTP_PORT=587
+export SMTP_USER=apikey SMTP_PASS=re_xxx MAIL_FROM=billing@yourdomain.com
+
+python -m memsave billing test              # 不发网络请求的自检
+python -m memsave billing serve --provider stripe --port 8787
+python -m memsave billing stats             # 订单 / 已发送 / 待发送
+python -m memsave billing pending           # 列出待人工发送的授权码
+python -m memsave billing retry             # 邮件失败后补发
+python -m memsave billing reconcile --provider afdian --days 3   # 对账补漏单
+```
+
+`reconcile` 是"不买服务器"这条路的兜底：webhook 是推送，你关机时收不到。
+它反过来主动去平台拉订单，只补发本地账本里没有的（走同一套三道闸和幂等账本，
+重复跑不会重复发码）。详见 **[`docs/hosting.md`](docs/hosting.md)**。
+
+Stripe 后台配 `checkout.session.completed`，Lemon Squeezy 配 `order_created`。创建 Checkout Session 时带上 `metadata: {"tier": "pro", "seats": 1}`（`days` 留空即永久）。
+
+放 Caddy 后面：
+
+```
+pay.yourdomain.com { reverse_proxy 127.0.0.1:8787 }
+```
+
+**默认只监听 127.0.0.1。** `--public` 是给容器用的，不是给笔记本用的。
+
+### 三条不可妥协的规则
+
+1. **验签必须开。** 不验签的 webhook 就是一台任何人都能 POST 的免费发码机。签名密钥每次请求都重新读取，轮换不用重启。
+2. **幂等由本地账本保证，不信 provider。** Stripe 收到任何非 2xx 都会重试，而且重试不止一次。没有幂等，客户会收到三把不同的钥匙，然后不知道该用哪把。
+3. **授权码绝不丢。** 邮件发不出去就落盘到 `~/.memsave/pending-delivery/`，然后 `billing pending` 人工补发。静默丢码是一张无法挽回的工单。
+
+## 运维
+
+```bash
+memsave ops doctor          # 体检：密钥 / 数据库完整性 / 磁盘 / 邮件积压
+memsave ops backup          # 备份（自动校验可读性）
+memsave ops restore <file>  # 恢复（先把当前状态另存，绝不直接覆盖）
+memsave ops prune --keep 14 # 清理旧备份
+memsave ops new-secret      # 生成密钥
+memsave ops rotate-key <新密钥>   # 轮换并重新签发全部已售授权码
+memsave ops audit .         # 扫描硬编码密钥，发布前必做
+```
+
+服务器部署：
+
+```bash
+sudo ./deploy/install.sh    # 建用户、装服务、配 cron 备份、给 Caddy 提示
+```
+
+完整运维流程、故障排查表、应急预案见 **[`docs/operations.md`](docs/operations.md)**。
+
+一句话说清运维的本质：**每天能回答"它健康吗"，以及随时能把数据拿回来。** 其余都是细节。
+
+## 文档
+
+| 文档 | 内容 |
+|---|---|
+| [`README.md`](README.md) | 安装、用法、原理、收款、运维 |
+| [`site/guide.html`](site/guide.html) | **用户使用教程**（已上线，含各客户端配置路径与排错） |
+| [`docs/pricing.md`](docs/pricing.md) | 付费模式设计、上线清单、护城河与风险 |
+| [`docs/operations.md`](docs/operations.md) | 运维手册、故障排查、应急预案 |
+| [`docs/marketing.md`](docs/marketing.md) | 推广骨架与口径 |
+| [`promo/README.md`](promo/README.md) | **推广执行包**：口径卡 + 发布追踪表（先看这个） |
+| [`promo/06-video.md`](promo/06-video.md) | 推广视频：分镜、口播稿、各平台配文 |
+| [`docs/hosting.md`](docs/hosting.md) | **托管方案**：为什么现在不用买服务器 |
+| [`docs/pypi-release.md`](docs/pypi-release.md) | **PyPI 发布**：注册 → token → 上传（工程已就绪，只差你 3 步） |
+| [`CHANGELOG.md`](CHANGELOG.md) | 版本记录 |
+
+## 接进任意 AI（MCP）
+
+MCP 是"让所有 AI 都能调用"的答案：Claude Desktop、Cursor、Windsurf、Cline、WorkBuddy 都支持。
+
+```json
+{
+  "mcpServers": {
+    "memsave": {
+      "command": "python",
+      "args": ["-m", "memsave", "serve"],
+      "env": { "MEMSAVE_HOME": "C:/Users/you/.memsave" }
+    }
+  }
+}
+```
+
+暴露 9 个工具：`memory_index` / `memory_search` / `memory_get` / `memory_add`（支持 `raw` 自动蒸馏）/ `memory_update` / `memory_forget` / `memory_export` / `memory_license` / `memory_stats`。
+
+每次 `memory_search` 的返回都在末尾附一行统计：
+
+```
+本轮注入 140 token，全库基线 33442 token，省下 33302 token。
+累计 6 次调用共省下 199,858 token (≈ $0.60)
+```
+
+**这个数字就是产品本身。** 用户不需要你解释技术原理，他只需要看到"本次对话省了 3 万 token"。当省下的钱超过定价时，付费没有任何心理阻力。
+
+## 建议的系统提示
+
+```
+每次会话开始时调用 memory_index 一次。
+需要细节时调用 memory_search，默认只取摘要。
+禁止一次性加载全部记忆原文。
+新学到的用户偏好、决策、人物关系，用 memory_add 写入，
+写入前先蒸馏成事实，不要存原始对话。
+```
+
+## 商业化设计
+
+见 `docs/pricing.md`。要点：**BYOK 路径边际成本≈0，所以终身买断是净赚**；纯订阅在这个人群里转化率很差，因为 AI 重度用户已经订阅疲劳了。
+
+## 已知边界
+
+- 语义检索只在装了 `onnxruntime` 后启用，否则退化为 BM25 + 哈希向量。功能不残，语义质量下降。
+- 自动关键词用的是位置 + 词频启发式，不是真 IDF。要真 IDF 就得每次写入全量重算，不值得。
+- **标签里会出现 `库最`、`终选` 这种跨词碎片** —— 这是 bigram 索引无分词的固有痕迹。检索走完整 bigram 索引不受影响，标签只是给人扫一眼用的。要干净的中文标签就得引 jieba，为了这个不值当。
+- 单机单文件。多机同步和团队共享是商业版的事，也是服务端校验应该待的地方。
+- `estimate_tokens` 是启发式估算，误差约 15%。它用于展示节省量，**不用于计费**。
+- 客户端授权可被绕过，这是设计上的取舍，不是 bug。见上文。