yuanwei 0.1.0a1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. yuanwei-0.1.0a1/LICENSE +75 -0
  2. yuanwei-0.1.0a1/MANIFEST.in +2 -0
  3. yuanwei-0.1.0a1/NOTICE +42 -0
  4. yuanwei-0.1.0a1/PKG-INFO +133 -0
  5. yuanwei-0.1.0a1/README.md +112 -0
  6. yuanwei-0.1.0a1/README.zh-CN.md +110 -0
  7. yuanwei-0.1.0a1/pyproject.toml +37 -0
  8. yuanwei-0.1.0a1/setup.cfg +4 -0
  9. yuanwei-0.1.0a1/src/yuanwei/__init__.py +7 -0
  10. yuanwei-0.1.0a1/src/yuanwei/__main__.py +5 -0
  11. yuanwei-0.1.0a1/src/yuanwei/access.py +690 -0
  12. yuanwei-0.1.0a1/src/yuanwei/anchors.py +76 -0
  13. yuanwei-0.1.0a1/src/yuanwei/answer.py +84 -0
  14. yuanwei-0.1.0a1/src/yuanwei/ask.py +74 -0
  15. yuanwei-0.1.0a1/src/yuanwei/cards.py +255 -0
  16. yuanwei-0.1.0a1/src/yuanwei/catalog.py +302 -0
  17. yuanwei-0.1.0a1/src/yuanwei/cli.py +860 -0
  18. yuanwei-0.1.0a1/src/yuanwei/config.py +125 -0
  19. yuanwei-0.1.0a1/src/yuanwei/contract.py +84 -0
  20. yuanwei-0.1.0a1/src/yuanwei/control.py +66 -0
  21. yuanwei-0.1.0a1/src/yuanwei/convert.py +446 -0
  22. yuanwei-0.1.0a1/src/yuanwei/convhelp.py +105 -0
  23. yuanwei-0.1.0a1/src/yuanwei/cuts.py +50 -0
  24. yuanwei-0.1.0a1/src/yuanwei/deletion.py +981 -0
  25. yuanwei-0.1.0a1/src/yuanwei/directory.py +60 -0
  26. yuanwei-0.1.0a1/src/yuanwei/embedsetup.py +654 -0
  27. yuanwei-0.1.0a1/src/yuanwei/embedwork.py +385 -0
  28. yuanwei-0.1.0a1/src/yuanwei/encoding.py +78 -0
  29. yuanwei-0.1.0a1/src/yuanwei/enginepkg.py +681 -0
  30. yuanwei-0.1.0a1/src/yuanwei/enginerun.py +1086 -0
  31. yuanwei-0.1.0a1/src/yuanwei/errors.py +81 -0
  32. yuanwei-0.1.0a1/src/yuanwei/gate.py +217 -0
  33. yuanwei-0.1.0a1/src/yuanwei/hermes_adapter.py +824 -0
  34. yuanwei-0.1.0a1/src/yuanwei/hermes_compat.py +436 -0
  35. yuanwei-0.1.0a1/src/yuanwei/hermes_profile.py +114 -0
  36. yuanwei-0.1.0a1/src/yuanwei/hermes_setup.py +759 -0
  37. yuanwei-0.1.0a1/src/yuanwei/hermes_workspace.py +157 -0
  38. yuanwei-0.1.0a1/src/yuanwei/hosts.py +139 -0
  39. yuanwei-0.1.0a1/src/yuanwei/idchain.py +75 -0
  40. yuanwei-0.1.0a1/src/yuanwei/idsource.py +100 -0
  41. yuanwei-0.1.0a1/src/yuanwei/keystore.py +279 -0
  42. yuanwei-0.1.0a1/src/yuanwei/lstate.py +504 -0
  43. yuanwei-0.1.0a1/src/yuanwei/mcp/__init__.py +1 -0
  44. yuanwei-0.1.0a1/src/yuanwei/mcp/__main__.py +5 -0
  45. yuanwei-0.1.0a1/src/yuanwei/mcp/server.py +100 -0
  46. yuanwei-0.1.0a1/src/yuanwei/memory.py +1403 -0
  47. yuanwei-0.1.0a1/src/yuanwei/modes.py +419 -0
  48. yuanwei-0.1.0a1/src/yuanwei/multi.py +73 -0
  49. yuanwei-0.1.0a1/src/yuanwei/note.py +357 -0
  50. yuanwei-0.1.0a1/src/yuanwei/ops.py +31 -0
  51. yuanwei-0.1.0a1/src/yuanwei/pack.py +367 -0
  52. yuanwei-0.1.0a1/src/yuanwei/paging.py +154 -0
  53. yuanwei-0.1.0a1/src/yuanwei/provider.py +63 -0
  54. yuanwei-0.1.0a1/src/yuanwei/queries.py +83 -0
  55. yuanwei-0.1.0a1/src/yuanwei/rank.py +118 -0
  56. yuanwei-0.1.0a1/src/yuanwei/reader.py +483 -0
  57. yuanwei-0.1.0a1/src/yuanwei/redact.py +126 -0
  58. yuanwei-0.1.0a1/src/yuanwei/resources/answer-prompt-R1.txt +3 -0
  59. yuanwei-0.1.0a1/src/yuanwei/resources/answer-prompt-addendum.txt +8 -0
  60. yuanwei-0.1.0a1/src/yuanwei/resources/encoding-map.json +24 -0
  61. yuanwei-0.1.0a1/src/yuanwei/resources/hermes_plugin.yaml +7 -0
  62. yuanwei-0.1.0a1/src/yuanwei/resources/hermes_plugin_init.py.txt +179 -0
  63. yuanwei-0.1.0a1/src/yuanwei/resources/hermes_plugin_neutral.py.txt +25 -0
  64. yuanwei-0.1.0a1/src/yuanwei/resources/write-prompt-A.txt +108 -0
  65. yuanwei-0.1.0a1/src/yuanwei/resources/write-prompt-B0.txt +115 -0
  66. yuanwei-0.1.0a1/src/yuanwei/resources.py +37 -0
  67. yuanwei-0.1.0a1/src/yuanwei/retrieve.py +184 -0
  68. yuanwei-0.1.0a1/src/yuanwei/rules.py +45 -0
  69. yuanwei-0.1.0a1/src/yuanwei/sealing.py +71 -0
  70. yuanwei-0.1.0a1/src/yuanwei/secretscan.py +108 -0
  71. yuanwei-0.1.0a1/src/yuanwei/shortlist.py +114 -0
  72. yuanwei-0.1.0a1/src/yuanwei/sources.py +195 -0
  73. yuanwei-0.1.0a1/src/yuanwei/split.py +82 -0
  74. yuanwei-0.1.0a1/src/yuanwei/sqlstore.py +835 -0
  75. yuanwei-0.1.0a1/src/yuanwei/step.py +326 -0
  76. yuanwei-0.1.0a1/src/yuanwei/storeerr.py +89 -0
  77. yuanwei-0.1.0a1/src/yuanwei/tools.py +253 -0
  78. yuanwei-0.1.0a1/src/yuanwei/util.py +57 -0
  79. yuanwei-0.1.0a1/src/yuanwei/vectors.py +211 -0
  80. yuanwei-0.1.0a1/src/yuanwei/view.py +105 -0
  81. yuanwei-0.1.0a1/src/yuanwei/window.py +660 -0
  82. yuanwei-0.1.0a1/src/yuanwei/wizard.py +1130 -0
  83. yuanwei-0.1.0a1/src/yuanwei/workspace.py +36 -0
  84. yuanwei-0.1.0a1/src/yuanwei.egg-info/PKG-INFO +133 -0
  85. yuanwei-0.1.0a1/src/yuanwei.egg-info/SOURCES.txt +87 -0
  86. yuanwei-0.1.0a1/src/yuanwei.egg-info/dependency_links.txt +1 -0
  87. yuanwei-0.1.0a1/src/yuanwei.egg-info/entry_points.txt +2 -0
  88. yuanwei-0.1.0a1/src/yuanwei.egg-info/requires.txt +9 -0
  89. yuanwei-0.1.0a1/src/yuanwei.egg-info/top_level.txt +1 -0
@@ -0,0 +1,75 @@
1
+ Required Notice: Copyright 2026 Junzhi Gu (顾钧之)
2
+
3
+ # PolyForm Noncommercial License 1.0.0
4
+
5
+ <https://polyformproject.org/licenses/noncommercial/1.0.0>
6
+
7
+ ## Acceptance
8
+
9
+ In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
10
+
11
+ ## Copyright License
12
+
13
+ The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
14
+
15
+ ## Distribution License
16
+
17
+ The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
18
+
19
+ ## Notices
20
+
21
+ You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
22
+
23
+ > Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
24
+
25
+ ## Changes and New Works License
26
+
27
+ The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
28
+
29
+ ## Patent License
30
+
31
+ The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
32
+
33
+ ## Noncommercial Purposes
34
+
35
+ Any noncommercial purpose is a permitted purpose.
36
+
37
+ ## Personal Uses
38
+
39
+ Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
40
+
41
+ ## Noncommercial Organizations
42
+
43
+ Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
44
+
45
+ ## Fair Use
46
+
47
+ You may have "fair use" rights for the software under the law. These terms do not limit them.
48
+
49
+ ## No Other Rights
50
+
51
+ These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
52
+
53
+ ## Patent Defense
54
+
55
+ If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
56
+
57
+ ## Violations
58
+
59
+ The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
60
+
61
+ ## No Liability
62
+
63
+ ***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
64
+
65
+ ## Definitions
66
+
67
+ The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
68
+
69
+ **You** refers to the individual or entity agreeing to these terms.
70
+
71
+ **Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
72
+
73
+ **Your licenses** are all the licenses granted to you for the software under these terms.
74
+
75
+ **Use** means anything you do with the software requiring one of your licenses.
@@ -0,0 +1,2 @@
1
+ prune tests
2
+ include README.zh-CN.md
yuanwei-0.1.0a1/NOTICE ADDED
@@ -0,0 +1,42 @@
1
+ 原委(yuanwei)第三方声明
2
+
3
+ 一、切句有 Tencent MemoryCore 的分叉渊源(MIT)。研究里的切句(锚点切法)按本地 MemoryCore 的 splitSentences 的正则、trim 和短句行为重写,位置另算。以下是随源的许可全文:
4
+
5
+ Tencent is pleased to support the open source community by making TencentDB Agent Memory available.
6
+
7
+ Copyright (C) 2026 Tencent. All rights reserved.
8
+
9
+ TencentDB Agent Memory is licensed under the MIT.
10
+
11
+
12
+ Terms of the MIT:
13
+ --------------------------------------------------------------------
14
+ Permission is hereby granted, free of charge, to any person obtaining
15
+ a copy of this software and associated documentation files (the
16
+ "Software"), to deal in the Software without restriction, including
17
+ without limitation the rights to use, copy, modify, merge, publish,
18
+ distribute, sublicense, and/or sell copies of the Software, and to
19
+ permit persons to whom the Software is furnished to do so, subject to
20
+ the following conditions:
21
+
22
+ The above copyright notice and this permission notice shall be
23
+ included in all copies or substantial portions of the Software.
24
+
25
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
26
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
27
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
28
+ IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
29
+ CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
30
+ TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
31
+ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
32
+ ----------------------------------------------------------------
33
+
34
+ 二、NumPy(选装,pip install yuanwei[vector]):BSD-3-Clause。随包不分发 NumPy 本身;用户自己安装时,请保留它自带的版权、条款、免责声明及不得借名背书的要求;
35
+ 如果分发平台 wheel/捆绑二进制,还应保留该构建所附 BLAS、编译器运行库等各自的许可。
36
+
37
+ 三、基础包只用 Python 标准库(含 sqlite3)。向量服务、重排服务可以由用户自备(Ollama、LM Studio 等,不随包分发);也可以选「自带向量引擎」(见下一条)。
38
+
39
+ 四、自带向量引擎(用户选了「自带」、并明确同意以后才下载;原委不随包分发下面两样东西,只从官方发布地址下载,核对钉住的校验码以后使用):
40
+ 1. llama.cpp 的服务程序 llama-server:MIT 许可,版权归 llama.cpp 作者们(The ggml authors)所有;许可全文随它的发布包附带,下载后保存在引擎目录的 bin/ 里。
41
+ 2. Qwen3-Embedding-0.6B 的 GGUF 模型文件:Apache-2.0 许可,版权归 Alibaba Cloud(通义千问团队)所有;许可全文见模型的官方发布页。
42
+ 原委只是把它们当作外部程序和数据文件来运行,不修改它们。
@@ -0,0 +1,133 @@
1
+ Metadata-Version: 2.4
2
+ Name: yuanwei
3
+ Version: 0.1.0a1
4
+ Summary: 原委:事有原委,话有出处。给 AI 助手用的长期记忆(预览版)
5
+ Author: Junzhi Gu (顾钧之)
6
+ License-Expression: LicenseRef-PolyForm-Noncommercial-1.0.0
7
+ Project-URL: Homepage, https://github.com/guzhijun40134679/yuanwei
8
+ Project-URL: Source, https://github.com/guzhijun40134679/yuanwei
9
+ Project-URL: Issues, https://github.com/guzhijun40134679/yuanwei/issues
10
+ Requires-Python: >=3.11
11
+ Description-Content-Type: text/markdown
12
+ License-File: LICENSE
13
+ License-File: NOTICE
14
+ Provides-Extra: vector
15
+ Requires-Dist: numpy>=1.26; extra == "vector"
16
+ Provides-Extra: mcp
17
+ Requires-Dist: mcp<2,>=1.28.1; extra == "mcp"
18
+ Provides-Extra: test
19
+ Requires-Dist: pytest>=8; extra == "test"
20
+ Dynamic: license-file
21
+
22
+ # Yuanwei (原委)
23
+
24
+ English | [简体中文](https://github.com/guzhijun40134679/yuanwei/blob/main/README.zh-CN.md)
25
+
26
+ **Every memory has its origin; every quote has its source.** Long-term memory for AI assistants.
27
+
28
+ > Preview release · research prototype; some features are still being developed and tested. On 2026-11-11 it was installed on Hermes v0.22.0 (+10397) and every item on that checklist passed; what the checklist did not cover is listed under the limits below.
29
+
30
+ > **Language:** the setup wizard, the command-line messages and the detailed guides in `docs/` are currently in Chinese only.
31
+
32
+ ## What it does
33
+
34
+ - **Keeps your words verbatim.** What you and your assistant said is stored exactly as it was said, with who said it and on which day. Nothing is rewritten or summarized.
35
+ - **Files them by event.** On write it does one small thing: it attaches each message to an event and to one episode of that event, plus a one-line summary. Messages about the same event stay together; similar events on different occasions stay apart.
36
+ - **Answers from the original words.** When the assistant needs something from the past, it searches the original messages, the same event first, and receives each one with its date, so it can work out what is newer and what is outdated.
37
+
38
+ Underneath, it is retrieval over the original messages (what is usually called RAG: keywords, plus optional local vectors), with a very light layer of event filing on top. The filing only helps with finding things; what the assistant receives is always the original words.
39
+
40
+ ## Why keep the original words
41
+
42
+ Many memory products summarize conversations, or extract a handful of facts, and store those. We do the opposite: the original words are kept as they are, and the filing is only an index.
43
+
44
+ - **When a summary is wrong, everything built on it is wrong too**, and you can't tell which message it came from. Original words carry their dates, so you can check them yourself.
45
+ - **Public research points the same way.** The LongMemEval paper compared the two: giving the model summaries or extracted facts instead of the original messages lowers accuracy, except on questions that aggregate across sessions; using extracted facts only to help retrieval, while still handing over the original messages, improved both recall and accuracy.
46
+ - **Retrieval over original words is far from exhausted.** In our own tests, original-message retrieval plus light filing tied with Mem0. But a question usually needs only two or three original messages, while we hand the model several hundred. Finding them more completely and handing them over more precisely is what comes next.
47
+
48
+ ## Supported assistants
49
+
50
+ | Assistant | Status |
51
+ |---|---|
52
+ | Hermes | Available in the preview (installed as Hermes's external memory plugin) |
53
+ | Claude Code, Codex, Pi | Coming in later updates |
54
+
55
+ **Platform: tested on Mac only** (macOS on Apple M-series chips). Windows and Linux are untested. Known possible problems on Windows: the file lock for concurrent writes does not work, command-line output may be garbled or fail, and a black console window may flash while organizing. These will be fixed once it has been tested on a real Windows machine. On systems other than macOS, the wizard says so first.
56
+
57
+ ## Install
58
+
59
+ Requires Python 3.11 or later and an existing Hermes install.
60
+
61
+ We recommend a separate environment for Yuanwei at `~/.yuanwei/venv` (next to the built-in vector engine's `~/.yuanwei/engine/`, out of everything else's way). The commands below use full paths, so you don't need to add `yuanwei` to your PATH:
62
+
63
+ ```
64
+ python3 -m venv ~/.yuanwei/venv
65
+ ~/.yuanwei/venv/bin/pip install yuanwei
66
+ ~/.yuanwei/venv/bin/yuanwei setup
67
+ ```
68
+
69
+ You can also skip the environment and use `python3 -m pip install yuanwei` (don't type plain `pip`: some machines only have `pip3`); at the end, the wizard tells you the full path of `yuanwei`.
70
+
71
+ `yuanwei setup` is a question-and-answer wizard (in Chinese): check the environment → pick a preset → pick the organizing model → set the key (input is hidden; it is stored in a file on your computer that only you can read, shared by all your bots) → choose whether to turn on local vectors → show the plan → change nothing until you confirm.
72
+
73
+ | Preset | Organizing | Retrieval |
74
+ |---|---|---|
75
+ | Recommended (推荐) | DeepSeek (organizing tested) | Keywords + local vectors (needs a model download of about 600 MB, only after asking you; vectors: LM Studio is the tested setup; the built-in program is almost identical to it but did not pass our own strict standard) |
76
+ | Light (轻量) | DeepSeek | Keywords only |
77
+ | Custom (自选) | Your own provider and model (untested) | Your choice |
78
+ | All local (全本机, experimental) | A local LLM | Local vectors |
79
+
80
+ Local vectors come from one of two sources. **Built-in** (Apple M-series Macs): Yuanwei prepares the vector program and model for you, asks before downloading and tells you the size, then checks the download against the checksums pinned in this release; you don't need to install anything else. Or **LM Studio / Ollama**, if you already have them. **Only LM Studio is tested.** The built-in program uses the same model file, and its vectors are almost identical to LM Studio's: in a full check, 8 of 11,588 sentences fell slightly below our threshold, the lowest at 0.9977, none below 0.995. It did not pass our own strict standard, so it is not labeled "tested".
81
+
82
+ You can also let your assistant install it: give `docs/让助手来装.md` to Hermes. The assistant only shows you a plan first; you set the key yourself in a terminal.
83
+
84
+ The full guide (install, use, check status, uninstall; what each step changes and how to undo it) is `docs/装到Hermes上.md`, in Chinese.
85
+
86
+ ## You stay in control
87
+
88
+ - **No memory in this window.** Say "don't use memory" (别用记忆), or put `#yuanwei-nomem` on the first line of a message, and this conversation window stops searching Yuanwei's memory until you turn it back on. Turning it back on needs your own confirmation: reply exactly 「确认开启」 ("confirm enable"), or put `#yuanwei-mem` on the first line. The assistant cannot confirm for you. Only the commands are guaranteed; plain language relies on the assistant understanding it, and how reliably it does has not been measured.
89
+ - **Delete a conversation.** Tell your assistant; it is deleted only after you reply exactly 「确认删除」 ("confirm delete"). You can also delete it from the command line. The conversation's original messages are removed from Yuanwei, and the filing text that depends on them is cleared too. Deleted content cannot be recovered.
90
+ - **Keys in your messages are masked first.** Recognizable API keys and passwords are masked before anything is stored, so they never enter memory and are never sent to the organizing model. Formats it doesn't recognize may slip through.
91
+ - **Stored on your own computer.** The memory store is a local SQLite file. Organizing sends conversations to the model service you configured; by default the vector service only connects to your own machine.
92
+ - **Only your own words.** Other people's messages in groups, and messages from bots, are not recorded.
93
+ - **One store per bot.** Each new bot you create in Hermes needs Yuanwei installed once more (run the wizard for that bot's directory). Until then, settings copied from elsewhere stay inactive and never read or write the main Hermes store.
94
+ - **One organizing key for all bots.** All your bots share it, so you change it once (`yuanwei key set`). If one bot needs a different key, set it for that bot alone (`yuanwei key set --this-bot-only --hermes-home <its directory>`). To keep the shared key somewhere else, set `YUANWEI_KEY_DIR`: absolute paths only; the directory is made readable only by you, so use one meant just for keys; your terminal and the Hermes service must use the same setting. `yuanwei key status` only reports where the key comes from; it never shows the key itself.
95
+ - **Hermes's own memory stays on.** Yuanwei takes only Hermes's single "external memory plugin" slot. The "no memory" switch above applies to Yuanwei only, not to Hermes's built-in notes.
96
+
97
+ ## How it tested
98
+
99
+ We wrote a long story in Chinese, spread over 150 conversations, and two batches of questions, 55 each. Three memory systems each organized it, then the same answering model (DeepSeek) answered every question with the same material budget (16,000 tokens). Fully correct answers (2026-11-02):
100
+
101
+ | System | After conversation 48 | After conversation 150 |
102
+ |---|---|---|
103
+ | Yuanwei | 50 | 43 |
104
+ | Mem0 | 49 | 43 |
105
+ | Hindsight | 47 | 34 |
106
+ | No memory system: all earlier original messages given straight to the model (control, no budget limit) | 54 | not tested |
107
+
108
+ Limits:
109
+ - This release only covers one-to-one chats between you and a single bot. Group chats and messages between bots are neither recorded nor searched; to have something decided in a group remembered, say it once in your one-to-one chat.
110
+ - The story and questions are our own, not a public benchmark.
111
+ - Each system ran once.
112
+ - The grader knew which systems were being compared. When a different grader regraded the answers, Mem0 scored 4 more than Yuanwei on the conversation-150 batch.
113
+ - With the way the preview writes memory now, a re-answer of the same questions on November 10, graded separately, scored 53 and 46. Those numbers are not directly comparable with the table above.
114
+
115
+ Results on public benchmarks, run-to-run variation, cost and speed will follow.
116
+
117
+ ## Documentation
118
+
119
+ The source code and these documents are on GitHub: https://github.com/guzhijun40134679/yuanwei (the documents are in `docs/`, in Chinese for now).
120
+
121
+ - `docs/装到Hermes上.md`: the full user guide.
122
+ - `docs/让助手来装.md`: give it to Hermes and let Hermes install Yuanwei.
123
+ - `docs/产品规则表.md`: every behavior rule and its limits.
124
+ - `docs/开发说明.md`: for people changing the code or writing host adapters.
125
+ - `docs/复制关系表.md`: which code was copied from the research directory.
126
+
127
+ ## Credits
128
+
129
+ Designed and directed by Junzhi Gu. The code was written with Claude ([Anthropic](https://github.com/anthropics)); the algorithms, architecture and code were reviewed with GPT through Codex ([OpenAI](https://github.com/openai)).
130
+
131
+ ## License
132
+
133
+ Source-available under PolyForm Noncommercial 1.0.0: free for personal, learning, research and other non-commercial use; commercial use needs the copyright holder's permission first. Full text in `LICENSE`. Copyright holder: Junzhi Gu (顾钧之).
@@ -0,0 +1,112 @@
1
+ # Yuanwei (原委)
2
+
3
+ English | [简体中文](https://github.com/guzhijun40134679/yuanwei/blob/main/README.zh-CN.md)
4
+
5
+ **Every memory has its origin; every quote has its source.** Long-term memory for AI assistants.
6
+
7
+ > Preview release · research prototype; some features are still being developed and tested. On 2026-11-11 it was installed on Hermes v0.22.0 (+10397) and every item on that checklist passed; what the checklist did not cover is listed under the limits below.
8
+
9
+ > **Language:** the setup wizard, the command-line messages and the detailed guides in `docs/` are currently in Chinese only.
10
+
11
+ ## What it does
12
+
13
+ - **Keeps your words verbatim.** What you and your assistant said is stored exactly as it was said, with who said it and on which day. Nothing is rewritten or summarized.
14
+ - **Files them by event.** On write it does one small thing: it attaches each message to an event and to one episode of that event, plus a one-line summary. Messages about the same event stay together; similar events on different occasions stay apart.
15
+ - **Answers from the original words.** When the assistant needs something from the past, it searches the original messages, the same event first, and receives each one with its date, so it can work out what is newer and what is outdated.
16
+
17
+ Underneath, it is retrieval over the original messages (what is usually called RAG: keywords, plus optional local vectors), with a very light layer of event filing on top. The filing only helps with finding things; what the assistant receives is always the original words.
18
+
19
+ ## Why keep the original words
20
+
21
+ Many memory products summarize conversations, or extract a handful of facts, and store those. We do the opposite: the original words are kept as they are, and the filing is only an index.
22
+
23
+ - **When a summary is wrong, everything built on it is wrong too**, and you can't tell which message it came from. Original words carry their dates, so you can check them yourself.
24
+ - **Public research points the same way.** The LongMemEval paper compared the two: giving the model summaries or extracted facts instead of the original messages lowers accuracy, except on questions that aggregate across sessions; using extracted facts only to help retrieval, while still handing over the original messages, improved both recall and accuracy.
25
+ - **Retrieval over original words is far from exhausted.** In our own tests, original-message retrieval plus light filing tied with Mem0. But a question usually needs only two or three original messages, while we hand the model several hundred. Finding them more completely and handing them over more precisely is what comes next.
26
+
27
+ ## Supported assistants
28
+
29
+ | Assistant | Status |
30
+ |---|---|
31
+ | Hermes | Available in the preview (installed as Hermes's external memory plugin) |
32
+ | Claude Code, Codex, Pi | Coming in later updates |
33
+
34
+ **Platform: tested on Mac only** (macOS on Apple M-series chips). Windows and Linux are untested. Known possible problems on Windows: the file lock for concurrent writes does not work, command-line output may be garbled or fail, and a black console window may flash while organizing. These will be fixed once it has been tested on a real Windows machine. On systems other than macOS, the wizard says so first.
35
+
36
+ ## Install
37
+
38
+ Requires Python 3.11 or later and an existing Hermes install.
39
+
40
+ We recommend a separate environment for Yuanwei at `~/.yuanwei/venv` (next to the built-in vector engine's `~/.yuanwei/engine/`, out of everything else's way). The commands below use full paths, so you don't need to add `yuanwei` to your PATH:
41
+
42
+ ```
43
+ python3 -m venv ~/.yuanwei/venv
44
+ ~/.yuanwei/venv/bin/pip install yuanwei
45
+ ~/.yuanwei/venv/bin/yuanwei setup
46
+ ```
47
+
48
+ You can also skip the environment and use `python3 -m pip install yuanwei` (don't type plain `pip`: some machines only have `pip3`); at the end, the wizard tells you the full path of `yuanwei`.
49
+
50
+ `yuanwei setup` is a question-and-answer wizard (in Chinese): check the environment → pick a preset → pick the organizing model → set the key (input is hidden; it is stored in a file on your computer that only you can read, shared by all your bots) → choose whether to turn on local vectors → show the plan → change nothing until you confirm.
51
+
52
+ | Preset | Organizing | Retrieval |
53
+ |---|---|---|
54
+ | Recommended (推荐) | DeepSeek (organizing tested) | Keywords + local vectors (needs a model download of about 600 MB, only after asking you; vectors: LM Studio is the tested setup; the built-in program is almost identical to it but did not pass our own strict standard) |
55
+ | Light (轻量) | DeepSeek | Keywords only |
56
+ | Custom (自选) | Your own provider and model (untested) | Your choice |
57
+ | All local (全本机, experimental) | A local LLM | Local vectors |
58
+
59
+ Local vectors come from one of two sources. **Built-in** (Apple M-series Macs): Yuanwei prepares the vector program and model for you, asks before downloading and tells you the size, then checks the download against the checksums pinned in this release; you don't need to install anything else. Or **LM Studio / Ollama**, if you already have them. **Only LM Studio is tested.** The built-in program uses the same model file, and its vectors are almost identical to LM Studio's: in a full check, 8 of 11,588 sentences fell slightly below our threshold, the lowest at 0.9977, none below 0.995. It did not pass our own strict standard, so it is not labeled "tested".
60
+
61
+ You can also let your assistant install it: give `docs/让助手来装.md` to Hermes. The assistant only shows you a plan first; you set the key yourself in a terminal.
62
+
63
+ The full guide (install, use, check status, uninstall; what each step changes and how to undo it) is `docs/装到Hermes上.md`, in Chinese.
64
+
65
+ ## You stay in control
66
+
67
+ - **No memory in this window.** Say "don't use memory" (别用记忆), or put `#yuanwei-nomem` on the first line of a message, and this conversation window stops searching Yuanwei's memory until you turn it back on. Turning it back on needs your own confirmation: reply exactly 「确认开启」 ("confirm enable"), or put `#yuanwei-mem` on the first line. The assistant cannot confirm for you. Only the commands are guaranteed; plain language relies on the assistant understanding it, and how reliably it does has not been measured.
68
+ - **Delete a conversation.** Tell your assistant; it is deleted only after you reply exactly 「确认删除」 ("confirm delete"). You can also delete it from the command line. The conversation's original messages are removed from Yuanwei, and the filing text that depends on them is cleared too. Deleted content cannot be recovered.
69
+ - **Keys in your messages are masked first.** Recognizable API keys and passwords are masked before anything is stored, so they never enter memory and are never sent to the organizing model. Formats it doesn't recognize may slip through.
70
+ - **Stored on your own computer.** The memory store is a local SQLite file. Organizing sends conversations to the model service you configured; by default the vector service only connects to your own machine.
71
+ - **Only your own words.** Other people's messages in groups, and messages from bots, are not recorded.
72
+ - **One store per bot.** Each new bot you create in Hermes needs Yuanwei installed once more (run the wizard for that bot's directory). Until then, settings copied from elsewhere stay inactive and never read or write the main Hermes store.
73
+ - **One organizing key for all bots.** All your bots share it, so you change it once (`yuanwei key set`). If one bot needs a different key, set it for that bot alone (`yuanwei key set --this-bot-only --hermes-home <its directory>`). To keep the shared key somewhere else, set `YUANWEI_KEY_DIR`: absolute paths only; the directory is made readable only by you, so use one meant just for keys; your terminal and the Hermes service must use the same setting. `yuanwei key status` only reports where the key comes from; it never shows the key itself.
74
+ - **Hermes's own memory stays on.** Yuanwei takes only Hermes's single "external memory plugin" slot. The "no memory" switch above applies to Yuanwei only, not to Hermes's built-in notes.
75
+
76
+ ## How it tested
77
+
78
+ We wrote a long story in Chinese, spread over 150 conversations, and two batches of questions, 55 each. Three memory systems each organized it, then the same answering model (DeepSeek) answered every question with the same material budget (16,000 tokens). Fully correct answers (2026-11-02):
79
+
80
+ | System | After conversation 48 | After conversation 150 |
81
+ |---|---|---|
82
+ | Yuanwei | 50 | 43 |
83
+ | Mem0 | 49 | 43 |
84
+ | Hindsight | 47 | 34 |
85
+ | No memory system: all earlier original messages given straight to the model (control, no budget limit) | 54 | not tested |
86
+
87
+ Limits:
88
+ - This release only covers one-to-one chats between you and a single bot. Group chats and messages between bots are neither recorded nor searched; to have something decided in a group remembered, say it once in your one-to-one chat.
89
+ - The story and questions are our own, not a public benchmark.
90
+ - Each system ran once.
91
+ - The grader knew which systems were being compared. When a different grader regraded the answers, Mem0 scored 4 more than Yuanwei on the conversation-150 batch.
92
+ - With the way the preview writes memory now, a re-answer of the same questions on November 10, graded separately, scored 53 and 46. Those numbers are not directly comparable with the table above.
93
+
94
+ Results on public benchmarks, run-to-run variation, cost and speed will follow.
95
+
96
+ ## Documentation
97
+
98
+ The source code and these documents are on GitHub: https://github.com/guzhijun40134679/yuanwei (the documents are in `docs/`, in Chinese for now).
99
+
100
+ - `docs/装到Hermes上.md`: the full user guide.
101
+ - `docs/让助手来装.md`: give it to Hermes and let Hermes install Yuanwei.
102
+ - `docs/产品规则表.md`: every behavior rule and its limits.
103
+ - `docs/开发说明.md`: for people changing the code or writing host adapters.
104
+ - `docs/复制关系表.md`: which code was copied from the research directory.
105
+
106
+ ## Credits
107
+
108
+ Designed and directed by Junzhi Gu. The code was written with Claude ([Anthropic](https://github.com/anthropics)); the algorithms, architecture and code were reviewed with GPT through Codex ([OpenAI](https://github.com/openai)).
109
+
110
+ ## License
111
+
112
+ Source-available under PolyForm Noncommercial 1.0.0: free for personal, learning, research and other non-commercial use; commercial use needs the copyright holder's permission first. Full text in `LICENSE`. Copyright holder: Junzhi Gu (顾钧之).
@@ -0,0 +1,110 @@
1
+ # 原委 Yuanwei
2
+
3
+ [English](https://github.com/guzhijun40134679/yuanwei/blob/main/README.md) | 简体中文
4
+
5
+ **事有原委,话有出处。** 给 AI 助手的长期记忆。
6
+
7
+ > 预览版 · 研究原型,部分功能还在开发和测试中。2026-11-11 在 Hermes v0.22.0(+10397)上试装过,记录里列的各项都过了;没覆盖到的写在限制里。
8
+
9
+ ## 它做什么
10
+
11
+ - **原话原样存。** 你和助手说过的话原样存下,记着是谁说的、哪天说的。不改写,不总结。
12
+ - **按事归好。** 写入时只做一件小事:把每句话挂到哪件事、哪一回,加一句摘要。同一件事的话归在一起,同类不同次的分开。
13
+ - **翻原话回答。** 助手要用到以前的事,先查原话,同一件事的先查,每句带日期交给助手,由助手对着日期理清新旧。
14
+
15
+ 底子是检索原话(也就是常说的 RAG:关键词,加上可选的本机向量),上面加了一层很轻的按事整理。整理只用来帮着找,交给助手的始终是原话。
16
+
17
+ ## 为什么存原话
18
+
19
+ 很多记忆产品的做法,是把对话总结成摘要,或者抽成几条事实再存。我们反过来:原话原样存,整理只当目录。
20
+
21
+ - **总结一错,后面就跟着错**,还查不出是哪句话说的。原话带着日期,对不对你自己能核。
22
+ - **公开研究里也有类似的发现。** LongMemEval 的论文比较过:用摘要或抽出来的事实去代替原话交给模型,答对率会降,跨会话汇总的题是例外;反过来,把抽出来的事实只用来帮着检索、交出去的仍是原话,召回和答对率都提高了。
23
+ - **检索原话这条路还远没挖到头。** 我们自己的测试里,原话检索加一层轻整理,和 Mem0 打平;但每道题真正需要的原话一般只有两三句,我们交给模型的却有几百句。怎么找得更全、交得更准,是接下来要做的。
24
+
25
+ ## 支持哪些助手
26
+
27
+ | 助手 | 状态 |
28
+ |---|---|
29
+ | Hermes | 预览版可用(装成 Hermes 的外接记忆插件) |
30
+ | Claude Code、Codex、Pi | 后续更新 |
31
+
32
+ **系统:目前只在 Mac 上测过**(M 系列芯片的 macOS)。Windows、Linux 没测过。Windows 上已知可能出问题:同时写库时的文件锁不起作用、命令行输出可能乱码或报错、整理时可能闪出黑色窗口;要等用真的 Windows 电脑测过再修。向导在 Mac 以外的系统上会先提醒一句。
33
+
34
+ ## 安装
35
+
36
+ 需要 Python 3.11 以上,以及已经装好的 Hermes。
37
+
38
+ 推荐先给原委单独建一个环境,放在 `~/.yuanwei/venv`(和自带向量引擎的 `~/.yuanwei/engine/` 放在一处,不和别的东西打架)。后面的命令都写完整路径,不用你把 `yuanwei` 加进系统路径:
39
+
40
+ ```
41
+ python3 -m venv ~/.yuanwei/venv
42
+ ~/.yuanwei/venv/bin/pip install yuanwei
43
+ ~/.yuanwei/venv/bin/yuanwei setup
44
+ ```
45
+
46
+ 不想建环境也行,用 `python3 -m pip install yuanwei`(不要直接写 `pip`:有的电脑上只有 `pip3`);装完 `yuanwei` 在哪,向导最后会把完整路径写给你。
47
+
48
+ `yuanwei setup` 是一问一答的向导:检查环境 → 选预设 → 选整理用的模型 → 设密钥(输入时不显示;存在你电脑上只有你能读的一个文件里,几个机器人共用)→ 选要不要开本机向量 → 列出计划 → 你确认了才改。
49
+
50
+ | 预设 | 整理 | 检索 |
51
+ |---|---|---|
52
+ | 推荐 | DeepSeek(整理测过) | 关键词+本机向量(要下载约 600 MB 的模型,问过你才下载;向量:LM Studio 是测过的那一套,自带程序和它几乎一样、没过我们自己定的严格标准) |
53
+ | 轻量 | DeepSeek | 只用关键词 |
54
+ | 自选 | 自己选供应商和模型(没测过) | 自己选 |
55
+ | 全本机(实验) | 本机大模型 | 本机向量 |
56
+
57
+ 本机向量有两种来源:**自带**(Mac 的 M 系列;原委替你准备向量程序和模型,下载前先问你、说清大小,下载后按原委这一版钉住的校验码核对;不用你装别的软件);或者用你电脑上已有的 LM Studio、Ollama。**测过的只有 LM Studio**:自带程序用的是同一个模型文件,算出的向量和 LM Studio 的几乎一样(核对时全量 11,588 句里有 8 句略低于我们定的线,最低 0.9977,没有低于 0.995 的),但没过我们自己定的严格标准,所以不写「测过」。
58
+
59
+ 也可以让助手来装:把 `docs/让助手来装.md` 交给 Hermes。助手只会先列计划给你看,密钥由你自己在终端里设。
60
+
61
+ 完整说明(装、用、看状态、卸载,每一步改什么、怎么撤回):`docs/装到Hermes上.md`。
62
+
63
+ ## 你说了算
64
+
65
+ - **这个窗口别用记忆。** 说一句「别用记忆」,或者在消息第一行写 `#yuanwei-nomem`,这个对话窗口就不再查原委的记忆,直到你重新打开。打开要你自己确认:回一句「确认开启」,或者第一行写 `#yuanwei-mem`,助手替你确认不了。能保证的只有口令;大白话靠助手听懂,可靠度没量过。
66
+ - **删掉一段对话。** 跟助手说一声,你整条回复「确认删除」才删;也可以用命令删。原委里这段对话的原话会删掉,跟它有关的整理文字也一起清掉,删了找不回来。
67
+ - **对话里的密钥先遮掉。** 认得出的 API 密钥、密码,存之前先遮掉,不进记忆,也不发给整理用的模型。认不出的格式可能会漏。
68
+ - **存在你自己的电脑上。** 记忆库是本机的一个 SQLite 文件。整理时会把对话发给你配置的模型服务;向量服务默认只连本机。
69
+ - **只记你本人的话。** 群里别人的话、机器人的话不记。
70
+ - **每个机器人一个库。** Hermes 里新建的机器人要单独装一次原委(对它的目录跑一次向导);没装之前,复制来的设置不会启用,也不会读写主 Hermes 的库。
71
+ - **整理用的密钥全局一份。** 几个机器人共用,换密钥只换一次(`yuanwei key set`);某个机器人要用别的,可以单独给它设(`yuanwei key set --this-bot-only --hermes-home 它的目录`)。想换全局目录可设 `YUANWEI_KEY_DIR`(只认绝对路径;目录会被设成只有你能读,要用专门放密钥的目录;终端和 Hermes 服务要用同一个设置)。`yuanwei key status` 只报来源,不显示密钥的值。
72
+ - **Hermes 自带的记忆照常开着。** 原委只占 Hermes「外接记忆插件」那一个位置。上面那个「别用记忆」的开关只管原委,管不到 Hermes 自带的笔记。
73
+
74
+ ## 测出来怎么样
75
+
76
+ 我们写了一份 150 次对话的中文长故事,出了两批题,每批 55 道。三个记忆系统各自整理,再交给同一个回答模型(DeepSeek)作答,每题的材料额度相同(16,000 词元)。下面是答完整的题数(2026-11-02):
77
+
78
+ | 系统 | 第 48 次对话后 | 第 150 次对话后 |
79
+ |---|---|---|
80
+ | 原委 | 50 | 43 |
81
+ | Mem0 | 49 | 43 |
82
+ | Hindsight | 47 | 34 |
83
+ | 不用记忆系统,把之前的全部原话直接给模型(对照,不受额度限制) | 54 | 没测 |
84
+
85
+ 限制:
86
+ - 这一版只管你和某一个机器人的一对一:群聊、机器人之间互发的消息不记也不查;想记住群里定的事,回到一对一里说一句;
87
+ - 故事和题是我们自己编的,不是公开测试集;
88
+ - 每个系统只跑了一遍;
89
+ - 判卷的人知道比的是哪几家,换一位判卷人复判时,第 150 次那批 Mem0 比原委多 4 题;
90
+ - 预览版现在的写法,11 月 10 日在同一批题上重答、另一次判卷,是 53 题和 46 题,不和上表直接比。
91
+
92
+ 公开测试集上的成绩、多跑几遍的波动、费用和速度,后续会补。
93
+
94
+ ## 文档
95
+
96
+ 源代码和下面这些文档都在 GitHub:https://github.com/guzhijun40134679/yuanwei (文档在 `docs/` 目录里)。
97
+
98
+ - `docs/装到Hermes上.md`:给用户看的完整说明。
99
+ - `docs/让助手来装.md`:交给 Hermes,让它照着装。
100
+ - `docs/产品规则表.md`:每一条行为规则和它的边界。
101
+ - `docs/开发说明.md`:给改代码、写接头的人看。
102
+ - `docs/复制关系表.md`:哪些代码从研究目录复制过来。
103
+
104
+ ## 致谢
105
+
106
+ 顾钧之设计和主导;代码由 Claude([Anthropic](https://github.com/anthropics))协助写成;算法、架构和代码由 GPT([OpenAI](https://github.com/openai),通过 Codex)协助审查。
107
+
108
+ ## 许可
109
+
110
+ 源码公开。PolyForm Noncommercial 1.0.0:个人、学习、研究等非商业用途免费;商业用途要先取得版权人同意。全文见 `LICENSE`,版权人 Junzhi Gu(顾钧之)。
@@ -0,0 +1,37 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "yuanwei"
7
+ version = "0.1.0a1"
8
+ description = "原委:事有原委,话有出处。给 AI 助手用的长期记忆(预览版)"
9
+ requires-python = ">=3.11"
10
+ dependencies = []
11
+ readme = "README.md"
12
+ license = "LicenseRef-PolyForm-Noncommercial-1.0.0"
13
+ license-files = ["LICENSE", "NOTICE"]
14
+ authors = [{ name = "Junzhi Gu (顾钧之)" }]
15
+
16
+ [project.urls]
17
+ Homepage = "https://github.com/guzhijun40134679/yuanwei"
18
+ Source = "https://github.com/guzhijun40134679/yuanwei"
19
+ Issues = "https://github.com/guzhijun40134679/yuanwei/issues"
20
+
21
+ [project.optional-dependencies]
22
+ vector = ["numpy>=1.26"]
23
+ mcp = ["mcp>=1.28.1,<2"] # 官方 Python SDK(MIT);基础包不依赖它,只有 python -m yuanwei.mcp 要用
24
+ test = ["pytest>=8"]
25
+
26
+ [project.scripts]
27
+ yuanwei = "yuanwei.cli:main"
28
+
29
+ [tool.setuptools.packages.find]
30
+ where = ["src"]
31
+
32
+ [tool.setuptools.package-data]
33
+ yuanwei = ["resources/*"]
34
+
35
+ [tool.pytest.ini_options]
36
+ testpaths = ["tests"]
37
+ pythonpath = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,7 @@
1
+ """原委(Yuanwei):给 AI 助手用的长期记忆。记下对话原话,按「主线→哪一回」整理,回答前先查。预览版。"""
2
+ from .config import Config
3
+ from .errors import * # noqa: F401,F403
4
+ from .memory import Memory
5
+
6
+ __version__ = "0.1.0a1"
7
+ __all__ = ["Memory", "Config", "__version__"]
@@ -0,0 +1,5 @@
1
+ import sys
2
+
3
+ from .cli import main
4
+
5
+ sys.exit(main())