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

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