hm-arch

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.4): install from PyPI, npm, the v2.0.4 GitHub Release, or from source (below).

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

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.4-py3-none-any.whl from the v2.0.4 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.4-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
# or: pipx install hm-arch

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

npm install -g @hm-arch/installer
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

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 bundled hm-arch runtime for that installer release.

Install Agents With npm

One-shot usage with npx:

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

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

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

Or install the npm launcher globally:

npm install -g @hm-arch/installer

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

To verify Codex specifically, start with the HM-Arch bridge before opening the
Codex CLI:

printf '%s' '{"prompt":"Codex-HM-Arch-local-check","last_assistant_message":"Stored through HM-Arch."}' \
  | hm-arch codex record

printf '%s' '{"hook_event_name":"UserPromptSubmit","prompt":"Codex-HM-Arch-local-check"}' \
  | hm-arch codex recall

The recall JSON should include
hookSpecificOutput.hookEventName: "UserPromptSubmit" and an
HM-Arch recalled memory section in additionalContext. In interactive Codex,
run /hooks and trust the HM-Arch hooks if prompted. If Codex native memories
are enabled, they can still inject local file-backed memory; for a one-off
HM-Arch-only check, launch Codex with codex --disable memories.

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 uninstall codex

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

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

For global Codex or Claude Code hooks:

npx @hm-arch/installer uninstall codex --global
npx @hm-arch/installer 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

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.

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

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.