How to use AgentMemory

Scope of use

This tool applies to the following agent frameworks and MCP clients:

Installation methods

You can install AgentMemory by using an RPM package (recommended for Alinux 4) or from source code.

RPM package installation (recommended):

# Install with dnf (auto-resolves dependencies)
sudo dnf install agent-memory

RPM installs to the following system-level FHS paths:

• Service binary: /usr/bin/agent-memory

• Default configuration: /usr/share/anolisa/agent-memory/default.toml

• MCP service descriptor: /usr/share/anolisa/mcp-servers/agent-memory.json

• systemd user template: /usr/lib/systemd/user/anolisa-memory@.service

• OpenClaw adapter bundle: /usr/share/anolisa/adapters/agent-memory/

Install from source:

git clone https://github.com/alibaba/anolisa.git
cd src/agent-memory
make build # cargo build --release --locked
sudo make install
# Installed under /usr/local
# Build dependencies: Rust >= 1.85, cmake (vendored libgit2 build), systemd-devel (journald audit fan-out).
# Only Linux is supported at runtime (requires user_namespace, mount(2), cgroup v2, inotify, and journald).

Configuration and integration

After RPM installation, the OpenClaw adapter resources reside in /usr/share/anolisa/adapters/agent-memory/ and include scripts/install.sh, which registers the plug-in. Other MCP clients are integrated directly through their MCP configuration files.

OpenClaw integration

sudo bash /usr/share/anolisa/adapters/agent-memory/openclaw/scripts/install.sh
# Restart the OpenClaw gateway after installation:
openclaw gateway restart
# Use the openclaw command to check the agent-memory plug-in installation status:
openclaw plugins list |grep memory

Integration with Claude Code and other agents

Add agent-memory to the MCP configuration file of Claude Code:

{
   "mcpServers":
   {
      "agent-memory":
      {
         "command": "/usr/bin/agent-memory",
         "args": [],
         "env": 
         {
            "USER_ID": "alice",
            "MEMORY_PROFILE": "advanced"
         }
      }
   }
}

systemd service management

After RPM installation, you can manage the agent-memory service by using the systemd user template:

# Start the service (user alice is used as an example)
systemctl --user start anolisa-memory@alice
# Check the status
systemctl --user status anolisa-memory@alice
# Start the service on boot
systemctl --user enable anolisa-memory@alice
# View the logs
journalctl --user -u anolisa-memory@alice -f

MCP toolset

agent-memory provides 37 standard tools over the MCP protocol. The tools are divided into three tiers by function:

mem_read # Read file content
mem_write # Write to a file
mem_append # Append content
mem_edit # Edit a file (replaces a unique old_str match)
mem_list # List directory content
mem_grep # Search file content by regular expression
mem_diff # Compare file differences
mem_mkdir # Create a directory
mem_remove # Delete a file or directory
mem_promote # Atomically move a session draft into the persistent store
mem_session_log # View the JSONL log of the current session

memory_search # BM25, vector, or hybrid semantic search
memory_observe # Automatically capture observations and deduplicate them
memory_get_context # Get a context preview of recently modified files
memory_sessions # List historical sessions
memory_timeline # Tool call timeline of a specified session
mem_index_refresh # Force a rebuild of the FTS5 index

mem_snapshot # Create a tar.gz snapshot
mem_snapshot_list # List snapshots
mem_snapshot_restore # Restore a snapshot
mem_log # Git change history
mem_revert # Roll back a file by using Git
mem_consolidate # Automatically extract atomic facts and persist them
mem_compact # Archive cold data

memory_about # Retrieve memories by topic
memory_auto_created # List automatically extracted facts
memory_consent # Grant or revoke consent for memory operations
memory_forget # Delete the memories of a specified topic
mem_export # Export the memory store as AMA JSON
mem_import # Import memories from AMA JSON
memory_task_save # Save or update a task
memory_task_list # List task summaries
memory_task_resume # Resume the task context
memory_task_close # Close a task
memory_summary # Statistical overview of the memory store
memory_session_context # Inject the session startup context
mem_dream # Synthesize a user profile

Configurations

[global]
user_id = "alice"

[memory]
profile = "advanced" # basic | advanced | expert
max_read_bytes = 1048576 # 1 MiB
max_write_bytes = 16777216 # 16 MiB

[memory.paths]
base_dir = "~/.anolisa/memory"

[memory.mount]
strategy = "auto" # auto | userland | userns

[memory.index]
enabled = true

[memory.consolidation]
enabled = true

Profile descriptions

A profile controls tool visibility and is verified at both the tools/list and tools/call layers:

• basic: All 37 tools are displayed. Weaker models can also use the structured APIs in Tier B.

• advanced (default): All 37 tools are displayed. Powerful models are expected to use the Tier A file operations first.

• expert: Tier B tools, such as memory_search, memory_observe, and memory_get_context, are hidden. Corresponding tools/call requests are rejected with METHOD_NOT_FOUND.

Key environment variables

Each configuration item has a corresponding MEMORY_* environment variable. The priority is env > config.toml > default.