convez.ai
Agente
zhhjluka

hm-arch

zhhjluka/hm-arch

Ver no GitHub
BomPluginScore · de 0 a 100

A human-like memory for AI Agent

Instalação

$npx convez-ai zhhjluka/hm-arch

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
19
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
v2.0.4
Issues abertas
1
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.


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):

ChannelPackageCurrent versionInstall
GitHub Releaseswheel + sdist + standalone binariesv2.0.4Download assets
PyPIhm-archlatest stablepip install hm-arch
npm@hm-arch/installerlatest stablenpm install -g @hm-arch/installer

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

LayerNameRole
L0Sensory registerCaptures the most recent signals in memory
L1Working memoryHolds session-scoped context
L2Episodic memoryStores durable events and conversations
L3Semantic memoryStores extracted facts and relationships
L4Long-term archiveCompresses low-retention memories
L5Procedural memoryStores reusable skills and procedures
L6Meta-memoryTracks 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 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

AgentInstallInspect
Codexhm-arch install codexhm-arch status codex, hm-arch doctor codex
Claude Codehm-arch install claude-codehm-arch status claude-code, hm-arch doctor claude-code
Hermeshm-arch install hermeshm-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.

BackendPurposeSetup
LocalOffline retrieval and semantic extractionNo dependencies or credentials
OpenAI / DeepSeekLLM scoring and semantic extractionMemoryConfig(enable_llm_providers=True) plus API key
ChromaDBPersistent vector indexInstall 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

DocumentPurpose
docs/api.mdPublic API reference
docs/spec.mdProduct and API contract
docs/benchmarks.mdPRD benchmark results and limitations
docs/RELEASE_NOTES_v1.0.0.mdv1.0.0 release notes
docs/RELEASE_NOTES_v2.0.0.mdv2.0.0 coordinated release notes
docs/RELEASE_NOTES_v2.0.4.mdv2.0.4 three-agent validation and latest install guidance
docs/v2-migration-guide.mdv2.0.0 migration and compatibility
docs/agents/README.mdCodex, Claude Code, and Hermes setup
docs/pypi-clean-install.mdpip / pipx clean-install verification
docs/npm-installer.mdnpm installer requirements, usage, and version pairing
docs/npm-installer-publication.mdnpm publication checklist (maintainer approval required)
docs/RELEASE_CHECKLIST.mdRelease and registry publication policy
docs/VERSIONING.mdSemver and cross-channel version alignment
docs/agent-integration-roadmap.mdPyPI and npm integration timeline
CHANGELOG.mdVersion 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.

Ver o original no GitHub

Bom para

Relacionados