npm package: @humanlikememory/human-like-mem-hermes-plugin
Description: HumanLike memory provider for Hermes Agent with automatic recall, turn-based storage, and agent memory tools.
Author: hanlaomo
Latest version: 1.0.10

# HumanLike Memory for Hermes Agent

HumanLike ships as a Hermes memory provider, not as a skill. It plugs into Hermes' native `MemoryProvider` lifecycle so the agent can:

Install it with one command and give Hermes persistent long-term memory backed by HumanLike.

- recall relevant long-term memories before each turn
- batch conversation turns and persist them automatically
- expose `memory_search` and `memory_store` as model tools
- preserve platform user identity from channel-formatted messages when available

## Install

Choose one method below. You only need to run one of them.

- Recommended: one-line install

```bash
curl -fsSL https://cdn.jsdelivr.net/npm/@humanlikememory/human-like-mem-hermes-plugin@latest/install.sh | bash
```

Hermes is switched to `humanlike` automatically during installation. No manual `config.yaml` edit is required.

- Or: if you want a reproducible install, pin a version

```bash
curl -fsSL https://cdn.jsdelivr.net/npm/@humanlikememory/human-like-mem-hermes-plugin@1.0.10/install.sh | bash -s -- --version 1.0.10
```

- Or: if you already unpacked the bundle locally

```bash
bash install.sh
```

- Or: pull the npm package into a folder first, then run the local installer

```bash
mkdir -p ~/.hermes/humanlike-memory-provider \
  && cd ~/.hermes/humanlike-memory-provider \
  && npm pack @humanlikememory/human-like-mem-hermes-plugin \
  && tar xzf *.tgz \
  && cp -R package/. ./ \
  && rm -rf package *.tgz \
  && bash install.sh
```

What the installer does for you:

- download the npm package when needed
- symlink `adapters/hermes` into Hermes' `plugins/memory/`
- set `memory.provider: humanlike` in `~/.hermes/config.yaml`
- verify that Hermes can load the provider

## Quick Start After Install

After the installer finishes:

```bash
echo 'HUMAN_LIKE_MEM_API_KEY=mp_xxxxxx' >> ~/.hermes/.env
```

If Hermes is not running yet, start it normally and you are done.

If Hermes is already running, restart it so the active process picks up the new memory provider:

```bash
hermes gateway restart
```

If you are using `hermes chat` in a terminal instead of the background gateway, stop the current process and start `hermes` again.

## Optional Environment Variables

- `HUMAN_LIKE_MEM_BASE_URL` - Memory service base URL. Default: `https://plugin.human-like.me`
- `HUMAN_LIKE_MEM_USER_ID` - Fallback user identifier when no platform identity is present. Default: `hermes-user`
- `HUMAN_LIKE_MEM_AGENT_ID` - Agent identifier stored with writes. Default: `main`
- `HUMAN_LIKE_MEM_RECALL_ENABLED` - Enable automatic recall. Default: `true`
- `HUMAN_LIKE_MEM_ADD_ENABLED` - Enable automatic writes. Default: `true`
- `HUMAN_LIKE_MEM_RECALL_GLOBAL` - Search across conversations instead of only the current session. Default: `true`
- `HUMAN_LIKE_MEM_LIMIT_NUMBER` - Maximum recalled memories per search. Default: `6`
- `HUMAN_LIKE_MEM_MIN_SCORE` - Minimum recall score. Default: `0.1`
- `HUMAN_LIKE_MEM_MIN_TURNS` - Minimum completed turns before an automatic flush. Default: `5`
- `HUMAN_LIKE_MEM_SESSION_TIMEOUT` - Idle flush timeout in milliseconds. Default: `300000`
- `HUMAN_LIKE_MEM_TAGS` - Comma-separated tags applied to stored memories. Default: `hermes`
- `HUMAN_LIKE_MEM_SCENARIO` - Scenario used for both writes and searches. Default: `openclaw-plugin`
- `HUMAN_LIKE_MEM_STRIP_PLATFORM_METADATA` - Disable metadata extraction from channel transcripts. Default: `false`
- `HUMAN_LIKE_MEM_TIMEOUT_MS` - HTTP timeout for provider requests. Default: `5000`

## Important: Share Memory Across Multiple AI Agents

By default, Hermes now matches the original HumanLike plugin defaults: `scenario=openclaw-plugin` and `agent_id=main`. If you are reusing memories written by the historical HumanLike OpenClaw plugin, you usually do not need any extra configuration.

**If you want multiple AI agents to share the same memory pool, you must align both `HUMAN_LIKE_MEM_AGENT_ID` and `HUMAN_LIKE_MEM_SCENARIO`.**

These two values work together:

- `HUMAN_LIKE_MEM_AGENT_ID` controls which agent the memory belongs to
- `HUMAN_LIKE_MEM_SCENARIO` controls which client or workflow namespace is used for writes and searches

`HUMAN_LIKE_MEM_SCENARIO` now scopes both writes and searches. If you want Hermes to retrieve memories written by another client, set the same scenario value on both sides.

In many setups, `agent_id` also needs to match. If the other client wrote memories under `agent_id=default`, set Hermes to the same value:

```bash
echo 'HUMAN_LIKE_MEM_SCENARIO=claude' >> ~/.hermes/.env
echo 'HUMAN_LIKE_MEM_AGENT_ID=default' >> ~/.hermes/.env
```

Then restart Hermes if it is already running:

```bash
hermes gateway restart
```

If these two values do not match across clients, memory writes may still succeed, but shared retrieval across agents will not line up.

## Optional Verification

If you want to confirm the provider is active, check that `~/.hermes/config.yaml` contains:

```yaml
memory:
  provider: humanlike
```

Or verify directly with Python:

```bash
python3 - <<'PY'
from plugins.memory import load_memory_provider

provider = load_memory_provider("humanlike")
print(provider.name if provider else "missing")
PY
```

## Runtime Behavior

- `prefetch()` retrieves relevant memories and injects them into the next turn
- `sync_turn()` stores user and assistant turns in a session buffer
- sessions flush automatically on the turn threshold or idle timeout
- `on_session_end()` flushes any remaining buffered turns
- `on_memory_write()` mirrors Hermes built-in memory additions into HumanLike

## Tools

### `memory_search`

```json
{
  "query": "What did the user mention about their travel plans?",
  "limit": 6
}
```

### `memory_store`

```json
{
  "content": "User prefers concise project updates with direct action items.",
  "category": "preference"
}
```

## Development

Run a quick syntax check before publishing:

```bash
npm run check
```

## License

Apache-2.0