# MemorylAIer

> Persistent memory infrastructure for AI agents. Store facts, query by meaning, build knowledge graphs, track behavioral lessons. BYOI architecture — you bring the LLM, we handle storage, retrieval, dedup, decay, and self-improvement. Pay per call ($0.001 write, $0.0005 read) with no subscription. Dual auth: API key or x402 USDC micropayments (zero signup). EU-hosted, GDPR-aware. PostgreSQL + pgvector with local embeddings (all-MiniLM-L6-v2, 384 dims).

Base URL: https://memorylaier.com
Auth: `Authorization: Bearer <api-key>` or x402 payment header
OpenAPI: https://memorylaier.com/v1/docs
Interactive docs: https://memorylaier.com/docs

## Getting Started

- [MCP Setup](https://github.com/janza/Agent-memory#mcp-setup): Add MemorylAIer to Claude Desktop, Cursor, or any MCP client with one JSON block
- [Quick Start](https://github.com/janza/Agent-memory#quick-start): Store and query your first fact in two cURL commands
- [Authentication](https://github.com/janza/Agent-memory#authentication): API key (Bearer token) or x402 USDC micropayments — no account needed for x402
- [AI Agent Integration Guide](https://github.com/janza/Agent-memory/blob/main/docs/ai-agent-guide.md): System prompt snippets, workflows, and anti-patterns for AI agents using MemorylAIer

## Core API

- [Store Facts](https://memorylaier.com/docs#put-items): `PUT /v1/{ns}/items` — Store up to 20 structured facts per request. Auto-dedup, entity extraction, write-gate quality scoring. $0.001/call
- [Semantic Query](https://memorylaier.com/docs#post-query): `POST /v1/{ns}/query` — Search by meaning with time-decay scoring. Supports text or raw 384-dim embeddings, category filters, temporal `as_of` queries. Set `hybrid: true` for combined vector + full-text search (RRF) — best for entity names and exact identifiers. $0.001/call
- [Sessions](https://memorylaier.com/docs#post-sessions): 24-hour ephemeral working memory. Create, read/write JSON, flush or discard. $0.001 create, $0.0005 read
- [Lessons](https://memorylaier.com/docs#put-lessons): Behavioral self-improvement. Store corrections and patterns your agent should remember. $0.001 write, $0.0005 read
- [Knowledge Graph](https://memorylaier.com/docs#put-relationships): Relationships with multi-hop traversal (BFS, up to 4 hops). Auto-extracted from stored facts. $0.001 write, $0.0005 read
- [Conversation Extraction](https://memorylaier.com/docs#post-extract): `POST /v1/{ns}/extract` — Extract facts from raw chat messages automatically. $0.001/call
- [Temporal Triggers](https://memorylaier.com/docs#put-triggers): Schedule memory surfacing at a future time with optional webhook delivery. $0.001 write
- [Entity Search](https://memorylaier.com/docs#get-entities): Find all facts and relationships about a named entity. $0.0005/call
- [Categories](https://memorylaier.com/docs#get-categories): Auto-organized fact categories with top facts per category. $0.0005/call
- [Stats & Health](https://memorylaier.com/docs#get-stats): Namespace usage statistics, memory health metrics, item counts. $0.0005/call

## SDKs & Integrations

- [MCP Server](https://www.npmjs.com/package/memorylayer): `npx memorylayer-mcp` — 25 tools for Claude Desktop, Cursor, VS Code, Windsurf, and any MCP client
- [Python SDK](https://pypi.org/project/memorylayer/): `pip install memorylayer` — Full API surface with httpx async support
- [OpenAPI Spec](https://memorylaier.com/v1/docs): Full OpenAPI 3.1.0 YAML specification for code generation
- [Interactive API Docs](https://memorylaier.com/docs): Scalar-powered interactive documentation with try-it-out

## Self-Hosting

- [Self-Hosting Guide](https://github.com/janza/Agent-memory#self-hosting): Deploy on your own infrastructure with Caddy, systemd, and PostgreSQL 16 + pgvector
- [Setup Script](https://github.com/janza/Agent-memory/blob/main/deploy/setup-vps.sh): One-shot VPS provisioning for Ubuntu 24.04
- [Environment Config](https://github.com/janza/Agent-memory/blob/main/.env.example): All configuration variables with defaults

## Reference

- [API Endpoint Table](https://github.com/janza/Agent-memory#api-endpoints): All 32 endpoints with methods, paths, rate limits, and x402 prices
- [Key Concepts](https://github.com/janza/Agent-memory#key-concepts): Items, semantic query, write gate, score decay, sessions, lessons, categories
- [Pricing](https://github.com/janza/Agent-memory#pricing): $0.001 write/search, $0.0005 read — no subscription
- [Competitive Comparison](https://github.com/janza/Agent-memory#why-memorylaier): Feature comparison vs Mem0, Zep, MemoClaw

## Optional

- [Changelog](https://github.com/janza/Agent-memory/blob/main/CHANGELOG.md): Version history
- [Contributing](https://github.com/janza/Agent-memory/blob/main/CONTRIBUTING.md): Development setup and code standards
- [Security Policy](https://github.com/janza/Agent-memory/blob/main/SECURITY.md): Vulnerability reporting and security measures
- [License](https://github.com/janza/Agent-memory/blob/main/LICENSE): Apache 2.0