qwen-memory-agent 0.1.0__tar.gz

qwen_memory_agent-0.1.0/.env.example

@@ -0,0 +1,7 @@
+# Qwen Cloud (OpenAI-compatible)
+QWEN_API_KEY=sk-ws-xxxxxxxx
+QWEN_BASE_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1
+
+# Model roles
+QWEN_MODEL_INLINE=qwen-plus
+QWEN_MODEL_REVIEW=qwen-turbo

qwen_memory_agent-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: Publish to PyPI
+
+# v* 태그를 푸시하면 빌드 후 PyPI에 발행 (Trusted Publishing / OIDC, 토큰 불필요)
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # OIDC trusted publishing
+      contents: read    # private repo checkout (permissions 블록 선언 시 명시 필요)
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: uv publish   # OIDC 신뢰 발행 — API 토큰 없이 업로드

qwen_memory_agent-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Secrets
+.env
+.env.*
+!.env.example
+*.key
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+.pytest_cache/
+
+# Memory store / local data
+*.db
+*.sqlite
+*.sqlite3
+data/
+memory_store/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+
+# build artifacts
+dist/
+build/

qwen_memory_agent-0.1.0/CLAUDE.md

@@ -0,0 +1,17 @@
+# Qwen MemoryAgent
+
+쓸수록 정확해지는(self-improving) 영속 메모리 에이전트. Qwen Cloud 기반. 자세한 설계는 `README.md` 참고.
+
+## Agent skills
+
+### Issue tracker
+
+Issues are tracked as GitHub issues via the `gh` CLI (repo: `Mrbaeksang/qwen-memory-agent`). External PRs are **not** a triage surface. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Five canonical triage roles, each mapped to its identically-named label (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context layout — one `CONTEXT.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`.

qwen_memory_agent-0.1.0/CONTEXT.md

@@ -0,0 +1,156 @@
+# CONTEXT — Qwen MemoryAgent
+
+이 문서는 아키텍처 정본(source of truth)이자 도메인 용어집(ubiquitous language)이다.
+설계 결정의 배경은 `docs/adr/` 참고.
+
+---
+
+## 한 줄 정의
+
+코딩 에이전트의 **낡은 학습지식 + 웹서치 미동봉**으로 생기는 라이브러리/API 실수를,
+**compact 시점에 수확 → 디스크의 실제 설치버전으로 검증 → 루트 메모리에 저장 →
+다음 어떤 플랫폼의 어떤 세션이든 세션당 1회 자동 주입**하고,
+결과로 **스스로 점수를 교정(자가 발전)**하는 host-agnostic 로컬 메모리 데몬.
+
+효용: *"네 코딩 에이전트는 웹서치를 안 해서 낡은 API로 틀린다. 이 메모리는 그 실수를
+한 번 잡아 정답을 확인해두고, 모든 미래 세션에 자동 주입한다. 틀리면 스스로 도태시킨다."*
+
+---
+
+## 도메인 용어 (ubiquitous language)
+
+| 용어 | 정의 |
+|---|---|
+| **Lesson** | 검증된 교정 1건. `{trigger, wrong, right, snippet, source, scope, confidence, use/success/fail, stale}` |
+| **Trigger** | lesson 매칭 키 = `패키지@버전 + 작업유형` (예: `sqlalchemy==2.0.31 \| async test`) |
+| **Harvest** | PreCompact 시 transcript+에러로그를 스캔해 "사용법 실수 후보"를 뽑는 단계 |
+| **Verify** | 후보의 정답을 확정하는 단계. A=설치패키지 뜯기(우선), B=웹서치(폴백) |
+| **Inject** | 미래 세션에 lesson을 컨텍스트로 끼워넣음. 호스트 LLM의 도구호출 없이(무개입) |
+| **Reflect** | 주입 결과(성공/실패) 신호로 confidence/score를 갱신, 틀린 lesson 도태 |
+| **Root memory** | 크로스세션·크로스플랫폼 공용 저장소(`~/.qmem/mem.db`) |
+| **Adapter** | 플랫폼별 얇은 훅 스크립트. 이벤트를 데몬에 POST, 주입 컨텍스트를 stdout |
+| **Daemon** | 항상 실행되는 두뇌. 저장/회상/수확/검증/reflect 담당 |
+| **Tier** | 플랫폼의 통합 가능 등급. 1=훅(풀루프) / 2=MCP / 3=룰파일 |
+| **Provider** | LLM 백엔드. OpenAI 호환 추상화, Qwen이 기본값 |
+
+회상 점수: `score = confidence × recency_decay(last_used) × success/(success+fail+1)`
+
+---
+
+## 시스템 토폴로지
+
+```
+HOSTS (결정은 얘들이, 메모리에 무개입)
+  Claude Code[레퍼런스] · Codex · Gemini CLI · Cursor · ...
+       │ 라이프사이클 훅 (stdin: event+transcript_path / stdout: 주입ctx)
+  ┌────▼──────────────────────────────────────┐
+  │ ADAPTER LAYER  플랫폼별 얇은 훅 스크립트       │
+  └────────────────┬───────────────────────────┘
+                   │ HTTP localhost  fire-and-forget
+  ┌────────────────▼───────────────────────────────────────────┐
+  │ LOCAL DAEMON                                                │
+  │  Ingress · Recall(inject) · Harvest(compact) · Reflect      │
+  │  ┌───────────────────────────────────────────────────────┐ │
+  │  │ MEMORY STORE  SQLite+FTS5  ~/.qmem/mem.db              │ │
+  │  │ L1 Curated(항상주입,~2k) · L2 Episodic(원문,FTS5) ·     │ │
+  │  │ L3 Scored(lesson 본체, rerank top-K 주입)              │ │
+  │  └───────────────────────────────────────────────────────┘ │
+  │  Verifier(A:패키지뜯 / B:웹서치) · LLM Provider(Qwen기본)    │
+  └──────┬───────────────────────────────┬─────────────────────┘
+         │ DISK                          │ LLM ENDPOINT (OpenAI 호환)
+   node_modules/ site-packages/    qwen-turbo(추출) · qwen-plus(검증/합성,+search)
+   (실제 설치버전 = 정답 출처)        · qwen3-rerank(회상)  | 교체: OpenAI/로컬
+```
+
+---
+
+## 5단계 파이프라인 (lesson의 생애)
+
+```
+①HARVEST   PreCompact 훅 → transcript + 세션중 에러로그
+           → qwen-turbo가 "사용법 실수 후보" 추출 (에러신호로 후보 좁힘) [async]
+②VERIFY    A. 설치패키지 뜯기(버전·타입·README) ◄우선
+           B. 없으면 웹서치(qwen-plus enable_search) 폴백
+           → qwen-plus가 "버전-정확 권장법"=lesson 합성 [async]
+③STORE     lesson 레코드 + FTS5 인덱싱 + 모순체크(충돌→옛것 stale)
+④INJECT    SessionStart: 매니페스트(package.json/requirements.txt) 읽어 프리로드
+           UserPromptSubmit: 기술언급 감지→주입
+           세션당 보증: injected={session_id: set(lesson_id)} 로 (세션,lesson) 1회
+           → additionalContext stdout → 호스트가 모델 컨텍스트에 삽입 (LLM 무개입)
+⑤REFLECT   결과신호(테스트통과/에러0=success / 또터짐·유저교정=fail)
+           → score 갱신 → 낮으면 archive(도태), 높으면 우선주입 ↺①
+```
+
+약한 고리: **결과 귀속(outcome attribution)** 은 상관에 근사 — 인과 보장 X.
+양이 쌓이면 통계적으로 수렴. 데모는 "테스트 통과/실패 → confidence 막대"로 증명.
+
+---
+
+## 멀티플랫폼 통합 — 3등급
+
+감지는 쉬움(설정경로 `exists` 루프). 변수는 통합 가능 등급:
+
+```
+TIER 1 훅   → 풀루프(자동주입+compact수확)  ★타겟
+            Claude Code · Gemini CLI · Cursor · Copilot CLI · Kiro · (Qwen Code)
+TIER 2 MCP  → recall을 MCP 툴 노출(호스트가 호출, 반쪽)
+            VS Code Copilot · Zed · OpenCode · Kilo · Kimi · JetBrains · Antigravity
+TIER 3 룰   → AGENTS.md 정적 포인터만(동적주입 X, 최소)
+            Aider · Cline · Goose · Warp · Windsurf
+```
+
+감지 레지스트리(데이터로 분리, 새 플랫폼=표 한 줄):
+
+| 플랫폼 | 감지 경로 | tier |
+|---|---|---|
+| Claude Code | `~/.claude/settings.json` | hooks |
+| Qwen Code | `~/.qwen/settings.json` | hooks |
+| Gemini CLI | `~/.gemini/settings.json` | hooks |
+| Codex | `~/.codex/config.toml` | mcp(훅 신규) |
+| Cursor | `~/.cursor/hooks.json`, `~/.cursor/mcp.json` | hooks |
+| Copilot CLI | `~/.copilot/hooks/` | hooks(precompact X) |
+| Zed | `~/.config/zed/settings.json` | mcp |
+| Aider | `AGENTS.md` | rules |
+
+---
+
+## 설치기 (코어 이후 단계)
+
+```
+$ uvx qwen-memory init
+ STEP1 SCAN     레지스트리 감지경로 exists 루프 → detected
+ STEP2 PRESENT  감지된 것만 체크박스(기본 전체ON), tier 표기(거짓약속 금지)
+ STEP3 WIRE     선택 플랫폼에 등급별 와이어링
+                tier1→settings/hooks.json에 훅 등록
+                tier2→mcp.json에 qmem MCP 등록
+                tier3→AGENTS.md에 참조 블록 append
+ STEP4 DAEMON   ~/.qmem 생성, mem.db 초기화, 데몬 등록/기동
+```
+
+---
+
+## 차별점 (vs prior art)
+
+claude-mem · agentmemory · context-mode 는 "대화를 압축 저장/주입"까지만 한다.
+본 프로젝트의 wedge:
+1. **설치된 패키지를 직접 뜯어 버전-정확하게 검증** (낡음·환각 0, 오프라인)
+2. **점수형 Reflect로 자가 교정** (틀린 lesson 자동 도태 = "increasingly accurate")
+
+플러밍(훅·자동감지·멀티플랫폼)은 prior art 패턴을 그대로 차용하고,
+시간은 위 두 wedge에 집중한다.
+
+---
+
+## 기술 스택 (권장)
+
+```
+언어     Python 3.12          데몬   FastAPI + uvicorn (async)
+저장     sqlite3 + FTS5       LLM    openai SDK (base_url 교체)
+기본모델  qwen-turbo/plus/qwen3-rerank (dashscope-intl)
+검증     importlib.metadata / node_modules 파서 · enable_search(폴백)
+설치기   uvx qwen-memory init (npx 래퍼 가능)
+```
+```
+
+scoring:  score = confidence × recency_decay × success/(success+fail+1)
+```

qwen_memory_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mrbaeksang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qwen_memory_agent-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: qwen-memory-agent
+Version: 0.1.0
+Summary: Host-agnostic, self-correcting library/API memory daemon for coding agents (Qwen MemoryAgent)
+Project-URL: Homepage, https://github.com/Mrbaeksang/qwen-memory-agent
+Project-URL: Repository, https://github.com/Mrbaeksang/qwen-memory-agent
+Project-URL: Issues, https://github.com/Mrbaeksang/qwen-memory-agent/issues
+Author-email: Mrbaeksang <qortkdgus95@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Mrbaeksang
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agent,claude,claude-code,hooks,llm,mcp,memory,qwen
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: openai>=1.40
+Requires-Dist: uvicorn>=0.30
+Description-Content-Type: text/markdown
+
+# Qwen MemoryAgent
+
+> **Global AI Hackathon Series with Qwen Cloud — Track 1: MemoryAgent**
+> 낡은 학습지식 때문에 라이브러리 실수를 반복하는 코딩 에이전트를, **쓸수록 정확해지게** 만드는
+> host-agnostic 자가교정 메모리. Qwen Cloud 기반.
+
+---
+
+## 문제
+
+AI 코딩 에이전트는 **학습된(낡은) 지식**으로 라이브러리/의존성을 다루다 실수한다. 웹서치를
+기본 동봉하지 않으니 최신 API를 모른다. 결정적으로 — **한 세션에서 그 실수를 교정해도
+다음/다른 세션은 그걸 모른다.** 같은 함정에 매번 다시 빠진다.
+
+## 효용
+
+> 네 코딩 에이전트는 웹서치를 안 해서 낡은 API로 틀린다. 이 메모리는 그 실수를 **compact
+> 순간에 잡아 — 디스크에 깔린 실제 버전을 뜯어 정답을 확인해두고 — 모든 플랫폼의 모든 미래
+> 세션에 세션당 1회 자동 주입한다. 틀리면 스스로 도태시킨다.**
+
+핵심은 단순 저장이 아니라 **(1) 실수 수확 · (2) 버전-정확 검증 · (3) 무개입 주입 · (4) 자가 교정**.
+
+---
+
+## 아키텍처 (요약 — 정본은 [`CONTEXT.md`](./CONTEXT.md))
+
+```
+HOSTS (결정은 얘들이, 메모리에 무개입)
+  Claude Code · Codex · Gemini CLI · Cursor · ...
+       │ 라이프사이클 훅
+  ADAPTER LAYER  (플랫폼별 얇은 훅 스크립트)
+       │ HTTP localhost
+  LOCAL DAEMON  ── Ingress · Recall · Harvest · Reflect
+       ├─ MEMORY STORE  SQLite+FTS5  (~/.qmem/mem.db)
+       │     L1 Curated(항상주입) · L2 Episodic(원문/FTS5) · L3 Scored(lesson/rerank)
+       ├─ Verifier   A:설치패키지 뜯기(우선) / B:웹서치(폴백)
+       └─ LLM Provider  Qwen 기본 (qwen-turbo/plus/qwen3-rerank) · 교체 가능
+```
+
+### 5단계 파이프라인
+
+```
+①HARVEST  PreCompact 훅 → transcript+에러로그 → qwen-turbo가 실수후보 추출 [async]
+②VERIFY   설치패키지 뜯기(A,우선) → 없으면 웹서치(B) → qwen-plus가 정답=lesson 합성 [async]
+③STORE    lesson + FTS5 인덱싱 + 모순체크(충돌→stale)
+④INJECT   SessionStart/UserPromptSubmit 훅 → 세션당 1회 자동 주입 (LLM 무개입)
+⑤REFLECT  결과신호(테스트통과/실패) → score 갱신 → 도태/우선주입 ↺①
+```
+
+`score = confidence × recency_decay(last_used) × success/(success+fail+1)`
+
+---
+
+## 차별점 (vs claude-mem · agentmemory · context-mode)
+
+기존 툴은 "대화를 압축 저장/주입"까지만 한다. 본 프로젝트의 wedge:
+
+| | 본 프로젝트 | 기존 툴 |
+|---|---|---|
+| 검증 | **설치 패키지를 직접 뜯어 버전-정확** (환각 0) | 대화 요약 저장 |
+| 학습 | **점수형 Reflect 자가교정** (틀린 lesson 도태) | 없음 |
+
+플러밍(훅·자동감지·멀티플랫폼)은 prior art 패턴을 차용하고, 시간은 위 둘에 집중.
+
+---
+
+## 멀티플랫폼 — 자동감지 + 등급별 통합
+
+설치기 `uvx qwen-memory init`이 설정경로를 스캔해 깔린 플랫폼을 감지하고, 대화형으로 적용 대상을
+고른 뒤 등급별로 와이어링한다. 등급:
+
+```
+TIER 1 훅   풀루프(자동주입+수확)  ← Claude Code · Gemini CLI · Cursor · Copilot CLI · Kiro
+TIER 2 MCP  recall을 MCP 툴 노출   ← Zed · OpenCode · VS Code Copilot · JetBrains ...
+TIER 3 룰   AGENTS.md 정적 포인터  ← Aider · Cline · Goose · Warp ...
+```
+
+해커톤 데모는 **Claude Code(Tier1)** 레퍼런스로 풀루프를 완성형으로 시연.
+
+---
+
+## Qwen 모델 배분 (비종속, Qwen 기본 권장)
+
+| 용도 | 모델 |
+|---|---|
+| 실수 후보 추출 (대량) | `qwen-turbo` |
+| 검증/lesson 합성 (+웹서치) | `qwen-plus` (`enable_search`) |
+| 회상 재정렬 | `qwen3-rerank` |
+| L2 키워드 검색 | LLM 미사용 (FTS5) |
+
+**Qwen 쓰면 풀스택, 타 프로바이더는 코어(rerank/웹서치 차등).**
+**API**: OpenAI 호환 — `base_url=https://dashscope-intl.aliyuncs.com/compatible-mode/v1`
+
+---
+
+## 심사 기준 매핑
+
+| 심사 기준 | 구현 |
+|---|---|
+| ① 효율 저장/검색 | L2 FTS5(임베딩 0) + L3 점수 랭킹 + qwen3-rerank |
+| ② 적시 망각 | 모순 stale + 점수 감쇠 archive + 용량 통합 |
+| ③ 제한 컨텍스트 회상 | L1 토큰캡 + rerank top-K + 세션당 1회 주입 |
+| **increasingly accurate** | 패키지-검증 + Reflect success/fail 점수 교정 |
+
+---
+
+## 빌드 단계
+
+- [x] **P1** — SQLite+FTS5 스키마, lesson CRUD/검색 (L2/L3) — #2 #3
+- [x] **P2** — Claude Code 어댑터: SessionStart/UserPromptSubmit 주입 (세션당 1회) — #5 #6 #7
+- [x] **P3** — PreCompact 수확 → Verifier(패키지 뜯기 A) → lesson 합성 — #8 #9
+- [x] **P4** — Reflect 점수 루프 + 웹서치 폴백(B) *(차별화 핵심)* — #4 #10 #11
+- [x] **P5** — 데모 시나리오 + confidence 시각화 — #12
+- [~] **P6** — 설치기: Claude Code(Tier1) 훅 와이어링 + launchd 데몬 완료 / 멀티플랫폼 자동감지·대화형은 다음
+
+> 코어(P1~P5) 구현 완료 — `uv run pytest` 51 passed, `uv run python demo/run_demo.py`로 크로스세션 학습 데모 실행.
+
+---
+
+## 실사용 설치 (Claude Code)
+
+**PyPI (권장)** — 레포 클론 없이:
+```bash
+uv tool install qwen-memory-agent   # 또는 pipx install qwen-memory-agent
+qmem install                        # 훅 와이어링 + 데몬 기동
+# ~/.qmem/.env 에 QWEN_API_KEY 입력 후: qmem install 재실행(또는 데몬 재기동)
+```
+명령: `qmem install` / `qmem uninstall` / `qmem status` / `qmem daemon` / `qmem hook`
+
+**레포에서(개발)** — 원스크립트:
+```bash
+git clone https://github.com/Mrbaeksang/qwen-memory-agent && cd qwen-memory-agent
+cp .env.example .env   # QWEN_API_KEY 입력
+./install.sh           # uv sync + qmem install (idempotent)
+```
+
+제거: `qmem uninstall` (또는 `./uninstall.sh`). 메모리 완전삭제는 `rm -rf ~/.qmem`.
+
+데몬은 `127.0.0.1:8787`, 루트 메모리는 `~/.qmem/mem.db`. 이후 모든 Claude Code 세션에서
+SessionStart/UserPromptSubmit 시 관련 교정이 자동 주입되고, PreCompact 시 실수가 수확·검증된다.
+LLM 키는 프로젝트 `.env`(`QWEN_API_KEY`)에서 로드한다. (현재 macOS/launchd 기준)
+
+---
+
+## 데모 시나리오
+
+1. **세션 1 (Claude Code)**: AI가 SQLAlchemy 2.0 async에서 sync Session 사용 → asyncpg
+   `another operation in progress` 에러 → compact가 수확 → 설치된 `sqlalchemy==2.x`를 뜯어
+   정답(AsyncSession+savepoint) 검증 → **lesson 저장**
+2. **재시작(크로스세션) → 세션 2**: 같은 작업 → SessionStart가 lesson 자동 주입 →
+   AI가 처음부터 올바르게 → **에러 0**
+3. 옛 lesson이 틀린 것으로 판명(또 터짐) → fail++ → confidence 하락 → **stale 도태**
+4. confidence 막대 시각화 → "학습 중" 증명
+
+---
+
+## 참고
+
+- omp 메모리 설계: https://github.com/can1357/oh-my-pi/blob/main/docs/memory.md
+- Hermes Agent: https://yuv.ai/blog/hermes-agent
+- prior art: [claude-mem](https://github.com/thedotmack/claude-mem) · [agentmemory](https://github.com/rohitg00/agentmemory) · [context-mode](https://github.com/mksglu/context-mode) · [ruler](https://github.com/intellectronica/ruler)
+- "Hindsight is 20/20" (arxiv 2512.12818): https://arxiv.org/abs/2512.12818
+- Qwen Cloud Hackathon: https://qwencloud-hackathon.devpost.com/

qwen_memory_agent-0.1.0/README.md

@@ -0,0 +1,163 @@
+# Qwen MemoryAgent
+
+> **Global AI Hackathon Series with Qwen Cloud — Track 1: MemoryAgent**
+> 낡은 학습지식 때문에 라이브러리 실수를 반복하는 코딩 에이전트를, **쓸수록 정확해지게** 만드는
+> host-agnostic 자가교정 메모리. Qwen Cloud 기반.
+
+---
+
+## 문제
+
+AI 코딩 에이전트는 **학습된(낡은) 지식**으로 라이브러리/의존성을 다루다 실수한다. 웹서치를
+기본 동봉하지 않으니 최신 API를 모른다. 결정적으로 — **한 세션에서 그 실수를 교정해도
+다음/다른 세션은 그걸 모른다.** 같은 함정에 매번 다시 빠진다.
+
+## 효용
+
+> 네 코딩 에이전트는 웹서치를 안 해서 낡은 API로 틀린다. 이 메모리는 그 실수를 **compact
+> 순간에 잡아 — 디스크에 깔린 실제 버전을 뜯어 정답을 확인해두고 — 모든 플랫폼의 모든 미래
+> 세션에 세션당 1회 자동 주입한다. 틀리면 스스로 도태시킨다.**
+
+핵심은 단순 저장이 아니라 **(1) 실수 수확 · (2) 버전-정확 검증 · (3) 무개입 주입 · (4) 자가 교정**.
+
+---
+
+## 아키텍처 (요약 — 정본은 [`CONTEXT.md`](./CONTEXT.md))
+
+```
+HOSTS (결정은 얘들이, 메모리에 무개입)
+  Claude Code · Codex · Gemini CLI · Cursor · ...
+       │ 라이프사이클 훅
+  ADAPTER LAYER  (플랫폼별 얇은 훅 스크립트)
+       │ HTTP localhost
+  LOCAL DAEMON  ── Ingress · Recall · Harvest · Reflect
+       ├─ MEMORY STORE  SQLite+FTS5  (~/.qmem/mem.db)
+       │     L1 Curated(항상주입) · L2 Episodic(원문/FTS5) · L3 Scored(lesson/rerank)
+       ├─ Verifier   A:설치패키지 뜯기(우선) / B:웹서치(폴백)
+       └─ LLM Provider  Qwen 기본 (qwen-turbo/plus/qwen3-rerank) · 교체 가능
+```
+
+### 5단계 파이프라인
+
+```
+①HARVEST  PreCompact 훅 → transcript+에러로그 → qwen-turbo가 실수후보 추출 [async]
+②VERIFY   설치패키지 뜯기(A,우선) → 없으면 웹서치(B) → qwen-plus가 정답=lesson 합성 [async]
+③STORE    lesson + FTS5 인덱싱 + 모순체크(충돌→stale)
+④INJECT   SessionStart/UserPromptSubmit 훅 → 세션당 1회 자동 주입 (LLM 무개입)
+⑤REFLECT  결과신호(테스트통과/실패) → score 갱신 → 도태/우선주입 ↺①
+```
+
+`score = confidence × recency_decay(last_used) × success/(success+fail+1)`
+
+---
+
+## 차별점 (vs claude-mem · agentmemory · context-mode)
+
+기존 툴은 "대화를 압축 저장/주입"까지만 한다. 본 프로젝트의 wedge:
+
+| | 본 프로젝트 | 기존 툴 |
+|---|---|---|
+| 검증 | **설치 패키지를 직접 뜯어 버전-정확** (환각 0) | 대화 요약 저장 |
+| 학습 | **점수형 Reflect 자가교정** (틀린 lesson 도태) | 없음 |
+
+플러밍(훅·자동감지·멀티플랫폼)은 prior art 패턴을 차용하고, 시간은 위 둘에 집중.
+
+---
+
+## 멀티플랫폼 — 자동감지 + 등급별 통합
+
+설치기 `uvx qwen-memory init`이 설정경로를 스캔해 깔린 플랫폼을 감지하고, 대화형으로 적용 대상을
+고른 뒤 등급별로 와이어링한다. 등급:
+
+```
+TIER 1 훅   풀루프(자동주입+수확)  ← Claude Code · Gemini CLI · Cursor · Copilot CLI · Kiro
+TIER 2 MCP  recall을 MCP 툴 노출   ← Zed · OpenCode · VS Code Copilot · JetBrains ...
+TIER 3 룰   AGENTS.md 정적 포인터  ← Aider · Cline · Goose · Warp ...
+```
+
+해커톤 데모는 **Claude Code(Tier1)** 레퍼런스로 풀루프를 완성형으로 시연.
+
+---
+
+## Qwen 모델 배분 (비종속, Qwen 기본 권장)
+
+| 용도 | 모델 |
+|---|---|
+| 실수 후보 추출 (대량) | `qwen-turbo` |
+| 검증/lesson 합성 (+웹서치) | `qwen-plus` (`enable_search`) |
+| 회상 재정렬 | `qwen3-rerank` |
+| L2 키워드 검색 | LLM 미사용 (FTS5) |
+
+**Qwen 쓰면 풀스택, 타 프로바이더는 코어(rerank/웹서치 차등).**
+**API**: OpenAI 호환 — `base_url=https://dashscope-intl.aliyuncs.com/compatible-mode/v1`
+
+---
+
+## 심사 기준 매핑
+
+| 심사 기준 | 구현 |
+|---|---|
+| ① 효율 저장/검색 | L2 FTS5(임베딩 0) + L3 점수 랭킹 + qwen3-rerank |
+| ② 적시 망각 | 모순 stale + 점수 감쇠 archive + 용량 통합 |
+| ③ 제한 컨텍스트 회상 | L1 토큰캡 + rerank top-K + 세션당 1회 주입 |
+| **increasingly accurate** | 패키지-검증 + Reflect success/fail 점수 교정 |
+
+---
+
+## 빌드 단계
+
+- [x] **P1** — SQLite+FTS5 스키마, lesson CRUD/검색 (L2/L3) — #2 #3
+- [x] **P2** — Claude Code 어댑터: SessionStart/UserPromptSubmit 주입 (세션당 1회) — #5 #6 #7
+- [x] **P3** — PreCompact 수확 → Verifier(패키지 뜯기 A) → lesson 합성 — #8 #9
+- [x] **P4** — Reflect 점수 루프 + 웹서치 폴백(B) *(차별화 핵심)* — #4 #10 #11
+- [x] **P5** — 데모 시나리오 + confidence 시각화 — #12
+- [~] **P6** — 설치기: Claude Code(Tier1) 훅 와이어링 + launchd 데몬 완료 / 멀티플랫폼 자동감지·대화형은 다음
+
+> 코어(P1~P5) 구현 완료 — `uv run pytest` 51 passed, `uv run python demo/run_demo.py`로 크로스세션 학습 데모 실행.
+
+---
+
+## 실사용 설치 (Claude Code)
+
+**PyPI (권장)** — 레포 클론 없이:
+```bash
+uv tool install qwen-memory-agent   # 또는 pipx install qwen-memory-agent
+qmem install                        # 훅 와이어링 + 데몬 기동
+# ~/.qmem/.env 에 QWEN_API_KEY 입력 후: qmem install 재실행(또는 데몬 재기동)
+```
+명령: `qmem install` / `qmem uninstall` / `qmem status` / `qmem daemon` / `qmem hook`
+
+**레포에서(개발)** — 원스크립트:
+```bash
+git clone https://github.com/Mrbaeksang/qwen-memory-agent && cd qwen-memory-agent
+cp .env.example .env   # QWEN_API_KEY 입력
+./install.sh           # uv sync + qmem install (idempotent)
+```
+
+제거: `qmem uninstall` (또는 `./uninstall.sh`). 메모리 완전삭제는 `rm -rf ~/.qmem`.
+
+데몬은 `127.0.0.1:8787`, 루트 메모리는 `~/.qmem/mem.db`. 이후 모든 Claude Code 세션에서
+SessionStart/UserPromptSubmit 시 관련 교정이 자동 주입되고, PreCompact 시 실수가 수확·검증된다.
+LLM 키는 프로젝트 `.env`(`QWEN_API_KEY`)에서 로드한다. (현재 macOS/launchd 기준)
+
+---
+
+## 데모 시나리오
+
+1. **세션 1 (Claude Code)**: AI가 SQLAlchemy 2.0 async에서 sync Session 사용 → asyncpg
+   `another operation in progress` 에러 → compact가 수확 → 설치된 `sqlalchemy==2.x`를 뜯어
+   정답(AsyncSession+savepoint) 검증 → **lesson 저장**
+2. **재시작(크로스세션) → 세션 2**: 같은 작업 → SessionStart가 lesson 자동 주입 →
+   AI가 처음부터 올바르게 → **에러 0**
+3. 옛 lesson이 틀린 것으로 판명(또 터짐) → fail++ → confidence 하락 → **stale 도태**
+4. confidence 막대 시각화 → "학습 중" 증명
+
+---
+
+## 참고
+
+- omp 메모리 설계: https://github.com/can1357/oh-my-pi/blob/main/docs/memory.md
+- Hermes Agent: https://yuv.ai/blog/hermes-agent
+- prior art: [claude-mem](https://github.com/thedotmack/claude-mem) · [agentmemory](https://github.com/rohitg00/agentmemory) · [context-mode](https://github.com/mksglu/context-mode) · [ruler](https://github.com/intellectronica/ruler)
+- "Hindsight is 20/20" (arxiv 2512.12818): https://arxiv.org/abs/2512.12818
+- Qwen Cloud Hackathon: https://qwencloud-hackathon.devpost.com/