> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memcontext.in/llms.txt
> Use this file to discover all available pages before exploring further.

# 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"
})
```

<Note>
  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.
</Note>

### 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)