Metadata-Version: 2.4
Name: agentloop-memory-fs
Version: 0.1.0
Summary: Virtual filesystem for Alibaba Cloud CMS AgentLoop Memory API - Agent-friendly design
Author: CMS Team
License: MIT
Project-URL: Homepage, https://github.com/aliyun/agentloop-memory-fs
Project-URL: Documentation, https://help.aliyun.com/product/28958.html
Keywords: cms,agentloop,memory,fuse,filesystem,agent,ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Filesystems
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: fusepy>=3.0.1
Requires-Dist: python-dotenv>=0.19.0
Requires-Dist: alibabacloud-tea-openapi>=0.3.0
Requires-Dist: alibabacloud-tea-util>=0.3.0
Requires-Dist: alibabacloud-credentials>=0.3.0
Requires-Dist: alibabacloud-cms20240330>=6.2.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: mypy; extra == "dev"

# 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

```bash
pip install .
```

### Install from wheel

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

### OS Dependencies (FUSE)

#### macOS

```bash
brew install macfuse
```

#### Linux (Ubuntu/Debian)

```bash
sudo apt-get install fuse libfuse-dev
```

#### Linux (CentOS/RHEL)

```bash
sudo yum install fuse fuse-devel
```

## Configuration

Set environment variables or use a `.env` file:

```bash
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

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

Or with options:

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

### Basic Operations

```bash
# 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

```bash
# 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](agent_integration/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](agent_integration/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](agent_integration/skill/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:
```bash
# 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

```bash
# 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
