memorytrace 0.1.0__tar.gz → 0.3.0__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 (136) hide show
  1. memorytrace-0.3.0/.claude/workspace/evaluation.md +72 -0
  2. {memorytrace-0.1.0 → memorytrace-0.3.0}/.gitignore +20 -20
  3. {memorytrace-0.1.0 → memorytrace-0.3.0}/CLAUDE.md +13 -0
  4. {memorytrace-0.1.0 → memorytrace-0.3.0}/LICENSE +21 -21
  5. {memorytrace-0.1.0 → memorytrace-0.3.0}/PKG-INFO +4 -4
  6. {memorytrace-0.1.0 → memorytrace-0.3.0}/README.md +100 -100
  7. memorytrace-0.3.0/claude-setup/.claude/agents/evaluator.md +83 -0
  8. memorytrace-0.3.0/claude-setup/.claude/agents/planner.md +50 -0
  9. memorytrace-0.3.0/claude-setup/.claude/agents/researcher.md +19 -0
  10. memorytrace-0.3.0/claude-setup/.claude/agents/security-reviewer.md +36 -0
  11. memorytrace-0.3.0/claude-setup/.claude/hooks/README.md +46 -0
  12. memorytrace-0.3.0/claude-setup/.claude/hooks/on-stop-checkpoint.sh +25 -0
  13. memorytrace-0.3.0/claude-setup/.claude/hooks/on-stop-verify.sh +40 -0
  14. memorytrace-0.3.0/claude-setup/.claude/hooks/post-edit-completeness.sh +55 -0
  15. memorytrace-0.3.0/claude-setup/.claude/hooks/post-edit-lint.sh +34 -0
  16. memorytrace-0.3.0/claude-setup/.claude/hooks/post-edit-robustness.sh +70 -0
  17. memorytrace-0.3.0/claude-setup/.claude/hooks/pre-compact-save.sh +25 -0
  18. memorytrace-0.3.0/claude-setup/.claude/hooks/session-memory-load.sh +35 -0
  19. memorytrace-0.3.0/claude-setup/.claude/hooks/stop-memory-save.sh +52 -0
  20. memorytrace-0.3.0/claude-setup/.claude/rules/harness-design.md +12 -0
  21. memorytrace-0.3.0/claude-setup/.claude/rules/production-robustness.md +85 -0
  22. memorytrace-0.3.0/claude-setup/.claude/settings.json +123 -0
  23. memorytrace-0.3.0/claude-setup/.claude/skills/deploy/SKILL.md +21 -0
  24. memorytrace-0.3.0/claude-setup/.claude/skills/memory-context/SKILL.md +30 -0
  25. memorytrace-0.3.0/claude-setup/.claude/skills/memory-find/SKILL.md +29 -0
  26. memorytrace-0.3.0/claude-setup/.claude/skills/memory-save/SKILL.md +30 -0
  27. memorytrace-0.3.0/claude-setup/.claude/skills/review/SKILL.md +77 -0
  28. memorytrace-0.3.0/claude-setup/.claude/skills/sprint/SKILL.md +62 -0
  29. memorytrace-0.3.0/claude-setup/.claude/skills/thorough/SKILL.md +49 -0
  30. memorytrace-0.3.0/claude-setup/.gitignore +11 -0
  31. memorytrace-0.3.0/claude-setup/CLAUDE.md +141 -0
  32. memorytrace-0.3.0/claude-setup/README.md +62 -0
  33. memorytrace-0.3.0/claude-setup/blog-post.md +199 -0
  34. memorytrace-0.3.0/claude-setup/install.sh +290 -0
  35. {memorytrace-0.1.0 → memorytrace-0.3.0}/docs/01-project-analysis/01-overview.md +49 -49
  36. {memorytrace-0.1.0 → memorytrace-0.3.0}/docs/01-project-analysis/02-tech-stack.md +60 -60
  37. {memorytrace-0.1.0 → memorytrace-0.3.0}/docs/01-project-analysis/03-architecture.md +171 -171
  38. {memorytrace-0.1.0 → memorytrace-0.3.0}/docs/01-project-analysis/04-directory-structure.md +130 -130
  39. {memorytrace-0.1.0 → memorytrace-0.3.0}/docs/01-project-analysis/05-cli-commands.md +95 -95
  40. {memorytrace-0.1.0 → memorytrace-0.3.0}/docs/01-project-analysis/06-core-features.md +200 -200
  41. {memorytrace-0.1.0 → memorytrace-0.3.0}/docs/01-project-analysis/07-storage-model.md +173 -173
  42. {memorytrace-0.1.0 → memorytrace-0.3.0}/docs/01-project-analysis/08-design-decisions.md +151 -151
  43. {memorytrace-0.1.0 → memorytrace-0.3.0}/docs/01-project-analysis/09-setup-guide.md +181 -181
  44. {memorytrace-0.1.0 → memorytrace-0.3.0}/docs/02-problem-analysis/10-problem-analysis.md +394 -394
  45. {memorytrace-0.1.0 → memorytrace-0.3.0}/docs/02-problem-analysis/11-agent-memory-critique.md +398 -398
  46. {memorytrace-0.1.0 → memorytrace-0.3.0}/docs/02-problem-analysis/13-markdown-storage-problems.md +646 -646
  47. memorytrace-0.3.0/docs/02-problem-analysis/14-engram-code-review-2026-04-12.md +346 -0
  48. memorytrace-0.3.0/docs/02-problem-analysis/15-engram-code-review-followup-2026-04-12.md +371 -0
  49. memorytrace-0.3.0/docs/02-problem-analysis/16-engram-code-review-round3-2026-04-12.md +295 -0
  50. memorytrace-0.3.0/docs/02-problem-analysis/17-engram-code-review-round4-and-korean-ner-plan-2026-04-12.md +314 -0
  51. {memorytrace-0.1.0 → memorytrace-0.3.0}/docs/03-improvement-plan/12-improvements-blueprint.md +817 -817
  52. {memorytrace-0.1.0 → memorytrace-0.3.0}/docs/04-usage-guide/01-quickstart.md +273 -273
  53. {memorytrace-0.1.0 → memorytrace-0.3.0}/docs/04-usage-guide/02-claude-code-setup.md +161 -161
  54. memorytrace-0.3.0/docs/05-windows-compatibility/windows-encoding.md +95 -0
  55. {memorytrace-0.1.0 → memorytrace-0.3.0}/docs/README.md +41 -39
  56. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/__init__.py +8 -8
  57. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/__main__.py +6 -6
  58. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/cli/__init__.py +1 -1
  59. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/cli/app.py +301 -291
  60. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/cli/formatters.py +90 -90
  61. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/cli/simple.py +74 -2
  62. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/config.py +72 -72
  63. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/engine.py +782 -612
  64. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/exceptions.py +41 -41
  65. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/extraction/__init__.py +6 -6
  66. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/extraction/base.py +20 -20
  67. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/extraction/llm_extractor.py +197 -197
  68. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/extraction/ner/__init__.py +7 -7
  69. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/extraction/ner/cjk.py +63 -63
  70. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/extraction/ner/english.py +109 -109
  71. memorytrace-0.3.0/engram/extraction/ner/korean.py +176 -0
  72. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/extraction/regex_extractor.py +188 -188
  73. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/integrations/__init__.py +1 -1
  74. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/integrations/mcp_server.py +218 -213
  75. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/integrations/sdk.py +197 -194
  76. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/models/__init__.py +19 -19
  77. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/models/entity.py +72 -72
  78. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/models/fact.py +58 -58
  79. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/models/quality.py +62 -61
  80. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/models/relation.py +26 -26
  81. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/models/search.py +112 -96
  82. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/models/session.py +53 -53
  83. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/models/source.py +73 -73
  84. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/quality/__init__.py +8 -8
  85. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/quality/confidence.py +38 -38
  86. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/quality/conflict.py +80 -79
  87. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/quality/decay.py +28 -28
  88. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/quality/gate.py +143 -120
  89. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/quality/pii.py +80 -80
  90. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/search/__init__.py +13 -13
  91. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/search/base.py +20 -20
  92. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/search/fts5_search.py +210 -210
  93. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/search/hybrid.py +99 -99
  94. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/search/semantic.py +186 -186
  95. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/search/tokenizer.py +85 -85
  96. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/session/__init__.py +6 -6
  97. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/session/context.py +87 -87
  98. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/session/manager.py +152 -152
  99. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/session/working_memory.py +57 -57
  100. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/storage/__init__.py +6 -6
  101. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/storage/base.py +63 -63
  102. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/storage/markdown_export.py +144 -144
  103. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/storage/migrations.py +30 -30
  104. {memorytrace-0.1.0 → memorytrace-0.3.0}/engram/storage/sqlite_store.py +754 -615
  105. {memorytrace-0.1.0 → memorytrace-0.3.0}/mem +139 -139
  106. {memorytrace-0.1.0 → memorytrace-0.3.0}/pyproject.toml +75 -75
  107. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/conftest.py +99 -99
  108. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_cli/test_app.py +166 -166
  109. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_e2e.py +212 -212
  110. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_engine.py +159 -159
  111. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_extraction/test_llm_extractor.py +112 -112
  112. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_extraction/test_ner/test_english.py +101 -101
  113. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_extraction/test_ner/test_korean.py +71 -71
  114. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_extraction/test_regex_extractor.py +92 -92
  115. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_integrations/test_mcp_server.py +12 -12
  116. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_quality/test_confidence.py +55 -55
  117. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_quality/test_conflict.py +199 -199
  118. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_quality/test_gate.py +207 -207
  119. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_quality/test_pii.py +117 -117
  120. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_search/test_fts5_search.py +248 -248
  121. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_search/test_semantic.py +19 -19
  122. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_search/test_tokenizer.py +102 -102
  123. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_session/test_manager.py +117 -117
  124. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_session/test_working_memory.py +73 -73
  125. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_storage/test_sqlite_store.py +288 -288
  126. memorytrace-0.1.0/engram/extraction/ner/korean.py +0 -106
  127. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/__init__.py +0 -0
  128. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/fixtures/__init__.py +0 -0
  129. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_cli/__init__.py +0 -0
  130. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_extraction/__init__.py +0 -0
  131. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_extraction/test_ner/__init__.py +0 -0
  132. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_integrations/__init__.py +0 -0
  133. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_quality/__init__.py +0 -0
  134. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_search/__init__.py +0 -0
  135. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_session/__init__.py +0 -0
  136. {memorytrace-0.1.0 → memorytrace-0.3.0}/tests/test_storage/__init__.py +0 -0
@@ -0,0 +1,72 @@
1
+ # Evaluation: Engram 3-Session Vibe Coding E2E Simulation
2
+
3
+ ## Verdict: PASS
4
+
5
+ ## Test Results Summary
6
+
7
+ | Step | Test | Status | Details |
8
+ |------|------|--------|---------|
9
+ | Session 1 - Save #1 | Tech stack save | PASS | Saved successfully, no entities auto-detected |
10
+ | Session 1 - Save #2 | Church model save | PASS | Saved successfully |
11
+ | Session 1 - Save #3 | JWT auth save | PASS | Saved, entities detected: Access Token, Refresh Token |
12
+ | Session 1 - Save #4 | Kakao map save | PASS | Saved successfully |
13
+ | Session 1 - Save #5 | Session summary save | PASS | Saved successfully |
14
+ | Session 2 - Save #1 | Review model save | PASS | Saved successfully |
15
+ | Session 2 - Save #2 | CORS fix save | PASS | Saved successfully |
16
+ | Session 2 - Save #3 | PostGIS search save | PASS | Saved successfully |
17
+ | Session 2 - Save #4 | Session summary save | PASS | Saved successfully |
18
+ | Session 3 - recent 10 | All 9 notes returned | PASS | All 9 notes listed in reverse chronological order |
19
+ | Session 3 - find JWT | JWT note found | PASS | Returned exact match |
20
+ | Session 3 - find CORS | CORS note found | PASS | Returned exact match |
21
+ | Session 3 - find Review | Review model found | PASS | Returned exact match |
22
+ | Session 3 - find PostGIS | PostGIS notes found | PASS | Returned 3 matching notes (tech stack, PostGIS specific, Church model) |
23
+ | Session 3 - status | Correct counts | PASS | 2 entities, 0 facts, 9 notes, 0 conflicts, healthy |
24
+ | Dedup - duplicate save | No new note created | PASS | Output said "Updated" (not "Saved"), notes stayed at 9 |
25
+ | Delete - preview | Shows matching note | PASS | Found 1 note, displayed preview, showed confirm command |
26
+ | Delete - confirm | Note deleted | PASS | "Deleted 1 note(s)" |
27
+ | Delete - verify gone | Search returns nothing | PASS | "Nothing found for CORS" |
28
+ | Delete - count check | Notes dropped to 8 | PASS | Status shows 8 notes |
29
+
30
+ ## Criteria Results
31
+
32
+ | Criterion | Status | Notes |
33
+ |-----------|--------|-------|
34
+ | Multi-session persistence | PASS | Notes saved in session 1 and 2 fully retrievable in session 3 |
35
+ | Korean text handling | PASS | All Korean content stored and retrieved without corruption |
36
+ | Search accuracy | PASS | All 4 search queries returned correct results |
37
+ | Deduplication | PASS | Exact duplicate did not increment notes count (stayed at 9) |
38
+ | Delete preview (safe mode) | PASS | Without --confirm, shows preview only and prompts for confirmation |
39
+ | Delete execution | PASS | With --confirm, deletes the note and confirms count |
40
+ | Delete verification | PASS | Deleted note no longer appears in search |
41
+ | Entity auto-detection | PASS | Detected "Access Token" and "Refresh Token" as entities from JWT note |
42
+ | Status reporting | PASS | Accurate counts at every checkpoint |
43
+
44
+ ## Issues Found
45
+
46
+ ### [Issue 1 - Severity: Low]
47
+ - **What**: Entity auto-detection is sparse -- only 2 entities detected across 9 notes containing terms like "NestJS", "Prisma", "PostgreSQL", "PostGIS", "Church", "Review", "JWT", "CORS"
48
+ - **Where**: Entity extraction logic (internal to engram)
49
+ - **Expected**: More domain terms would be recognized as entities
50
+ - **Actual**: Only "Access Token" and "Refresh Token" were detected (2 entities total)
51
+ - **Fix suggestion**: This is a minor observation. The entity detection appears to focus on capitalized multi-word terms. Not a functional problem since `find` search works correctly regardless.
52
+
53
+ ### [Issue 2 - Severity: Low]
54
+ - **What**: `engram recent 10` requested 10 notes but only 9 existed -- no error or warning, just returned all 9
55
+ - **Where**: `recent` subcommand
56
+ - **Expected**: This is actually correct behavior (return up to N)
57
+ - **Actual**: Correct -- returned all 9 without error
58
+ - **Fix suggestion**: No fix needed, this is the expected behavior.
59
+
60
+ ## Regressions
61
+
62
+ None detected. All core operations (save, find, recent, status, delete-note, dedup) function correctly.
63
+
64
+ ## Summary
65
+
66
+ All 20 test steps passed. The engram tool correctly handles:
67
+ - Persistent storage across simulated sessions
68
+ - Korean (UTF-8) content without corruption
69
+ - Full-text search returning accurate results
70
+ - Deduplication of exact-match notes (count stays stable)
71
+ - Two-phase delete (preview then confirm) with verification
72
+ - Accurate status reporting at every checkpoint
@@ -1,20 +1,20 @@
1
- __pycache__/
2
- *.py[cod]
3
- *.egg-info/
4
- dist/
5
- build/
6
- .eggs/
7
- *.egg
8
- .pytest_cache/
9
- .mypy_cache/
10
- .ruff_cache/
11
- *.db
12
- *.db-wal
13
- *.db-shm
14
- .engram/
15
- /tmp/
16
- *.tmp
17
- .DS_Store
18
- .env
19
- .venv/
20
- venv/
1
+ __pycache__/
2
+ *.py[cod]
3
+ *.egg-info/
4
+ dist/
5
+ build/
6
+ .eggs/
7
+ *.egg
8
+ .pytest_cache/
9
+ .mypy_cache/
10
+ .ruff_cache/
11
+ *.db
12
+ *.db-wal
13
+ *.db-shm
14
+ .engram/
15
+ /tmp/
16
+ *.tmp
17
+ .DS_Store
18
+ .env
19
+ .venv/
20
+ venv/
@@ -90,6 +90,19 @@ engine.close()
90
90
  - 코어 엔진에 `print()` 금지 — CLI 계층에서만 출력
91
91
  - 모든 메서드는 구조화된 객체를 반환 (stdout 오염 없음)
92
92
  - 타입 힌트 필수, `from __future__ import annotations` 사용
93
+ ## Dependencies
94
+
95
+ - **jq** (필수): 모든 Claude Code hooks가 JSON 파싱에 사용. 미설치 시 hooks가 조용히 스킵됨
96
+ - Windows: `winget install jqlang.jq`
97
+ - macOS: `brew install jq`
98
+ - Linux: `apt install jq` / `yum install jq`
99
+ - **engram** (선택): AI 대화 간 지식 유지 메모리. `pip install memorytrace`
100
+
101
+ ## Windows 호환성
102
+
103
+ - Windows에서 `engram` CLI 사용 시 `PYTHONIOENCODING=utf-8` 환경변수 필요
104
+ - `cli_entry()`에서 stdout/stderr를 UTF-8로 reconfigure하여 cp949 인코딩 에러 방지
105
+ - 상세: `docs/05-windows-compatibility/windows-encoding.md` 참고
93
106
 
94
107
  ## Design Principles
95
108
  1. **에이전트 퍼스트**: MCP/SDK가 1급 인터페이스, CLI는 래퍼
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 Engram Contributors
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Engram Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -1,9 +1,9 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: memorytrace
3
- Version: 0.1.0
3
+ Version: 0.3.0
4
4
  Summary: AI agent memory system with SQLite+FTS5, MCP integration, and quality gates
5
- Project-URL: Homepage, https://github.com/engram-memory/engram
6
- Project-URL: Issues, https://github.com/engram-memory/engram/issues
5
+ Project-URL: Homepage, https://github.com/aop60003/default
6
+ Project-URL: Issues, https://github.com/aop60003/default/issues
7
7
  License-Expression: MIT
8
8
  License-File: LICENSE
9
9
  Keywords: agent,ai,fts5,llm,mcp,memory,sqlite
@@ -43,7 +43,7 @@ AI agent memory that learns across conversations.
43
43
  ## Install
44
44
 
45
45
  ```bash
46
- pip install git+https://github.com/aop60003/default.git
46
+ pip install memorytrace
47
47
  ```
48
48
 
49
49
  ## Use
@@ -1,100 +1,100 @@
1
- # Engram
2
-
3
- AI agent memory that learns across conversations.
4
-
5
- ## Install
6
-
7
- ```bash
8
- pip install git+https://github.com/aop60003/default.git
9
- ```
10
-
11
- ## Use
12
-
13
- ```bash
14
- engram save "Minseong Jeong is the Space King of Galaxy Corp"
15
- engram find "Space King"
16
- engram who "Minseong Jeong"
17
- ```
18
-
19
- That's it. 3 commands. No config, no API keys, no database setup.
20
-
21
- ## All Commands
22
-
23
- ```
24
- engram save "text" Save information (auto-extracts entities & facts)
25
- engram find "query" Search memory
26
- engram who "name" Look up a person/org
27
- engram remember "name" "fact" Manually remember something
28
- engram all List everything
29
- engram status Health check
30
- engram forget "name" Delete an entity
31
- engram export Export to Markdown files
32
- ```
33
-
34
- ## Examples
35
-
36
- ```bash
37
- # Store meeting notes
38
- engram save "Met Alice Johnson, VP of Engineering at Google. Discussed cloud AI partnership."
39
-
40
- # Store Korean
41
- engram remember "정민성" "AI와 우주 탐사에 관심이 많다"
42
-
43
- # Search later
44
- engram find "Google partnership"
45
- engram who "Alice Johnson"
46
-
47
- # Check status
48
- engram status
49
- ```
50
-
51
- ## What It Does Automatically
52
-
53
- - **Extracts** people & organizations from text (English, Korean, Chinese, Japanese)
54
- - **Masks PII** — phone numbers, credit cards, emails become `[REDACTED]`
55
- - **Deduplicates** — same fact won't be stored twice
56
- - **Detects conflicts** — "CEO" then "CTO" for same person gets flagged
57
- - **Generates summaries** — auto-summary when you don't provide one
58
- - **Learns across sessions** — every conversation builds on previous ones
59
-
60
- ## For Claude Code Users
61
-
62
- Add slash commands to use memory inside Claude Code:
63
-
64
- ```bash
65
- # Copy command files
66
- mkdir -p ~/.claude/commands
67
- # See docs/04-usage-guide/02-claude-code-setup.md for details
68
- ```
69
-
70
- Then use: `/memory-save`, `/memory-find`, `/memory-who`, `/memory-remember`, `/memory-status`
71
-
72
- ## For Developers (Python SDK)
73
-
74
- ```python
75
- from engram.integrations.sdk import EngramSDK
76
-
77
- with EngramSDK() as sdk:
78
- sdk.store("Minseong Jeong is the Space King of Galaxy Corp")
79
- result = sdk.search("Space King")
80
- print(result.to_agent_context())
81
- ```
82
-
83
- ## How It Works
84
-
85
- ```
86
- Text → NER Extraction → Quality Gate → SQLite+FTS5 → BM25 Search
87
-
88
- Confidence Scoring
89
- PII Masking
90
- Duplicate Check
91
- Conflict Detection
92
- ```
93
-
94
- - **Storage**: SQLite + FTS5 (zero dependencies, genuine BM25)
95
- - **Export**: Markdown files for human reading
96
- - **Session**: Context carries over between conversations
97
-
98
- ## License
99
-
100
- MIT
1
+ # Engram
2
+
3
+ AI agent memory that learns across conversations.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ pip install memorytrace
9
+ ```
10
+
11
+ ## Use
12
+
13
+ ```bash
14
+ engram save "Minseong Jeong is the Space King of Galaxy Corp"
15
+ engram find "Space King"
16
+ engram who "Minseong Jeong"
17
+ ```
18
+
19
+ That's it. 3 commands. No config, no API keys, no database setup.
20
+
21
+ ## All Commands
22
+
23
+ ```
24
+ engram save "text" Save information (auto-extracts entities & facts)
25
+ engram find "query" Search memory
26
+ engram who "name" Look up a person/org
27
+ engram remember "name" "fact" Manually remember something
28
+ engram all List everything
29
+ engram status Health check
30
+ engram forget "name" Delete an entity
31
+ engram export Export to Markdown files
32
+ ```
33
+
34
+ ## Examples
35
+
36
+ ```bash
37
+ # Store meeting notes
38
+ engram save "Met Alice Johnson, VP of Engineering at Google. Discussed cloud AI partnership."
39
+
40
+ # Store Korean
41
+ engram remember "정민성" "AI와 우주 탐사에 관심이 많다"
42
+
43
+ # Search later
44
+ engram find "Google partnership"
45
+ engram who "Alice Johnson"
46
+
47
+ # Check status
48
+ engram status
49
+ ```
50
+
51
+ ## What It Does Automatically
52
+
53
+ - **Extracts** people & organizations from text (English, Korean, Chinese, Japanese)
54
+ - **Masks PII** — phone numbers, credit cards, emails become `[REDACTED]`
55
+ - **Deduplicates** — same fact won't be stored twice
56
+ - **Detects conflicts** — "CEO" then "CTO" for same person gets flagged
57
+ - **Generates summaries** — auto-summary when you don't provide one
58
+ - **Learns across sessions** — every conversation builds on previous ones
59
+
60
+ ## For Claude Code Users
61
+
62
+ Add slash commands to use memory inside Claude Code:
63
+
64
+ ```bash
65
+ # Copy command files
66
+ mkdir -p ~/.claude/commands
67
+ # See docs/04-usage-guide/02-claude-code-setup.md for details
68
+ ```
69
+
70
+ Then use: `/memory-save`, `/memory-find`, `/memory-who`, `/memory-remember`, `/memory-status`
71
+
72
+ ## For Developers (Python SDK)
73
+
74
+ ```python
75
+ from engram.integrations.sdk import EngramSDK
76
+
77
+ with EngramSDK() as sdk:
78
+ sdk.store("Minseong Jeong is the Space King of Galaxy Corp")
79
+ result = sdk.search("Space King")
80
+ print(result.to_agent_context())
81
+ ```
82
+
83
+ ## How It Works
84
+
85
+ ```
86
+ Text → NER Extraction → Quality Gate → SQLite+FTS5 → BM25 Search
87
+
88
+ Confidence Scoring
89
+ PII Masking
90
+ Duplicate Check
91
+ Conflict Detection
92
+ ```
93
+
94
+ - **Storage**: SQLite + FTS5 (zero dependencies, genuine BM25)
95
+ - **Export**: Markdown files for human reading
96
+ - **Session**: Context carries over between conversations
97
+
98
+ ## License
99
+
100
+ MIT
@@ -0,0 +1,83 @@
1
+ ---
2
+ name: evaluator
3
+ description: Independent quality evaluator. Use after completing a feature or sprint to objectively assess quality. NEVER use the same agent that wrote the code to evaluate it.
4
+ tools: Read Write Grep Glob Bash(npm test *) Bash(pnpm test *) Bash(npx playwright *) Bash(curl *)
5
+ model: claude-opus-4-6
6
+ maxTurns: 20
7
+ ---
8
+
9
+ # Evaluator Agent
10
+
11
+ You are an independent quality evaluator. You did NOT write this code. Your job is to find real problems, not praise the work.
12
+
13
+ ## Core Principle (from Anthropic harness design)
14
+
15
+ "When asked to evaluate work they've produced, agents tend to confidently praise the work—even when the quality is obviously mediocre."
16
+
17
+ You are a SEPARATE evaluator. Be critical. Be thorough. Probe edge cases.
18
+
19
+ ## Anti-Patterns to Avoid
20
+
21
+ - NEVER say "overall the code looks good" without specific evidence
22
+ - NEVER identify a legitimate issue then talk yourself into deciding it's not a big deal
23
+ - NEVER test only the happy path — probe edge cases, error states, boundary conditions
24
+ - NEVER rubber-stamp — if you can't find issues, look harder
25
+
26
+ ## Evaluation Process
27
+
28
+ 1. **Read the sprint contract** from `.claude/workspace/sprint-contract.md`
29
+ 2. **Check each acceptance criterion** — does the implementation actually satisfy it?
30
+ 3. **Run the tests** and verify they actually test meaningful behavior
31
+ 4. **Test edge cases**: empty inputs, large data, concurrent access, error states
32
+ 5. **Check for regressions**: did the new code break existing functionality?
33
+ 6. **Grade against hard thresholds** — pass or fail, no "mostly works"
34
+
35
+ ## Grading Criteria
36
+
37
+ ### Functionality (Pass/Fail)
38
+ - All acceptance criteria from sprint contract met?
39
+ - No broken existing features?
40
+
41
+ ### Robustness (Pass/Fail) — CRITICAL
42
+ - All external calls (network, DB, file I/O) have error handling?
43
+ - Network calls have explicit timeout?
44
+ - Resources cleaned up in finally blocks (connections, handles)?
45
+ - Input validation at system boundaries?
46
+ - No generic catch-all handlers (`catch { return null }`)?
47
+ - No hardcoded secrets or config values?
48
+ - Concurrent access handled where applicable?
49
+ - Graceful degradation when dependencies fail?
50
+
51
+ ### Code Quality (Pass/Fail)
52
+ - Constraints from CLAUDE.md respected?
53
+ - Tests written and passing?
54
+ - No TODO/FIXME/stub patterns?
55
+ - Specific error types caught (not generic)?
56
+
57
+ ## Output
58
+
59
+ Write evaluation to `.claude/workspace/evaluation.md`:
60
+
61
+ ```markdown
62
+ # Evaluation: [Feature/Sprint Name]
63
+
64
+ ## Verdict: PASS / FAIL
65
+
66
+ ## Criteria Results
67
+ | Criterion | Status | Notes |
68
+ |-----------|--------|-------|
69
+ | ... | PASS/FAIL | ... |
70
+
71
+ ## Issues Found
72
+ ### [Issue 1 - Severity: Critical/High/Medium/Low]
73
+ - **What**: Description
74
+ - **Where**: file:line
75
+ - **Expected**: What should happen
76
+ - **Actual**: What actually happens
77
+ - **Fix suggestion**: How to fix
78
+
79
+ ## Regressions
80
+ [List any broken existing functionality]
81
+ ```
82
+
83
+ If FAIL: return detailed feedback. The Generator will use this to fix issues.
@@ -0,0 +1,50 @@
1
+ ---
2
+ name: planner
3
+ description: High-level product planning and spec writing. Use for expanding brief requirements into full product specs. Focuses on product context and architecture, NOT implementation details.
4
+ tools: Read Grep Glob Write Bash(git log *)
5
+ model: claude-sonnet-4-6
6
+ maxTurns: 10
7
+ ---
8
+
9
+ # Planner Agent
10
+
11
+ You are a product planner. Expand brief requirements into comprehensive product specs.
12
+
13
+ ## Principles
14
+
15
+ 1. Focus on **product context and high-level technical design**
16
+ 2. NEVER write granular implementation details — that causes cascading errors
17
+ 3. Describe WHAT and WHY, not HOW
18
+ 4. Always include failure mode analysis
19
+
20
+ ## Output
21
+
22
+ Write plan to `.claude/workspace/plan.md`:
23
+
24
+ ```markdown
25
+ # Product Spec: [Feature Name]
26
+
27
+ ## Problem Statement
28
+ [What problem does this solve? Who is the user?]
29
+
30
+ ## Success Criteria
31
+ [How do we know this is done? Measurable outcomes.]
32
+
33
+ ## High-Level Architecture
34
+ [System components and their relationships. No implementation code.]
35
+
36
+ ## Feature Breakdown
37
+ [Sprint-sized chunks. Each independently testable.]
38
+
39
+ ## Failure Modes
40
+ [How can this feature fail in production?]
41
+ - Network/dependency failures and handling strategy
42
+ - Invalid input scenarios
43
+ - Concurrency/race condition risks
44
+ - Resource exhaustion risks
45
+
46
+ ## Risks & Open Questions
47
+ [What needs clarification?]
48
+ ```
49
+
50
+ NEVER include specific code, file paths, or function signatures.
@@ -0,0 +1,19 @@
1
+ ---
2
+ name: researcher
3
+ description: Deep codebase research with read-only access. Use for investigating bugs, understanding architecture, or tracing data flows across files.
4
+ tools: Read Grep Glob Bash(git log *) Bash(git blame *)
5
+ model: claude-sonnet-4-6
6
+ maxTurns: 15
7
+ ---
8
+
9
+ # Researcher Agent
10
+
11
+ You are a code researcher. Your role:
12
+
13
+ 1. Search the codebase thoroughly using Grep and Glob
14
+ 2. Read relevant files to understand the full picture
15
+ 3. Trace data flows and dependencies across files
16
+ 4. Use git log/blame for historical context
17
+ 5. Report findings with specific file:line references
18
+
19
+ NEVER modify files. NEVER run build/test commands. Read-only investigation only.
@@ -0,0 +1,36 @@
1
+ ---
2
+ name: security-reviewer
3
+ description: Security audit agent. Use when reviewing auth, input handling, API security, or checking for vulnerabilities.
4
+ tools: Read Grep Glob
5
+ maxTurns: 10
6
+ ---
7
+
8
+ # Security Review Agent
9
+
10
+ You are a security auditor. Check for:
11
+
12
+ 1. Injection vulnerabilities (SQL, command, XSS)
13
+ 2. Authentication/authorization bypass
14
+ 3. Hardcoded secrets or credentials
15
+ 4. Insecure data handling (PII exposure, missing encryption)
16
+ 5. OWASP Top 10 violations
17
+
18
+ NEVER modify source code. Read-only investigation only.
19
+
20
+ ## Output
21
+
22
+ Report findings directly. Use this format:
23
+
24
+ ```
25
+ # Security Audit: [scope]
26
+
27
+ ## Summary
28
+ [Critical count] Critical, [High count] High, [Medium count] Medium, [Low count] Low
29
+
30
+ ## Findings
31
+ ### [Finding 1 - Severity: Critical/High/Medium/Low]
32
+ - **File**: file:line
33
+ - **Vulnerability**: Description
34
+ - **Impact**: What an attacker could do
35
+ - **Fix**: Recommended remediation
36
+ ```
@@ -0,0 +1,46 @@
1
+ # Hooks Reference
2
+
3
+ ## SessionStart (세션 시작 시)
4
+
5
+ | Hook | 동작 | 조건 |
6
+ |---|---|---|
7
+ | **session-memory-load.sh** | Engram에서 프로젝트 관련 메모리 로드 | engram 설치 시 |
8
+
9
+ ## PostToolUse (매 Edit/Write 후 순차 실행)
10
+
11
+ | Hook | 검사 내용 | 동작 | 성능 |
12
+ |---|---|---|---|
13
+ | **post-edit-lint.sh** | ESLint(JS/TS), Ruff(Python) | 자동 수정 | ~500ms-2s |
14
+ | **post-edit-completeness.sh** | TODO/FIXME, stub, placeholder | 경고 (비블로킹) | ~50ms |
15
+ | **post-edit-robustness.sh** | try 없는 fetch, empty catch, 비밀값, bare except, timeout 누락 | 경고 (비블로킹) | ~50ms |
16
+
17
+ ## Stop (Claude 작업 완료 시)
18
+
19
+ | Hook | 동작 | 조건 |
20
+ |---|---|---|
21
+ | **on-stop-checkpoint.sh** | workspace/progress.md 수정 시간 알림 | progress.md 존재 시 |
22
+ | **on-stop-verify.sh** | 프로젝트 전체 TODO/stub 검색 | 소스 디렉토리 존재 시 |
23
+ | **stop-memory-save.sh** | workspace 파일(plan/progress/evaluation)을 Engram에 자동 저장 | engram 설치 시 |
24
+
25
+ ## PreCompact (컨텍스트 압축 전)
26
+
27
+ | Hook | 동작 |
28
+ |---|---|
29
+ | **pre-compact-save.sh** | workspace/*.md 파일 목록 → Claude에게 보존 안내 |
30
+
31
+ ## 의존성
32
+
33
+ - **jq** — 모든 hook이 JSON 파싱에 사용. 미설치 시 hook이 조용히 스킵됨
34
+ - **perl** — post-edit-robustness.sh의 멀티라인 catch 감지 (macOS 기본 포함)
35
+ - **engram** (선택) — 메모리 hook. `pip install memorytrace`로 설치. 미설치 시 스킵
36
+ - **eslint** (선택) — post-edit-lint.sh. node_modules에 설치된 경우만 실행
37
+ - **ruff** (선택) — post-edit-lint.sh. Python 프로젝트에서 설치된 경우만 실행
38
+
39
+ ## 커스터마이즈
40
+
41
+ - **소스 디렉토리 변경**: `on-stop-verify.sh`의 `SOURCE_CANDIDATES` 배열 수정
42
+ - **언어 추가**: `post-edit-completeness.sh`와 `post-edit-robustness.sh`의 `case` 블록에 추가
43
+ - **블로킹 전환**: `exit 0`을 `exit 2`로 변경하면 경고 → 블로킹으로 전환
44
+ - **린트 도구 변경**: `post-edit-lint.sh`의 `case` 블록에 도구 추가
45
+ - **성능 최적화**: `eslint_d` (데몬 모드) 사용 시 린트 ~50ms로 단축
46
+ - **메모리 비활성화**: `session-memory-load.sh`와 `stop-memory-save.sh`를 settings.json에서 제거
@@ -0,0 +1,25 @@
1
+ #!/bin/bash
2
+ set -uo pipefail
3
+ # Stop hook: 작업 완료 시 체크포인트 알림
4
+
5
+ if ! command -v jq &>/dev/null; then
6
+ exit 0
7
+ fi
8
+
9
+ PROGRESS="${CLAUDE_PROJECT_DIR:-}/.claude/workspace/progress.md"
10
+
11
+ if [ -f "$PROGRESS" ]; then
12
+ # macOS/Linux 호환 stat
13
+ if LAST_MODIFIED=$(stat -f "%Sm" -t "%Y-%m-%d %H:%M" "$PROGRESS" 2>/dev/null); then
14
+ : # macOS 성공
15
+ elif LAST_MODIFIED=$(date -r "$PROGRESS" "+%Y-%m-%d %H:%M" 2>/dev/null); then
16
+ : # Linux fallback
17
+ else
18
+ LAST_MODIFIED="unknown"
19
+ fi
20
+
21
+ jq -n --arg msg "[Checkpoint] Progress file last updated: $LAST_MODIFIED. Review .claude/workspace/progress.md before next session." \
22
+ '{systemMessage: $msg}' 2>/dev/null
23
+ fi
24
+
25
+ exit 0