https://github.com/fo0/clawstash
AI-optimized stash storage — dynamic RAG for agents. Store, search, and retrieve docs, code, and data on demand via MCP or REST API.
https://github.com/fo0/clawstash
ai-tools api claw-util developer-tools docker knowledge-bas mcp mcp-server model-context-protocol openclaw rag react self-hosted stash ui
Last synced: 3 months ago
JSON representation
AI-optimized stash storage — dynamic RAG for agents. Store, search, and retrieve docs, code, and data on demand via MCP or REST API.
- Host: GitHub
- URL: https://github.com/fo0/clawstash
- Owner: fo0
- License: mit
- Created: 2026-02-14T20:39:35.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-04-03T17:32:54.000Z (3 months ago)
- Last Synced: 2026-04-04T01:45:21.095Z (3 months ago)
- Topics: ai-tools, api, claw-util, developer-tools, docker, knowledge-bas, mcp, mcp-server, model-context-protocol, openclaw, rag, react, self-hosted, stash, ui
- Language: TypeScript
- Homepage:
- Size: 473 KB
- Stars: 0
- Watchers: 0
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# ClawStash
**Persistent storage for AI agents.** Store text, code, configs, and files — retrieve them via MCP or REST API.
Built for agents like [OpenClaw](https://github.com/openclaw/openclaw) that need a reliable place to save and recall information across sessions.
## Why ClawStash?
AI agents lose context between sessions. ClawStash gives them a persistent memory:
- **Store anything** — code snippets, configs, notes, multi-file projects
- **Organize with tags & metadata** — structured key-value metadata and tags for easy retrieval
- **Full-text search** — find stashes by content, name, description, or tags
- **Token-efficient** — MCP tools return summaries first, full content only on demand
- **Version history** — every change is tracked, diffable, and restorable
- **Web GUI included** — dark-themed dashboard to browse, search, and manage stashes manually
## Get Started
### 1. Let your agent do it (recommended)
Copy this into your OpenClaw agent — it installs ClawStash, creates test stashes, and sets up MCP automatically:
```
Install ClawStash (ghcr.io/fo0/clawstash) on my server and set it up as your default persistent storage via MCP. Server: , User: , Auth: . Use port (docker compose port mapping ":3000"). Set ADMIN_PASSWORD to a secure value. After install: create an API token (scopes: read, write, mcp), create 2 test stashes to verify, then fetch /api/mcp-onboarding to read the full MCP spec and configure yourself. Details: https://raw.githubusercontent.com/fo0/clawstash/main/docs/openclaw-onboarding-prompt.md
```
Replace the `<...>` placeholders with your server details — your agent handles the rest.
> Step-by-step version: [docs/openclaw-onboarding-prompt.md](docs/openclaw-onboarding-prompt.md)
### 2. Manual setup
Run this on your server — no clone needed:
```bash
mkdir clawstash && cd clawstash && cat > docker-compose.yml <<'EOF'
services:
clawstash:
image: ghcr.io/fo0/clawstash:latest
ports:
- "3000:3000"
volumes:
- ./data:/app/data
environment:
- NODE_ENV=production
- DATABASE_PATH=/app/data/clawstash.db
# - ADMIN_PASSWORD=your-secret-password
restart: unless-stopped
EOF
docker compose up -d
```
Open http://localhost:3000 — done. Database persists in `./data/`.
> Change port mapping (e.g. `"8080:3000"`) for a different port. Uncomment `ADMIN_PASSWORD` to protect the instance.
After starting, point your AI agent at the onboarding endpoint to self-configure:
```
GET http://:/api/mcp-onboarding
```
This returns all available MCP tools, schemas, and recommended workflows — your agent reads it and starts using ClawStash immediately.
## MCP Connection
Add to your MCP client config (OpenClaw, Claude Code, Cursor, etc.):
```json
{
"mcpServers": {
"clawstash": {
"type": "streamable-http",
"url": "http://:/mcp",
"headers": { "Authorization": "Bearer YOUR_TOKEN" }
}
}
}
```
Create API tokens in the web GUI under **Settings > API & Tokens** (scopes: `read`, `write`, `mcp`).
## MCP Tools
| Tool | What it does |
|------|-------------|
| `create_stash` | Store new content with files, tags, metadata |
| `read_stash` | Get stash metadata + file list (content on demand) |
| `read_stash_file` | Read a single file — most token-efficient |
| `list_stashes` | Browse all stashes with summaries |
| `search_stashes` | Full-text search with ranked results |
| `update_stash` | Update existing stash content |
| `delete_stash` | Remove a stash |
| `list_tags` | List all tags with usage counts |
| `get_tag_graph` | Explore tag relationships |
| `get_stats` | Storage statistics |
| `refresh_tools` | Get latest tool specs (for connected agents) |
| `check_version` | Check for updates |
## Documentation
| Doc | Content |
|-----|---------|
| [OpenClaw Onboarding](docs/openclaw-onboarding-prompt.md) | Copy-paste prompt for full agent-driven setup |
| [API Reference](docs/api-reference.md) | REST endpoints, examples, query parameters |
| [MCP Guide](docs/mcp.md) | MCP tools, token-efficient patterns, transport options |
| [Authentication](docs/authentication.md) | Admin login, API tokens, scopes |
| [Deployment](docs/deployment.md) | Docker, CI/CD, GHCR, production setup |
## License
[MIT](LICENSE)