adaptive-memory-engine 0.1.6__tar.gz

adaptive_memory_engine-0.1.6/.gitignore

@@ -0,0 +1,17 @@
+.DS_Store
+.env
+.coverage
+htmlcov/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ame*/
+exports/
+tests/out/
+.venv/
+dist/
+build/
+*.egg-info/
+content/
+/docs/adaptive_memory_engine_*.md
+/adaptive_memory_engine_*.md

adaptive_memory_engine-0.1.6/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+## 0.1.6 - 2026-06-12
+
+- Switched public install docs from TestPyPI to PyPI.
+- Added macOS/Linux and Windows installer scripts for one-command local setup.
+- Simplified README around the agent-first MCP flow: install once, connect once, then use Codex/Claude Code in natural language.
+
+## 0.1.5 - 2026-06-12
+
+- Changed MCP config output to use `command: "ame"` by default.
+- Added `--include-path-env` for MCP clients that need PATH included in generated config.
+- Added `--absolute-command` for users who prefer the previous absolute executable path behavior.
+
+## 0.1.4 - 2026-06-11
+
+- Updated MCP client config generation to use the absolute `ame` executable path.
+- Clarified that virtual environments are only for installation isolation; MCP clients do not need the venv activated after config is added.
+
+## 0.1.3 - 2026-06-11
+
+- Added `ame` as the recommended CLI command to avoid collisions with older or unrelated `memory` commands.
+- Kept `memory` as a backwards-compatible alias.
+- Updated README examples to use `ame` first.
+
+## 0.1.2 - 2026-06-11
+
+- Added corpus-free bootstrap MCP mode through `memory mcp stdio`.
+- Added MCP tools for agent-led setup: `ame_doctor`, `ame_setup`, `ame_load`, `ame_connect`, and `ame_corpora`.
+- Updated `memory connect` so Codex/Claude Code can connect before any corpus exists.
+- Added tests for agent bootstrap load and query flow.
+
+## 0.1.1 - 2026-06-11
+
+- Added `memory chat <corpus>` for interactive terminal questions without typing `memory query` each time.
+- Updated Korean and English README usage docs to show terminal chat mode and MCP usage more clearly.
+
+## 0.1.0 - 2026-06-11
+
+Initial alpha release.
+
+- Added local-first `memory` CLI for corpus setup, ingestion, retrieval, graph inspection, and export.
+- Added Bronze/Silver/Gold document memory pipeline with local LLM assisted Silver extraction.
+- Added hardware diagnosis and Ollama model recommendation through `memory doctor` and `memory setup`.
+- Added stdio MCP server and client config generation for Codex and Claude Code.
+- Added deterministic ingestion fallback for tests and lightweight smoke runs.
+- Added macOS, Windows, and Linux runtime path handling.
+- Added TestPyPI packaging support and GitHub Actions CI/publish workflows.

adaptive_memory_engine-0.1.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adaptive Memory Engine contributors
+
+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.

adaptive_memory_engine-0.1.6/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: adaptive-memory-engine
+Version: 0.1.6
+Summary: Local-first CLI memory engine that builds Bronze/Silver/Gold RAG memory from local documents.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,local-first,mcp,memory,ollama,rag
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Indexing
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: lightrag
+Requires-Dist: lightrag-hku; extra == 'lightrag'
+Requires-Dist: ollama; extra == 'lightrag'
+Description-Content-Type: text/markdown
+
+# Adaptive Memory Engine Core
+
+[English](README.en.md)
+
+Adaptive Memory Engine Core는 내 로컬 문서를 읽어 Bronze/Silver/Gold 메모리로 만들고,
+Codex나 Claude Code가 그 메모리를 보고 답할 수 있게 해주는 local-first 메모리 엔진입니다.
+
+사용자가 매번 긴 명령어를 치는 방식보다, **Codex/Claude Code에 AME를 연결하고 자연어로 맡기는 방식**을 우선합니다.
+
+현재는 alpha 단계이며 PyPI로 배포 중입니다. 현재 버전은 `0.1.6`입니다.
+
+## 1. 설치
+
+macOS/Linux:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/kimdol1045-hash/adaptive-memory-engine/main/install.sh | bash
+```
+
+Windows PowerShell:
+
+```powershell
+irm https://raw.githubusercontent.com/kimdol1045-hash/adaptive-memory-engine/main/install.ps1 | iex
+```
+
+설치 스크립트는 `~/.ame`에 AME를 설치하고 `ame` 명령을 PATH에 추가합니다. macOS/Linux에서는 설치 직후 스크립트가 출력하는 `source ...` 명령을 현재 터미널에 한 번 실행하면 됩니다.
+
+```bash
+source ~/.zshrc
+```
+
+직접 설치하고 싶다면 PyPI에서 설치할 수 있습니다.
+
+```bash
+python -m pip install adaptive-memory-engine
+```
+
+커스텀 MCP로만 쓸 때도 AME 실행 파일은 로컬에 있어야 합니다. PyPI/GitHub는 설치 파일을 배포하는 곳이고, MCP 클라이언트는 로컬에서 `ame mcp stdio` 프로세스를 실행합니다.
+
+## 2. Codex 또는 Claude Code에 연결
+
+Codex용 MCP 설정을 출력해서 Codex의 커스텀 MCP 설정에 붙입니다.
+
+```bash
+ame connect --client codex
+```
+
+Claude Code를 쓴다면 다음 명령을 사용합니다.
+
+```bash
+ame connect --client claude
+```
+
+출력된 JSON의 기본 `command`는 절대경로가 아니라 `ame`입니다.
+
+```json
+{
+  "command": "ame",
+  "args": ["mcp", "stdio"]
+}
+```
+
+기본 설정에는 실행 파일 절대경로를 넣지 않습니다. MCP 클라이언트가 실행될 때마다 가상환경을 직접 활성화할 필요도 없습니다.
+
+이때 아직 문서 메모리를 만들지 않았어도 괜찮습니다. `ame connect --client ...`는 bootstrap MCP 설정을 출력하므로, Codex/Claude Code가 사양 진단부터 메모리 구축까지 진행할 수 있습니다.
+
+## 3. 자연어로 요청
+
+이제 Codex나 Claude Code에 이렇게 말하면 됩니다.
+
+```text
+내 컴퓨터 사양을 진단하고 AME에 맞는 로컬 모델을 추천해줘.
+다운로드가 필요하면 어떤 모델을 받을지 먼저 알려줘.
+내가 승인하면 모델을 설치해줘.
+그 다음 /Users/me/Documents/planning 폴더를 my-docs라는 이름으로 메모리화해줘.
+구축이 끝나면 그 메모리를 기준으로 질문에 답해줘.
+```
+
+이후에는 평소처럼 질문하면 됩니다.
+
+```text
+이 문서들에서 현재 유효한 결정은 뭐야?
+왜 이런 구조를 선택했는지 근거를 찾아줘.
+지난 결정 중 지금은 superseded 된 게 있어?
+```
+
+## AME가 제공하는 MCP 도구
+
+Codex/Claude Code는 AME MCP를 통해 다음 도구를 사용할 수 있습니다.
+
+- `ame_doctor`: 컴퓨터 사양과 로컬 모델 상태 진단
+- `ame_setup`: 추천 모델 다운로드 계획 또는 실행
+- `ame_load`: 문서 폴더를 Bronze/Silver/Gold 메모리로 구축
+- `ame_corpora`: 만들어진 corpus 목록 확인
+- `memory_search`, `memory_query`: 구축된 메모리 기반 질문
+- `memory_graph`, `memory_decisions`, `memory_timeline`, `memory_why`: 구조화된 메모리 조회
+
+모델 다운로드는 시간과 디스크를 사용합니다. Codex/Claude Code가 먼저 다운로드 계획을 보여준 뒤, 사용자가 승인하면 실행하는 흐름을 권장합니다.
+
+## CLI로 직접 쓰고 싶을 때
+
+에이전트 없이 직접 사용할 수도 있습니다.
+
+```bash
+ame doctor
+ame setup
+ame setup --execute
+ame load my-docs ./path/to/markdown-docs
+ame chat my-docs
+```
+
+`ame chat`에 들어가면 매번 명령어를 치지 않고 질문만 입력할 수 있습니다.
+
+```text
+ame> 현재 유효한 결정은 뭐야?
+ame> 왜 LightRAG를 선택했어?
+ame> /exit
+```
+
+## 설치 문제 해결
+
+가상환경은 패키지를 격리해서 설치하기 위한 용도입니다.
+MCP 설정을 한 번 추가한 뒤에는 Codex/Claude Code가 `ame` 명령을 직접 실행합니다.
+
+터미널에서 `ame` 명령이 안 보이면 PATH를 다시 적용합니다.
+
+```bash
+source ~/.zshrc
+ame --help
+ame connect --client codex
+```
+
+MCP 클라이언트가 `ame`를 찾지 못한다면 PATH를 JSON에 같이 넣을 수 있습니다.
+
+```bash
+ame connect --client codex --include-path-env
+```
+
+그래도 안 되면 예전 방식처럼 실행 파일 절대경로를 넣을 수 있습니다.
+
+```bash
+ame connect --client codex --absolute-command
+```
+
+예전 문서의 `memory` 명령과 충돌할 수 있어서, 새 버전에서는 `ame` 명령을 기본으로 사용합니다.
+`memory`는 호환용 alias로 남아 있지만 가능하면 `ame`를 사용하세요.
+
+## MCP 모드
+
+AME는 두 가지 MCP 모드를 제공합니다.
+
+아직 corpus가 없고 Codex/Claude Code가 설정부터 진행해야 한다면 bootstrap MCP를 사용합니다.
+
+```bash
+ame mcp stdio
+```
+
+이미 만들어진 특정 corpus만 보게 하려면 corpus-bound MCP를 사용합니다.
+
+```bash
+ame mcp stdio my-docs
+```
+
+대부분의 사용자는 직접 `ame mcp stdio`를 실행하지 않고, `ame connect --client codex` 또는 `ame connect --client claude`로 출력된 설정을 클라이언트에 넣으면 됩니다.
+
+## Bronze/Silver/Gold 구조
+
+- Bronze: 원본 문서를 보존합니다.
+- Silver: 엔티티, 관계, 결정, 근거, 제약을 구조화합니다.
+- Gold: 그래프, 타임라인, supersession, 검증 정보를 구성합니다.
+
+`ame load`의 기본 모드는 로컬 LLM을 사용하는 Bronze/Silver/Gold 구축입니다.
+테스트나 fallback이 필요할 때만 deterministic 모드를 사용합니다.
+
+```bash
+ame load my-docs ./path/to/docs --mode deterministic
+```
+
+## SDK
+
+```python
+from ame.sdk import Corpus
+from memory import Corpus
+```
+
+## 테스트
+
+```bash
+pytest
+```
+
+## 참고 문서
+
+- `docs/product_user_flow.md`: 의도한 CLI 제품 흐름
+- `docs/release_distribution_plan.md`: 외부 배포 계획
+- `docs/pypi_release_checklist.md`: PyPI/TestPyPI 배포 체크리스트
+- `docs/standalone_distribution.md`: standalone 패키지 분리 전략

adaptive_memory_engine-0.1.6/README.en.md

@@ -0,0 +1,197 @@
+# Adaptive Memory Engine Core
+
+Adaptive Memory Engine Core turns local documents into Bronze/Silver/Gold memory
+and exposes that memory to Codex, Claude Code, or another MCP client.
+
+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.6`.
+
+## 1. Install
+
+macOS/Linux:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/kimdol1045-hash/adaptive-memory-engine/main/install.sh | bash
+```
+
+Windows PowerShell:
+
+```powershell
+irm https://raw.githubusercontent.com/kimdol1045-hash/adaptive-memory-engine/main/install.ps1 | iex
+```
+
+The installer puts AME in `~/.ame` and adds `ame` to PATH. On macOS/Linux, run
+the printed `source ...` command once in the current terminal after
+installation:
+
+```bash
+source ~/.zshrc
+```
+
+Manual PyPI install is also available:
+
+```bash
+python -m pip install adaptive-memory-engine
+```
+
+Even when you only use custom MCP, the AME executable still needs to exist
+locally. PyPI/GitHub distributes the package; the MCP client starts a local `ame
+mcp stdio` process so AME can read local documents and use local LLMs.
+
+## 2. Connect Codex Or Claude Code
+
+Print a Codex MCP config and paste it into Codex custom MCP settings:
+
+```bash
+ame connect --client codex
+```
+
+For Claude Code:
+
+```bash
+ame connect --client claude
+```
+
+By default, the `command` field is `ame`, not an absolute executable path.
+
+```json
+{
+  "command": "ame",
+  "args": ["mcp", "stdio"]
+}
+```
+
+The default config does not include an absolute executable path. The MCP client
+does not need the virtual environment to be activated every time.
+
+This works even before a corpus exists. The bootstrap MCP server lets Codex or
+Claude Code diagnose hardware, plan model downloads, build memory, and query the
+built memory.
+
+## 3. Ask In Natural Language
+
+Then ask Codex or Claude Code:
+
+```text
+Diagnose my computer for AME and recommend local models.
+If downloads are needed, show me the model plan first.
+After I approve, install the models.
+Then build memory named my-docs from /Users/me/Documents/planning.
+Once memory is built, answer questions from that local memory.
+```
+
+After that, ask normally:
+
+```text
+What decisions are currently valid?
+Why did we choose this architecture?
+Which past decisions are now superseded?
+```
+
+## MCP Tools
+
+AME exposes these tools to Codex or Claude Code:
+
+- `ame_doctor`: diagnose hardware and local model status
+- `ame_setup`: plan or execute recommended model downloads
+- `ame_load`: build Bronze/Silver/Gold memory from a folder
+- `ame_corpora`: list built corpora
+- `memory_search`, `memory_query`: answer from built memory
+- `memory_graph`, `memory_decisions`, `memory_timeline`, `memory_why`: structured memory lookup
+
+Model downloads can take time and disk space. The agent should show the plan
+first, then run downloads after user approval.
+
+## Manual CLI Use
+
+You can also use AME directly:
+
+```bash
+ame doctor
+ame setup
+ame setup --execute
+ame load my-docs ./path/to/markdown-docs
+ame chat my-docs
+```
+
+Inside chat mode:
+
+```text
+ame> What decisions are currently valid?
+ame> Why did we choose LightRAG?
+ame> /exit
+```
+
+## Troubleshooting
+
+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` is not on PATH, reload your shell config:
+
+```bash
+source ~/.zshrc
+ame --help
+ame connect --client codex
+```
+
+If the MCP client still cannot find `ame`, include PATH in the generated JSON:
+
+```bash
+ame connect --client codex --include-path-env
+```
+
+If that still fails, use the previous absolute command mode:
+
+```bash
+ame connect --client codex --absolute-command
+```
+
+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`.
+
+## MCP Modes
+
+Bootstrap MCP:
+
+```bash
+ame mcp stdio
+```
+
+Corpus-bound MCP:
+
+```bash
+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.
+
+## Bronze/Silver/Gold
+
+- Bronze: preserves raw documents.
+- Silver: extracts entities, relations, decisions, rationales, and constraints.
+- Gold: builds graph, timeline, supersession, and validation views.
+
+Use deterministic mode only for tests or fallback:
+
+```bash
+ame load my-docs ./path/to/docs --mode deterministic
+```
+
+## SDK
+
+```python
+from ame.sdk import Corpus
+from memory import Corpus
+```
+
+## Tests
+
+```bash
+pytest
+```