hmem

hmem is an MCP server that provides persistent, humanlike memory for AI agents. It stores memory in a five-level hierarchy and serves memory through MCP-style read and write operations, enabling agents to remember past decisions, context, and knowledge across sessions and machines. The server exposes tools like read_memory, write_memory, update_memory, and append_memory to manage hierarchical memory entries, with support for branching, bookmarking, and obsolescence marking. When an agent starts, it loads Level 1 summaries and fetches deeper levels on demand, ensuring agents receive just the right amount of context for the task at hand.

To use it, install the MCP package (via npx as shown in the Quick Start), start the server, and connect your MCP-enabled agents. Use read_memory() to fetch memory, write_memory(...) to create new entries, update_memory(...) to correct or adjust existing nodes, and append_memory(...) to add sub-nodes. You can navigate memory via IDs like L0003, L0003.2, and so on, and you can mark entries obsolete without deleting them. The system also supports exporting/importing memory, tagging, pinning, and advanced features like per-agent memory stores and skill-driven instruction for agents. Monitor and curate memory health with the included memory curation concepts (duplicate merging, stale pointer pruning, and ID remapping on conflicts).

Prerequisites:

• Node.js and npm installed on your system
• Internet access to install MCP package

Step-by-step installation:

1. Verify Node.js is installed

node -v
npm -v

2. Initialize and install the hmem MCP server using npx (recommended, per Quick Start):

npx hmem-mcp init

This will install the hmem-mcp package, configure memory storage location (system-wide or project-local), and create initial config files.

3. Start the MCP server (the exact command may depend on your setup; typically the tool spawns a server on a default port or prints instructions after init):

# If the installer provided a startup command, run it. Example placeholder:
npx hmem-mcp start

4. Connect your MCP-enabled agents to the running hmem server and begin memory operations (read_memory, write_memory, etc.).

5. Optional: Review or customize the generated hmem.config.json and the per-tool skill files to integrate with your development environment.

Prerequisites summary:

• Node.js and npm
• Internet connection for initial install
• A compatible MCP-enabled agent toolchain to consume read_memory/write_memory APIs

Tips and common considerations:

• The system stores memory in five nested levels; Level 1 is loaded at spawn, deeper levels are fetched on-demand to conserve tokens.
• Use update_memory to modify existing nodes without deleting children; use append_memory to add new sub-nodes.
• Obsolete entries are hidden from bulk reads but remain accessible by ID for auditing and learning from past mistakes.
• Utilize markers and tags (e.g., [♥], [P], [!], #tags) to organize memory for faster bulk reads.
• If memory size or performance becomes an issue, consider adjusting bulk read behavior, memory curation cadence, and per-agent memory stores.
• The recommended npm package name is hmem-mcp; the install command uses npx to run the package initialization workflow.