Files
6665940656 fix(memory): return stored id from a background DirectMem0 save (#4759)
## Description

`DirectMem0Adapter.save_memory(background=True)` returned an id from a
second `_generate_id` call. That helper salts with the current time, so
the returned id never matched the Qdrant point the background task
wrote, and a later `memory_update` / `memory_delete` with it found
nothing.

The direct-write ids are now generated once, passed to the background
task, and returned. On the Mem0 extraction path (no pre-extracted data),
Mem0 assigns ids itself, so no id is known up front. The save is marked
`_id_pending`, and `memory_save` reports `memory_id: None` instead of an
invented id. The real id is available from `get_task_status(task_id)`.

Refs #4362 (item 6 only).

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/memory/backends/direct_mem0.py`: generate fact ids before
scheduling the background task, then store and return those same ids.
`_write_facts_to_qdrant` accepts optional `memory_ids`. Mem0-path
background saves are marked `_id_pending`. Fixed the `_generate_id`
docstring, which said the ids were "deterministic".
- `headroom/memory/system.py`: `memory_save` returns `memory_id: None`
when the id is pending.
- Background saves snapshot `facts` before generating ids and schedule
that same snapshot, so a caller mutating its list after queueing can't
make the task fail. The returned `_all_memory_ids` is a copy for the
same reason.
- `tests/test_memory/test_direct_mem0_background_ids.py`: 4 regression
tests, using a fake Qdrant client and a fake Mem0 client.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ pytest tests/test_memory/test_direct_mem0_background_ids.py -v
test_background_save_returns_stored_fact_id PASSED
test_mutating_lists_after_queueing_does_not_break_the_save PASSED
test_background_mem0_extraction_does_not_invent_an_id PASSED
test_memory_save_tool_withholds_a_pending_id PASSED
4 passed in 0.36s
```

## Real Behavior Proof

- Environment: macOS; Qdrant v1.15.5 server in Docker
(`localhost:6333`); `mem0ai` 2.2.1 and `qdrant-client` 1.20.0 (real
`Memory.get/update/delete`); embeddings from Ollama 0.40.6
`nomic-embed-text` through its OpenAI-compatible API
(`OPENAI_BASE_URL=http://localhost:11434/v1`). `DirectMem0Adapter` ran
unmodified, with `enable_graph=False`.
- Exact command / steps: a script on a fresh 768-dim collection:
`save_memory(facts=[...], background=True)` → append to the caller's
`facts` list → `flush_pending()` → `get_memory` / `update_memory` /
`get_memory` / `delete_memory` / `get_memory`, all using the
**returned** id. Run once on this branch and once on `main` (`a385ea8e`)
as a control.
- Observed result: Returned IDs resolve to the stored points;
before/after results are below.

  | | this branch | `main` |
  |---|---|---|
  | task status | completed | completed |
  | returned id is a stored Qdrant point | **True** | False |
| `get_memory(returned id)` | `'Prefers Python over JavaScript'` |
`None` |
| `update_memory` → `get_memory` | `'Prefers Rust over Python'` |
`Memory with id 0ad08f… not found` |
| `delete_memory(returned id)` | `True`, 0 points left | `False`, 2
points left |
| fact appended after queueing | not stored (snapshot) | stored under an
id never returned to the caller |

- Not tested: the Mem0 LLM-extraction background path (`_id_pending`; it
needs an OpenAI LLM and none was available); Neo4j graph writes; hosted
Qdrant; OpenAI's own embedding API.

## Runtime Rollout Safety

- Rollout-managed feature(s): None
- Minimum rollout channel: NA
- Stable/default behavior changed: Only background saves on
`DirectMem0Adapter` (opt-in via `background=true` or
`async_writes=True`). The proxy doesn't use background saves.
Synchronous saves are unchanged.
- Kill switch / disable path: Don't use background saves.
- Unsafe override required: NA
- Qualification impact: None
- Rollback path: Revert this PR

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)
<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4759"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-11-16 19:47:14 -06:00
..