agent-memory-git 0.1.5__tar.gz → 0.1.6__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 (64) hide show
  1. agent_memory_git-0.1.6/PKG-INFO +108 -0
  2. agent_memory_git-0.1.6/README.md +87 -0
  3. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/pyproject.toml +4 -3
  4. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/pyproject.toml.orig +4 -3
  5. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/src/agent_memory/cli.py +18 -2
  6. agent_memory_git-0.1.6/src/agent_memory/demo/memories/2026/08/20260804-alex-profile-ujzd.md +17 -0
  7. agent_memory_git-0.1.6/src/agent_memory/demo/memories/2026/08/20260804-reply-language-xdnc.md +15 -0
  8. agent_memory_git-0.1.6/src/agent_memory/demo/memories/2026/08/20260812-ask-before-push-pf3d.md +22 -0
  9. agent_memory_git-0.1.6/src/agent_memory/demo/memories/2026/08/20260820-tests-before-done-odzd.md +22 -0
  10. agent_memory_git-0.1.6/src/agent_memory/demo/memories/2026/08/20260827-etl-orders-export-deadline-pft7.md +22 -0
  11. agent_memory_git-0.1.6/src/agent_memory/demo/memories/2026/08/20260828-etl-dashboard-72ce.md +18 -0
  12. agent_memory_git-0.1.6/src/agent_memory/demo/memories/2026/09/20260902-report-eta-is2j.md +22 -0
  13. agent_memory_git-0.1.6/src/agent_memory/demo/memories/2026/09/20260908-shop-web-stripe-checkout-lgmx.md +22 -0
  14. agent_memory_git-0.1.6/src/agent_memory/demo/memories/2026/09/20260910-shop-web-deploys-dn73.md +23 -0
  15. agent_memory_git-0.1.6/src/agent_memory/demo/memories/2026/09/20260915-etl-parquet-partitioning-seh2.md +22 -0
  16. agent_memory_git-0.1.6/src/agent_memory/demo/memories/2026/09/20260922-design-tokens-source-uvw7.md +20 -0
  17. agent_memory_git-0.1.6/src/agent_memory/demo/memories/2026/10/20261002-shop-web-v3-freeze-5xtp.md +22 -0
  18. agent_memory_git-0.1.6/src/agent_memory/demo/memories/2026/10/20261009-thesis-setup-fr6e.md +19 -0
  19. agent_memory_git-0.1.6/src/agent_memory/demo/memories/2026/10/20261012-payments-runbook-4syw.md +18 -0
  20. agent_memory_git-0.1.6/src/agent_memory/demo.py +112 -0
  21. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/src/agent_memory/install.py +12 -8
  22. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/src/agent_memory/ui_server.py +3 -11
  23. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/src/agent_memory/update.py +1 -1
  24. agent_memory_git-0.1.6/src/agent_memory/webui/app.css +516 -0
  25. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/src/agent_memory/webui/index.html +4 -2
  26. agent_memory_git-0.1.6/src/agent_memory/webui/js/api.js +39 -0
  27. agent_memory_git-0.1.6/src/agent_memory/webui/js/filters.js +71 -0
  28. agent_memory_git-0.1.6/src/agent_memory/webui/js/format.js +31 -0
  29. agent_memory_git-0.1.6/src/agent_memory/webui/js/h.js +74 -0
  30. agent_memory_git-0.1.6/src/agent_memory/webui/js/icons.js +38 -0
  31. agent_memory_git-0.1.6/src/agent_memory/webui/js/main.js +272 -0
  32. agent_memory_git-0.1.6/src/agent_memory/webui/js/markdown.js +124 -0
  33. agent_memory_git-0.1.6/src/agent_memory/webui/js/search.js +39 -0
  34. agent_memory_git-0.1.6/src/agent_memory/webui/js/store.js +386 -0
  35. agent_memory_git-0.1.6/src/agent_memory/webui/js/views/insights.js +161 -0
  36. agent_memory_git-0.1.6/src/agent_memory/webui/js/views/list.js +159 -0
  37. agent_memory_git-0.1.6/src/agent_memory/webui/js/views/memory.js +105 -0
  38. agent_memory_git-0.1.6/src/agent_memory/webui/js/views/overlays.js +54 -0
  39. agent_memory_git-0.1.6/src/agent_memory/webui/js/views/settings.js +84 -0
  40. agent_memory_git-0.1.6/src/agent_memory/webui/js/views/shell.js +69 -0
  41. agent_memory_git-0.1.6/src/agent_memory/webui/js/views/ui.js +40 -0
  42. agent_memory_git-0.1.5/PKG-INFO +0 -214
  43. agent_memory_git-0.1.5/README.md +0 -194
  44. agent_memory_git-0.1.5/src/agent_memory/webui/assets/index-MdftBYNd.js +0 -19
  45. agent_memory_git-0.1.5/src/agent_memory/webui/assets/index-h-rsgD7i.css +0 -1
  46. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/LICENSE +0 -0
  47. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/src/agent_memory/PROTOCOL.md +0 -0
  48. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/src/agent_memory/__init__.py +0 -0
  49. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/src/agent_memory/__main__.py +0 -0
  50. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/src/agent_memory/capture.py +0 -0
  51. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/src/agent_memory/config.py +0 -0
  52. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/src/agent_memory/context.py +0 -0
  53. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/src/agent_memory/embed_worker.py +0 -0
  54. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/src/agent_memory/frontmatter.py +0 -0
  55. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/src/agent_memory/gitsync.py +0 -0
  56. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/src/agent_memory/hooks.py +0 -0
  57. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/src/agent_memory/importers.py +0 -0
  58. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/src/agent_memory/lint.py +0 -0
  59. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/src/agent_memory/select.py +0 -0
  60. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/src/agent_memory/sessions.py +0 -0
  61. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/src/agent_memory/store.py +0 -0
  62. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/src/agent_memory/ui.py +0 -0
  63. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/src/agent_memory/util.py +0 -0
  64. {agent_memory_git-0.1.5 → agent_memory_git-0.1.6}/src/agent_memory/workdir.py +0 -0
@@ -0,0 +1,108 @@
1
+ Metadata-Version: 2.4
2
+ Name: agent-memory-git
3
+ Version: 0.1.6
4
+ Summary: Shared, git-backed memory for Claude Code and Codex.
5
+ Keywords: claude-code,codex,memory,agents,git
6
+ Author: Shichao Song
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Classifier: Environment :: Console
10
+ Classifier: Operating System :: MacOS
11
+ Classifier: Operating System :: POSIX :: Linux
12
+ Classifier: Programming Language :: Python :: 3
13
+ Requires-Dist: numpy>=2.0 ; extra == 'ui'
14
+ Requires-Python: >=3.11
15
+ Project-URL: Homepage, https://ki-seki.github.io/agent-memory/
16
+ Project-URL: Documentation, https://ki-seki.github.io/agent-memory/docs.html
17
+ Project-URL: Demo, https://ki-seki.github.io/agent-memory/demo/
18
+ Project-URL: Repository, https://github.com/Ki-Seki/agent-memory
19
+ Provides-Extra: ui
20
+ Description-Content-Type: text/markdown
21
+
22
+ <p align="center">
23
+ <img src="https://raw.githubusercontent.com/Ki-Seki/agent-memory/main/docs/logo.svg" width="64" height="64" alt="">
24
+ </p>
25
+
26
+ <h1 align="center">agent-memory</h1>
27
+
28
+ <p align="center">
29
+ <b>One memory for Claude Code and Codex.</b><br>
30
+ What your agents learn, kept as plain Markdown in a git repository you own.
31
+ </p>
32
+
33
+ <p align="center">
34
+ <a href="https://ki-seki.github.io/agent-memory/demo/"><b>Live demo</b></a> ·
35
+ <a href="https://ki-seki.github.io/agent-memory/">Website</a> ·
36
+ <a href="https://ki-seki.github.io/agent-memory/docs.html">Docs</a>
37
+ </p>
38
+
39
+ <p align="center">
40
+ <a href="https://pypi.org/project/agent-memory-git/"><img src="https://img.shields.io/pypi/v/agent-memory-git?color=5b5bd6" alt="PyPI"></a>
41
+ <a href="https://pypi.org/project/agent-memory-git/"><img src="https://img.shields.io/pypi/pyversions/agent-memory-git?color=5b5bd6" alt="Python"></a>
42
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-5b5bd6" alt="MIT license"></a>
43
+ </p>
44
+
45
+ <a href="https://ki-seki.github.io/agent-memory/demo/">
46
+ <picture>
47
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Ki-Seki/agent-memory/main/site/assets/shots/memories-dark.png">
48
+ <img alt="mem ui, open in the live demo: a list of memories on the left, one open on the right with where it came from" src="https://raw.githubusercontent.com/Ki-Seki/agent-memory/main/site/assets/shots/memories-light.png">
49
+ </picture>
50
+ </a>
51
+
52
+ ## Why agent-memory
53
+
54
+ - **Tell one agent, both remember.** A preference you give Codex is there the next time Claude
55
+ Code starts, and the other way round, on every machine that pulls.
56
+ - **The right memories in each session.** Everything global, plus what was learned in this folder
57
+ or repository, and nothing from your other projects.
58
+ - **Memory in git.** One Markdown file per memory in a git repository you own, with where it came
59
+ from recorded by the hooks. Every change is a commit you can review or revert; add a private
60
+ remote to sync machines, or keep it all on one. Here is [an example](https://github.com/Ki-Seki/agent-memory-data-demo).
61
+ - **Nothing to run.** Two hooks and git. No service, no account; search by meaning runs on your CPU.
62
+ - **A page to keep it tidy.** `mem ui` searches by words and by meaning, edits with undo, and shows
63
+ what changed week by week.
64
+
65
+ ## Quick start
66
+
67
+ See it first, with nothing installed:
68
+
69
+ ```bash
70
+ uvx --from "agent-memory-git[ui]" mem ui --demo
71
+ ```
72
+
73
+ Then set it up (Python 3.11+, git and [uv](https://docs.astral.sh/uv/)):
74
+
75
+ ```bash
76
+ uv tool install "agent-memory-git[ui]"
77
+ mem init ~/repos/agent-memory-data # your data repository
78
+ mem install --dry-run # every change, as a diff
79
+ mem install
80
+ ```
81
+
82
+ Codex asks you to trust new hooks once: open `/hooks` in Codex and enable the three agent-memory
83
+ hooks. The [docs](https://ki-seki.github.io/agent-memory/docs.html#install) cover importing existing
84
+ memories, every file `mem install` changes, upgrading and uninstalling.
85
+
86
+ ## How it works
87
+
88
+ ![mem install wires hooks into Claude Code and Codex; at session start they load an index from the private data repository, and at the end of each turn they commit and push new memories back](https://raw.githubusercontent.com/Ki-Seki/agent-memory/main/docs/how-it-works.svg)
89
+
90
+ At session start a hook gives the agent an index of the memories that apply where it runs. The
91
+ agent saves what is worth keeping as Markdown files, following
92
+ [PROTOCOL.md](src/agent_memory/PROTOCOL.md), and at the end of each turn a hook records where each
93
+ came from, commits and pushes. The [docs](https://ki-seki.github.io/agent-memory/docs.html) explain
94
+ the file format, where memories load, the commands and the configuration.
95
+
96
+ ## Contributing
97
+
98
+ ```bash
99
+ uv sync --all-extras && uv run pytest
100
+ ```
101
+
102
+ The `mem ui` page is plain HTML, CSS and JavaScript with no build step, and
103
+ `uv run scripts/site.py serve` runs the website and its live demo locally. More in the
104
+ [docs](https://ki-seki.github.io/agent-memory/docs.html#development).
105
+
106
+ ## License
107
+
108
+ [MIT](LICENSE)
@@ -0,0 +1,87 @@
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/Ki-Seki/agent-memory/main/docs/logo.svg" width="64" height="64" alt="">
3
+ </p>
4
+
5
+ <h1 align="center">agent-memory</h1>
6
+
7
+ <p align="center">
8
+ <b>One memory for Claude Code and Codex.</b><br>
9
+ What your agents learn, kept as plain Markdown in a git repository you own.
10
+ </p>
11
+
12
+ <p align="center">
13
+ <a href="https://ki-seki.github.io/agent-memory/demo/"><b>Live demo</b></a> ·
14
+ <a href="https://ki-seki.github.io/agent-memory/">Website</a> ·
15
+ <a href="https://ki-seki.github.io/agent-memory/docs.html">Docs</a>
16
+ </p>
17
+
18
+ <p align="center">
19
+ <a href="https://pypi.org/project/agent-memory-git/"><img src="https://img.shields.io/pypi/v/agent-memory-git?color=5b5bd6" alt="PyPI"></a>
20
+ <a href="https://pypi.org/project/agent-memory-git/"><img src="https://img.shields.io/pypi/pyversions/agent-memory-git?color=5b5bd6" alt="Python"></a>
21
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-5b5bd6" alt="MIT license"></a>
22
+ </p>
23
+
24
+ <a href="https://ki-seki.github.io/agent-memory/demo/">
25
+ <picture>
26
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Ki-Seki/agent-memory/main/site/assets/shots/memories-dark.png">
27
+ <img alt="mem ui, open in the live demo: a list of memories on the left, one open on the right with where it came from" src="https://raw.githubusercontent.com/Ki-Seki/agent-memory/main/site/assets/shots/memories-light.png">
28
+ </picture>
29
+ </a>
30
+
31
+ ## Why agent-memory
32
+
33
+ - **Tell one agent, both remember.** A preference you give Codex is there the next time Claude
34
+ Code starts, and the other way round, on every machine that pulls.
35
+ - **The right memories in each session.** Everything global, plus what was learned in this folder
36
+ or repository, and nothing from your other projects.
37
+ - **Memory in git.** One Markdown file per memory in a git repository you own, with where it came
38
+ from recorded by the hooks. Every change is a commit you can review or revert; add a private
39
+ remote to sync machines, or keep it all on one. Here is [an example](https://github.com/Ki-Seki/agent-memory-data-demo).
40
+ - **Nothing to run.** Two hooks and git. No service, no account; search by meaning runs on your CPU.
41
+ - **A page to keep it tidy.** `mem ui` searches by words and by meaning, edits with undo, and shows
42
+ what changed week by week.
43
+
44
+ ## Quick start
45
+
46
+ See it first, with nothing installed:
47
+
48
+ ```bash
49
+ uvx --from "agent-memory-git[ui]" mem ui --demo
50
+ ```
51
+
52
+ Then set it up (Python 3.11+, git and [uv](https://docs.astral.sh/uv/)):
53
+
54
+ ```bash
55
+ uv tool install "agent-memory-git[ui]"
56
+ mem init ~/repos/agent-memory-data # your data repository
57
+ mem install --dry-run # every change, as a diff
58
+ mem install
59
+ ```
60
+
61
+ Codex asks you to trust new hooks once: open `/hooks` in Codex and enable the three agent-memory
62
+ hooks. The [docs](https://ki-seki.github.io/agent-memory/docs.html#install) cover importing existing
63
+ memories, every file `mem install` changes, upgrading and uninstalling.
64
+
65
+ ## How it works
66
+
67
+ ![mem install wires hooks into Claude Code and Codex; at session start they load an index from the private data repository, and at the end of each turn they commit and push new memories back](https://raw.githubusercontent.com/Ki-Seki/agent-memory/main/docs/how-it-works.svg)
68
+
69
+ At session start a hook gives the agent an index of the memories that apply where it runs. The
70
+ agent saves what is worth keeping as Markdown files, following
71
+ [PROTOCOL.md](src/agent_memory/PROTOCOL.md), and at the end of each turn a hook records where each
72
+ came from, commits and pushes. The [docs](https://ki-seki.github.io/agent-memory/docs.html) explain
73
+ the file format, where memories load, the commands and the configuration.
74
+
75
+ ## Contributing
76
+
77
+ ```bash
78
+ uv sync --all-extras && uv run pytest
79
+ ```
80
+
81
+ The `mem ui` page is plain HTML, CSS and JavaScript with no build step, and
82
+ `uv run scripts/site.py serve` runs the website and its live demo locally. More in the
83
+ [docs](https://ki-seki.github.io/agent-memory/docs.html#development).
84
+
85
+ ## License
86
+
87
+ [MIT](LICENSE)
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "agent-memory-git"
3
- version = "0.1.5"
3
+ version = "0.1.6"
4
4
  description = "Shared, git-backed memory for Claude Code and Codex."
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -31,9 +31,10 @@ ui = ["numpy>=2.0"]
31
31
  mem = "agent_memory.cli:main"
32
32
 
33
33
  [project.urls]
34
- Homepage = "https://github.com/Ki-Seki/agent-memory"
34
+ Homepage = "https://ki-seki.github.io/agent-memory/"
35
+ Documentation = "https://ki-seki.github.io/agent-memory/docs.html"
36
+ Demo = "https://ki-seki.github.io/agent-memory/demo/"
35
37
  Repository = "https://github.com/Ki-Seki/agent-memory"
36
- Demo = "https://github.com/Ki-Seki/agent-memory-data-demo"
37
38
 
38
39
  [build-system]
39
40
  requires = ["uv_build>=0.12.13,<0.13.0"]
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "agent-memory-git"
3
- version = "0.1.5"
3
+ version = "0.1.6"
4
4
  description = "Shared, git-backed memory for Claude Code and Codex."
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -23,9 +23,10 @@ ui = ["numpy>=2.0"]
23
23
  mem = "agent_memory.cli:main"
24
24
 
25
25
  [project.urls]
26
- Homepage = "https://github.com/Ki-Seki/agent-memory"
26
+ Homepage = "https://ki-seki.github.io/agent-memory/"
27
+ Documentation = "https://ki-seki.github.io/agent-memory/docs.html"
28
+ Demo = "https://ki-seki.github.io/agent-memory/demo/"
27
29
  Repository = "https://github.com/Ki-Seki/agent-memory"
28
- Demo = "https://github.com/Ki-Seki/agent-memory-data-demo"
29
30
 
30
31
  [build-system]
31
32
  requires = ["uv_build>=0.12.13,<0.13.0"]
@@ -1,6 +1,9 @@
1
1
  """`mem` command line."""
2
2
 
3
3
  import argparse
4
+ import atexit
5
+ import os
6
+ import shutil
4
7
  import sys
5
8
  from pathlib import Path
6
9
 
@@ -179,10 +182,20 @@ def cmd_lint(args):
179
182
 
180
183
 
181
184
  def cmd_ui(args):
182
- from . import ui, ui_server
185
+ from . import demo, ui, ui_server
183
186
 
184
187
  if args.fetch_model:
185
188
  return ui.fetch_model()
189
+ if args.demo:
190
+ # in a new process, so every path the config module works out on import points into the demo
191
+ demo.prepare()
192
+ again = (
193
+ ["ui", "--port", str(args.port)] + ["--no-open"] * args.no_open + ["--keywords-only"] * args.keywords_only
194
+ )
195
+ os.execv(sys.executable, [sys.executable, "-m", "agent_memory", *again])
196
+ if os.environ.get(demo.ENV):
197
+ print("Demo: made-up memories in a temporary repository; nothing you change is kept.", flush=True)
198
+ atexit.register(shutil.rmtree, os.environ[demo.ENV], ignore_errors=True)
186
199
  ui_server.run(_data(), port=args.port, open_browser=not args.no_open, semantic=not args.keywords_only)
187
200
 
188
201
 
@@ -220,7 +233,7 @@ def cmd_import(args):
220
233
  def cmd_doctor(args):
221
234
  from .install import doctor
222
235
 
223
- doctor()
236
+ return doctor()
224
237
 
225
238
 
226
239
  def cmd_hook(args):
@@ -286,6 +299,9 @@ def main(argv=None):
286
299
  sp.add_argument(
287
300
  "--fetch-model", action="store_true", help="download the local embedding model (about 625 MB) and exit"
288
301
  )
302
+ sp.add_argument(
303
+ "--demo", action="store_true", help="open made-up memories in a temporary repository instead of yours"
304
+ )
289
305
  sp.set_defaults(fn=cmd_ui)
290
306
 
291
307
  sp = sub.add_parser("sync", help="pull and push the data repository")
@@ -0,0 +1,17 @@
1
+ ---
2
+ id: 20260804-alex-profile-ujzd
3
+ name: alex-profile
4
+ type: user
5
+ scope: global
6
+ description: Alex is a backend engineer working mostly in Python and TypeScript; prefers short answers with the code first
7
+ created: 2026-08-04T10:12:00+08:00
8
+ source:
9
+ tool: claude-code
10
+ session_id: 1818e811-892f-402b-923f-0824128b2f33
11
+ session_name: set-up-laptop
12
+ host: alex-laptop
13
+ cwd: /Users/alex/code/shop-web
14
+ ---
15
+ Alex is a backend engineer. Most work is Python (data jobs) and TypeScript (the shop-web app).
16
+
17
+ Prefers short answers that lead with the code or command, then one or two lines of explanation.
@@ -0,0 +1,15 @@
1
+ ---
2
+ id: 20260804-reply-language-xdnc
3
+ name: reply-language
4
+ type: user
5
+ scope: global
6
+ description: Alex 在上海;对话默认用中文回复,代码、注释和提交信息用英文
7
+ created: 2026-08-04T10:20:00+08:00
8
+ source:
9
+ tool: codex
10
+ session_id: 11e20b8f-6b0d-449b-af03-675a1600a35a
11
+ session_name: 整理开发环境
12
+ host: alex-laptop
13
+ cwd: /Users/alex/code/shop-web
14
+ ---
15
+ Alex 在上海(UTC+8)。对话默认用中文回复;代码、注释、提交信息和 PR 描述用英文。
@@ -0,0 +1,22 @@
1
+ ---
2
+ id: 20260812-ask-before-push-pf3d
3
+ name: ask-before-push
4
+ type: feedback
5
+ scope: global
6
+ description: Ask before every git push, and keep each commit to one change
7
+ created: 2026-08-12T15:40:00+08:00
8
+ source:
9
+ tool: claude-code
10
+ session_id: f28c105d-1fb1-4c23-90c1-92cfd3ac94af
11
+ session_name: shop-web-checkout
12
+ host: alex-laptop
13
+ cwd: /Users/alex/code/shop-web
14
+ git_root: /Users/alex/code/shop-web
15
+ git_remote: git.example.com/shop-web
16
+ git_branch: main
17
+ ---
18
+ Ask Alex before every `git push`, even when an earlier push in the same session was approved. Keep each commit to one change.
19
+
20
+ **Why:** a force-push once overwrote a teammate's commit on a shared branch.
21
+
22
+ **How to apply:** commit locally as you go, then list the commits and ask before pushing. Split unrelated edits into separate commits.
@@ -0,0 +1,22 @@
1
+ ---
2
+ id: 20260820-tests-before-done-odzd
3
+ name: tests-before-done
4
+ type: feedback
5
+ scope: global
6
+ description: Run the tests before saying a change works, and quote the failing output when they fail
7
+ created: 2026-08-20T09:05:00+08:00
8
+ source:
9
+ tool: codex
10
+ session_id: 8e81973e-0bec-47b0-b898-d190f9ebdacc
11
+ session_name: etl-nightly-export
12
+ host: alex-laptop
13
+ cwd: /Users/alex/code/etl-jobs
14
+ git_root: /Users/alex/code/etl-jobs
15
+ git_remote: git.example.com/etl-jobs
16
+ git_branch: main
17
+ ---
18
+ Before saying a change works, run the project's tests (`pytest -q` in etl-jobs, `pnpm test` in shop-web).
19
+
20
+ **Why:** twice a fix was reported as done while the suite was red.
21
+
22
+ **How to apply:** paste the summary line; if anything fails, show the failing output instead of paraphrasing it.
@@ -0,0 +1,22 @@
1
+ ---
2
+ id: 20260827-etl-orders-export-deadline-pft7
3
+ name: etl-orders-export-deadline
4
+ type: project
5
+ scope: here
6
+ description: "etl-jobs: the nightly orders export must finish before 06:00 because finance reads it at 06:30"
7
+ created: 2026-08-27T08:30:00+08:00
8
+ source:
9
+ tool: codex
10
+ session_id: 72e6cc3a-babc-4d20-97ee-05cde00902c7
11
+ session_name: etl-nightly-export
12
+ host: alex-laptop
13
+ cwd: /Users/alex/code/etl-jobs
14
+ git_root: /Users/alex/code/etl-jobs
15
+ git_remote: git.example.com/etl-jobs
16
+ git_branch: main
17
+ ---
18
+ The `orders_export` job in etl-jobs runs at 01:00 and must finish before 06:00 (Shanghai time); finance pulls the file at 06:30.
19
+
20
+ **Why:** the daily revenue report is built from it; a late file delays that report for everyone.
21
+
22
+ **How to apply:** do not add heavy steps to `orders_export`; anything slow goes in a separate job after 06:30.
@@ -0,0 +1,18 @@
1
+ ---
2
+ id: 20260828-etl-dashboard-72ce
3
+ name: etl-dashboard
4
+ type: reference
5
+ scope: global
6
+ description: "etl-jobs run history and alerts: the Grafana dashboard at grafana.example.com/d/etl-runs"
7
+ created: 2026-08-28T10:00:00+08:00
8
+ source:
9
+ tool: codex
10
+ session_id: ca02135e-92b1-43f2-8ede-0d7ac3baea9e
11
+ session_name: etl-nightly-export
12
+ host: alex-laptop
13
+ cwd: /Users/alex/code/etl-jobs
14
+ git_root: /Users/alex/code/etl-jobs
15
+ git_remote: git.example.com/etl-jobs
16
+ git_branch: main
17
+ ---
18
+ Run history, durations and failure alerts for every etl-jobs job are on the Grafana dashboard `grafana.example.com/d/etl-runs`. The `orders_export` panel shows how close each night came to the 06:00 deadline ([[etl-orders-export-deadline]]).
@@ -0,0 +1,22 @@
1
+ ---
2
+ id: 20260902-report-eta-is2j
3
+ name: report-eta
4
+ type: feedback
5
+ scope: global
6
+ description: 长任务开跑时要报预计完成时间,用上海时间
7
+ created: 2026-09-02T21:30:00+08:00
8
+ source:
9
+ tool: claude-code
10
+ session_id: 4ef8aa38-9227-4658-9e27-a1c08a6a63ec
11
+ session_name: etl-backfill
12
+ host: alex-laptop
13
+ cwd: /Users/alex/code/etl-jobs
14
+ git_root: /Users/alex/code/etl-jobs
15
+ git_remote: git.example.com/etl-jobs
16
+ git_branch: main
17
+ ---
18
+ 启动任何超过几分钟的任务(回填、训练、批量导出)时,先说还要多久、预计上海时间几点完成。
19
+
20
+ **Why:** Alex 需要据此安排什么时候回来看结果。
21
+
22
+ **How to apply:** 开跑时报一次,进度明显偏离时再更新一次。
@@ -0,0 +1,22 @@
1
+ ---
2
+ id: 20260908-shop-web-stripe-checkout-lgmx
3
+ name: shop-web-stripe-checkout
4
+ type: project
5
+ scope: here
6
+ description: shop-web checkout moved to the Stripe Payment Element in September; the old Charges API code path is dead
7
+ created: 2026-09-08T14:10:00+08:00
8
+ source:
9
+ tool: claude-code
10
+ session_id: 1012f037-b64c-4422-8c38-fb2918f135d2
11
+ session_name: shop-web-checkout
12
+ host: alex-laptop
13
+ cwd: /Users/alex/code/shop-web
14
+ git_root: /Users/alex/code/shop-web
15
+ git_remote: git.example.com/shop-web
16
+ git_branch: main
17
+ ---
18
+ Checkout in shop-web now uses the Stripe Payment Element (`src/checkout/PaymentForm.tsx`). The old Charges API path in `src/legacy/charge.ts` is no longer called and is kept only until the v3 cleanup.
19
+
20
+ **Why:** Charges API is deprecated, and 3-D Secure needed the Payment Element.
21
+
22
+ **How to apply:** do not fix bugs in `src/legacy/`; change the Payment Element flow instead. See [[shop-web-deploys]] before shipping.
@@ -0,0 +1,23 @@
1
+ ---
2
+ id: 20260910-shop-web-deploys-dn73
3
+ name: shop-web-deploys
4
+ type: project
5
+ scope: here
6
+ description: "shop-web: staging deploys from the release branch, production only from version tags"
7
+ created: 2026-09-10T11:00:00+08:00
8
+ updated: 2026-10-03T10:05:00+08:00
9
+ source:
10
+ tool: codex
11
+ session_id: 95e761d1-7731-4f10-906b-f2efc6f87718
12
+ session_name: shop-web-release
13
+ host: alex-laptop
14
+ cwd: /Users/alex/code/shop-web
15
+ git_root: /Users/alex/code/shop-web
16
+ git_remote: git.example.com/shop-web
17
+ git_branch: main
18
+ ---
19
+ shop-web staging deploys automatically from the `release` branch. Production deploys only from tags like `v2.14.0`, cut from `release` after QA signs off.
20
+
21
+ **Why:** QA signs off on what runs in staging, and a tag pins exactly the build they approved.
22
+
23
+ **How to apply:** never tag from `main`; open the release PR into `release` first.
@@ -0,0 +1,22 @@
1
+ ---
2
+ id: 20260915-etl-parquet-partitioning-seh2
3
+ name: etl-parquet-partitioning
4
+ type: project
5
+ scope: here
6
+ description: etl-jobs 的 Parquet 按日期分区而不是按客户;改分区前要先迁移历史数据
7
+ created: 2026-09-15T19:20:00+08:00
8
+ source:
9
+ tool: claude-code
10
+ session_id: 26e87555-5790-482e-81d3-fcff2a3af4d4
11
+ session_name: etl-backfill
12
+ host: alex-laptop
13
+ cwd: /Users/alex/code/etl-jobs
14
+ git_root: /Users/alex/code/etl-jobs
15
+ git_remote: git.example.com/etl-jobs
16
+ git_branch: main
17
+ ---
18
+ etl-jobs 写出的 Parquet 按 `dt=YYYY-MM-DD` 分区,不按客户分区。下游报表都假设这个布局。
19
+
20
+ **Why:** 按客户分区会产生上万个小文件,查询反而变慢。
21
+
22
+ **How to apply:** 想改分区方式,先写迁移脚本处理历史数据,再改写入逻辑。
@@ -0,0 +1,20 @@
1
+ ---
2
+ id: 20260922-design-tokens-source-uvw7
3
+ name: design-tokens-source
4
+ type: reference
5
+ scope: global
6
+ description: Design tokens (colours, spacing, type) live in git.example.com/design-tokens and sync into shop-web weekly
7
+ created: 2026-09-22T13:15:00+08:00
8
+ source:
9
+ tool: claude-code
10
+ session_id: 119a72d1-74c9-4f6a-8c01-1cdd9474031b
11
+ session_name: shop-web-theme
12
+ host: alex-laptop
13
+ cwd: /Users/alex/code/shop-web
14
+ git_root: /Users/alex/code/shop-web
15
+ git_remote: git.example.com/shop-web
16
+ git_branch: main
17
+ ---
18
+ Colours, spacing and type scales come from `git.example.com/design-tokens`. A weekly bot PR copies them into `shop-web/src/theme/tokens.ts`.
19
+
20
+ **How to apply:** change tokens in design-tokens, not in shop-web; local edits are overwritten by the next sync.
@@ -0,0 +1,22 @@
1
+ ---
2
+ id: 20261002-shop-web-v3-freeze-5xtp
3
+ name: shop-web-v3-freeze
4
+ type: project
5
+ scope: here
6
+ description: "shop-web v3 feature freeze on 2026-11-01: no schema migrations after that date"
7
+ created: 2026-10-02T16:45:00+08:00
8
+ source:
9
+ tool: claude-code
10
+ session_id: c7a2ea20-b2f1-4c94-ae05-319acb5c7427
11
+ session_name: shop-web-v3-plan
12
+ host: alex-laptop
13
+ cwd: /Users/alex/code/shop-web
14
+ git_root: /Users/alex/code/shop-web
15
+ git_remote: git.example.com/shop-web
16
+ git_branch: main
17
+ ---
18
+ Feature freeze for shop-web v3 is 2026-11-01. After that only bug fixes land; no database schema migrations until the v3 release.
19
+
20
+ **Why:** the data team snapshots the schema for the Q4 reporting work.
21
+
22
+ **How to apply:** if a change needs a migration, flag it before the freeze. Release flow: [[shop-web-deploys]].
@@ -0,0 +1,19 @@
1
+ ---
2
+ id: 20261009-thesis-setup-fr6e
3
+ name: thesis-setup
4
+ type: project
5
+ scope: here
6
+ description: "Thesis: LaTeX in ~/Documents/thesis, figures come from plots.py; chapter 3 is due to the advisor on Nov 15"
7
+ created: 2026-10-09T22:10:00+08:00
8
+ source:
9
+ tool: claude-code
10
+ session_id: 4f426dcb-b394-4b36-bb2d-420f0f88080b
11
+ session_name: thesis-figures
12
+ host: alex-laptop
13
+ cwd: /Users/alex/Documents/thesis
14
+ ---
15
+ The thesis is a LaTeX project in `~/Documents/thesis` (not a git repo; it syncs through iCloud), and chapter 3 is due to the advisor on 2026-11-15.
16
+
17
+ **Why:** the figures change whenever the data does, so they are generated by `plots.py` into `figures/` rather than edited.
18
+
19
+ **How to apply:** change `plots.py` and rerun it instead of touching the PDFs; plan chapter 3 work back from 2026-11-15.
@@ -0,0 +1,18 @@
1
+ ---
2
+ id: 20261012-payments-runbook-4syw
3
+ name: payments-runbook
4
+ type: reference
5
+ scope: global
6
+ description: "On-call runbook for payment failures: docs.example.com/runbooks/payments"
7
+ created: 2026-10-12T09:40:00+08:00
8
+ source:
9
+ tool: codex
10
+ session_id: 5affb229-7631-4992-b0ce-583505c6af07
11
+ session_name: shop-web-oncall
12
+ host: alex-laptop
13
+ cwd: /Users/alex/code/shop-web
14
+ git_root: /Users/alex/code/shop-web
15
+ git_remote: git.example.com/shop-web
16
+ git_branch: main
17
+ ---
18
+ When checkout payments fail, follow `docs.example.com/runbooks/payments`: check the Stripe status page, then the webhook queue, then recent shop-web deploys. Background: [[shop-web-stripe-checkout]].