MemVault

Production-ready long-term memory server for AI agents with Ebbinghaus decay and strength-weighted retrieval. Use when you need persistent memory across agen...

Security Scan

The skill appears to implement the advertised memory server, but the installer auto-downloads/runs third‑party installers (curl | sh for Ollama), the package expects and creates many environment settings not declared in the registry, and running it may send stored memories to whatever LLM endpoint you configure — review before installing.

Purpose & Capability

The code, Dockerfile, docker-compose, and CLI match the stated purpose (a long‑term memory server with embeddings, decay, and retrieval). However the registry metadata says 'required env vars: none' while the code and docker-compose rely on many environment variables (DB DSN, LLM base URL, API key, embedding URL, etc.). That mismatch is unexpected but plausibly an omission rather than outright malice.

Instruction Scope

SKILL.md instructs you to run the included install script and then call local endpoints and cron jobs. The runtime instructions themselves are scoped to installing and operating the service (memorize, retrieve, decay). They do not instruct arbitrary file system reads. Caveat: troubleshooting text references an OpenClaw workspace path which may not exist in all installs (minor inconsistency).

Install Mechanism

The provided scripts/install.sh will attempt to auto-install Ollama on Linux by executing a remote script via curl -fsSL https://ollama.com/install.sh | sh — this is a high‑risk pattern (running a remote installer without review). The installer also starts background processes (ollama serve) and runs docker compose up --build which will download images, pip packages, and pre-download embedding models during the Docker build. These are expected for this project but are higher risk than an instruction-only skill; review the installer and the remote install script before running.

Credentials

Although the registry metadata declared no required environment variables, the code and docker-compose rely on many env vars (MEMVAULT_DB_DSN, MEMVAULT_LLM_BASE_URL, MEMVAULT_LLM_API_KEY, MEMVAULT_EMBEDDING_URL, etc.). Defaults include cleartext DB credentials (postgres/postgres) in the compose file and the installer creates a .env. If you point MEMVAULT_LLM_BASE_URL to a public/cloud LLM (OpenAI, etc.), memories and potentially sensitive content will be sent to that provider. The skill may therefore handle secrets/PII; you should explicitly set appropriate credentials and endpoints and avoid using public LLMs if you want to keep data local.

Persistence & Privilege

The skill does not request permanent platform presence (always:false). Installer creates a CLI symlink in ~/.local/bin and writes a .env in the skill directory and uses a Docker volume for DB persistence; these are normal for a self‑hosted service and do not modify other skills or system-wide agent settings.

What to consider before installing

This package is functionally consistent with a self‑hosted long‑term memory server, but take caution before running the installer. Review scripts/install.sh and avoid blindly running curl | sh from the network; consider installing Ollama manually or configuring MEMVAULT_LLM_BASE_URL to a known local endpoint. Update the default DB password (postgres/postgres) and confirm where MEMVAULT_LLM_BASE_URL points — if you set it to a cloud LLM (OpenAI/Groq), your stored memories will be transmitted to that provider. If you must test, run inside an isolated environment (VM/container) and inspect docker-compose and Dockerfile builds so you can audit downloaded models and packages. If you want lower risk, you can skip the auto‑installer and manually start the docker-compose build after reviewing files.

MemVault — Long-term Memory for AI Agents

Quick Start

# Install (one command — Docker handles everything)
bash scripts/install.sh

# Verify
memvault health

Usage

# Store a memory
memvault memorize-text <user_id> "<message>" "[reply]"

# Retrieve memories (strength-weighted)
memvault retrieve <user_id> "<query>"

# Run daily decay (memories fade like human memory)
memvault decay <user_id>

# Check stats
memvault stats <user_id>

API Endpoints

Method	Endpoint	Description
POST	/memorize	Store conversation → extract facts/events/knowledge
POST	/retrieve	Strength-weighted vector search (similarity × strength)
POST	/decay	Ebbinghaus forgetting curve (run daily via cron)
GET	/stats	Memory distribution, access patterns, agent breakdown
GET	/health	Service health

How It Works

1. Store: Conversations → LLM extracts facts → embedded → stored in pgvector
2. Retrieve: Query embedded → cosine similarity × memory strength → ranked results
3. Decay: strength = exp(-rate × days / (1 + damping × ln(1 + access_count)))
4. Access boost: Each retrieval increments access_count, slowing decay

Fading memories (strength < 0.1) are excluded from search.

Configuration

All via environment variables in .env (created by install script):

• MEMVAULT_LLM_BASE_URL — Default: Ollama local. Set to OpenAI/Groq/etc URL if preferred
• MEMVAULT_LLM_MODEL — Default: qwen2.5:3b
• MEMVAULT_TRANSLATION — Set true + MEMVAULT_TRANSLATION_LANG for auto-translation
• MEMVAULT_PORT — Default: 8002

Daily Cron Setup

Add Ebbinghaus decay to your agent's cron:

0 3 * * *  curl -s -X POST 'http://127.0.0.1:8002/decay?user_id=YOUR_USER_ID'

TOOLS.md Snippet

## MemVault 🧠
memvault memorize-text "<user_id>" "<content>" "<context>"
memvault retrieve "<user_id>" "<query>"
memvault decay <user_id>
memvault stats <user_id>
- API: 127.0.0.1:8002

Multi-Agent Memory

Tag memories by source agent:

curl -X POST http://localhost:8002/memorize -H "Content-Type: application/json" \
  -d '{"conversation": [
    {"role": "metadata", "content": "{\"source_agent\": \"research-bot\"}"},
    {"role": "user", "content": "Found new papers on transformers"}
  ], "user_id": "team"}'

Troubleshooting

• "Connection refused" → Run docker compose -f ~/.openclaw/workspace/skills/memvault/docker-compose.yml up -d
• Slow memorize → Normal, LLM extraction takes 5-15s per conversation
• No results from retrieve → Check memvault stats — if total=0, nothing stored yet
• All memories fading → Reduce decay_rate: curl -X POST 'http://localhost:8002/decay?decay_rate=0.05'