agentloop-memory-fs 0.1.0

Virtual filesystem for Alibaba Cloud CMS AgentLoop Memory API - Agent-friendly design

AgentLoop Memory FS

Virtual filesystem for Alibaba Cloud CMS AgentLoop Memory API - designed for AI Agent interaction.

Features

• Agent-Friendly Design: Explore the filesystem with standard shell commands (ls, cat, echo, mkdir, rm)
• Self-Describing: _help.txt files at every level guide usage
• Semantic Search: Search memories using natural language via file paths
• POSIX Compatible: Works with any tool that uses standard file operations

Installation

Install from source

pip install .

Install from wheel

pip install build
python3 -m build
pip install dist/agentloop_memory_fs-*.whl

OS Dependencies (FUSE)

macOS

brew install macfuse

Linux (Ubuntu/Debian)

sudo apt-get install fuse libfuse-dev

Linux (CentOS/RHEL)

sudo yum install fuse fuse-devel

Configuration

Set environment variables or use a .env file:

export ALIBABA_CLOUD_ACCESS_KEY_ID="your-access-key-id"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="your-access-key-secret"
export CMS_WORKSPACE="your-workspace-name"
export CMS_ENDPOINT="cms.cn-hangzhou.aliyuncs.com"  # optional

Or create a .env file in the working directory:

ALIBABA_CLOUD_ACCESS_KEY_ID=your-access-key-id
ALIBABA_CLOUD_ACCESS_KEY_SECRET=your-access-key-secret
CMS_WORKSPACE=your-workspace-name
CMS_ENDPOINT=cms.cn-hangzhou.aliyuncs.com

Usage

Mount the Filesystem

mkdir -p /tmp/memory
agentloop-memory-fs /tmp/memory

Or with options:

agentloop-memory-fs /tmp/memory --workspace my-project --endpoint cms.cn-shanghai.aliyuncs.com

Basic Operations

# View help
cat /tmp/memory/_help.txt

# List memory stores
ls /tmp/memory/stores/

# Create a new store
mkdir /tmp/memory/stores/my_memories

# Add a memory (WRITE-ONLY, async processing)
echo "User prefers dark mode" > /tmp/memory/stores/my_memories/_add.txt

# Wait 30-60 seconds for processing...

# Search memories (semantic)
cat /tmp/memory/stores/my_memories/search/preferences.txt

# View all memories for a user
cat /tmp/memory/stores/my_memories/users/default_user/_all.txt

# View store info
cat /tmp/memory/stores/my_memories/_info.json

# Delete a memory store
rmdir /tmp/memory/stores/my_memories

Important Notes

• _add.txt is WRITE-ONLY: data is sent to API, not stored locally
• After writing, memories are processed asynchronously (30-60s delay)
• To view memories, use search/{query}.txt or users/{user}/_all.txt
• Do NOT cat _add.txt to check if write succeeded

Unmount

# macOS
umount /tmp/memory

# Linux
fusermount -u /tmp/memory

Directory Structure

/
├── _help.txt                    # Root help
└── stores/
    ├── _help.txt                # Stores help
    └── {store_name}/
        ├── _info.json           # Store configuration (READ-ONLY)
        ├── _add.txt             # Add memories (WRITE-ONLY, async)
        ├── _help.txt            # Store help
        ├── memories/
        │   ├── _help.txt
        │   └── {memory_id}.json # Individual memory
        ├── users/
        │   ├── _help.txt
        │   └── {user_id}/
        │       ├── _all.txt     # All user memories (READ)
        │       └── _add.txt     # Add for user (WRITE)
        ├── agents/
        │   ├── _help.txt
        │   └── {agent_id}/...
        └── search/
            ├── _help.txt
            └── {query}.txt      # Search results (READ)

API Mapping

Shell Command	CMS AgentLoop Memory API
mkdir stores/{name}	CreateMemoryStore
rmdir stores/{name}	DeleteMemoryStore
cat stores/{name}/_info.json	GetMemoryStore
echo "text" > stores/{name}/_add.txt	AddMemories
cat stores/{name}/search/{query}.txt	SearchMemories
cat stores/{name}/memories/{id}.json	GetMemory
rm stores/{name}/memories/{id}.json	DeleteMemory
ls stores/	ListMemoryStores

For AI Agents

This filesystem is specifically designed to give AI agents persistent memory capabilities using standard shell commands.

We provide ready-to-use prompt templates in the agent_integration/ directory:

1. INSTALL_PROMPT.md: Give this instruction to your AI Agent when you want it to automatically install dependencies, configure credentials, and mount the filesystem in its environment.
2. USAGE_PROMPT.md: Append this to your AI Agent's System Prompt. It teaches the agent how to actively read, write, and search its memory using bash commands like ls, cat, and echo. (Note: Before injecting this prompt, make sure to replace the {{YOUR_STORE_NAME}} placeholder with the actual memory store assigned to the agent).
3. SKILL.md: If you are using an agent framework that supports "Skills" (like Cursor Agent), you can add this folder as a custom skill. The agent will automatically read it when it needs to use memory.

A quick example of what the agent learns to do:

# Agent remembers a user preference
echo "User prefers Python" > /tmp/agentloop_memory/stores/my_agent_store/_add.txt

# Agent recalls information later
cat "/tmp/agentloop_memory/stores/my_agent_store/search/What language does the user prefer.txt"

CLI Reference

agentloop-memory-fs [-h] [-V] [-e FILE] [--endpoint HOST]
              [-w NAME] [-p NAME] [--access-key-id ID]
              [--access-key-secret SECRET] [-f] [-d]
              [--allow-other]
              mountpoint

Options:
  mountpoint            Directory to mount the filesystem
  -V, --version         Show version
  -e, --env FILE        Path to .env file
  --endpoint HOST       CMS endpoint
  -w, --workspace NAME  CMS workspace name
  -p, --project NAME    CMS project name (alias for workspace)
  --access-key-id ID    Alibaba Cloud Access Key ID
  --access-key-secret   Alibaba Cloud Access Key Secret
  -f, --foreground      Run in foreground (default)
  -d, --debug           Enable debug logging
  --allow-other         Allow other users access

Testing

# Integration tests (requires credentials)
python tests/test_memory_api.py

# E2E tests (requires mounted filesystem)
agentloop-memory-fs /tmp/agentloop_memory &
bash tests/e2e_test.sh

License

MIT License