adaptive-memory-engine 0.1.8__tar.gz → 0.1.9__tar.gz

{adaptive_memory_engine-0.1.8 → adaptive_memory_engine-0.1.9}/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.9 - 2026-06-12
+
+- Updated the packaged README with cleaner AME MCP flow guidance and response templates.
+- Kept troubleshooting focused on user actions instead of internal debugging history.
+- Bumped package and MCP server metadata to 0.1.9.
+
 ## 0.1.8 - 2026-06-12
 
 - Added standard MCP `Content-Length` stdio framing support while keeping newline JSON-RPC compatibility.

{adaptive_memory_engine-0.1.8 → adaptive_memory_engine-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adaptive-memory-engine
-Version: 0.1.8
+Version: 0.1.9
 Summary: Local-first CLI memory engine that builds Bronze/Silver/Gold RAG memory from local documents.
 License-Expression: MIT
 License-File: LICENSE
@@ -38,7 +38,7 @@ Codex나 Claude Code가 그 메모리를 보고 답할 수 있게 해주는 loca
 
 사용자가 매번 긴 명령어를 치는 방식보다, **Codex/Claude Code에 AME를 연결하고 자연어로 맡기는 방식**을 우선합니다.
 
-현재는 alpha 단계이며 PyPI로 배포 중입니다. 현재 버전은 `0.1.8`입니다.
+현재는 alpha 단계이며 PyPI로 배포 중입니다. 현재 버전은 `0.1.9`입니다.
 
 ## 1. 설치
 
@@ -99,10 +99,13 @@ ame connect --client claude
 
 한 번에 길게 요청하기보다, 아래 흐름대로 하나씩 진행하는 것을 권장합니다.
 
-먼저 AME MCP를 사용한다고 명시하고 진행 방식을 확인합니다.
+처음에는 아래 문장을 그대로 입력하는 것이 가장 안전합니다. 이 문장은 에이전트가 shell 명령이나 웹 검색보다 AME MCP 도구를 먼저 쓰도록 유도합니다.
 
 ```text
-AME MCP를 사용해서 단계별로 진행해줘. 먼저 ame_flow를 확인해줘.
+AME MCP를 사용해서 단계별로 진행해줘.
+먼저 ame_flow를 확인하고, 사양 진단은 ame_doctor로 해줘.
+모델 다운로드는 ame_setup execute=false로 계획만 먼저 보여주고,
+내가 승인하기 전에는 execute=true를 실행하지 마.
 ```
 
 그 다음 사양 진단을 요청합니다.
@@ -135,6 +138,79 @@ AME MCP를 사용해서 단계별로 진행해줘. 먼저 ame_flow를 확인해
 my-docs 메모리를 기준으로 현재 유효한 결정과 그 근거를 알려줘.
 ```
 
+정상 플로우는 다음 순서입니다.
+
+```text
+ame_flow -> ame_doctor -> ame_setup execute=false -> 사용자 승인 -> ame_setup execute=true -> ame_load -> memory_query/memory_search
+```
+
+사양 진단과 모델 추천 단계에서는 corpus가 필요 없습니다. 문서 메모리 구축 단계에서만 corpus 이름을 정하면 됩니다.
+
+## 4. 단계별 응답 템플릿
+
+AME MCP의 `ame_flow`는 에이전트가 답변에 사용할 템플릿을 제공합니다. 사용자가 직접 템플릿을 보고 싶다면 이렇게 요청하면 됩니다.
+
+```text
+ame_flow에서 model_plan 단계의 output_template을 보여줘.
+```
+
+권장 응답 형태는 다음과 같습니다.
+
+사양 진단:
+
+```text
+사양 진단 결과입니다.
+
+- OS/CPU: ...
+- RAM: ...
+- 사용 가능 디스크: ...
+- AME tier: ...
+
+추천 모델은 다음과 같습니다.
+
+- 추출: ...
+- 검증: ...
+- 종합: ...
+- 임베딩: ...
+
+현재 설치 상태를 보면 ...입니다.
+다음 단계는 ...입니다.
+```
+
+모델 다운로드 계획:
+
+```text
+모델 설치 계획입니다. 아직 다운로드는 실행하지 않았습니다.
+
+필요한 모델:
+...
+
+이 모델들이 필요한 이유:
+- 추출 모델: 문서에서 엔티티, 관계, 결정, 근거를 뽑기 위해 사용합니다.
+- 검증 모델: 추출된 내용을 원문과 대조해 과한 추론을 줄이는 데 사용합니다.
+- 종합 모델: Bronze/Silver 결과를 Gold 메모리로 정리하는 데 사용합니다.
+- 임베딩 모델: 문서 검색과 RAG 검색에 사용합니다.
+
+진행하면 로컬 디스크와 다운로드 시간이 사용됩니다.
+이 계획대로 모델을 설치해도 될까요?
+```
+
+문서 메모리 구축:
+
+```text
+문서 메모리 구축 결과입니다.
+
+- corpus: ...
+- 대상 폴더: ...
+- 구축 방식: Bronze -> Silver -> Gold
+- 처리 문서: ...
+- Gold nodes: ...
+- Gold edges: ...
+- 제외/실패 항목: ...
+
+이제 이 메모리를 기준으로 질문할 수 있습니다.
+```
+
 ## AME가 제공하는 MCP 도구
 
 Codex/Claude Code는 AME MCP를 통해 다음 도구를 사용할 수 있습니다.
@@ -149,7 +225,7 @@ Codex/Claude Code는 AME MCP를 통해 다음 도구를 사용할 수 있습니
 
 모델 다운로드는 시간과 디스크를 사용합니다. Codex/Claude Code가 먼저 다운로드 계획을 보여준 뒤, 사용자가 승인하면 실행하는 흐름을 권장합니다.
 
-사양 진단이나 모델 추천은 corpus가 필요 없는 bootstrap MCP에서 처리합니다. 사용자가 직접 만든 corpus가 아니라면 `openclaw` 같은 예시 corpus 이름을 임의로 사용하지 않아야 합니다.
+사양 진단이나 모델 추천은 corpus가 필요 없는 bootstrap MCP에서 처리합니다. 문서 메모리 구축 단계에서만 corpus 이름과 문서 폴더가 필요합니다.
 
 ## CLI로 직접 쓰고 싶을 때
 
@@ -176,6 +252,15 @@ ame> /exit
 가상환경은 패키지를 격리해서 설치하기 위한 용도입니다.
 MCP 설정을 한 번 추가한 뒤에는 Codex/Claude Code가 `ame` 명령을 직접 실행합니다.
 
+이미 설치한 적이 있다면 업그레이드를 명시합니다.
+
+```bash
+python -m pip install --upgrade adaptive-memory-engine
+python -m pip show adaptive-memory-engine
+```
+
+출력의 `Version`이 현재 README의 버전과 같아야 합니다.
+
 터미널에서 `ame` 명령이 안 보이면 PATH를 다시 적용합니다.
 
 ```bash
@@ -199,6 +284,14 @@ ame connect --client codex --absolute-command
 예전 문서의 `memory` 명령과 충돌할 수 있어서, 새 버전에서는 `ame` 명령을 기본으로 사용합니다.
 `memory`는 호환용 alias로 남아 있지만 가능하면 `ame`를 사용하세요.
 
+`ame`가 여전히 보이지 않으면 설치 스크립트로 `~/.ame`에 격리 설치하는 방법이 가장 단순합니다.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/kimdol1045-hash/adaptive-memory-engine/main/install.sh | bash
+source ~/.zshrc
+ame --help
+```
+
 ## MCP 모드
 
 AME는 두 가지 MCP 모드를 제공합니다.
@@ -217,8 +310,6 @@ ame mcp stdio my-docs
 
 대부분의 사용자는 직접 `ame mcp stdio`를 실행하지 않고, `ame connect --client codex` 또는 `ame connect --client claude`로 출력된 설정을 클라이언트에 넣으면 됩니다.
 
-`ame mcp stdio`는 표준 MCP `Content-Length` 프레이밍과 newline JSON-RPC를 모두 지원합니다.
-
 ## Bronze/Silver/Gold 구조
 
 - Bronze: 원본 문서를 보존합니다.

{adaptive_memory_engine-0.1.8 → adaptive_memory_engine-0.1.9}/README.en.md

@@ -7,7 +7,7 @@ The preferred UX is agent-first: connect AME through MCP, then ask Codex or
 Claude Code to diagnose hardware, recommend models, build memory, and answer
 questions in natural language.
 
-Current status: alpha, distributed through PyPI. Current version: `0.1.8`.
+Current status: alpha, distributed through PyPI. Current version: `0.1.9`.
 
 ## 1. Install
 
@@ -75,10 +75,14 @@ built memory.
 
 Use separate steps instead of one long request.
 
-First ask the agent to use AME MCP and follow the AME flow:
+Start with this exact prompt. It nudges the agent to use AME MCP tools before
+shell commands or web search:
 
 ```text
-Use AME MCP and follow the AME flow step by step. Start by checking ame_flow.
+Use AME MCP and follow the AME flow step by step.
+Start by checking ame_flow, and diagnose hardware with ame_doctor.
+For model downloads, first show the plan with ame_setup execute=false.
+Do not run execute=true until I explicitly approve it.
 ```
 
 Then diagnose hardware and model fit:
@@ -111,6 +115,78 @@ After memory is built, ask grounded questions:
 Using my-docs memory, tell me the current decisions and their rationale.
 ```
 
+The expected flow is:
+
+```text
+ame_flow -> ame_doctor -> ame_setup execute=false -> user approval -> ame_setup execute=true -> ame_load -> memory_query/memory_search
+```
+
+Hardware diagnosis and model recommendation do not require a corpus. Choose a
+corpus name only when building memory from documents.
+
+## 4. Response Templates
+
+AME MCP exposes templates through `ame_flow`. To inspect one:
+
+```text
+Show me the output_template for the model_plan stage from ame_flow.
+```
+
+Recommended diagnosis response:
+
+```text
+Hardware diagnosis result.
+
+- OS/CPU: ...
+- RAM: ...
+- Available disk: ...
+- AME tier: ...
+
+Recommended models:
+
+- Extract: ...
+- Verify: ...
+- Synthesize: ...
+- Embedding: ...
+
+Current install status: ...
+Next step: ...
+```
+
+Recommended model plan response:
+
+```text
+Model installation plan. No downloads have been started yet.
+
+Required models:
+...
+
+Why these models are needed:
+- Extract model: extracts entities, relations, decisions, and rationale.
+- Verify model: checks extracted content against source text.
+- Synthesize model: turns Bronze/Silver outputs into Gold memory.
+- Embedding model: supports document and RAG search.
+
+This will use local disk and download time.
+Should I install these models?
+```
+
+Recommended memory build response:
+
+```text
+Memory build result.
+
+- corpus: ...
+- source folder: ...
+- build path: Bronze -> Silver -> Gold
+- processed documents: ...
+- Gold nodes: ...
+- Gold edges: ...
+- rejected items: ...
+
+You can now ask questions against this memory.
+```
+
 ## MCP Tools
 
 AME exposes these tools to Codex or Claude Code:
@@ -127,8 +203,8 @@ Model downloads can take time and disk space. The agent should show the plan
 first, then run downloads after user approval.
 
 Hardware diagnosis and model recommendations should use bootstrap MCP because
-they do not require a corpus. Agents should not invent example corpus IDs such
-as `openclaw` unless the user explicitly provided that corpus.
+they do not require a corpus. A corpus name and document folder are only needed
+when building memory.
 
 ## Manual CLI Use
 
@@ -155,6 +231,15 @@ ame> /exit
 The virtual environment is only used to isolate the Python package install. Once
 the MCP config is added, Codex or Claude Code launches the `ame` command.
 
+If AME was already installed, upgrade explicitly:
+
+```bash
+python -m pip install --upgrade adaptive-memory-engine
+python -m pip show adaptive-memory-engine
+```
+
+The printed `Version` should match the current README version.
+
 If `ame` is not on PATH, reload your shell config:
 
 ```bash
@@ -179,6 +264,14 @@ New versions use `ame` as the recommended command because the older `memory`
 command can collide with previous installs. `memory` remains as a compatibility
 alias, but prefer `ame`.
 
+If `ame` is still unavailable, the simplest path is the isolated installer:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/kimdol1045-hash/adaptive-memory-engine/main/install.sh | bash
+source ~/.zshrc
+ame --help
+```
+
 ## MCP Modes
 
 Bootstrap MCP:
@@ -196,9 +289,6 @@ ame mcp stdio my-docs
 Most users do not need to run these manually. Use `ame connect --client codex`
 or `ame connect --client claude` and paste the printed config into the client.
 
-`ame mcp stdio` supports both standard MCP `Content-Length` framing and newline
-JSON-RPC.
-
 ## Bronze/Silver/Gold
 
 - Bronze: preserves raw documents.

{adaptive_memory_engine-0.1.8 → adaptive_memory_engine-0.1.9}/README.md

@@ -7,7 +7,7 @@ Codex나 Claude Code가 그 메모리를 보고 답할 수 있게 해주는 loca
 
 사용자가 매번 긴 명령어를 치는 방식보다, **Codex/Claude Code에 AME를 연결하고 자연어로 맡기는 방식**을 우선합니다.
 
-현재는 alpha 단계이며 PyPI로 배포 중입니다. 현재 버전은 `0.1.8`입니다.
+현재는 alpha 단계이며 PyPI로 배포 중입니다. 현재 버전은 `0.1.9`입니다.
 
 ## 1. 설치
 
@@ -68,10 +68,13 @@ ame connect --client claude
 
 한 번에 길게 요청하기보다, 아래 흐름대로 하나씩 진행하는 것을 권장합니다.
 
-먼저 AME MCP를 사용한다고 명시하고 진행 방식을 확인합니다.
+처음에는 아래 문장을 그대로 입력하는 것이 가장 안전합니다. 이 문장은 에이전트가 shell 명령이나 웹 검색보다 AME MCP 도구를 먼저 쓰도록 유도합니다.
 
 ```text
-AME MCP를 사용해서 단계별로 진행해줘. 먼저 ame_flow를 확인해줘.
+AME MCP를 사용해서 단계별로 진행해줘.
+먼저 ame_flow를 확인하고, 사양 진단은 ame_doctor로 해줘.
+모델 다운로드는 ame_setup execute=false로 계획만 먼저 보여주고,
+내가 승인하기 전에는 execute=true를 실행하지 마.
 ```
 
 그 다음 사양 진단을 요청합니다.
@@ -104,6 +107,79 @@ AME MCP를 사용해서 단계별로 진행해줘. 먼저 ame_flow를 확인해
 my-docs 메모리를 기준으로 현재 유효한 결정과 그 근거를 알려줘.
 ```
 
+정상 플로우는 다음 순서입니다.
+
+```text
+ame_flow -> ame_doctor -> ame_setup execute=false -> 사용자 승인 -> ame_setup execute=true -> ame_load -> memory_query/memory_search
+```
+
+사양 진단과 모델 추천 단계에서는 corpus가 필요 없습니다. 문서 메모리 구축 단계에서만 corpus 이름을 정하면 됩니다.
+
+## 4. 단계별 응답 템플릿
+
+AME MCP의 `ame_flow`는 에이전트가 답변에 사용할 템플릿을 제공합니다. 사용자가 직접 템플릿을 보고 싶다면 이렇게 요청하면 됩니다.
+
+```text
+ame_flow에서 model_plan 단계의 output_template을 보여줘.
+```
+
+권장 응답 형태는 다음과 같습니다.
+
+사양 진단:
+
+```text
+사양 진단 결과입니다.
+
+- OS/CPU: ...
+- RAM: ...
+- 사용 가능 디스크: ...
+- AME tier: ...
+
+추천 모델은 다음과 같습니다.
+
+- 추출: ...
+- 검증: ...
+- 종합: ...
+- 임베딩: ...
+
+현재 설치 상태를 보면 ...입니다.
+다음 단계는 ...입니다.
+```
+
+모델 다운로드 계획:
+
+```text
+모델 설치 계획입니다. 아직 다운로드는 실행하지 않았습니다.
+
+필요한 모델:
+...
+
+이 모델들이 필요한 이유:
+- 추출 모델: 문서에서 엔티티, 관계, 결정, 근거를 뽑기 위해 사용합니다.
+- 검증 모델: 추출된 내용을 원문과 대조해 과한 추론을 줄이는 데 사용합니다.
+- 종합 모델: Bronze/Silver 결과를 Gold 메모리로 정리하는 데 사용합니다.
+- 임베딩 모델: 문서 검색과 RAG 검색에 사용합니다.
+
+진행하면 로컬 디스크와 다운로드 시간이 사용됩니다.
+이 계획대로 모델을 설치해도 될까요?
+```
+
+문서 메모리 구축:
+
+```text
+문서 메모리 구축 결과입니다.
+
+- corpus: ...
+- 대상 폴더: ...
+- 구축 방식: Bronze -> Silver -> Gold
+- 처리 문서: ...
+- Gold nodes: ...
+- Gold edges: ...
+- 제외/실패 항목: ...
+
+이제 이 메모리를 기준으로 질문할 수 있습니다.
+```
+
 ## AME가 제공하는 MCP 도구
 
 Codex/Claude Code는 AME MCP를 통해 다음 도구를 사용할 수 있습니다.
@@ -118,7 +194,7 @@ Codex/Claude Code는 AME MCP를 통해 다음 도구를 사용할 수 있습니
 
 모델 다운로드는 시간과 디스크를 사용합니다. Codex/Claude Code가 먼저 다운로드 계획을 보여준 뒤, 사용자가 승인하면 실행하는 흐름을 권장합니다.
 
-사양 진단이나 모델 추천은 corpus가 필요 없는 bootstrap MCP에서 처리합니다. 사용자가 직접 만든 corpus가 아니라면 `openclaw` 같은 예시 corpus 이름을 임의로 사용하지 않아야 합니다.
+사양 진단이나 모델 추천은 corpus가 필요 없는 bootstrap MCP에서 처리합니다. 문서 메모리 구축 단계에서만 corpus 이름과 문서 폴더가 필요합니다.
 
 ## CLI로 직접 쓰고 싶을 때
 
@@ -145,6 +221,15 @@ ame> /exit
 가상환경은 패키지를 격리해서 설치하기 위한 용도입니다.
 MCP 설정을 한 번 추가한 뒤에는 Codex/Claude Code가 `ame` 명령을 직접 실행합니다.
 
+이미 설치한 적이 있다면 업그레이드를 명시합니다.
+
+```bash
+python -m pip install --upgrade adaptive-memory-engine
+python -m pip show adaptive-memory-engine
+```
+
+출력의 `Version`이 현재 README의 버전과 같아야 합니다.
+
 터미널에서 `ame` 명령이 안 보이면 PATH를 다시 적용합니다.
 
 ```bash
@@ -168,6 +253,14 @@ ame connect --client codex --absolute-command
 예전 문서의 `memory` 명령과 충돌할 수 있어서, 새 버전에서는 `ame` 명령을 기본으로 사용합니다.
 `memory`는 호환용 alias로 남아 있지만 가능하면 `ame`를 사용하세요.
 
+`ame`가 여전히 보이지 않으면 설치 스크립트로 `~/.ame`에 격리 설치하는 방법이 가장 단순합니다.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/kimdol1045-hash/adaptive-memory-engine/main/install.sh | bash
+source ~/.zshrc
+ame --help
+```
+
 ## MCP 모드
 
 AME는 두 가지 MCP 모드를 제공합니다.
@@ -186,8 +279,6 @@ ame mcp stdio my-docs
 
 대부분의 사용자는 직접 `ame mcp stdio`를 실행하지 않고, `ame connect --client codex` 또는 `ame connect --client claude`로 출력된 설정을 클라이언트에 넣으면 됩니다.
 
-`ame mcp stdio`는 표준 MCP `Content-Length` 프레이밍과 newline JSON-RPC를 모두 지원합니다.
-
 ## Bronze/Silver/Gold 구조
 
 - Bronze: 원본 문서를 보존합니다.

{adaptive_memory_engine-0.1.8 → adaptive_memory_engine-0.1.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "adaptive-memory-engine"
-version = "0.1.8"
+version = "0.1.9"
 description = "Local-first CLI memory engine that builds Bronze/Silver/Gold RAG memory from local documents."
 readme = "README.md"
 requires-python = ">=3.11"

adaptive_memory_engine-0.1.9/src/ame/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.9"

{adaptive_memory_engine-0.1.8 → adaptive_memory_engine-0.1.9}/src/ame/agent/mcp.py

@@ -19,7 +19,7 @@ from ame.models.router import ModelRouter
 from ame.pipeline import MemoryPipeline
 
 
-SERVER_VERSION = "0.1.8"
+SERVER_VERSION = "0.1.9"
 
 MCP_INSTRUCTIONS = "\n".join(
     [

{adaptive_memory_engine-0.1.8 → adaptive_memory_engine-0.1.9}/tests/test_plan_compliance_runtime.py

@@ -125,7 +125,7 @@ def test_mcp_stdio_accepts_content_length_framing() -> None:
     _headers, payload = raw.split("\r\n\r\n", 1)
     response = json.loads(payload)
     assert response["result"]["serverInfo"]["name"] == "adaptive-memory-engine"
-    assert response["result"]["serverInfo"]["version"] == "0.1.8"
+    assert response["result"]["serverInfo"]["version"] == "0.1.9"
     assert "Use AME MCP tools before shell commands" in response["result"]["instructions"]
 
 

adaptive_memory_engine-0.1.8/src/ame/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.1.8"