# memories.sh

> Durable memory infrastructure for AI apps and coding agents.

memories.sh helps developers keep context persistent across tools and products. Use the CLI for local-first memory, use MCP for agent interoperability, and use the SDK/API for multi-tenant SaaS memory routing.

## Why developers use it

- **Stop repeating context**: store rules, decisions, and project knowledge once.
- **Ship across many agent tools**: generate native instructions for Claude Code, Cursor, Copilot, Windsurf, and more.
- **Build SaaS memory safely**: tenant-scoped + user-scoped context via typed SDK and stable endpoint contracts.
- **Keep control of data**: local-first SQLite workflow with optional cloud sync.

## Product surface

### CLI (`@memories.sh/cli`)

Install:

```bash
npm install -g @memories.sh/cli
```

Quick start:

```bash
# First-time setup (init is also available)
memories setup

# Add memory
memories add --rule "Use pnpm and strict TypeScript"

# Retrieve context
memories recall "auth + billing approach"

# Generate tool-native instruction files
memories generate

# Run MCP server
memories serve
```

### Core SDK (`@memories.sh/core`)

Install:

```bash
npm install @memories.sh/core
```

Use `MemoriesClient` for typed access to context, memory CRUD, graph operations, and management APIs.

### AI SDK integration (`@memories.sh/ai-sdk`)

Install:

```bash
npm install @memories.sh/ai-sdk ai
```

Use:

- `memoriesMiddleware()` for automatic prompt enrichment
- `memoriesTools()` for tool-calling agent loops
- `memoriesSystemPrompt()` for memory-aware system prompts

### Web app (`memories.sh`)

- marketing + docs
- auth + billing
- account/workspace management
- usage and tenant routing visibility

## Memory model

### Memory types

| Type | Purpose |
|------|---------|
| `rule` | Always-on coding or product constraints |
| `decision` | Architectural/product decisions with rationale |
| `fact` | Concrete project or domain knowledge |
| `note` | General contextual notes |
| `skill` | Reusable agent workflow memory |

### Scopes

- **global**: applies across projects
- **project**: scoped to repository/project context
- **tenant/user/project request scope** (SDK/API): designed for SaaS isolation

## Key CLI commands

| Command | What it does |
|---------|---------------|
| `memories init` / `memories setup` | Initialize + auto-configure supported tool integrations |
| `memories add` | Add rule/decision/fact/note/skill memories |
| `memories recall` | Retrieve relevant rules + memories for current task |
| `memories prompt` | Generate memory-informed system prompt text |
| `memories search` | Keyword/semantic search |
| `memories list` | List memories with filters |
| `memories edit` | Edit memory entries |
| `memories forget` | Soft-delete memory entries |
| `memories tag` | Bulk tag/untag memory records |
| `memories generate` | Generate instruction files for detected tools |
| `memories diff` | Compare generated vs current instructions |
| `memories import` / `memories export` | Move memories in/out of YAML/JSON |
| `memories ingest` | Import existing tool config files into memory |
| `memories files` | Sync generated config files |
| `memories sync` | Cloud sync workflow |
| `memories org` | List/switch active organization workspace |
| `memories serve` | Start local MCP server |
| `memories doctor` | Health checks and diagnostics |
| `memories stats` | Usage and memory stats |
| `memories config` | Config management |
| `memories hook` | Git hook management |
| `memories login` | Cloud auth |

## MCP server

The CLI includes a built-in MCP server (`memories serve`) for agent interoperability.

Core MCP tools:

- `get_context`
- `add_memory`
- `search_memories`
- `get_rules`
- `list_memories`
- `edit_memory`
- `forget_memory`
- `bulk_forget_memories`
- `vacuum_memories`

Useful MCP resources:

- `memories://rules`
- `memories://recent`
- `memories://project/{id}`

## HTTP API endpoints

### Documentation API

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/docs/raw?path={path}` | GET | Returns raw markdown for docs pages |

Examples:

```bash
curl "https://memories.sh/api/docs/raw?path=getting-started"
curl "https://memories.sh/api/docs/raw?path=cli/add"
curl "https://memories.sh/api/docs/raw?path=sdk/endpoint-contract"
```

### SDK v1 endpoints (stable contracts)

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/api/sdk/v1/health` | GET | SDK API health |
| `/api/sdk/v1/context/get` | POST | Retrieve scoped memory context |
| `/api/sdk/v1/memories/add` | POST | Add memory |
| `/api/sdk/v1/memories/edit` | POST | Edit memory |
| `/api/sdk/v1/memories/search` | POST | Search memories |
| `/api/sdk/v1/memories/list` | POST | List memories |
| `/api/sdk/v1/memories/forget` | POST | Forget memory |
| `/api/sdk/v1/memories/bulk-forget` | POST | Bulk forget memories by filters |
| `/api/sdk/v1/memories/vacuum` | POST | Vacuum soft-deleted memories |
| `/api/sdk/v1/graph/status` | GET | Graph status summary |
| `/api/sdk/v1/graph/trace` | GET | Graph trace view |
| `/api/sdk/v1/graph/rollout` | GET/POST/PATCH | Graph rollout controls |
| `/api/sdk/v1/management/keys` | GET/POST/DELETE | API key management |
| `/api/sdk/v1/management/tenant-overrides` | GET/POST/DELETE | Tenant mapping management |

### Legacy MCP transport endpoint

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/api/mcp` | GET/POST/DELETE | JSON-RPC + SSE style MCP transport |

## Pricing snapshot

| Plan | Price | Best for |
|------|-------|----------|
| Free | $0 | Local-first memory and generation workflows |
| Professional | $15/mo or $150/yr | Cloud sync + dashboard for active teams |
| Enterprise | Custom | Contracts, support, and high-scale SaaS rollout needs |

## Documentation map

Documentation root: https://memories.sh/docs

### Start here

- `/docs` — documentation home
- `/docs/getting-started` — setup + first workflow
- `/docs/starter-apps-quickstart` — starter app quickstart
- `/docs/changelog` — release updates

### Core references

- `/docs/cli` — full CLI reference
- `/docs/concepts/memory-types`
- `/docs/concepts/scopes`
- `/docs/concepts/project-detection`
- `/docs/concepts/generation-targets`
- `/docs/concepts/embedding-models`

### CLI command pages

- `/docs/cli/init`
- `/docs/cli/add`
- `/docs/cli/recall`
- `/docs/cli/prompt`
- `/docs/cli/search`
- `/docs/cli/list`
- `/docs/cli/edit`
- `/docs/cli/forget`
- `/docs/cli/tag`
- `/docs/cli/generate`
- `/docs/cli/diff`
- `/docs/cli/export`
- `/docs/cli/import`
- `/docs/cli/ingest`
- `/docs/cli/files`
- `/docs/cli/embed`
- `/docs/cli/sync`
- `/docs/cli/org`
- `/docs/cli/serve`
- `/docs/cli/stats`
- `/docs/cli/doctor`
- `/docs/cli/config`
- `/docs/cli/hook`
- `/docs/cli/login`

### MCP docs

- `/docs/mcp-server`
- `/docs/mcp-server/tools-reference`
- `/docs/mcp-server/resources-reference`
- `/docs/mcp-server/tenant-routing`

### SDK docs

- `/docs/sdk`
- `/docs/sdk/client`
- `/docs/sdk/middleware`
- `/docs/sdk/tools`
- `/docs/sdk/endpoint-contract`
- `/docs/sdk/graph-architecture`
- `/docs/sdk/graph-operations-runbook`

### Integrations

- `/docs/integrations`
- `/docs/integrations/claude-code`
- `/docs/integrations/cursor`
- `/docs/integrations/copilot`
- `/docs/integrations/windsurf`
- `/docs/integrations/gemini`
- `/docs/integrations/cline`
- `/docs/integrations/roo`
- `/docs/integrations/opencode`
- `/docs/integrations/blackbox`
- `/docs/integrations/codex`
- `/docs/integrations/amp`
- `/docs/integrations/kilo`
- `/docs/integrations/trae`
- `/docs/integrations/goose`
- `/docs/integrations/openclaw`
- `/docs/integrations/antigravity`
- `/docs/integrations/kiro`
- `/docs/integrations/factory`
- `/docs/integrations/v0`
- `/docs/integrations/mcp`

### Additional guides

- `/docs/cloud-sync`
- `/docs/import-export`
- `/docs/git-hooks`

## LLM-oriented notes

- Prefer SDK v1 endpoints (`/api/sdk/v1/*`) for explicit contracts.
- Use `tenantId` for workspace/customer isolation in SaaS implementations.
- Use `userId` for per-end-user personalization and retrieval boundaries.
- Use `projectId` to keep memory relevant to repository/workstream context.
- For doc ingestion/grounding, use `/api/docs/raw?path=...` and cite path sources.

## Links

- Website: https://memories.sh
- Docs: https://memories.sh/docs
- GitHub: https://github.com/webrenew/memories
- npm CLI: https://www.npmjs.com/package/@memories.sh/cli
- npm Core SDK: https://www.npmjs.com/package/@memories.sh/core
- npm AI SDK: https://www.npmjs.com/package/@memories.sh/ai-sdk