HM-Arch v2.0.4

HM-Arch v2.0.4

HM-Arch 2.0.4 is a patch release for the three-agent integration line. It
keeps the v2.0.x Python, npm, and standalone channels aligned while making the
default user-facing install path use the latest stable package.

What changed

• Codex recall hook output now includes
  hookSpecificOutput.hookEventName: "UserPromptSubmit" alongside
  additionalContext, matching the expected lifecycle hook JSON shape.
• Hermes, Claude Code, and Codex installation and memory smoke paths were
  validated together after the v2.0.x integration fixes.
• README and agent setup docs now recommend latest stable install commands for
  normal users:

pip install hm-arch
pipx install hm-arch
npm install -g @hm-arch/installer
npx @hm-arch/installer install hermes
npx @hm-arch/installer install claude-code
npx @hm-arch/installer install codex

Version-pinned installs remain supported when users need reproducible
environments:

pip install hm-arch==2.0.4
npm install -g @hm-arch/installer@2.0.4

Verification

Release verification before tagging:

uv run pytest
uv run python examples/release_smoke.py
python scripts/verify_release_versions.py
cd packages/installer && npm test

Compatibility

• Python: 3.10+
• Node.js: 18+
• Supported agents: Codex, Claude Code, Hermes
• Supported standalone npm targets: linux x86_64/aarch64, darwin arm64, windows
  x86_64

HM-Arch v2.0.3

HM-Arch v2.0.3

HM-Arch 2.0.3 is a patch release for npm-managed Codex and Claude Code
hook commands on standalone installs.

Fixes

• Fixed Codex and Claude Code hook commands created by the npm installer when
  the managed runtime is a standalone HM-Arch executable.

• Standalone installs now write hook commands like:

  /path/to/hm-arch claude-code recall
  /path/to/hm-arch codex recall

  instead of treating the standalone executable like a Python interpreter with
  -m hm_arch.integrations.cli.

• hm-arch status claude-code and hm-arch doctor claude-code no longer warn
  that hm-arch is missing from PATH when they are running from the standalone
  executable.

• The same standalone runtime diagnostic improvement applies to Codex hooks.

Install

pip install hm-arch==2.0.3
npm install -g @hm-arch/installer@2.0.3

For one-shot npm usage:

npx @hm-arch/installer@2.0.3 install claude-code
npx @hm-arch/installer@2.0.3 install codex

HM-Arch v2.0.2

HM-Arch v2.0.2

HM-Arch 2.0.2 is a patch release for smooth Hermes uninstall support.

Fixes

• hm-arch uninstall hermes now removes HM-Arch-owned Hermes provider settings
  instead of returning unsupported.
• hm-arch-install uninstall hermes now works through the npm installer path.
• Hermes uninstall is idempotent: repeating the command reports that HM-Arch is
  already not installed.
• Hermes uninstall removes the HM-Arch plugin bridge and preserves existing
  memory databases by default.
• Hermes uninstall preserves unrelated Hermes memory providers and plugin
  configuration.

Verification

• Hermes install/uninstall CLI regression tests.
• Hermes worker-thread provider tests.
• Full offline test suite before release.

Install

pip install hm-arch==2.0.2
npm install -g @hm-arch/installer@2.0.2

HM-Arch v2.0.1

HM-Arch v2.0.1

HM-Arch 2.0.1 is a patch release for the v2.0 line.

Fixes

• Fixed Hermes hm_arch_remember tool calls when Hermes runs tools from a worker thread.
• Fixed Hermes hm_arch_search tool calls under the same threaded execution path.
• Updated Hermes prefetch handling so file-backed SQLite databases are read through fresh handles after explicit tool writes.

Verification

• Hermes worker-thread regression test for explicit remember/search tool calls.
• Full offline test suite: 1021 passed, 21 deselected.

Install

pip install hm-arch==2.0.1
npm install -g @hm-arch/installer@2.0.1

HM-Arch v2.0.0

HM-Arch v2.0.0 — coordinated Python, npm, and standalone release

HM-Arch 2.0.0 is the first coordinated release line for the Python package,
the npm installer, and standalone executable artifacts.

Publication requires explicit maintainer approval. Automated agents may
prepare files, run tests, and build local artifacts, but must not create tags,
publish GitHub Releases, upload to PyPI, or run npm publish unless explicitly
instructed for v2.0.0.

Install

GitHub Release

Download hm_arch-2.0.0-py3-none-any.whl and/or hm_arch-2.0.0.tar.gz from the
release assets:

python3.12 -m venv .venv && source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install /path/to/hm_arch-2.0.0-py3-none-any.whl
hm-arch --help
python -c "import hm_arch; print(hm_arch.__version__)"

PyPI (after maintainer-approved publish)

pip install hm-arch==2.0.0
# or isolated CLI:
pipx install hm-arch==2.0.0
hm-arch --help

npm (after maintainer-approved publish)

npm install -g @hm-arch/installer@2.0.0
hm-arch-install doctor

One-shot usage is also supported:

npx @hm-arch/installer@2.0.0 doctor

What's new

Python-free npm path

@hm-arch/installer can now use verified standalone executables on supported
targets, so Node.js users can run HM-Arch agent management commands without a
preinstalled Python runtime.

Supported standalone targets:

OS	Architectures
linux	x86_64, aarch64
darwin	arm64
windows	x86_64

Unsupported targets, such as Intel macOS and Windows ARM64, can continue using
the managed Python runtime with HM_ARCH_RUNTIME=python.

Shared hm-arch CLI

The Python package exposes the same CLI surface used by direct Python users,
agent hooks, and the npm installer:

hm-arch recall | record | consolidate
hm-arch codex recall | record | consolidate
hm-arch claude-code recall | record | consolidate
hm-arch install <agent> [--global]
hm-arch uninstall <agent> [--global]
hm-arch status [agent] [--global]
hm-arch doctor [agent] [--global]

Agent integrations

• Codex: idempotent project/global hook installation via hm-arch install codex.
• Claude Code: idempotent .claude/settings.json merge via
  hm-arch install claude-code.
• Hermes: native Memory Provider foundation with status and doctor
  support; install/uninstall remain manual by design.

Setup guides:

• https://github.com/ZhangHangjianMA/hm-arch/blob/v2.0.0/docs/agents/codex.md
• https://github.com/ZhangHangjianMA/hm-arch/blob/v2.0.0/docs/agents/claude-code.md
• https://github.com/ZhangHangjianMA/hm-arch/blob/v2.0.0/docs/agents/hermes.md

Version coordination

All release channels use 2.0.0:

Channel	Version
Python package hm-arch	2.0.0
GitHub Release tag	v2.0.0
npm package @hm-arch/installer	2.0.0
Standalone artifacts	hm-arch-2.0.0-{os}-{arch}

The release includes automated version checks for Python, npm, bundled installer
metadata, and standalone release naming.

Runtime selection

HM_ARCH_RUNTIME controls npm installer behavior:

Value	Behavior
auto	Prefer standalone on supported targets; fall back to managed Python
standalone	Require a verified standalone binary
python	Always use the managed Python virtual environment

See v2-migration-guide.md and
npm-installer.md for details.

Unchanged from v1.0.0

• Offline-first HMArch facade with SQLite source of truth
• L0-L6 memory layers, retention-aware retrieval, forgetting, and consolidation
• Optional OpenAI, DeepSeek, and ChromaDB backends with local fallback defaults
• No automatic agent configuration changes during package installation

Known limitations

• Standalone binaries are not built for every OS/architecture combination.
• Hermes hook installation is manual; CLI management is status/doctor only.
• Registry publication requires maintainer action and credentials.
• The npm package is an installer/launcher; memory logic remains in HM-Arch.

Verification

Before tagging or publishing:

uv run pytest
(cd packages/installer && npm test)
python scripts/verify_release_versions.py
uv run python examples/release_smoke.py

Full release gates:

• https://github.com/ZhangHangjianMA/hm-arch/blob/v2.0.0/docs/RELEASE_CHECKLIST.md
• https://github.com/ZhangHangjianMA/hm-arch/blob/v2.0.0/docs/pypi-clean-install.md
• https://github.com/ZhangHangjianMA/hm-arch/blob/v2.0.0/docs/npm-installer-publication.md

HM-Arch v1.0.0

HM-Arch v1.0.0

HM-Arch 1.0.0 is distributed through this GitHub Release only. It is not published to PyPI or any other package registry.

Install from release artifacts

Download hm_arch-1.0.0-py3-none-any.whl and/or hm_arch-1.0.0.tar.gz from the release assets, then install in a virtual environment (Python >= 3.10):

python3 --version   # requires Python >= 3.10
python3 -m venv .venv && source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install /path/to/hm_arch-1.0.0-py3-none-any.whl
python -c "import hm_arch; print(hm_arch.__version__)"
python examples/release_smoke.py

Optional ChromaDB support (not required for offline use):

python -m pip install '/path/to/hm_arch-1.0.0-py3-none-any.whl[chroma]'

For development from source (before or without a published release):

git clone https://github.com/ZhangHangjianMA/memashuman.git
cd memashuman
python3 -m pip install -e ".[dev]"

What's included

Memory layers (L0–L6)

Layer	Role
L0	Sensory register (in-memory)
L1	Working memory (in-memory, session-scoped)
L2	Episodic buffer (SQLite + vector index)
L3	Semantic memory (SQLite triples + vector index)
L4	Long-term gzip archive
L5	Procedural / skills memory
L6	Meta-memory and strategy hints

All layers are reachable through the HMArch facade with accurate cross-layer statistics.

Public API (HMArch)

• add(), search(), forget(), consolidate(), get_retention_curve(), get_stats()
• context() / agent_context() for agent session load/save
• MemoryConfig presets: code_agent, chat_agent, research_agent
• Offline-first defaults: no API keys, network, or ChromaDB required for core behavior

Optional backends

Backend	Purpose	Requirement
Local (default)	Deterministic token-overlap vectors and rule-based semantic extraction	None
OpenAI	LLM scoring and extraction	enable_llm_providers=True, API key
DeepSeek	LLM scoring and extraction	enable_llm_providers=True, API key
ChromaDB	Persistent vector store	chromadb>=0.5.0, vector_backend="chroma" (from source: pip install -e '.[chroma]'; from this release wheel: pip install '/path/to/hm_arch-1.0.0-py3-none-any.whl[chroma]')

When provider_fallback_to_local=True (the default), missing optional dependencies, credentials, or runtime provider failures use local deterministic behavior (tests and demos run fully offline). With provider_fallback_to_local=False, those conditions raise actionable errors.

Agent integration examples

• examples/codex_hooks/ — Codex CLI turn-start, turn-end, idle consolidation
• examples/claude_code_hooks/ — Claude Code equivalents (offline demos)

Set HM_ARCH_DB_PATH to choose the SQLite database file.

Benchmark evidence (HM-31)

Reproducible PRD benchmarks validate single-process, local-fallback operation. See https://github.com/ZhangHangjianMA/memashuman/blob/v1.0.0/docs/benchmarks.md

Example observed results (Linux, Python 3.12, local fallback, 2026-06-03):

Metric	Observed	PRD test limit
add() p95	~3.8 ms	< 50 ms
search() p95 @ 10k L2	~73 ms	< 100 ms
consolidate() @ 10k L2	~0.9 s	< 60 s
SQLite storage (10k L2 + 5k L3)	~8.5 MB	< 500 MB
7-day L3 semantic accuracy	100%	> 80%

Run on your hardware:

uv run pytest tests/prd_benchmarks -m benchmark -v
uv run python scripts/run_prd_benchmarks.py

Known limitations

• Not on PyPI — install from GitHub Release artifacts or source only.
• No MCP server — SDK library only; MCP tooling remains out of scope.
• Single-process, single-agent — no multi-user sharing, encryption, or distributed storage.
• L4 archive PRD formula deviation — uniform 30-day-old L2 rows typically do not archive because modeled retention (~0.26) stays above l2_archive_threshold (0.15). Mixed-age and agent-simulation scenarios are documented at https://github.com/ZhangHangjianMA/memashuman/blob/v1.0.0/docs/benchmarks.md
• Week 9 stretch targets — reported for information only; they do not gate benchmark acceptance.
• Optional backends — OpenAI, DeepSeek, and Chroma require extra packages and credentials; with provider_fallback_to_local=True (default), missing pieces use the offline path.

Verification (maintainers)

Before tagging v1.0.0 (Python >= 3.10):

uv run pytest && uv run python examples/release_smoke.py
python3 --version
uv run --with build python -m build --outdir dist
# Clean wheel + sdist install — see https://github.com/ZhangHangjianMA/memashuman/blob/v1.0.0/docs/RELEASE_CHECKLIST.md

Full checklist: https://github.com/ZhangHangjianMA/memashuman/blob/v1.0.0/docs/RELEASE_CHECKLIST.md

Full changelog

https://github.com/ZhangHangjianMA/memashuman/blob/v1.0.0/CHANGELOG.md#100---2026-06-03