hm-arch 2.0.2

Offline-first human-like memory SDK for coding agents (L0–L6, SQLite, consolidation)

Human-like memory architecture for AI agents.
Store experiences, retrieve useful context, forget safely, and consolidate knowledge over time.

---

HM-Arch is an offline-first Python SDK that gives agents a layered memory system inspired by human memory. It combines short-lived working context, durable episodic and semantic memory, long-term archives, procedural skills, meta-memory, retention decay, and automatic consolidation behind one HMArch facade.

Core behavior runs locally with SQLite and deterministic retrieval. No API keys, network access, or external services are required for tests, demos, or the default runtime.

Why HM-Arch?

Most agent memory systems focus on storing and retrieving text. HM-Arch also models what happens after storage:

• Layered memory, L0-L6: sensory, working, episodic, semantic, archive, procedural, and meta-memory.
• Retention-aware retrieval: rank results using relevance, retention, and layer priority.
• Human-like forgetting: decay, review scheduling, safe deletion windows, and explicit forget().
• Automatic consolidation: extract semantics, merge duplicates, resolve conflicts, archive old memories, and schedule reviews.
• Agent-ready integration: packaged Codex and Claude Code hook installers, Hermes diagnostics, and portable hook examples.
• Offline-first by default: SQLite and local deterministic behavior, with optional OpenAI, DeepSeek, and ChromaDB backends.

Quick Start

Install

Current release (v2.0.2): install from PyPI, npm, the v2.0.2 GitHub Release, or from source (below).

Release channels (see docs/agent-integration-roadmap.md):

Channel	Package	Current version	Install
GitHub Releases	wheel + sdist + standalone binaries	v2.0.2	Download assets
PyPI	hm-arch	v2.0.2	pip install hm-arch==2.0.2
npm	@hm-arch/installer	v2.0.2	npm install -g @hm-arch/installer@2.0.2

All public channels use the same semver from src/hm_arch/_version.py. Automated agents must not create tags, GitHub Releases, or registry uploads without explicit maintainer instruction. See docs/RELEASE_CHECKLIST.md and docs/VERSIONING.md.

Install from the GitHub Release (current)

Download hm_arch-2.0.2-py3-none-any.whl from the v2.0.2 release page, then install it in a Python 3.10+ environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install /path/to/hm_arch-2.0.2-py3-none-any.whl

For development from source:

git clone https://github.com/zhhjluka/hm-arch.git
cd hm-arch
python -m pip install -e ".[dev]"

Install from PyPI:

pip install hm-arch==2.0.2
# or: pipx install hm-arch==2.0.2

Node.js users can install the agent installer from npm:

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

Maintainer clean-install verification: docs/pypi-clean-install.md.

Add and Search Memories

from hm_arch import EventType, HMArch

with HMArch(db_path="./.agent_memory.db") as memory:
    memory.add(
        "The user prefers concise Python code reviews",
        event_type=EventType.CONVERSATION,
        importance=0.9,
    )

    results = memory.search("How should I review this pull request?", top_k=3)

    for item in results.results:
        print(f"[L{item.layer}] {item.content} (score={item.score:.3f})")

Consolidate Knowledge

with HMArch(db_path="./.agent_memory.db") as memory:
    memory.add("The project uses Python 3.12 and pytest")
    report = memory.consolidate()

    print(report.extracted_semantics)
    print(memory.get_stats().by_layer)

Memory Architecture

Layer	Name	Role
L0	Sensory register	Captures the most recent signals in memory
L1	Working memory	Holds session-scoped context
L2	Episodic memory	Stores durable events and conversations
L3	Semantic memory	Stores extracted facts and relationships
L4	Long-term archive	Compresses low-retention memories
L5	Procedural memory	Stores reusable skills and procedures
L6	Meta-memory	Tracks strategies and memory-system knowledge

The facade exposes the complete lifecycle:

memory.add(...)
memory.search(...)
memory.forget(...)
memory.consolidate()
memory.get_retention_curve(...)
memory.get_stats()

See docs/api.md for the full public API and docs/spec.md for the product contract.

Agent Integration

Install and connect supported agents with the npm installer or the Python CLI (offline, no API keys). The npm installer exposes hm-arch-install and delegates to the matching hm-arch==2.0.2 runtime.

Install Agents With npm

One-shot usage with npx:

# Codex: run from the project root where .codex/ should be managed.
npx @hm-arch/installer@2.0.2 install codex
npx @hm-arch/installer@2.0.2 status codex
npx @hm-arch/installer@2.0.2 doctor codex

# Claude Code: run from the project root where .claude/ should be managed.
npx @hm-arch/installer@2.0.2 install claude-code
npx @hm-arch/installer@2.0.2 status claude-code
npx @hm-arch/installer@2.0.2 doctor claude-code

# Hermes: installs the Hermes memory provider bridge and updates config.yaml.
npx @hm-arch/installer@2.0.2 install hermes
npx @hm-arch/installer@2.0.2 status hermes
npx @hm-arch/installer@2.0.2 doctor hermes

Or install the npm launcher globally:

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

hm-arch-install install codex
hm-arch-install install claude-code
hm-arch-install install hermes

hm-arch-install status codex
hm-arch-install status claude-code
hm-arch-install status hermes

Use --global when you want Codex or Claude Code hooks in the user-level config instead of the current project:

hm-arch-install install codex --global
hm-arch-install install claude-code --global

Hermes uses its own home directory, usually ~/.hermes. After hm-arch-install install hermes, restart any running Hermes process so it loads the HM-Arch memory provider plugin. Validate with:

hm-arch-install doctor hermes
sqlite3 ~/.hermes/hm_arch_memory.db '.tables'

Uninstall Agents With npm

Use the same npm installer to remove HM-Arch-managed agent configuration:

# Codex: run from the same project root used during install.
npx @hm-arch/installer@2.0.2 uninstall codex

# Claude Code: run from the same project root used during install.
npx @hm-arch/installer@2.0.2 uninstall claude-code

# Hermes: removes the provider bridge/config entries, then restart Hermes.
npx @hm-arch/installer@2.0.2 uninstall hermes

For global Codex or Claude Code hooks:

npx @hm-arch/installer@2.0.2 uninstall codex --global
npx @hm-arch/installer@2.0.2 uninstall claude-code --global

If you installed the npm launcher globally, use hm-arch-install directly:

hm-arch-install uninstall codex
hm-arch-install uninstall claude-code
hm-arch-install uninstall hermes

Uninstalling agent integration removes HM-Arch-managed hooks or Hermes provider configuration, but it does not delete existing memory databases. Remove database files manually only after you no longer need the stored memories. Common paths:

.hm_arch_agent_memory.db
~/.hm-arch/global.db
~/.hermes/hm_arch_memory.db

Install Agents With Python

Agent	Install	Inspect
Codex	hm-arch install codex	hm-arch status codex, hm-arch doctor codex
Claude Code	hm-arch install claude-code	hm-arch status claude-code, hm-arch doctor claude-code
Hermes	hm-arch install hermes	hm-arch status hermes, hm-arch doctor hermes

Python uninstall commands mirror npm:

hm-arch uninstall codex
hm-arch uninstall claude-code
hm-arch uninstall hermes

Setup guides: docs/agents/README.md. Smoke tests: docs/integration-cli-smoke.md.

Portable example hook scripts (not auto-installed) remain under examples/codex_hooks/ and examples/claude_code_hooks/. Set HM_ARCH_DB_PATH to choose the SQLite database path.

Optional Backends

The local path remains the default even when optional integrations are available.

Backend	Purpose	Setup
Local	Offline retrieval and semantic extraction	No dependencies or credentials
OpenAI / DeepSeek	LLM scoring and semantic extraction	MemoryConfig(enable_llm_providers=True) plus API key
ChromaDB	Persistent vector index	Install the release wheel with [chroma] or source with .[chroma]

When provider_fallback_to_local=True (the default), missing credentials, dependencies, or provider failures fall back to deterministic local behavior.

Benchmarks

HM-Arch includes reproducible PRD-scale benchmarks for latency, storage, consolidation, and long-running memory behavior.

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

The benchmark suite covers 10k L2 memories, search and add latency p95, consolidation runtime, storage size, semantic accuracy, and 30-day archive scenarios. Results and known limitations are documented in docs/benchmarks.md.

Development

uv sync
uv run pytest
uv run python examples/basic_usage.py
uv run python examples/agent_integration.py
uv run python examples/release_smoke.py

The default test suite runs fully offline. Benchmark tests are marked separately and excluded from normal pytest runs.

Documentation

Document	Purpose
docs/api.md	Public API reference
docs/spec.md	Product and API contract
docs/benchmarks.md	PRD benchmark results and limitations
docs/RELEASE_NOTES_v1.0.0.md	v1.0.0 release notes
docs/RELEASE_NOTES_v2.0.0.md	v2.0.0 coordinated release notes
docs/RELEASE_NOTES_v2.0.2.md	v2.0.2 Hermes uninstall fix release notes
docs/v2-migration-guide.md	v2.0.0 migration and compatibility
docs/agents/README.md	Codex, Claude Code, and Hermes setup
docs/pypi-clean-install.md	pip / pipx clean-install verification
docs/npm-installer.md	npm installer requirements, usage, and version pairing
docs/npm-installer-publication.md	npm publication checklist (maintainer approval required)
docs/RELEASE_CHECKLIST.md	Release and registry publication policy
docs/VERSIONING.md	Semver and cross-channel version alignment
docs/agent-integration-roadmap.md	PyPI and npm integration timeline
CHANGELOG.md	Version history

Project Layout

src/hm_arch/          SDK source
tests/                Offline test suite
tests/prd_benchmarks/ Scale and performance benchmarks
examples/             Runnable examples and agent hooks
docs/                 Specifications, API docs, and release notes

License

HM-Arch is licensed under the Apache License 2.0.