# Create API key
Source: https://docs.memcontext.in/api-reference/api-keys/create-api-key
/openapi.yaml post /api/api-keys
# Delete API key
Source: https://docs.memcontext.in/api-reference/api-keys/delete-api-key
/openapi.yaml delete /api/api-keys/{id}
# List API keys
Source: https://docs.memcontext.in/api-reference/api-keys/list-api-keys
/openapi.yaml get /api/api-keys
# Add a curated company fact
Source: https://docs.memcontext.in/api-reference/context-vault/add-a-curated-company-fact
/openapi.yaml post /api/context-vault/memories
Adds atomic workspace context that may not be backed by an uploaded document.
# Browse context vault memories
Source: https://docs.memcontext.in/api-reference/context-vault/browse-context-vault-memories
/openapi.yaml get /api/context-vault/memories
# Cancel context vault document processing
Source: https://docs.memcontext.in/api-reference/context-vault/cancel-context-vault-document-processing
/openapi.yaml post /api/context-vault/documents/{documentId}/cancel
# Context vault scope/project hierarchy
Source: https://docs.memcontext.in/api-reference/context-vault/context-vault-scopeproject-hierarchy
/openapi.yaml get /api/context-vault/hierarchy
# Correct a context vault memory
Source: https://docs.memcontext.in/api-reference/context-vault/correct-a-context-vault-memory
/openapi.yaml post /api/context-vault/memories/{memoryId}/correction
Applies a correction to an extracted workspace memory. When
`correctedChunkContent` is provided, the cited source chunk is updated
too so future document retrieval stays aligned with the corrected
memory.
# Delete a curated company fact
Source: https://docs.memcontext.in/api-reference/context-vault/delete-a-curated-company-fact
/openapi.yaml delete /api/context-vault/memories/{memoryId}
Soft-deletes a curated company fact. Document-extracted memories are removed through document deletion instead.
# Delete context vault document
Source: https://docs.memcontext.in/api-reference/context-vault/delete-context-vault-document
/openapi.yaml delete /api/context-vault/documents/{documentId}
Deletes the document and its citations. Extracted memories stop
appearing only when this document is their only source; memories also
supported by other documents are preserved.
# Ingest context vault document
Source: https://docs.memcontext.in/api-reference/context-vault/ingest-context-vault-document
/openapi.yaml post /api/context-vault/documents
Adds workspace knowledge from extracted text, a public file URL, or a
documentation/web URL.
Use `content` when your app already has clean text or Markdown. Use
`uri` with a file `sourceType` for public PDF, DOCX, Markdown, TXT, CSV,
or image URLs. Use `sourceType: url` for documentation sites and web
pages.
# List context vault documents
Source: https://docs.memcontext.in/api-reference/context-vault/list-context-vault-documents
/openapi.yaml get /api/context-vault/documents
# List memories extracted from one context vault document
Source: https://docs.memcontext.in/api-reference/context-vault/list-memories-extracted-from-one-context-vault-document
/openapi.yaml get /api/context-vault/documents/{documentId}/memories
# List source evidence for a context vault memory
Source: https://docs.memcontext.in/api-reference/context-vault/list-source-evidence-for-a-context-vault-memory
/openapi.yaml get /api/context-vault/memories/{memoryId}/evidence
# Search context vault
Source: https://docs.memcontext.in/api-reference/context-vault/search-context-vault
/openapi.yaml get /api/context-vault/search
Returns ranked retrieval results for workspace knowledge. The endpoint
does not synthesize a single final answer; callers should use returned
chunks, extracted memories, and evidence as grounded context for their
own answer-generation layer.
The response keeps document passages and extracted memories separate.
`documents` mode fills `chunks` and leaves `memories` empty. `memories`
mode fills `memories` and leaves `chunks` empty. `hybrid` mode can fill
both arrays without flattening them into one mixed list, so clients can
pass source chunks as document context and extracted facts as a separate
memory-context document.
# Submit feedback on a context vault memory
Source: https://docs.memcontext.in/api-reference/context-vault/submit-feedback-on-a-context-vault-memory
/openapi.yaml post /api/context-vault/memories/{memoryId}/feedback
# Upload and ingest context vault document
Source: https://docs.memcontext.in/api-reference/context-vault/upload-and-ingest-context-vault-document
/openapi.yaml post /api/context-vault/documents/upload
Uploads a local file and adds it to Context Vault. Supports PDFs,
Markdown, TXT, DOCX, CSV, and image files. OCR is available for formats
that need text extraction.
# Submit feedback for a memory
Source: https://docs.memcontext.in/api-reference/feedback/submit-feedback-for-a-memory
/openapi.yaml post /api/memories/{id}/feedback
Record whether a retrieved memory was useful, irrelevant, outdated, or wrong.
This signal can be used to improve retrieval quality over time.
# Get memory version history
Source: https://docs.memcontext.in/api-reference/history/get-memory-version-history
/openapi.yaml get /api/memories/{id}/history
Returns the current version of a memory and all previous versions in its
version chain. Use this to inspect how a memory evolved over time.
# Delete a memory
Source: https://docs.memcontext.in/api-reference/memories/delete-a-memory
/openapi.yaml delete /api/memories/{id}
Deletes a memory from future search and list results.
# Forget a memory
Source: https://docs.memcontext.in/api-reference/memories/forget-a-memory
/openapi.yaml post /api/memories/{id}/forget
Removes a memory from future search and list results.
# Get a memory by ID
Source: https://docs.memcontext.in/api-reference/memories/get-a-memory-by-id
/openapi.yaml get /api/memories/{id}
# List memories
Source: https://docs.memcontext.in/api-reference/memories/list-memories
/openapi.yaml get /api/memories
Paginated list of current (non-deleted) memories. Supports filtering
by category, project, and text search. Categories and projects accept
comma-separated values for multi-filter queries.
# Save a memory
Source: https://docs.memcontext.in/api-reference/memories/save-a-memory
/openapi.yaml post /api/memories
Save a durable preference, fact, decision, or piece of context. If
similar content already exists, MemContext may update, extend, or
deduplicate it instead of creating a separate memory.
# Search memories
Source: https://docs.memcontext.in/api-reference/memories/search-memories
/openapi.yaml get /api/memories/search
Search saved memories with a natural-language query. Use filters such
as scope, project, and category when your app needs narrower results.
# Update a memory
Source: https://docs.memcontext.in/api-reference/memories/update-a-memory
/openapi.yaml patch /api/memories/{id}
Update a memory's content, category, or project. If only metadata changes,
a simple update is performed. If content changes, the system re-runs the
classification flow against similar memories and may supersede or relate to them.
# API Reference
Source: https://docs.memcontext.in/api-reference/overview
Complete reference for the MemContext REST API.
## Base URL
```
https://api.memcontext.in
```
All endpoints are prefixed with `/api/`.
## Authentication
Every request must include an API key in the `X-API-Key` header:
```bash theme={null}
curl https://api.memcontext.in/api/memories \
-H "X-API-Key: mc_your_key"
```
API keys are created from the [MemContext dashboard](https://app.memcontext.in). See [Authentication](/authentication) for details.
## Endpoints
| Method | Path | Description |
| -------- | ------------------------------------- | -------------------------------------------------------------------------------- |
| `POST` | `/api/memories` | [Save a memory](/api-reference/endpoint/save-a-memory) |
| `GET` | `/api/memories` | [List memories](/api-reference/endpoint/list-memories) |
| `GET` | `/api/memories/search` | [Search memories](/api-reference/endpoint/search-memories) |
| `GET` | `/api/memories/profile` | [Get user profile context](/api-reference/endpoint/get-user-profile-context) |
| `GET` | `/api/memories/graph` | Memory graph data for visualization |
| `GET` | `/api/memories/{id}` | [Get a memory by ID](/api-reference/endpoint/get-a-memory-by-id) |
| `PATCH` | `/api/memories/{id}` | [Update a memory](/api-reference/endpoint/update-a-memory) |
| `DELETE` | `/api/memories/{id}` | Delete a memory |
| `POST` | `/api/memories/{id}/forget` | [Forget a memory](/api-reference/endpoint/forget-a-memory-soft-delete) |
| `GET` | `/api/memories/{id}/history` | [Get memory version history](/api-reference/endpoint/get-memory-version-history) |
| `POST` | `/api/memories/{id}/feedback` | [Submit feedback](/api-reference/endpoint/submit-feedback-for-a-memory) |
| `GET` | `/api/workspaces` | List workspaces available to the authenticated user |
| `POST` | `/api/workspaces` | Create a workspace |
| `GET` | `/api/workspaces/{id}/team` | List workspace members and pending invitations |
| `POST` | `/api/context-vault/documents` | Queue Context Vault text, URL, or remote file ingestion |
| `POST` | `/api/context-vault/documents/upload` | Upload and ingest a Context Vault file |
| `GET` | `/api/context-vault/documents` | List Context Vault documents |
| `GET` | `/api/context-vault/search` | Search Context Vault documents and extracted memories |
| `GET` | `/api/context-vault/memories` | Browse extracted and curated workspace memories |
## Response format
All successful responses return JSON. Error responses follow a consistent shape:
For `POST /api/memories`, shorter memories usually return `201` with a final save result, while larger notes may return `202 Accepted` with a `jobId` and message for tracking extraction into atomic memories.
```json theme={null}
{
"error": "Human-readable error message",
"code": "HTTP_404",
"requestId": "abc123xyz456"
}
```
Every response includes an `X-Request-Id` header for tracing.
## Rate limits
Rate-limited endpoints return the following headers:
| Header | Description |
| ----------------------- | ----------------------------------------- |
| `X-RateLimit-Limit` | Maximum requests in the current window. |
| `X-RateLimit-Remaining` | Requests remaining in the current window. |
| `X-RateLimit-Reset` | Unix timestamp when the window resets. |
See [Authentication](/authentication#rate-limits) for per-endpoint limits.
## Request limits
* Maximum request body size: **50 KB**.
* Memory content maximum length: **10,000 characters**.
* Search query maximum length: **1,000 characters**.
# Get memory graph data
Source: https://docs.memcontext.in/api-reference/profiles/get-memory-graph-data
/openapi.yaml get /api/memories/graph
Returns graph visualization data for the current memory container. The graph only
includes memories inside the selected scope. Omit `scope` to visualize only unscoped/global memories.
# Get user profile context
Source: https://docs.memcontext.in/api-reference/profiles/get-user-profile-context
/openapi.yaml get /api/memories/profile
Returns pre-aggregated user context split into static (stable preferences and facts)
and dynamic (recent context from the last 14 days). Cached for performance.
# Change workspace subscription plan
Source: https://docs.memcontext.in/api-reference/subscription/change-workspace-subscription-plan
/openapi.yaml post /api/subscription/change-plan
# Create billing portal session
Source: https://docs.memcontext.in/api-reference/subscription/create-billing-portal-session
/openapi.yaml post /api/subscription/portal
# Create workspace checkout session
Source: https://docs.memcontext.in/api-reference/subscription/create-workspace-checkout-session
/openapi.yaml post /api/subscription/checkout
# Get workspace subscription
Source: https://docs.memcontext.in/api-reference/subscription/get-workspace-subscription
/openapi.yaml get /api/subscription/current
# Accept workspace invitation
Source: https://docs.memcontext.in/api-reference/workspaces/accept-workspace-invitation
/openapi.yaml post /api/workspaces/invitations/accept
# Create workspace
Source: https://docs.memcontext.in/api-reference/workspaces/create-workspace
/openapi.yaml post /api/workspaces
# Invite workspace member
Source: https://docs.memcontext.in/api-reference/workspaces/invite-workspace-member
/openapi.yaml post /api/workspaces/{workspaceId}/invitations
# List workspace team
Source: https://docs.memcontext.in/api-reference/workspaces/list-workspace-team
/openapi.yaml get /api/workspaces/{workspaceId}/team
# List workspaces
Source: https://docs.memcontext.in/api-reference/workspaces/list-workspaces
/openapi.yaml get /api/workspaces
# Remove workspace member
Source: https://docs.memcontext.in/api-reference/workspaces/remove-workspace-member
/openapi.yaml delete /api/workspaces/{workspaceId}/members/{memberId}
# Revoke workspace invitation
Source: https://docs.memcontext.in/api-reference/workspaces/revoke-workspace-invitation
/openapi.yaml delete /api/workspaces/{workspaceId}/invitations/{invitationId}
# Update workspace member role
Source: https://docs.memcontext.in/api-reference/workspaces/update-workspace-member-role
/openapi.yaml patch /api/workspaces/{workspaceId}/members/{memberId}
# Authentication
Source: https://docs.memcontext.in/authentication
How to authenticate with the MemContext API and MCP server.
## API key authentication
All public API requests require an API key sent in the `X-API-Key` header:
```bash theme={null}
curl https://api.memcontext.in/api/memories/search?query=... \
-H "X-API-Key: mc_your_key"
```
Create API keys from the [MemContext dashboard](https://app.memcontext.in) under **Settings > API Keys**. Each key is bound to one workspace selected at creation, and API-key requests cannot override that workspace. Keys are prefixed with `mc_` and shown only once at creation - store them securely.
## MCP server authentication
The hosted MCP server at `https://mcp.memcontext.in/mcp` accepts the API key via HTTP headers. Both `MEMCONTEXT-API-KEY` and `X-API-Key` are supported:
```json theme={null}
{
"mcpServers": {
"memcontext": {
"url": "https://mcp.memcontext.in/mcp",
"headers": {
"MEMCONTEXT-API-KEY": "mc_your_key"
}
}
}
}
```
See [MCP Setup](/guides/mcp-setup) for configs specific to Claude Code, Cursor, OpenCode, and Codex CLI.
## Claude.ai / Claude Desktop connector authentication
For Claude.ai and Claude Desktop custom connectors, MemContext uses OAuth instead of manual API-key entry.
1. Open **Settings → Connectors** in Claude.
2. Add a custom connector with `https://mcp.memcontext.in/mcp`.
3. Click **Connect**.
4. Sign in to MemContext and approve the requested scopes.
This path is intended for everyday Claude usage. API-key headers and config files are only needed for coding-agent setups such as Claude Code, Cursor, OpenCode, and Codex CLI.
## Rate limits
MemContext rate-limits requests per endpoint using fixed 1-minute windows. Authenticated memory endpoint limits scale with the workspace plan:
| Plan | Save memory | Search memories | Submit feedback |
| -------- | ----------- | --------------- | --------------- |
| Free | 30/min | 60/min | 30/min |
| Hobby | 100/min | 200/min | 60/min |
| Pro | 300/min | 600/min | 120/min |
| Ultimate | 1,000/min | 2,000/min | 300/min |
API traffic may also be protected by a global abuse backstop of 3,000 requests per minute.
Rate-limited responses include headers to help you manage request timing:
| Header | Description |
| ----------------------- | ---------------------------------------------- |
| `X-RateLimit-Limit` | Maximum requests allowed in the current window |
| `X-RateLimit-Remaining` | Remaining requests in the current window |
| `X-RateLimit-Reset` | Unix timestamp when the window resets |
When the limit is exceeded, the API returns `429 Too Many Requests`.
## Error responses
All errors follow a consistent JSON format:
```json theme={null}
{
"error": "Human-readable error message",
"code": "HTTP_429",
"requestId": "abc123xyz456"
}
```
| Field | Description |
| ----------- | --------------------------------------------------------------------------------- |
| `error` | What went wrong |
| `code` | Machine-readable error code (e.g. `HTTP_401`, `HTTP_404`, `INTERNAL_ERROR`) |
| `requestId` | Unique request ID, also returned in the `X-Request-Id` response header |
| `errorId` | Unique error reference for support (only on server errors, format `ERR_XXXXXXXX`) |
Common error codes:
| Code | Status | Meaning |
| ---------------- | ------ | -------------------------------------- |
| `HTTP_401` | 401 | Missing or invalid API key |
| `HTTP_403` | 403 | Memory limit exceeded for current plan |
| `HTTP_404` | 404 | Memory not found |
| `HTTP_429` | 429 | Rate limit exceeded |
| `INTERNAL_ERROR` | 500 | Unexpected server error |
## Request limits
| Constraint | Value |
| --------------------------- | ----------------- |
| Max request body size | 50 KB |
| Max memory content length | 10,000 characters |
| Max search query length | 1,000 characters |
| Max feedback context length | 1,000 characters |
## Best practices
* Create a separate API key per integration or environment
* Keep API keys server-side - never expose them in client-side code
* Rotate keys immediately if you suspect exposure
* Use `scope` as the hard isolation boundary when one API key serves multiple app users or tenants
* Use `project` only as a secondary grouping/filter inside that scope
# Context Vault
Source: https://docs.memcontext.in/concepts/context-vault
Turn workspace documents, files, and URLs into searchable AI context.
Context Vault lets your app add company or project knowledge once, then retrieve
the right source passages and extracted facts whenever your AI system needs
context.
Use it for support bots, internal copilots, onboarding agents, sales assistants,
or any workflow where an AI system needs to answer from trusted workspace
documents.
## Why Context Vault Exists
Normal memory is best for short, durable facts like preferences, decisions, and
project context. Company knowledge is different. It usually lives in PDFs,
Markdown files, help centers, contracts, onboarding docs, tickets, and long
internal notes.
Context Vault is the AI context pipeline for that kind of knowledge. It lets you
add long-form content, turn it into searchable context, and retrieve the right
pieces when your AI application needs to answer.
Use Context Vault when you want to:
* Let a support bot answer from product documentation
* Let an internal copilot search handbooks, policies, and SOPs
* Let a legal or finance assistant retrieve exact clauses from PDFs
* Let an AI workflow combine source passages with extracted facts
Do not use Context Vault for:
* Small user preferences that should be saved as personal memories
* Temporary chat messages that do not need to be remembered
* Private tenant data unless you put each tenant in its own workspace or scope
## What You Can Add
Context Vault accepts:
* PDFs
* Markdown and text files
* DOCX files
* CSV files
* Images and scanned documents
* Public file URLs
* Documentation or website URLs
* Already extracted text or Markdown
For files that need OCR, MemContext extracts readable text automatically. For
documentation URLs, MemContext fetches clean page content that is easier to
search than raw HTML.
## How The AI Context Pipeline Works
When you add a document, MemContext prepares it for retrieval in three layers:
1. **Source document**: the original file, URL, or text stays connected to the
workspace document.
2. **Document chunks**: the content is split into meaningful sections so your AI
can receive the exact source passage it needs.
3. **Extracted memories**: important facts are saved separately as atomic
memories and linked back to the chunks they came from.
This is why Context Vault can return both the original source context and the
clean extracted knowledge. Your app can pass both to an LLM, show citations, or
let users inspect the original document.
## Add A Document With The SDK
```typescript theme={null}
import { MemContextClient } from "memcontext-sdk";
const client = new MemContextClient({
apiKey: process.env.MEMCONTEXT_API_KEY!,
});
await client.ingestContextVaultDocument({
workspaceId: "8b3b8f4c-...",
title: "Product docs",
uri: "https://docs.example.com",
sourceType: "url",
crawlSubpages: true,
});
```
Upload a local file:
```typescript theme={null}
await client.uploadContextVaultDocument({
workspaceId: "8b3b8f4c-...",
title: "Employee handbook",
file,
filename: "handbook.pdf",
sourceType: "pdf",
});
```
## Add A Document With The API
### Upload A File
Use this when your client has the file bytes.
```bash theme={null}
curl -X POST https://api.memcontext.in/api/context-vault/documents/upload \
-H "X-API-Key: mc_your_key" \
-F "workspaceId=8b3b8f4c-..." \
-F "title=Employee Handbook" \
-F "sourceType=pdf" \
-F "file=@handbook.pdf"
```
### Add A Public File URL
Use this when the file is already available at a public URL.
```bash theme={null}
curl -X POST https://api.memcontext.in/api/context-vault/documents \
-H "Content-Type: application/json" \
-H "X-API-Key: mc_your_key" \
-d '{
"workspaceId": "8b3b8f4c-...",
"title": "Security Whitepaper",
"sourceType": "pdf",
"uri": "https://example.com/security-whitepaper.pdf",
"scope": "security"
}'
```
### Add A Documentation URL
Use this for documentation sites, help centers, or public web pages.
```bash theme={null}
curl -X POST https://api.memcontext.in/api/context-vault/documents \
-H "Content-Type: application/json" \
-H "X-API-Key: mc_your_key" \
-d '{
"workspaceId": "8b3b8f4c-...",
"title": "Product Docs",
"uri": "https://docs.example.com",
"sourceType": "url",
"crawlSubpages": true,
"priorityPageLimit": 15,
"subpageTarget": ["api", "guides"]
}'
```
For docs sites that expose `llms.txt`, MemContext uses the page map to discover
and rank useful pages, then ingests only the selected priority pages.
`priorityPageLimit` defaults to `15` and is capped at `25`.
### Add Text Or Markdown Directly
Use this when your app already has clean text.
```bash theme={null}
curl -X POST https://api.memcontext.in/api/context-vault/documents \
-H "Content-Type: application/json" \
-H "X-API-Key: mc_your_key" \
-d '{
"workspaceId": "8b3b8f4c-...",
"title": "Leave Policy",
"sourceType": "markdown",
"content": "# Leave Policy\nEmployees get 18 paid leave days..."
}'
```
## Check Document Status
After a document is accepted, list documents to see its current status and
progress.
```typescript theme={null}
const docs = await client.listContextVaultDocuments("8b3b8f4c-...");
```
```bash theme={null}
curl "https://api.memcontext.in/api/context-vault/documents?workspaceId=8b3b8f4c-..." \
-H "X-API-Key: mc_your_key"
```
Common statuses are `pending`, `processing`, `retrying`, `completed`, `failed`,
and `cancelled`.
## Search Workspace Knowledge
Context Vault search has three modes:
| Mode | What it returns |
| ----------- | ------------------------------------------------- |
| `documents` | Source passages from uploaded files and URLs |
| `memories` | Extracted atomic facts with evidence |
| `hybrid` | Both document passages and extracted memory facts |
Use `documents` when your AI needs exact source text, such as contract clauses,
policy language, or troubleshooting steps.
Use `memories` when your AI needs concise facts, such as "the refund window is
14 days" or "Scope is the tenant isolation key."
Use `hybrid` for most production AI apps. It gives the model both precise source
passages and distilled facts, which usually improves answer quality and makes
citations easier to show.
```typescript theme={null}
const results = await client.searchContextVault({
workspaceId: "8b3b8f4c-...",
query: "What is the leave policy?",
mode: "hybrid",
});
```
```bash theme={null}
curl "https://api.memcontext.in/api/context-vault/search?workspaceId=8b3b8f4c-...&query=leave%20policy&mode=hybrid" \
-H "X-API-Key: mc_your_key"
```
## Response Shape
Hybrid search returns document chunks and extracted memories separately:
```json theme={null}
{
"mode": "hybrid",
"found": 2,
"chunks": [
{
"id": "chunk_...",
"sourceId": "doc_...",
"title": "Employee Handbook",
"sourceType": "pdf",
"sectionPath": "Leave Policy",
"chunkIndex": 12,
"content": "Employees receive 18 paid leave days per year...",
"relevance": 0.91
}
],
"memories": [
{
"id": "mem_...",
"content": "Employees receive 18 paid leave days per year.",
"category": "fact",
"evidence": [
{
"sourceId": "doc_...",
"chunkId": "chunk_...",
"title": "Employee Handbook",
"sectionPath": "Leave Policy",
"chunkIndex": 12,
"quote": "Employees receive 18 paid leave days per year..."
}
]
}
]
}
```
For AI answer generation, pass `chunks[]` as source-document context and
`memories[]` as a separate memory-context block. This keeps citations and
high-level facts easy to handle in your own app.
## Why Search Quality Improves
Context Vault does more than match keywords. It first gathers candidate results
from document chunks and extracted memories. For document searches, MemContext
then uses a re-ranking model on the top candidate passages, currently up to 30
candidates, so the most useful source text appears higher.
This helps with questions where the best answer is not an exact keyword match.
| Query | Good result should surface |
| ---------------------------------------------- | ------------------------------------------------------- |
| "What obligations continue after termination?" | Termination, return, payment, and confidentiality terms |
| "Is the contractor an employee?" | Independent contractor and liability sections |
| "How should I isolate tenants?" | Scope and workspace isolation guidance |
For best results, ask complete questions and include names, section numbers, or
domain terms when they matter.
## Browse Extracted Memories
List all extracted workspace memories:
```typescript theme={null}
const page = await client.listContextVaultMemories({
workspaceId: "8b3b8f4c-...",
limit: 20,
});
```
List memories from one document:
```typescript theme={null}
const extracted = await client.listContextVaultDocumentMemories(
"8b3b8f4c-...",
"document-id",
);
```
Load citations for one extracted memory:
```typescript theme={null}
const evidence = await client.listContextVaultMemoryEvidence(
"8b3b8f4c-...",
"memory-id",
);
```
## Delete Or Cancel
Cancel a document that is still running:
```typescript theme={null}
await client.cancelContextVaultDocument("document-id");
```
Delete a document:
```typescript theme={null}
await client.deleteContextVaultDocument("document-id");
```
When a document is deleted, memories that only came from that document are
removed from future retrieval. Memories supported by other documents remain
available.
## Supported Sources
Start with:
* Markdown
* TXT
* PDF
* DOCX
* CSV
* PNG, JPG/JPEG, WebP, and TIFF
* Public documentation or website URLs
XLSX, PPTX, and external workspace connectors should be added after the core
document workflow is stable.
# How It Works
Source: https://docs.memcontext.in/concepts/how-it-works
How to save, retrieve, update, and isolate memory in your app.
MemContext gives your AI system a simple memory workflow:
1. Save durable context.
2. Search for relevant context before generating an answer.
3. Use scopes to isolate users or tenants.
4. Send feedback when results are helpful or wrong.
You do not need to manage deduplication, evolving facts, or retrieval quality
yourself.
## Save Memories
Use `POST /api/memories`, the TypeScript SDK, or MCP `save_memory`.
```typescript theme={null}
await client.save({
content: "User prefers concise release notes.",
category: "preference",
scope: "user_123",
project: "docs",
});
```
MemContext returns a status that tells you what happened:
| Status | Meaning |
| ----------- | ------------------------------------------- |
| `saved` | A new memory was created |
| `updated` | A newer memory replaced an older one |
| `extended` | The memory added detail to an existing fact |
| `duplicate` | The same memory already exists |
| `accepted` | A larger note was accepted for extraction |
For large notes, use the returned `jobId` to track extraction.
## Search Memories
Search before your app generates a response or makes a decision.
```typescript theme={null}
const results = await client.search({
query: "How should release notes be written?",
scope: "user_123",
project: "docs",
});
```
Each result includes memory content, optional category/project information, and
a relevance score.
## Use Scopes For Isolation
Use `scope` as the hard boundary for your own users, tenants, accounts, or
organizations.
```typescript theme={null}
const userMemory = client.withScope("user_123");
```
Only memories saved in that scope are searched when the same scope is provided.
If you omit `scope`, MemContext searches only the unscoped memory lane.
Use `project` for grouping inside a scope:
```typescript theme={null}
const projectMemory = userMemory.withProject("supportbot");
```
## Handle Changing Information
You can save updated information without manually deleting old memories.
Example:
1. Save: `User prefers long-form LinkedIn posts.`
2. Later save: `User now prefers short hook-first LinkedIn posts.`
MemContext can return the newer memory during search while preserving history
for audit or debugging through the history endpoint.
## Use Categories
Categories help you filter and reason about memory:
| Category | Use for |
| ------------ | ---------------------------- |
| `preference` | Likes, dislikes, style rules |
| `fact` | Objective information |
| `decision` | Choices that were made |
| `context` | General background or state |
## Use Expiry For Temporary Facts
Set `validUntil` when a memory should stop being used after a specific time.
```typescript theme={null}
await client.save({
content: "Sprint demo is on Friday.",
category: "fact",
validUntil: "2026-06-05T23:59:59Z",
});
```
Expired memories are excluded from search.
## Recommended App Flow
1. Search MemContext with the current user or workspace context.
2. Add the returned memories to your AI prompt.
3. Generate the answer in your own app.
4. Save any durable new preference, fact, or decision.
5. Send feedback when retrieved memories were useful or wrong.
# Hybrid Search
Source: https://docs.memcontext.in/concepts/hybrid-search
Search memories with natural-language questions and exact terms.
Hybrid search is the default way to retrieve memories from MemContext. You ask a
normal question, and MemContext returns the most relevant saved memories.
The goal is simple: your AI should get the context it needs without your app
having to know whether the user used the exact same words when the memory was
saved.
It works well for:
* Natural-language questions
* Exact names, tools, acronyms, and project terms
* User preferences
* Decisions and facts
* Broader context gathering before generation
You do not need to choose or configure a retrieval algorithm. Start with clear
queries and add filters only when your app needs them.
## Why Hybrid Search Helps
AI memory has two common retrieval problems:
* Exact text search can miss useful memories when the wording is different.
* Semantic search can miss exact names, acronyms, product names, or short facts.
Hybrid search combines both signals. That means a query like "What package
manager should I use?" can match "User prefers pnpm for JavaScript projects",
while a query like "R2 upload" can still match exact technical terms.
For Context Vault document retrieval, MemContext also uses a re-ranking model on
the strongest candidate passages before returning results. This improves result
order when several chunks are related but only one contains the best answer.
## Basic Search
```bash theme={null}
curl "https://api.memcontext.in/api/memories/search?query=What%20package%20manager%20does%20the%20user%20prefer%3F" \
-H "X-API-Key: mc_your_key"
```
```json theme={null}
{
"found": 1,
"memories": [
{
"id": "a1b2c3d4-...",
"content": "User prefers pnpm for JavaScript projects.",
"category": "preference",
"relevance": 0.92,
"createdAt": "2026-04-11T12:00:00.000Z"
}
]
}
```
## Search A Specific User Or Tenant
Use `scope` when one API key serves multiple users, organizations, or tenants.
Use the same `scope` value when saving and searching.
```bash theme={null}
curl "https://api.memcontext.in/api/memories/search?query=What%20billing%20context%20do%20we%20know%3F&scope=user_123" \
-H "X-API-Key: mc_your_key"
```
Use `project` to narrow results inside a scope:
```bash theme={null}
curl "https://api.memcontext.in/api/memories/search?query=What%20package%20manager%20does%20this%20project%20use%3F&scope=user_123&project=memcontext" \
-H "X-API-Key: mc_your_key"
```
## Query Guidelines
* Ask full questions instead of short keyword fragments.
* Include names, tools, dates, or projects when they matter.
* Use `category` to narrow results to `preference`, `fact`, `decision`, or
`context`.
* Increase `limit` when your AI layer needs more context.
Good:
```text theme={null}
What package manager does this project use?
```
Less effective:
```text theme={null}
package manager
```
## Precision Controls
Most integrations should use the default settings. If you need more control, use
`threshold`.
| Threshold | Behavior | Use case |
| ------------- | ---------------- | ---------------------------------------- |
| `0.2` - `0.4` | Broader results | Gathering more context before generation |
| `0.6` | Default balance | Most app and assistant retrieval |
| `0.7` - `0.8` | Stricter results | Exact or high-confidence lookups |
Start with the default and tune only after testing real user queries.
## What It Can And Cannot Do
Hybrid search can:
* Find memories by meaning, even when the words differ.
* Find exact terms like company names, project names, tools, and acronyms.
* Improve over time when users submit feedback.
* Return a ranked set of memories that your app can pass to an LLM.
Hybrid search cannot:
* Answer a question from information that was never saved.
* Replace tenant isolation. Use `scope` or a workspace for isolation.
* Guarantee a final natural-language answer. It returns context so your app or
AI layer can answer with the right evidence.
# Scopes and Projects
Source: https://docs.memcontext.in/concepts/scopes-and-projects
Separate memory by customer, workspace, and project.
MemContext gives you two simple fields for organizing memory: `scope` and
`project`.
Use `scope` when your API key serves more than one user, tenant, organization, or
workspace. Use `project` when you want to group related memories inside that
scope.
For Context Vault, there are two additional fields: `workspaceId` and optional
`vaultId`. The workspace is the hard company/team/account boundary. A vault is
the shared knowledge container inside that workspace. `scope` is a hard lane
inside the selected workspace or vault. `project` is a soft grouping inside the
selected scope.
## Scope
`scope` is the isolation key. A search with one scope only returns memories saved
with that same scope.
```json theme={null}
{
"content": "User prefers concise release notes",
"category": "preference",
"scope": "user_123"
}
```
Good scope values are stable IDs from your own app, such as:
* `user_123`
* `org_acme`
* `workspace_42`
* `tenant_kakiyo`
If you omit `scope`, the memory belongs to the default area for that API key.
Named scopes are not included unless you pass that scope again during search,
update, delete, feedback, or history calls.
## Project
`project` is a filter inside the selected scope. It is useful for product areas,
repositories, support queues, or customer workspaces.
```json theme={null}
{
"content": "This project uses PNPM",
"category": "fact",
"scope": "user_123",
"project": "memcontext"
}
```
Projects are not meant for tenant isolation. If two customers must never see each
other's memories, put them in different scopes.
## Context Vault Semantics
For company knowledge bases:
| Field | Meaning | Example |
| ------------- | ----------------------------------------------------- | ------------------------------ |
| `workspaceId` | Hard company, team, customer, or tenant boundary | `acme_workspace_id` |
| `vaultId` | Optional Context Vault container inside the workspace | `engineering_vault_id` |
| `scope` | Hard lane inside the workspace | `hr`, `engineering`, `billing` |
| `project` | Soft grouping inside the scope | `onboarding`, `api-platform` |
Use `scope` when retrieving the wrong lane would be risky. Use `project` when
you only need a helpful filter or collection label.
Context Vault search also supports multi-scope retrieval with `scopes`.
```bash theme={null}
GET /api/context-vault/search?workspaceId=...&vaultId=...&query=trial&scopes=dev,billing
```
When `scopes` is provided, MemContext searches those named lanes inside the
selected workspace vault. It does not search other workspaces or vaults.
## Which Field Should I Use?
| Need | Use | Example |
| ----------------------------------- | --------- | ------------------------- |
| Separate end users | `scope` | `user_123` |
| Separate customer tenants | `scope` | `tenant_acme` |
| Separate internal workspaces | `scope` | `workspace_support` |
| Group a codebase, app, or workflow | `project` | `dashboard`, `api`, `crm` |
| Search all default memories for key | omit both | no `scope`, no `project` |
## Common Patterns
For a SaaS product:
```typescript theme={null}
await client.save({
content: "Kakiyo uses Intercom-style support workflows",
category: "fact",
scope: "customer_kakiyo",
project: "support",
});
```
For a coding assistant:
```typescript theme={null}
await client.save({
content: "The dashboard package uses Next.js",
category: "fact",
project: "memcontext",
});
```
For a multi-tenant AI app, always pass the same `scope` on save and search:
```typescript theme={null}
const customerMemory = client.withScope("customer_kakiyo");
await customerMemory.save({
content: "Kakiyo's support widget should answer in a concise tone",
category: "preference",
});
const results = await customerMemory.search({
query: "How should the support widget answer customers?",
});
```
See the [TypeScript SDK](/sdk/typescript) for full usage.
# User Profiles
Source: https://docs.memcontext.in/concepts/user-profiles
Pre-aggregated user context built from memory.
## What profiles are
Profiles are a convenience layer over memory. Instead of running multiple search calls to gather broad context, call a single endpoint:
```
GET /api/memories/profile
```
This returns a pre-aggregated snapshot of the user's knowledge base, useful for bootstrapping context at the start of a session.
## Profile sections
The response has two sections:
| Section | Contents | Source |
| --------- | ---------------------------- | ---------------------------------------------------- |
| `static` | Stable preferences and facts | Older memories with category `preference` or `fact` |
| `dynamic` | Recent context | Memories from the last 14 days across all categories |
```json theme={null}
{
"static": [
"Prefers TypeScript over JavaScript",
"Uses macOS with VS Code",
"Likes dark mode"
],
"dynamic": [
"Working on e-commerce checkout flow",
"Chose Stripe for payment processing"
]
}
```
## When to use profiles
Profiles work well for:
* **Application startup** - load broad user context in a single call
* **Personalization** - tailor content or UI based on known preferences
* **Content generation** - provide a persona or style guide derived from memory
* **Support systems** - give agents background before the user explains anything
## Profiles vs search
| | Profile | Search |
| ------------ | ---------------------------------- | ------------------------------------------- |
| **Use case** | Broad context | Specific retrieval |
| **Query** | None (returns everything relevant) | Natural language query |
| **Results** | Two arrays of strings | Ranked memory objects with relevance scores |
| **Caching** | Cached for performance | Always fresh |
Use profiles for "who is this user?" and search for "what did they decide about X?".
Profiles follow the same scope isolation rules as search and list. A scoped profile never includes memories from another scope, and an unscoped profile only includes global/unscoped memories.
## Scoping by scope and project
Pass a `scope` query parameter to build profile context from one isolated memory container only:
```
GET /api/memories/profile?scope=user_123
```
Omit `scope` to build a profile from unscoped/global memories only.
You can also add `project` to narrow the profile inside that scope:
```
GET /api/memories/profile?scope=user_123&project=memcontext
```
This returns only memories tagged with that project inside `user_123`.
# Versioning
Source: https://docs.memcontext.in/concepts/versioning
Let memory change over time without manually cleaning up old facts.
MemContext is built for information that changes.
If you save a newer fact that replaces an older one, search can return the newer
memory while keeping the previous version available through the history endpoint.
## Example
Earlier memory:
```text theme={null}
User prefers long-form LinkedIn posts.
```
Later memory:
```text theme={null}
User now prefers short hook-first LinkedIn posts.
```
When you search for the user's LinkedIn preference, MemContext should return the
newer memory. You do not need to manually delete the older statement first.
## Inspect History
Use the history endpoint when you need to see how a memory changed.
```bash theme={null}
curl https://api.memcontext.in/api/memories/a1b2c3d4-.../history \
-H "X-API-Key: mc_your_key"
```
Response:
```json theme={null}
{
"current": {
"id": "e5f6g7h8-...",
"content": "User now prefers short hook-first LinkedIn posts.",
"version": 2,
"createdAt": "2026-04-10T00:00:00Z"
},
"history": [
{
"id": "a1b2c3d4-...",
"content": "User prefers long-form LinkedIn posts.",
"version": 1,
"createdAt": "2026-03-15T00:00:00Z"
}
]
}
```
## Delete Memories
Use delete when a memory should no longer appear in search.
```bash theme={null}
curl -X DELETE https://api.memcontext.in/api/memories/a1b2c3d4-... \
-H "X-API-Key: mc_your_key"
```
Deleted memories are excluded from future retrieval.
# Access Control With Workspace, Scope, and Project
Source: https://docs.memcontext.in/context-vault/access-control
How Context Vault isolates and filters company knowledge.
Context Vault uses three levels of organization.
## Workspace
`workspaceId` is the hard tenant boundary. Use it for companies, customers,
teams, or legal entities.
Example:
* `acme`
* `globex`
* `customer_123`
## Scope
`scope` is a hard lane inside a workspace. Use it when retrieval should stay
inside a domain unless the caller explicitly asks for more scopes.
Examples:
* `hr`
* `engineering`
* `billing`
* `legal`
* `support`
If wrong cross-domain retrieval would be risky, use a scope.
## Project
`project` is a soft grouping inside a scope. Use it for initiatives,
collections, products, or document groups.
Examples:
* `onboarding`
* `api-platform`
* `q3-pricing`
* `refund-policy`
If the field is mainly for filtering or organization, use a project.
## Multi-scope retrieval
Use `scopes=hr,legal` when a query should search more than one hard lane. This
is useful for answers that need policy plus legal context, or support plus
billing context.
Multi-scope search never crosses workspace boundaries.
# Building a Company Knowledge Base
Source: https://docs.memcontext.in/context-vault/building-company-knowledge-base
Recommended patterns for production Context Vault deployments.
Start by modeling the knowledge boundary before uploading documents.
## Recommended setup
1. Create one workspace per company, customer, or tenant.
2. Pick scopes for hard knowledge lanes.
3. Pick projects for document collections inside those scopes.
4. Ingest documents with consistent scope and project values.
5. Add curated company facts for important context that is not documented yet.
6. Search with `hybrid` mode while evaluating retrieval quality.
7. Show evidence citations and curated-fact provenance in your product UI.
8. Let users submit feedback and corrections.
## Example model
| Workspace | Scope | Project | Documents |
| --------- | ------------- | -------------- | ----------------------- |
| `acme` | `hr` | `onboarding` | handbook, benefits, PTO |
| `acme` | `engineering` | `api-platform` | API docs, runbooks |
| `acme` | `billing` | `pricing` | plans, trials, refunds |
| `acme` | `support` | `playbooks` | escalation guides |
## Retrieval pattern
Use `hybrid` mode for most assistant experiences. Pass source chunks and
extracted memories into your answer-generation layer as separate context blocks.
Curated company facts should be passed as workspace-approved context and labeled
separately from document citations.
Use `documents` mode when the answer needs source wording. Use `memories` mode
when the answer needs short extracted facts or curated company context.
## Correction pattern
When a user flags a retrieved memory as wrong, ask for:
* the corrected memory text
* the reason for correction
* whether the source chunk should also be updated
Send the correction endpoint with `correctedChunkContent` when the cited chunk
should be updated too.
# Document Ingestion
Source: https://docs.memcontext.in/context-vault/document-ingestion
Upload or queue documents for Context Vault processing.
Use `POST /api/context-vault/documents` for text, Markdown, public URLs, and
remote file URLs. Use `POST /api/context-vault/documents/upload` when the client
has a local file.
## Supported sources
* Plain text and Markdown
* HTML and documentation URLs
* CSV
* PDF
* DOCX
* Images such as PNG, JPG, WebP, and TIFF
Text-like sources are decoded directly. PDFs, DOCX files, and images can be
stored and processed through OCR. Documentation URLs can be crawled when
`crawlSubpages` is enabled.
## Documentation URLs
For documentation sites, MemContext works best when the site exposes an
`llms.txt` file, such as `https://docs.example.com/llms.txt`.
When you submit a documentation URL with `crawlSubpages: true`, MemContext first
checks for a docs index like `llms.txt`, discovers the listed pages, ranks the
most useful pages, and ingests only the selected priority pages. This keeps the
surface area smaller while giving retrieval more relevant context.
If you want a URL to be scraped well, make sure the documentation URL is public,
uses normal HTTP/HTTPS links, and exposes a clean `llms.txt` page map whenever
possible.
## Processing lifecycle
1. The API validates workspace membership.
2. The document is queued as a source.
3. The processor resolves the source content.
4. Content is normalized and split into chunks.
5. Chunk embeddings are generated.
6. Atomic memories are extracted from each chunk.
7. Evidence links each memory to its source chunk.
The ingest endpoint returns `202 Accepted`; processing continues in the
background.
## Document limits
Context Vault document limits are enforced at the workspace subscription level.
If an invited admin or member uploads a document, it still counts against that
workspace's document allowance.
## Scope and project on ingestion
Set `scope` when the document should only appear in a specific hard lane, such
as `hr`, `engineering`, or `billing`.
Set `project` when the document is part of a softer collection inside that
scope, such as `onboarding`, `api-platform`, or `q3-invoices`.
# Evidence and Citations
Source: https://docs.memcontext.in/context-vault/evidence-citations
Load source chunks behind extracted memories.
Each extracted Context Vault memory can have one or more evidence rows. Evidence
links the memory to the document source and chunk it came from.
Use `GET /api/context-vault/memories/{memoryId}/evidence` to load citations.
```bash theme={null}
curl "https://api.memcontext.in/api/context-vault/memories/MEMORY_ID/evidence?workspaceId=WORKSPACE_ID" \
-H "X-API-Key: $MEMCONTEXT_API_KEY"
```
Evidence includes:
* `sourceId`
* `chunkId`
* `chunkIndex`
* `sectionPath`
* `pageNumber`
* source chunk `content`
* extraction `quote`
* `confidence`
Use evidence to show citations in your UI, inspect the original passage, and
decide whether a correction should update only the extracted memory or also the
source chunk.
# Context Vault Feedback
Source: https://docs.memcontext.in/context-vault/feedback
Rate and correct extracted workspace memories.
Feedback gives your application a way to record whether a retrieved memory was
useful.
Use `POST /api/context-vault/memories/{memoryId}/feedback` for lightweight
signals:
* `helpful`
* `not_helpful`
* `outdated`
* `wrong`
Use `POST /api/context-vault/memories/{memoryId}/correction` when the caller
knows the corrected content.
## Correction workflow
Corrections update the memory itself. For document-backed memories, if
`correctedChunkContent` is provided, the cited source chunk is updated as well
so future document retrieval does not drift away from the corrected memory. For
curated company facts, there is no source chunk, so the correction updates only
the company fact.
```bash theme={null}
curl -X POST "https://api.memcontext.in/api/context-vault/memories/MEMORY_ID/correction" \
-H "X-API-Key: $MEMCONTEXT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workspaceId": "WORKSPACE_ID",
"type": "wrong",
"reason": "The trial period changed after the latest pricing update.",
"correctedContent": "The free trial lasts 30 days.",
"correctedChunkContent": "The free trial lasts 30 days."
}'
```
Viewers can submit regular feedback but cannot directly correct workspace
memories. Correction is available to owners, admins, and members.
Use `DELETE /api/context-vault/memories/{memoryId}?workspaceId=...` to remove a
curated company fact. Document-extracted memories are cleaned up through document
deletion when they are no longer backed by any source document.
# Context Vault Overview
Source: https://docs.memcontext.in/context-vault/overview
Workspace document memory for shared company knowledge.
Context Vault is MemContext's workspace knowledge system. It stores shared
company documents separately from personal assistant memory, extracts durable
facts from those documents, keeps citations back to the original source chunks,
and lets teams add curated company facts that may not be documented yet.
Use Context Vault when your application needs a shared knowledge base for a
team, customer, department, or organization. Use personal memory when the
knowledge belongs to one user or assistant.
The API path, product surface, and docs use the Context Vault name:
`/api/context-vault/...`.
## Core model
* `workspaceId` is the hard team boundary.
* `scope` is a hard lane inside a workspace, such as `hr`, `engineering`, or
`billing`.
* `project` is a soft grouping inside a scope, such as `onboarding`,
`api-platform`, or `q3-pricing`.
* Documents are stored as `memory_sources`.
* Source passages are stored as `memory_source_chunks`.
* Extracted company facts are stored as document memories.
* Curated company facts are stored as company memories.
* Citations are stored through `memory_evidence`.
## Main capabilities
* Upload PDFs, DOCX files, images, CSV, Markdown, HTML, and text.
* Ingest public file URLs and documentation URLs.
* Search source chunks, extracted memories, or both.
* Add atomic company facts for important context that is not in a document yet.
* Browse extracted memories by workspace, scope, and project.
* Submit feedback and corrections.
* Load evidence chunks for any extracted memory.
Context Vault does not synthesize a final answer by itself. The search endpoint
returns ranked chunks, document memories, and curated company facts so your
application can build its own grounded answer layer.
# Context Vault Search
Source: https://docs.memcontext.in/context-vault/search
Search source chunks, extracted memories, or both.
Use `GET /api/context-vault/search` to retrieve Context Vault knowledge.
Search supports three modes:
| Mode | Returns |
| ----------- | --------------------------------------------------------------------- |
| `documents` | Source chunks from ingested documents |
| `memories` | Extracted document memories and curated company facts |
| `hybrid` | Source chunks, extracted document memories, and curated company facts |
The endpoint returns retrieval context, not a generated final answer.
Document memories include evidence when they were extracted from uploaded or
scraped sources. Curated company facts can return with `evidence: []`; treat
them as workspace-approved context rather than document-backed citations.
## Single-scope search
```bash theme={null}
curl "https://api.memcontext.in/api/context-vault/search?workspaceId=WORKSPACE_ID&query=leave%20policy&scope=hr&mode=hybrid" \
-H "X-API-Key: $MEMCONTEXT_API_KEY"
```
## Multi-scope search
Use `scopes` when the answer should come from two or more hard lanes.
```bash theme={null}
curl "https://api.memcontext.in/api/context-vault/search?workspaceId=WORKSPACE_ID&query=trial%20and%20billing&scopes=dev,billing&mode=hybrid" \
-H "X-API-Key: $MEMCONTEXT_API_KEY"
```
When `scopes` is provided, it takes precedence over `scope`. Results are still
limited to the same workspace.
## Project filter
Use `project` to narrow results inside the selected scope or scopes.
```bash theme={null}
curl "https://api.memcontext.in/api/context-vault/search?workspaceId=WORKSPACE_ID&query=refunds&scopes=billing,support&project=q3-policy" \
-H "X-API-Key: $MEMCONTEXT_API_KEY"
```
# Workspace and Vault Model
Source: https://docs.memcontext.in/context-vault/workspace-model
How MemContext organizes team memory, billing, and shared knowledge.
A workspace is the top-level team, billing, and memory-pool boundary. A vault is
the shared Context Vault container inside a workspace.
```txt theme={null}
Workspace
members
billing/subscription
member memories
vaults
documents
shared company/document memories
```
`workspace_id` always identifies the team/account boundary. `vault_id` identifies
a Context Vault inside that workspace.
In the dashboard, create workspaces, invite teammates, and manage billing owners
from **Settings → Workspaces**. Context Vault is focused on selecting a workspace,
adding knowledge, browsing documents, and searching vault content.
## Roles
| Role | Can search | Can ingest | Can correct | Can invite | Can manage members |
| -------- | ---------- | ---------- | ----------- | ---------- | ------------------------- |
| `owner` | Yes | Yes | Yes | Yes | Yes |
| `admin` | Yes | Yes | Yes | Yes | Yes, except owners/admins |
| `member` | Yes | Yes | Yes | No | No |
| `viewer` | Yes | No | No | No | No |
Workspace creators become `owner`. Invitations can assign `admin`, `member`, or
`viewer`; `owner` is not an invitable role. Invitations are emailed to the
teammate and do not create membership until that user accepts the invite from
the same email address.
## Billing owner
Each workspace has one billing owner. By default, the billing owner is the user
who created the workspace.
The workspace subscription controls the workspace memory pool and Context Vault
allowances. Invited admins and members can upload documents when their role
allows it, but usage is charged to the workspace, not to the uploader's personal
account.
Only workspace owners can change billing state such as checkout, cancellation,
or plan changes. Admins can view usage and billing status.
## Member memories
Member memories are saved inside the selected workspace and belong to the user
who created them.
```txt theme={null}
workspace_id = selected workspace
vault_id = null
user_id = current user
memory_type = member
```
Normal REST, SDK, API-key, OAuth, and MCP memory calls only search the caller's
own member memories within the selected workspace, even for workspace owners and
admins. Workspace-wide member-memory visibility is reserved for
dashboard-specific owner/admin surfaces. Update and delete operations remain
owner-scoped, and viewers cannot create, update, or delete member memories.
## Vault memories
Context Vault knowledge is saved inside a vault.
```txt theme={null}
workspace_id = selected workspace
vault_id = selected or default vault
memory_type = document | company
```
If a workspace has one default vault, dashboard and API flows can resolve it
automatically. If a workspace has multiple vaults, callers should select the
vault they want to search or ingest into.
## API keys
API keys are bound to one workspace. Existing keys are assigned to the user's
default workspace during migration. The dashboard prompts for a workspace when
creating keys; API calls that omit `workspaceId` use the user's default
workspace.
MCP and API-key calls resolve the workspace from the key, so normal memory tools
do not need a `workspaceId` parameter. Context Vault REST endpoints still accept
`workspaceId` for session callers; API-key callers must omit it or pass the same
workspace bound to the key.
## Workspace isolation
Every member memory, vault document, chunk, citation, feedback item, and
correction is checked against `workspace_id`. Vault retrieval additionally
checks `vault_id`. A query for one workspace never returns another workspace's
knowledge.
Use separate workspaces when the data belongs to different companies, customers,
tenants, or legal entities.
# Building With MemContext
Source: https://docs.memcontext.in/guides/building-with-memcontext
How to integrate MemContext as a memory backend for your application.
## Mental model
MemContext is the memory layer for your AI product. Your app sends durable
context to MemContext, then retrieves relevant context before generation.
Your application does not need to manage retrieval logic, duplicate memories, or
memory updates manually.
## Integration pattern
A typical integration follows four steps:
1. **Save** durable user or project context via `POST /api/memories`
2. **Search** before generation or decision-making via `GET /api/memories/search`
3. **Profile** (optional) - fetch broad context in one call via `GET /api/memories/profile`
4. **Feedback** - record retrieval quality via `POST /api/memories/:id/feedback`
For larger notes, `POST /api/memories` may return `202 Accepted`. This means extraction has started and can be tracked with the returned `jobId`.
For multi-user applications, always pass a stable end-user or tenant ID in `scope`. `project` remains a secondary grouping field inside that scope.
## Example: Support bot
```
User: "I'm having trouble with my subscription"
Bot workflow:
1. search_memory({ query: "user subscription plan and billing" })
→ finds: "User is on the Pro plan, subscribed via Stripe"
→ finds: "User had a billing issue resolved on March 15"
2. Generate response with memory context injected into prompt
3. memory_feedback({ memoryId: "...", type: "helpful" })
```
## Good fit use cases
| Use case | Memory role |
| ------------------ | ----------------------------------------------------------- |
| Coding assistants | Stable preferences, project decisions, architecture context |
| Content generation | Brand rules, evolving strategy, audience insights |
| Support bots | Customer history, past issues, plan details |
| CRM memory | Relationship context, interaction history |
| Onboarding | User progress, preferences learned during setup |
| Personalization | Style preferences, feature usage patterns |
## Ownership boundary
Keep your application logic outside MemContext.
**MemContext owns:**
* Saving and retrieving memory
* Handling duplicates and updates
* Memory history
* Expiry and temporal filtering
* MCP tool access
**Your application owns:**
* Business-specific prompts and logic
* UI and user experience
* Workflow orchestration
* Downstream actions and integrations
## API integration example
```typescript theme={null}
const MEMCONTEXT_API = "https://api.memcontext.in";
async function searchMemory(query: string, scope: string, project?: string) {
const params = new URLSearchParams({ query });
params.set("scope", scope);
if (project) params.set("project", project);
const res = await fetch(`${MEMCONTEXT_API}/api/memories/search?${params}`, {
headers: { "X-API-Key": process.env.MEMCONTEXT_API_KEY },
});
return res.json();
}
async function saveMemory(
content: string,
category: string,
scope: string,
project?: string,
) {
const res = await fetch(`${MEMCONTEXT_API}/api/memories`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": process.env.MEMCONTEXT_API_KEY,
},
body: JSON.stringify({ content, category, scope, project }),
});
return res.json();
}
```
If you submit a long note or transcript, check the returned `status`:
* `saved`, `updated`, `extended`, `duplicate` → final synchronous result
* `accepted` → asynchronous extraction in progress
## TypeScript SDK example
Install the SDK:
```bash theme={null}
npm install memcontext-sdk
```
```typescript theme={null}
import { MemContextClient } from "memcontext-sdk";
const client = new MemContextClient({
apiKey: process.env.MEMCONTEXT_API_KEY!,
scope: "user_123",
project: "memcontext",
});
const profile = await client.profile();
await client.save({
content: "User prefers TypeScript over JavaScript for type safety",
category: "preference",
});
const results = await client.search({
query: "What language does the user prefer?",
});
```
## Tips
* **Search before saving** - avoid duplicates by checking if the knowledge already exists
* **Use scope** for hard per-user or per-tenant isolation
* **Use projects** only to group memories inside that scope
* **Category matters** - `preference` and `fact` go into profile `static` context; everything goes into `dynamic`
* **Do not save noise** - only persist information with long-term value
# Evolving Memory
Source: https://docs.memcontext.in/guides/evolving-memory
How to model time-sensitive knowledge that changes over time.
## The pattern
Use evolving memory when facts can change over time and you need both the current truth and historical trail.
Good candidates:
* Content strategy (what is working right now)
* Active product priorities
* Temporary experiments and their outcomes
* Current customer state or lifecycle stage
## Example: LinkedIn content strategy
A LinkedIn post generator that adapts to changing strategy:
**Step 1 - Save initial strategy:**
```bash theme={null}
curl -X POST https://api.memcontext.in/api/memories \
-H "Content-Type: application/json" \
-H "X-API-Key: mc_your_key" \
-d '{
"content": "Long-form LinkedIn posts with personal stories are performing best right now",
"category": "fact",
"scope": "user_123",
"project": "linkedin-generator"
}'
```
**Step 2 - Strategy evolves, save new memory:**
```bash theme={null}
curl -X POST https://api.memcontext.in/api/memories \
-H "Content-Type: application/json" \
-H "X-API-Key: mc_your_key" \
-d '{
"content": "Short hook-first posts are now outperforming long-form content on LinkedIn",
"category": "fact",
"scope": "user_123",
"project": "linkedin-generator"
}'
```
MemContext automatically classifies the second memory as an **update** to the first, creating a version chain. Search now returns only the current truth.
**Step 3 - Save a lesson:**
```bash theme={null}
curl -X POST https://api.memcontext.in/api/memories \
-H "Content-Type: application/json" \
-H "X-API-Key: mc_your_key" \
-d '{
"content": "Posts with a question hook in the first line get 3x more engagement",
"category": "decision",
"scope": "user_123",
"project": "linkedin-generator"
}'
```
## Temporal awareness - automatic and explicit
MemContext automatically detects time-sensitive content during save. For example:
* "LinkedIn algorithm favors short posts right now" → auto-classified as medium-term, expires in 30 days
* "Meeting with client tomorrow at 3pm" → auto-classified as short-term, expires in 7 days
* "User prefers TypeScript" → auto-classified as permanent, no expiry
You can also explicitly set `validUntil` to override the auto-detection:
```json theme={null}
{
"content": "Running a 2-week A/B test on carousel vs single-image posts",
"category": "context",
"scope": "user_123",
"project": "linkedin-generator",
"validUntil": "2026-04-25T00:00:00Z"
}
```
Use the same `scope` for all memories that belong to the same end user or tenant. The `project` groups the LinkedIn generator context inside that isolated lane.
If you pass `validUntil`, auto-detection is skipped entirely. After April 25, this memory will not appear in search results.
## Recommended flow
1. Save current working strategy as a `fact` or `decision`
2. Generate content by combining profile context and search results
3. Observe outcomes
4. Save lessons as new memories (`decision` or `context`)
5. Submit feedback on memories that were useful or stale
6. When strategy changes, save a new memory - the system handles supersession automatically
## Feedback-driven ranking
When you use `memory_feedback` to mark memories as helpful, outdated, or wrong, search results are re-ranked accordingly:
* "Wrong" memories are pushed to the bottom (0.3x score)
* "Outdated" memories are demoted (0.5x score)
* "Helpful" memories get a small boost (1.1x score)
This means the system learns from your explicit signals over time.
## Why this works
You do not need fine-tuning or retraining for this class of problem. You need:
* Current truth (served by `isCurrent` filtering)
* Auto-expiry of temporal content (auto-TTL classification)
* Historical trail (accessible via the history endpoint)
* Retrieval that handles both semantic and exact-match queries (hybrid search)
* A feedback loop that directly affects ranking (via `memory_feedback`)
# MCP Setup
Source: https://docs.memcontext.in/guides/mcp-setup
Connect MemContext to Claude.ai, Claude Desktop, or your AI coding assistant.
MemContext provides a hosted MCP server. You can connect it directly to Claude.ai or Claude Desktop with OAuth, or use an API key for coding agents like Claude Code, Cursor, OpenCode, and Codex CLI.
## Prerequisites
* A MemContext account at [app.memcontext.in](https://app.memcontext.in)
* An API key if you are connecting a coding agent (create one under **Settings > API Keys**)
The [MCP page](https://app.memcontext.in/mcp) in your dashboard generates
ready-to-paste configs with your API key pre-filled.
## Claude.ai & Claude Desktop
Use this path when you want everyday Claude conversations to remember preferences, project context, and recurring details without editing config files.
**Step 1 - Open Connectors**
In Claude.ai or Claude Desktop, open **Settings → Connectors**.
**Step 2 - Add a custom connector**
Choose **Add custom connector**.
**Step 3 - Enter the production URL**
Use:
```text theme={null}
https://mcp.memcontext.in/mcp
```
**Step 4 - Connect and approve access**
Click **Connect**, sign in to MemContext if prompted, then approve the requested scopes on the consent screen.
### Recommended instructions
Paste this into **Claude → Settings → Profile → Instructions for Claude**:
```text theme={null}
- Search MemContext before assuming my preferences, projects, or past decisions.
- Save only stable preferences, recurring facts, and useful project context.
- Do not save one-off questions, random searches, or temporary details unless I ask you to remember them.
- Keep memory updates brief, accurate, and practical.
```
Claude.ai and Claude Desktop use OAuth for this flow. You do not need to paste
API keys, headers, or config files.
## Claude Code
**Step 1 - Add the MCP server via CLI:**
```bash theme={null}
claude mcp add memcontext --scope user --transport http https://mcp.memcontext.in/mcp \
--header "MEMCONTEXT-API-KEY:mc_your_key"
```
Or add this to `~/.claude.json`:
```json theme={null}
{
"mcpServers": {
"memcontext": {
"url": "https://mcp.memcontext.in/mcp",
"headers": {
"MEMCONTEXT-API-KEY": "mc_your_key"
}
}
}
}
```
**Step 2 - Add agent instructions to `~/.claude/CLAUDE.md`:**
```markdown theme={null}
# MemContext
At conversation start, ALWAYS call search_memory to load user context - do not skip.
Before making decisions or assumptions, search_memory to check for past context.
SAVE immediately (do not defer) when any of these happen:
- User shares a preference → save_memory(category: "preference")
- A technology or architecture decision is made → save_memory(category: "decision")
- User corrects you or says "remember" → save_memory(category: "fact")
- Important project fact learned → save_memory(category: "fact", project: "")
- Significant work completed → save_memory(category: "context")
- MCP tools do not accept scope. Use the REST API or TypeScript SDK when an app needs hard per-user or per-tenant isolation.
- Use project only when a clear project/app name is already known. Good: "memcontext", "carq". Omit if unsure. Never invent vague names like "123" or "abc".
- MCP memories use automatic TTL. Use the REST API, TypeScript SDK, or dashboard when exact expiry is required.
- After using search results, call memory_feedback to rate memories as helpful/not_helpful/outdated/wrong.
- If a retrieved memory is wrong or outdated and you know the corrected fact, call update_memory with the corrected content. Feedback alone only changes retrieval ranking; update_memory changes the saved memory.
- Use delete_memory only when a memory was saved incorrectly and should be removed entirely.
- Duplicates are handled automatically - when in doubt, save.
- Memory persists across all sessions. Use project only for known project-specific context.
```
## Cursor
**Step 1 - Add this to `~/.cursor/mcp.json`:**
```json theme={null}
{
"mcpServers": {
"memcontext": {
"url": "https://mcp.memcontext.in/mcp",
"headers": {
"x-api-key": "mc_your_key"
}
}
}
}
```
**Step 2 - Add the [agent instructions](#agent-instructions) to Cursor Settings > Rules and commands > User Rules.**
## OpenCode
**Step 1 - Add the MCP server to `~/.config/opencode/opencode.json`:**
```json theme={null}
{
"mcp": {
"memcontext": {
"type": "local",
"command": [
"npx",
"-y",
"mcp-remote",
"https://mcp.memcontext.in/mcp",
"--header",
"MEMCONTEXT-API-KEY:mc_your_key"
],
"enabled": true
}
}
}
```
**Step 2 - Add the [agent instructions](#agent-instructions) to `~/.config/opencode/AGENTS.md`.**
## Codex CLI
**Step 1 - Add the MCP server to `~/.codex/config.toml`:**
```toml theme={null}
[mcp_servers.memcontext]
url = "https://mcp.memcontext.in/mcp"
[mcp_servers.memcontext.http_headers]
MEMCONTEXT-API-KEY = "mc_your_key"
```
**Step 2 - Add the [agent instructions](#agent-instructions) to `~/.codex/instructions.md`.**
## Agent instructions
These instructions tell your AI assistant how and when to use MemContext. Add them to the preferences file for your client (listed above):
```markdown theme={null}
# MemContext
At conversation start, ALWAYS call search_memory to load user context - do not skip.
Before making decisions or assumptions, search_memory to check for past context.
SAVE immediately (do not defer) when any of these happen:
- User shares a preference → save_memory(category: "preference")
- A technology or architecture decision is made → save_memory(category: "decision")
- User corrects you or says "remember" → save_memory(category: "fact")
- Important project fact learned → save_memory(category: "fact", project: "")
- Significant work completed → save_memory(category: "context")
- MCP tools do not accept scope. Use the REST API or TypeScript SDK when an app needs hard per-user or per-tenant isolation.
- Use project only when a clear project/app name is already known. Good: "memcontext", "carq". Omit if unsure. Never invent vague names like "123" or "abc".
- MCP memories use automatic TTL. Use the REST API, TypeScript SDK, or dashboard when exact expiry is required.
- After using search results, call memory_feedback to rate memories as helpful/not_helpful/outdated/wrong.
- If a retrieved memory is wrong or outdated and you know the corrected fact, call update_memory with the corrected content. Feedback alone only changes retrieval ranking; update_memory changes the saved memory.
- Use delete_memory only when a memory was saved incorrectly and should be removed entirely.
- Duplicates are handled automatically - when in doubt, save.
- Memory persists across all sessions. Use project only for known project-specific context.
```
| Client | Preferences file |
| ----------- | ------------------------------------------------- |
| Claude Code | `~/.claude/CLAUDE.md` |
| Cursor | Cursor Settings > Rules and commands > User Rules |
| OpenCode | `~/.config/opencode/AGENTS.md` |
| Codex CLI | `~/.codex/instructions.md` |
## Available tools
Once connected, your assistant has access to five tools:
| Tool | Purpose |
| ----------------- | -------------------------------------------------- |
| `save_memory` | Persist preferences, facts, decisions, and context |
| `search_memory` | Find relevant memories before responding |
| `memory_feedback` | Rate memory quality after retrieval |
| `update_memory` | Correct or refine an existing saved memory |
| `delete_memory` | Remove a memory by ID |
See the [MCP Tools](/mcp/overview) section for parameter documentation.
## Verifying the connection
After setup, ask Claude or your coding assistant:
> "Search your memory for any information about me."
If the connection is working, it will call `search_memory` and return results (or an empty set if no memories exist yet).
# Introduction
Source: https://docs.memcontext.in/index
MemContext is a memory layer for AI systems that need persistent, evolving, and retrievable context.
## What is MemContext?
MemContext is memory infrastructure for AI agents and applications.
It provides a REST API and MCP server that allow AI systems to:
* **Save** durable user and project knowledge across sessions
* **Isolate** app users and tenants with hard memory containers via `scope`
* **Search** memories with natural-language questions and exact terms
* **Evolve** memories over time with automatic version chains
* **Profile** users with pre-aggregated context from their memory
* **Ingest** workspace documents through Context Vault for RAG-style AI context
## Who is it for?
MemContext serves three primary use cases:
1. **Coding assistants** that need stable preferences, decisions, and project context across sessions
2. **Product applications** that need evolving memory for content generation, support, onboarding, or personalization
3. **Workspace AI tools** that need to retrieve source passages and extracted facts from files, docs, and URLs
## The Three Retrieval Modes
MemContext supports three ways to retrieve context:
| Mode | Use it for | Returns |
| -------------------- | ----------------------------------------- | --------------------------------- |
| **Memories** | Durable facts, preferences, and decisions | Atomic memories |
| **Document chunks** | RAG over PDFs, Markdown, docs, and URLs | Source passages with citations |
| **Hybrid workspace** | Production AI tools that need both | Document chunks plus memory facts |
This gives your app a clear choice. Use memories when you need concise facts.
Use document chunks when you need source text. Use hybrid when you want the AI
layer to receive both precise passages and clean extracted knowledge.
## Core primitives
| Concept | Description |
| ------------------ | ---------------------------------------------------------------------------- |
| **Scope** | Hard isolation boundary for app users or tenants (e.g. `user_123`) |
| **Category** | Broad memory type: `preference`, `fact`, `decision`, or `context` |
| **Project** | Soft grouping/filter inside the selected scope or default memory area |
| **Version chains** | Memories can supersede old memories without losing history |
| **Hybrid search** | Natural-language search that also handles exact names, tools, and decisions |
| **MCP tools** | AI assistants can save and search memory directly via Model Context Protocol |
## Why it exists
Simple retrieval is not enough for memory. Memory needs:
* **Updates** when reality changes
* **History** when strategy evolves
* **Exact-match retrieval** for product names, org names, and decisions
* **Lightweight APIs** other tools can build on
## Next steps
Make your first API and MCP calls in under 2 minutes.
Understand how MemContext saves, updates, and retrieves memory.
Full endpoint documentation with interactive examples.
Connect MemContext to Claude Desktop, Cursor, or any MCP client.
# delete_memory
Source: https://docs.memcontext.in/mcp/delete-memory
Remove a memory by ID.
## Description
`delete_memory` removes a memory from future search results. In most cases, you
do not need to call this directly. When new information replaces old
information, save the new memory and MemContext can handle the update.
## Parameters
| Parameter | Type | Required | Description |
| ---------- | ------ | -------- | ------------------------------------------------------------------ |
| `memoryId` | string | Yes | The memory ID to delete. Use the `id` returned by `search_memory`. |
## Example
```
delete_memory({
memoryId: "a1b2c3d4-..."
})
```
## Response
Returns `{ success: true }` on success, or a `404` error if the memory was not
found. Deleted memories stop appearing in search and list results.
# memory_feedback
Source: https://docs.memcontext.in/mcp/memory-feedback
Rate a retrieved memory to improve future retrieval quality.
## Description
`memory_feedback` records whether a retrieved memory was useful, irrelevant, outdated, or wrong. **This feedback directly affects search ranking** - memories marked "wrong" are heavily penalized (0.3x score), "outdated" moderately (0.5x), while "helpful" gets a small boost (1.1x).
Feedback does not edit memory content. If the memory is wrong or outdated and
you know the corrected fact, call [`update_memory`](/mcp/update-memory) with the
corrected content after recording feedback.
## Parameters
| Parameter | Type | Required | Description |
| ---------- | ------ | -------- | ----------------------------------------------------------------------------------- |
| `memoryId` | string | Yes | The memory ID to rate. Use the `id` returned by `search_memory`. |
| `type` | string | Yes | Feedback type. One of the values below. |
| `context` | string | No | Optional explanation of why this feedback is being submitted. Max 1,000 characters. |
### Feedback types
| Type | When to use |
| ------------- | ------------------------------------------------------------ |
| `helpful` | The memory was relevant and useful in the current context |
| `not_helpful` | The memory was irrelevant to the current query |
| `outdated` | The memory contains stale information that is no longer true |
| `wrong` | The memory contains incorrect information |
## Example
```
memory_feedback({
memoryId: "a1b2c3d4-...",
type: "outdated",
context: "User switched from Redux to Zustand last week"
})
```
## Response
Returns `{ success: true }` on success, or a `404` error if the memory was not found.
# MCP Overview
Source: https://docs.memcontext.in/mcp/overview
Hosted MCP server that gives AI assistants persistent memory.
## What is it?
MemContext provides a hosted MCP server that gives AI assistants persistent memory through the [Model Context Protocol](https://modelcontextprotocol.io). No local installation or infrastructure required.
The server handles input validation, project name normalization, and response formatting for assistant consumption. All business logic - deduplication, classification, hybrid search - runs in the MemContext API.
MCP tools intentionally do not expose a free-form `scope` parameter. AI agents can invent isolation IDs, so app-user and tenant scopes should be controlled by your application through the REST API or TypeScript SDK. MCP remains focused on unscoped assistant memory plus optional `project` grouping.
## Connection URL
```
https://mcp.memcontext.in/mcp
```
Authenticate with your API key via the `MEMCONTEXT-API-KEY` or `X-API-Key` header. See [MCP Setup](/guides/mcp-setup) for client-specific configs.
## Tools
The server exposes five tools:
| Tool | Purpose |
| ----------------------------------------- | ------------------------------------------------------ |
| [`save_memory`](/mcp/save-memory) | Persist durable knowledge across sessions |
| [`search_memory`](/mcp/search-memory) | Find relevant memories using hybrid search |
| [`memory_feedback`](/mcp/memory-feedback) | Rate a retrieved memory as helpful, outdated, or wrong |
| [`update_memory`](/mcp/update-memory) | Correct or refine an existing saved memory |
| [`delete_memory`](/mcp/delete-memory) | Remove a memory by ID |
## Agent instructions
For best results, add the recommended agent instructions to your client's preferences file. These tell the assistant when to search, when to save, and how to use categories and projects.
The full instructions block and per-client file paths are documented in the [MCP Setup](/guides/mcp-setup#agent-instructions) guide.
# save_memory
Source: https://docs.memcontext.in/mcp/save-memory
Persist durable user or project knowledge across sessions.
## Description
`save_memory` stores a piece of knowledge that should be remembered across sessions. MemContext automatically handles deduplication, versioning, and relationship classification. Short memories are saved immediately; larger notes may be accepted for asynchronous extraction into multiple atomic memories.
## Parameters
| Parameter | Type | Required | Description |
| ---------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `content` | string | Yes | Clear, complete, searchable statement. Full sentences work best - not fragments or keywords. |
| `category` | string | No | One of `preference`, `fact`, `decision`, or `context`. See below. |
| `project` | string | No | Project grouping for known project/app context. Examples: `memcontext`, `carq`. Omit if unsure. Format: lowercase, no spaces. |
### Categories
| Category | Use for | Example |
| ------------ | ---------------------- | ------------------------------- |
| `preference` | User likes/dislikes | "User prefers dark mode" |
| `fact` | Objective information | "User uses macOS" |
| `decision` | Choices made | "Chose PostgreSQL for database" |
| `context` | Background information | "Working on e-commerce app" |
## What happens on save
For normal-size memories:
1. Content is expanded into a more searchable form via LLM
2. An embedding is generated
3. Similar existing memories are found
4. The relationship is classified (update, extend, similar, or duplicate)
5. The memory is saved, supersedes an existing one, extends one, or is deduplicated
For larger notes:
1. The request is accepted quickly
2. The note is prepared for asynchronous extraction
3. MemContext extracts atomic memories from the note
4. Each extracted item is saved as its own searchable memory
## Timing guidance
MCP memories use automatic TTL. Use the REST API, TypeScript SDK, or dashboard when exact expiry is required.
## Response
The response includes a `status` field indicating what happened:
| Status | Meaning |
| ----------- | ---------------------------------------------------------- |
| `saved` | New memory created |
| `updated` | Superseded an existing memory (old one marked non-current) |
| `extended` | Created a relation to an existing memory |
| `duplicate` | Content already exists, nothing saved |
| `accepted` | Large content accepted for asynchronous extraction |
Duplicates are handled automatically - re-saving an already-known fact is safe.
When `status` is `accepted`, the response includes a `jobId` plus a message for tracking extraction.
## Example
```
save_memory({
content: "User prefers TypeScript over JavaScript for type safety",
category: "preference"
})
```
MCP tools do not accept `scope` because AI agents can hallucinate isolation
IDs. Use the REST API or TypeScript SDK for app-user or tenant scoped
integrations.
### Content guidelines
Content should be written as clear, self-contained statements that will be searchable later:
* **Good:** `"User prefers TypeScript over JavaScript for type safety"`
* **Bad:** `"TS > JS"` (too vague, not searchable)
* **Bad:** `"user likes coding"` (not specific enough to be useful)
# search_memory
Source: https://docs.memcontext.in/mcp/search-memory
Retrieve relevant memories for the assistant's current task.
## Description
`search_memory` finds memories that may help the assistant answer, code, plan, or
make a decision. Use full natural-language questions for best results.
## Parameters
| Parameter | Type | Required | Default | Description |
| ----------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------- |
| `query` | string | Yes | - | Natural language description of what to find. Full sentences produce best results. |
| `limit` | number | No | 5 | Number of results to return. Use higher values for broad topics. |
| `category` | string | No | all | Filter to `preference`, `fact`, `decision`, or `context`. |
| `project` | string | No | all | Filter to a specific known project. |
| `threshold` | number | No | 0.6 | Search strictness. Higher values return broader matches. |
## Example
```
search_memory({
query: "What package manager does the user prefer?",
project: "memcontext"
})
```
## Response
```json theme={null}
{
"found": 1,
"memories": [
{
"id": "a1b2c3d4-...",
"content": "User prefers pnpm for JavaScript projects.",
"category": "preference",
"relevance": 0.92,
"createdAt": "2026-04-11T12:00:00.000Z"
}
]
}
```
Each result includes a `relevance` score from 0 to 1.
## Query Guidelines
* Ask a complete question.
* Include the project name when it matters.
* Use `category` if you only need one type of memory.
* Increase `limit` when preparing a larger answer.
Good:
```text theme={null}
What package manager does the user prefer?
```
Less effective:
```text theme={null}
package manager
```
MCP tools intentionally do not expose `scope`. Use the REST API or TypeScript
SDK when your app needs per-user or per-tenant isolation.
# update_memory
Source: https://docs.memcontext.in/mcp/update-memory
Correct or refine an existing saved memory.
## Description
`update_memory` changes an existing saved memory. Use it when `search_memory`
returns a memory that is wrong, outdated, incomplete, or poorly worded and you
know the corrected content.
Use `memory_feedback` separately to rate retrieval quality. Feedback affects
ranking; `update_memory` changes the saved memory and refreshes its retrieval
embedding.
## Parameters
| Parameter | Type | Required | Description |
| ---------- | ------ | -------- | ----------------------------------------------------------------------------- |
| `memoryId` | string | Yes | The memory ID to update. Use the `id` returned by `search_memory`. |
| `content` | string | Yes | Correct replacement memory text. Use a complete, searchable statement. |
| `category` | string | No | Updated category: `preference`, `fact`, `decision`, or `context`. |
| `project` | string | No | Updated project grouping. Only set when a clear project or app name is known. |
## Example
```
update_memory({
memoryId: "a1b2c3d4-...",
content: "User prefers Zustand for client state in new React projects.",
category: "preference",
project: "memcontext"
})
```
## Response
Returns the updated memory result on success, or a `404` error if the memory was
not found.
# Pricing and Limits
Source: https://docs.memcontext.in/pricing
Plan limits for memories, workspaces, Context Vault documents, retrieval, SDK, and API access.
MemContext plans limit how much durable context you can store. Memory retrieval is not capped by plan, though API endpoints still use rate limits to keep the service reliable.
## Plans
| Plan | Price | Memories | Workspaces | Context Vault documents |
| -------- | ----------- | -------- | ---------- | ----------------------- |
| Free | \$0/month | 300 | 1 | 5 |
| Hobby | \$20/month | 2K | 5 | 25 |
| Pro | \$50/month | 10K | 10 | 100 |
| Ultimate | \$100/month | 100K | 50 | 500 |
Pro is the recommended plan for serious builders and small teams. Ultimate is for power users, agencies, and teams running larger knowledge bases.
## What Counts
**Memories** are saved member or application memories created through MCP, the REST API, the SDK, or the dashboard. They are counted against the selected workspace's shared memory pool.
**Workspaces** are team/account boundaries for members, billing, API keys,
member memories, and vaults. The workspace limit is the number of workspaces
your account can own and bill.
**Context Vault documents** are documents, uploads, URLs, and other source files
ingested into a workspace vault. Extracted document memories are tracked
separately from the workspace member-memory pool during the beta. Workspace
documents count against the workspace's Context Vault document allowance,
regardless of which member uploads them.
## Workspace Billing
Each workspace owns its subscription and usage limits. By default, the user who
created the workspace controls billing. Invited admins and members can add
knowledge when their role allows it, but their uploads consume the workspace's
Context Vault document allowance.
For example, if Ayush creates a workspace on the Ultimate plan and invites
Vranda on the Free plan, Vranda's uploads use that workspace's document limit.
If Vranda upgrades her own separate workspace later, that does not automatically
move billing for Ayush's workspace.
## Access
All plans include:
* SDK and API access
* MCP integration
* Unlimited memory retrieval by plan
Search and write endpoints may still be rate limited for abuse protection and service reliability.
## Upgrades and Limits
When you upgrade, your new limits apply immediately after the subscription update is processed.
If you downgrade, existing memories, workspaces, and Context Vault documents are preserved. You cannot add more items of a type until usage is below the new plan limit.
# Quickstart
Source: https://docs.memcontext.in/quickstart
Make your first MemContext API and MCP calls in under 2 minutes.
## 1. Get an API key
Sign up at [app.memcontext.in](https://app.memcontext.in) and create an API key from **Settings > API Keys**.
Your key will look like `mc_abc123...` and is shown only once - store it securely.
## 2. Save a memory
```bash theme={null}
curl -X POST https://api.memcontext.in/api/memories \
-H "Content-Type: application/json" \
-H "X-API-Key: mc_your_key" \
-d '{
"content": "User prefers TypeScript over JavaScript for type safety",
"category": "preference"
}'
```
**Response:**
```json theme={null}
{
"id": "a1b2c3d4-...",
"status": "saved"
}
```
The `status` field tells you what happened:
| Status | Meaning |
| ----------- | -------------------------------------------------- |
| `saved` | New memory created |
| `updated` | New memory superseded an existing one |
| `extended` | New memory extends an existing one |
| `duplicate` | Content already exists, no new memory created |
| `accepted` | Large content accepted for asynchronous extraction |
Longer notes may return `202 Accepted` with a `jobId` and message for tracking extraction into atomic memories.
## 3. Search memories
```bash theme={null}
curl "https://api.memcontext.in/api/memories/search?query=What%20language%20does%20the%20user%20prefer" \
-H "X-API-Key: mc_your_key"
```
**Response:**
```json theme={null}
{
"found": 1,
"memories": [
{
"id": "a1b2c3d4-...",
"content": "User prefers TypeScript over JavaScript for type safety",
"category": "preference",
"relevance": 0.92,
"createdAt": "2026-04-11T12:00:00.000Z"
}
]
}
```
Use full natural-language sentences as queries for best results. Keywords alone reduce match quality.
## 4. Save a scope-isolated memory
```bash theme={null}
curl -X POST https://api.memcontext.in/api/memories \
-H "Content-Type: application/json" \
-H "X-API-Key: mc_your_key" \
-d '{
"content": "User prefers concise release notes",
"category": "fact",
"scope": "user_123"
}'
```
Use `scope` when one API key serves multiple end users or tenants. Omit it only for global, unscoped memories.
## 5. Save a project memory inside that scope
```bash theme={null}
curl -X POST https://api.memcontext.in/api/memories \
-H "Content-Type: application/json" \
-H "X-API-Key: mc_your_key" \
-d '{
"content": "This project uses PNPM as the package manager",
"category": "fact",
"scope": "user_123",
"project": "memcontext"
}'
```
## 6. Connect the MCP server
For Claude.ai or Claude Desktop, add a custom connector with:
```text theme={null}
https://mcp.memcontext.in/mcp
```
Then click **Connect**, sign in to MemContext, and approve access.
For coding assistants, you can still connect MemContext directly. For example, with Claude Code:
```bash theme={null}
claude mcp add memcontext --scope user --transport http https://mcp.memcontext.in/mcp \
--header "MEMCONTEXT-API-KEY:mc_your_key"
```
No local installation required. Once connected, your assistant can call `save_memory` and `search_memory` directly.
See [MCP Setup](/guides/mcp-setup) for Claude.ai, Claude Desktop, Cursor, OpenCode, Codex CLI, and agent instructions.
## TypeScript SDK
Install the SDK when integrating from a Node.js or TypeScript app:
```bash theme={null}
npm install memcontext-sdk
```
```typescript theme={null}
import { MemContextClient } from "memcontext-sdk";
const client = new MemContextClient({
apiKey: process.env.MEMCONTEXT_API_KEY!,
});
const userMemory = client.withScope("user_123");
const projectMemory = userMemory.withProject("memcontext");
await projectMemory.save({
content: "User prefers concise release notes",
category: "preference",
});
const results = await projectMemory.search({
query: "How should release notes be written?",
});
```
Use `withScope()` for the hard end-user or tenant boundary. Use `withProject()` only as a grouping filter inside that scope.
## Recommended workflow
1. **Search first** - check for existing context before making assumptions
2. **Save when durable** - persist stable preferences, decisions, and project facts
3. **Use categories** - tag memories so they can be filtered later
4. **Use scope** - isolate each app user or tenant into its own memory container
5. **Use projects** - group project-specific knowledge inside that scope
6. **Give feedback** - mark retrieved memories as helpful or outdated to improve quality
# TypeScript SDK
Source: https://docs.memcontext.in/sdk/typescript
Install and use the official MemContext TypeScript SDK.
`memcontext-sdk` is the official TypeScript SDK for the MemContext public API. It is a small typed wrapper around the REST API with API key auth, scope/project helpers, typed responses, and normalized API errors.
## Install
```bash theme={null}
npm install memcontext-sdk
```
## Quickstart
```typescript theme={null}
import { MemContextClient } from "memcontext-sdk";
const client = new MemContextClient({
apiKey: process.env.MEMCONTEXT_API_KEY!,
});
const userMemory = client.withScope("user_123");
const projectMemory = userMemory.withProject("memcontext");
await projectMemory.save({
content: "User prefers concise release notes",
category: "preference",
});
const results = await projectMemory.search({
query: "How should release notes be written?",
});
```
Use `withScope()` for the hard end-user or tenant boundary. Use `withProject()` only as a grouping filter inside that scope.
## Client Setup
```typescript theme={null}
const client = new MemContextClient({
apiKey: process.env.MEMCONTEXT_API_KEY!,
baseUrl: "https://api.memcontext.in",
scope: "user_123",
project: "memcontext",
});
```
| Option | Required | Description |
| --------- | -------- | --------------------------------------------------------- |
| `apiKey` | Yes | MemContext API key from the dashboard. |
| `baseUrl` | No | API base URL. Defaults to `https://api.memcontext.in`. |
| `scope` | No | Default hard isolation boundary for this client instance. |
| `project` | No | Default project grouping inside the selected scope. |
| `fetch` | No | Custom fetch implementation for tests or custom runtimes. |
## Scope Helpers
### `withScope(scope)`
Creates a new client with a default `scope`. Use this when one API key serves multiple app users, workspaces, organizations, or tenants.
```typescript theme={null}
const userMemory = client.withScope("user_123");
```
### `withProject(project)`
Creates a new client with a default `project`. Projects are soft grouping filters inside the current scope.
```typescript theme={null}
const projectMemory = userMemory.withProject("memcontext");
```
## Methods
### `save(request, options?)`
Saves durable memory. MemContext automatically handles embeddings, deduplication, relationship classification, and versioning. Larger notes may be accepted for asynchronous extraction into atomic memories.
```typescript theme={null}
await client.save({
content: "User prefers TypeScript over JavaScript",
category: "preference",
scope: "user_123",
project: "memcontext",
});
```
Returns a save result with `status` set to `saved`, `updated`, `extended`, `duplicate`, or `accepted`.
When `status` is `accepted`, the response includes a `jobId` and message for tracking extraction into atomic memories.
### `search(request)`
Searches memories using hybrid retrieval. Use full natural-language questions for best results.
```typescript theme={null}
const results = await client.search({
query: "What language does the user prefer?",
limit: 5,
threshold: 0.6,
});
```
Returns `{ found, memories }`, where each memory includes content, category, scope, project, relevance, and `createdAt` as a `Date`.
### `list(request?)`
Lists current non-deleted memories with pagination and filters.
```typescript theme={null}
const page = await client.list({
limit: 20,
offset: 0,
category: "fact",
search: "release notes",
});
```
Returns `{ memories, total, hasMore }`.
### `get(memoryId, options?)`
Fetches one memory by ID. Pass `scope` when retrieving scoped memories from a base client.
```typescript theme={null}
const memory = await client.get("memory-id", {
scope: "user_123",
});
```
### `update(memoryId, request, options?)`
Updates memory content, category, or project. Content updates may create relations or supersede related memories.
```typescript theme={null}
await client.update(
"memory-id",
{ content: "User now prefers concise changelogs" },
{ scope: "user_123" },
);
```
### `delete(memoryId, options?)`
Removes a memory from future search and list results.
```typescript theme={null}
await client.delete("memory-id", {
scope: "user_123",
});
```
### `forget(memoryId, options?)`
Endpoint-parity alias for `delete()`. Prefer `delete()` unless you specifically
want the `/forget` response shape.
```typescript theme={null}
await client.forget("memory-id", {
scope: "user_123",
});
```
### `feedback(memoryId, request, options?)`
Records retrieval quality feedback. Feedback helps improve future ranking.
```typescript theme={null}
await client.feedback(
"memory-id",
{
type: "helpful",
context: "This memory answered the user's question directly.",
},
{ scope: "user_123" },
);
```
Feedback `type` can be `helpful`, `not_helpful`, `outdated`, or `wrong`.
### `history(memoryId, options?)`
Returns the current memory and previous versions in its version chain.
```typescript theme={null}
const history = await client.history("memory-id", {
scope: "user_123",
});
```
### `profile(options?)`
Returns pre-aggregated profile context split into stable and recent memory.
```typescript theme={null}
const profile = await client.profile({
scope: "user_123",
project: "memcontext",
});
```
Returns `{ static, dynamic }`.
### `graph(options?)`
Returns graph visualization data for memories in the selected scope.
```typescript theme={null}
const graph = await client.graph({
scope: "user_123",
});
```
Returns `{ nodes, links, meta }`.
### `health(signal?)`
Checks API health.
```typescript theme={null}
const health = await client.health();
```
## Workspace Methods
Context Vault uses workspaces for shared knowledge. These methods require an API
key or dashboard session that belongs to the user.
### `listWorkspaces()`
Lists workspaces the current user belongs to.
```typescript theme={null}
const { workspaces } = await client.listWorkspaces();
```
### `createWorkspace(request)`
Creates a workspace and assigns the current user as owner.
```typescript theme={null}
const { workspace } = await client.createWorkspace({
name: "Acme Support",
});
```
### `inviteWorkspaceMember(workspaceId, request)`
Sends an email invitation for another workspace member. Roles can be `admin`,
`member`, or `viewer`. The user is added only after accepting the invite.
```typescript theme={null}
const invite = await client.inviteWorkspaceMember(workspace.id, {
email: "teammate@example.com",
role: "member",
});
```
### `listWorkspaceTeam(workspaceId)`
Lists current members and pending invitations.
```typescript theme={null}
const team = await client.listWorkspaceTeam(workspace.id);
```
### `updateWorkspaceMember(workspaceId, memberId, request)`
Updates a member role. Owners cannot be changed through this method.
```typescript theme={null}
await client.updateWorkspaceMember(workspace.id, memberId, {
role: "viewer",
});
```
### `removeWorkspaceMember(workspaceId, memberId)`
Removes a non-owner member from the workspace.
```typescript theme={null}
await client.removeWorkspaceMember(workspace.id, memberId);
```
### `revokeWorkspaceInvitation(workspaceId, invitationId)`
Revokes a pending invitation before it is accepted.
```typescript theme={null}
await client.revokeWorkspaceInvitation(workspace.id, invitationId);
```
### `acceptWorkspaceInvitation(request)`
Accepts a workspace invitation token.
```typescript theme={null}
await client.acceptWorkspaceInvitation({
token: "invitation-token",
});
```
## Context Vault Methods
Context Vault methods let you add documents, list processing status, search
workspace knowledge, and collect feedback from your app.
### `ingestContextVaultDocument(request, options?)`
Adds extracted text, a public file URL, or a documentation URL to a workspace.
```typescript theme={null}
await client.ingestContextVaultDocument({
workspaceId: workspace.id,
title: "Product docs",
uri: "https://docs.example.com",
sourceType: "url",
crawlSubpages: true,
priorityPageLimit: 15,
subpageTarget: ["api", "guides"],
});
```
For docs sites with `llms.txt`, MemContext uses the page map and ingests only
the top-priority pages. `priorityPageLimit` defaults to `15` and is capped at
`25`.
For public file URLs, pass the file type so the document can be parsed correctly:
```typescript theme={null}
await client.ingestContextVaultDocument({
workspaceId: workspace.id,
title: "Security report",
uri: "https://example.com/security-report.pdf",
sourceType: "pdf",
});
```
### `uploadContextVaultDocument(request, options?)`
Uploads a local file and adds it to Context Vault.
```typescript theme={null}
await client.uploadContextVaultDocument({
workspaceId: workspace.id,
title: "Employee handbook",
file,
filename: "handbook.pdf",
sourceType: "pdf",
});
```
### `listContextVaultDocuments(workspaceId, options?)`
Lists workspace documents and their current status.
```typescript theme={null}
const docs = await client.listContextVaultDocuments(workspace.id);
```
### `cancelContextVaultDocument(documentId, options?)`
Stops a pending, retrying, or active document job.
```typescript theme={null}
await client.cancelContextVaultDocument("document-id");
```
### `deleteContextVaultDocument(documentId, options?)`
Deletes the document, chunks, citations, and any extracted memories that are
only backed by that document.
```typescript theme={null}
await client.deleteContextVaultDocument("document-id");
```
### `createContextVaultMemory(request, options?)`
Adds a curated company fact to a workspace. Use this for important company
context that is not documented yet.
```typescript theme={null}
await client.createContextVaultMemory({
workspaceId: workspace.id,
content: "Refund discounts are not offered after the trial period ends.",
scope: "billing",
project: "pricing",
category: "fact",
});
```
### `deleteContextVaultMemory(workspaceId, memoryId, options?)`
Deletes a curated company fact from a workspace. Document-extracted memories are
removed by deleting their source document when they are not backed by any other
document.
```typescript theme={null}
await client.deleteContextVaultMemory(workspace.id, "memory-id");
```
### `searchContextVault(request, options?)`
Searches workspace knowledge in `documents`, `memories`, or `hybrid` mode.
```typescript theme={null}
const results = await client.searchContextVault({
workspaceId: workspace.id,
query: "How do refunds work?",
mode: "hybrid",
limit: 8,
});
// Source passages from files/docs.
console.log(results.chunks);
// Extracted atomic facts and curated company facts.
console.log(results.memories);
```
Hybrid mode keeps `chunks[]` and `memories[]` separate. For answer generation,
pass `chunks[]` as source document context and convert `memories[]` into a
second memory-context document. Curated company facts use
`memoryType: "company"` and may return with `evidence: []`.
### `listContextVaultMemories(request, options?)`
Browses extracted workspace memories.
```typescript theme={null}
const page = await client.listContextVaultMemories({
workspaceId: workspace.id,
limit: 20,
search: "refund",
});
```
### `listContextVaultDocumentMemories(workspaceId, documentId, options?)`
Lists memories extracted from one document.
```typescript theme={null}
const extracted = await client.listContextVaultDocumentMemories(
workspace.id,
"document-id",
);
```
### `submitContextVaultMemoryFeedback(memoryId, request, options?)`
Records feedback on an extracted workspace memory.
```typescript theme={null}
await client.submitContextVaultMemoryFeedback("memory-id", {
workspaceId: workspace.id,
type: "helpful",
});
```
### `listContextVaultMemoryEvidence(workspaceId, memoryId, options?)`
Loads source chunks for an extracted memory.
```typescript theme={null}
const evidence = await client.listContextVaultMemoryEvidence(
workspace.id,
"memory-id",
);
```
### `getContextVaultHierarchy(workspaceId, options?)`
Returns scope/project counts for workspace memories.
```typescript theme={null}
const hierarchy = await client.getContextVaultHierarchy(workspace.id);
```
## Error Handling
Failed API responses throw `MemContextApiError`.
```typescript theme={null}
import { MemContextApiError } from "memcontext-sdk";
try {
await client.get("missing-id");
} catch (error) {
if (error instanceof MemContextApiError) {
console.error(error.status, error.code, error.message);
}
}
```
## Links
* Website: [memcontext.in](https://memcontext.in)
* Official docs: [docs.memcontext.in](https://docs.memcontext.in)
* API reference: [REST API](/api-reference/overview)