Commit Graph
91 Commits
Author SHA1 Message Date
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
9321a415a6 fix(memory): scope TrafficLearner's SQLite reads to its user_id (#4850)
## Description

`TrafficLearner` saves its rows under its configured `user_id`, but its
two direct SQLite reads ignored `user_id`:

- `_hydrate_persisted_state` (startup) loaded every user's
`traffic_learner` rows into the dedup maps, then applied `LIMIT
dedup_window`. Bob's learner could bind a pattern hash to Alice's row
and later bump *her* evidence instead of creating his own row. Other
users' rows also used up his window.
- `_load_persisted_patterns_from_sqlite` (used by
`_collect_all_patterns` when writing learned context files) returned
every user's patterns, so Alice's learned text ended up in Bob's files.

Both queries now filter on `user_id = ?`. In hydration the filter runs
before the `LIMIT`. Only matters when several user IDs share one memory
database; a single-user setup (`user_id="default"`) is unchanged.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)

## Changes Made

- `headroom/memory/traffic_learner.py`: `WHERE user_id = ?` in both
reads. `_load_persisted_patterns_from_sqlite(db_path, user_id)` takes
the user explicitly (private helper; its only caller is updated).
- `tests/test_memory/test_traffic_learner.py`: new
`TestUserScopedPersistence`, which checks that hydration leaves another
user's row alone and collection excludes other users. Hand-built test
schemas gain the `user_id` column that the real `memories` table has,
and direct helper calls pass `"default"`.

## 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
# new tests against origin/main (c21b0813)
$ pytest tests/test_memory/test_traffic_learner.py -k TestUserScopedPersistence
E   assert ['Alice-only ...ge workflow."] == ["Bob's package workflow."]
FAILED ...::TestUserScopedPersistence::test_hydration_ignores_other_users_rows
FAILED ...::TestUserScopedPersistence::test_collected_patterns_exclude_other_users
====================== 2 failed, 236 deselected in 2.76s =======================

# this branch
$ pytest tests/test_memory/test_traffic_learner.py
============================= 238 passed in 18.28s =============================
$ pytest tests/test_openai_responses_traffic_learner.py tests/test_learn/test_worktree_merge.py tests/test_learn/test_section_lifecycle.py tests/test_memory/test_learn_flag.py
============================== 47 passed in 4.81s ==============================
$ ruff check / ruff format --check (0.17.3): All checks passed!
$ mypy headroom/memory/traffic_learner.py --ignore-missing-imports
Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: macOS, Python 3.12. One SQLite `memory.db` holding a
`traffic_learner` row for `alice` and one for `bob`.
- Exact command / steps: `TrafficLearner(backend=<backend pointing at
that db>, user_id="bob")._collect_all_patterns()`.
- Observed result:
```text
origin/main:  bob collects: ['Alice-only procedure.', "Bob's preference."]
this branch:  bob collects: ["Bob's preference."]
```
- Not tested: a full proxy run with `--learn --memory` and several
users.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: see Description
- Kill switch / disable path: none needed
- Unsafe override required: no
- 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
- [ ] 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)

## Screenshots (if applicable)

N/A

## Additional Notes

Rows written before this change already carry the correct `user_id` (the
save path always set it), so no migration is needed.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4850"
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 -->

Reported by @JoaoMarcos44. Thank you for your contribution! 🩵

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-15 01:52:47 +05:30
48df6df497 fix(memory): scope memory_update and memory_delete to the calling user (#4869)
## Description

The `memory_delete` tool called `backend.delete_memory(memory_id)`
without the user id. `LocalBackend.update_memory` and `delete_memory`
ignored `user_id`, and `DirectMem0Adapter` did the same. When users
share one store (`global` storage mode, or the qdrant-neo4j backend), a
memory id that belonged to another user could be deleted or overwritten.

The handler now passes the effective user id to `delete_memory`. Both
backends now treat an id owned by someone else as not found: delete
returns `False`, and update raises the same not-found `ValueError` it
raises for an unknown id. A caller that passes no `user_id` (the CLI,
`MemorySystem`) keeps the old unscoped behaviour.

## 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/proxy/memory_handler.py`: `_execute_delete`, and the
delete+save fallback in `_execute_update`, pass
`user_id=effective_user_id`. The fallback now returns `not_found` when
nothing was deleted, instead of saving a replacement.
- `headroom/memory/backends/local.py`: `update_memory` and
`delete_memory` check the stored owner when `user_id` is given.
- `headroom/memory/backends/direct_mem0.py`: `update_memory` and
`delete_memory` check the owner through `get_memory` when `user_id` is
given. If the lookup fails, the id is treated as not found.
- `headroom/memory/backends/mem0_system_adapter.py`: `delete_memory`
with a `user_id` used to delete anyway when the owner lookup raised (it
caught every exception) or when the record had no owner. It now deletes
only when the stored owner matches. A `ValueError`/`OSError` from the
lookup is logged and the delete is refused; anything else propagates.
`Mem0Backend` (`backends/mem0.py`) is the raw client that this adapter
wraps; the proxy never calls it directly.
- Tests: a new `tests/test_memory_tool_user_scope.py` runs through
`create_app` with a real `LocalBackend` in `global` mode and a
`MockTransport` upstream. There is also one `DirectMem0Adapter` test.
Fake backends in `test_memory_handler_native_ops.py` now accept
`user_id`.

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

In the test, alice saves a memory. bob's request then gets an upstream
turn that calls `memory_delete`, or `memory_update`, with alice's id.
The test passes when alice's memory is unchanged. The controls check
that bob can still delete and update his own memory.

On `origin/main` (0368a872):
```text
PASSED tests/test_memory_tool_user_scope.py::test_user_can_still_change_own_memory[memory_delete-args0]
PASSED tests/test_memory_tool_user_scope.py::test_user_can_still_change_own_memory[memory_update-args1]
FAILED tests/test_memory_tool_user_scope.py::test_memory_owned_by_another_user_is_left_alone[memory_delete-args0]
FAILED tests/test_memory_tool_user_scope.py::test_memory_owned_by_another_user_is_left_alone[memory_update-args1]
2 failed, 2 passed
FAILED tests/test_memory/test_direct_mem0.py::test_update_and_delete_leave_another_users_memory_alone
1 failed, 23 deselected
```
On this branch:
```text
PASSED tests/test_memory_tool_user_scope.py::test_memory_owned_by_another_user_is_left_alone[memory_delete-args0]
PASSED tests/test_memory_tool_user_scope.py::test_memory_owned_by_another_user_is_left_alone[memory_update-args1]
PASSED tests/test_memory_tool_user_scope.py::test_user_can_still_change_own_memory[memory_delete-args0]
PASSED tests/test_memory_tool_user_scope.py::test_user_can_still_change_own_memory[memory_update-args1]
4 passed
PASSED tests/test_memory/test_direct_mem0.py::test_update_and_delete_leave_another_users_memory_alone
1 passed, 23 deselected
```
`Mem0SystemAdapter` (second commit),
`test_delete_is_refused_unless_the_owner_is_confirmed`: 4 failed, 1
passed on the first commit (only `other-owner` passed); 5 passed with
the fix. Memory tests after it: 875 passed, 2 skipped.

The existing memory test files (74 files) pass on this branch:
```text
1447 passed, 27 skipped in 64.67s
(after review follow-ups: test_memory_tool_user_scope, test_memory_handler_native_ops, test_direct_mem0: 69 passed, 1 skipped)
```
`uvx ruff@0.17.3 check` and `format --check` pass on the changed files.
`mypy` on the three changed modules reports no issues.

## Real Behavior Proof

- Environment: macOS, Python 3.12. The proxy is created in-process with
`create_app(ProxyConfig(memory_enabled=True,
memory_storage_mode="global", memory_inject_tools=True))` and backed by
a real `LocalBackend` (SQLite plus sqlite-vec, fixed test embedder). The
upstream is `httpx.MockTransport`, and
`LITELLM_LOCAL_MODEL_COST_MAP=True`.
- Exact command / steps: `pytest tests/test_memory_tool_user_scope.py`.
alice saves a memory. A `/v1/messages` request with `x-headroom-user-id:
bob` gets an upstream `memory_delete` or `memory_update` with alice's
id. The proxy runs the tool and continues the turn.
- Observed result: on main, alice's memory is deleted, or superseded
with bob's content. On this branch it is unchanged. The model gets
`not_found` for delete, and the usual not-found error for update.
- Not tested: a live qdrant/neo4j deployment. `DirectMem0Adapter` is
covered with a stubbed mem0 client.

## Runtime Rollout Safety

- Rollout-managed feature(s): none.
- Minimum rollout channel: n/a.
- Stable/default behavior changed: only for update/delete calls on an id
the caller does not own. They now return not found.
- Kill switch / disable path: none needed.
- Unsafe override required: no.
- 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
- [ ] 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)

## Additional Notes

This PR is independent of the PR that limits which memory tool calls the
proxy runs. Either can merge first.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Reported by @JoaoMarcos44. Thank you for your contribution! 🩵

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-14 10:47:00 +05:30
7592e68145 fix(memory): read the relation key the memory_save schema advertises (#4647)
## Description

Item 7 of #4362. `memory_save`'s plain `relationships[]` schema names
the relationship key `relation` (`headroom/memory/tools.py:82-88`, also
the compact schema at `:384-387`), but `LocalBackend.save_memory` read
only `type` (`headroom/memory/backends/local.py:390` on `e4a60ed7`).
Every relationship a model saved through the tool was therefore stored
as the default `related_to`, and graph queries filtered by relation type
found nothing. The optimized `extracted_relationships` path already
converts its own key and is unchanged.

`save_memory` now reads `type` first (the class docstring example and
direct callers use it), then `relation`, then falls back to
`related_to`. The schema is not changed, so clients that already send
`relation` start working without a change on their side.

Refs #4362

## 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/local.py`: `rel_type = rel.get("type") or
rel.get("relation") or "related_to"`, with a one-line comment naming the
two key spellings.
- `tests/test_memory/test_local_relationship_key.py` (new): pins that
the advertised schema uses `relation`, and that `save_memory` stores
`works_with` from `{"relation": ...}`, `manages` from `{"type": ...}`,
and `related_to` when neither key is present.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`) (run on
`headroom/memory/backends/local.py` only, see below)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
# fail before (source at e4a60ed7, new test kept)
FAILED tests/test_memory/test_local_relationship_key.py::test_relationship_type_is_read_from_relation_or_type[rel0-works_with]
1 failed, 3 passed

# pass after
4 passed

# tests/test_memory + tests/test_memory_system.py + tests/test_sqlite_graph_store.py
e4a60ed7:     1 failed, 693 passed, 165 skipped   (the failure is the new test)
this branch:  694 passed, 165 skipped

# ruff check / ruff format --check: All checks passed! / 2 files already formatted
# mypy headroom/memory/backends/local.py: Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: Ubuntu (WSL2) on Windows 11, Python 3.12.15, `headroom`
Python source at `e4a60ed7` and at this branch, offline.
- Exact command / steps: `MemorySystem(LocalBackend,
user_id="alice").process_tool_call("memory_save", {"content": "Alice
works with Bob on the billing service", "importance": 0.7, "entities":
["Alice", "Bob"], "relationships": [{"source": "Alice", "relation":
"works_with", "target": "Bob"}]})`, with a real `SQLiteGraphStore` on a
temporary file as the backend's graph; then `get_entity_by_name("alice",
"Alice")` and `get_relationships(...)` on that store.
- Observed result: on `e4a60ed7` the stored `relation_type` is
`['related_to']`; on this branch it is `['works_with']`. Both runs
return `success: True`.
- Not tested: the vector/text side of `LocalBackend` was stubbed (no
embedder offline), so the proof covers the graph write only. Not tested:
the mem0 and Qdrant/Neo4j backends, and `mypy headroom` as a whole.

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A
- Stable/default behavior changed: Yes, narrowly: a relationship saved
with the schema's `relation` key is stored with that relation type
instead of `related_to`. Relationships stored before this change keep
`related_to`.
- Kill switch / disable path: None added; revert.
- Unsafe override required: No
- Qualification impact: None expected
- Rollback path: revert this commit.

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

## Screenshots (if applicable)

N/A

## Additional Notes

One logical change per PR, as CONTRIBUTING asks: this covers item 7 of
#4362 only. Of the other items, 3 is fixed by #4365, 4 is #3308, and 8
is #4452.

Produced with AI assistance (Claude Code) operated by me (HetCreep); the
reproduction was run on my machine against a clone of the repository.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4647"
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 -->

### Maintainer qualification against current main

Qualified source head `0e29e3faa7a505431de80893915ab1fd7ff5fb02` against
upstream main `e4a60ed72f6ef5b28569f8bfbe2163cfda32c948`. 58 focused
relation, SQLite graph, and Gemini fixture tests passed. Independent
public MemorySystem(LocalBackend).process_tool_call("memory_save", ...)
ran through composed HierarchicalMemory/SQLite/HNSW/FTS and
SQLiteGraphStore. Reopening the graph preserved works_with on this PR;
actual main stored related_to for the identical schema-advertised
relation input. Both tool calls reported success. Deterministic
embeddings were used; no cloud or model-factory qualification is
claimed.

The maintainer cherry-picked only the shared Gemini test-fixture repair
from #4644: real Starlette Request with two ASGI receive chunks,
preserving the existing test assertions. This addresses the same four
independently verified failures on main; contributor production logic is
unchanged. Ruff, formatting, and whitespace checks passed. Exact-head
hosted CI is being checked before formal approval.

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 13:07:49 -06:00
ee638f9532 fix(memory): replace the HNSW vector when a memory is re-indexed (#4649)
## Description

Item 5 of #4362. `HierarchicalMemory.update`, `refresh` and `detach`
re-index a memory under the same id after its content, and so its
embedding, changed (`headroom/memory/core.py:493-504`, `:520-522`,
`:626`). On the HNSW backend that re-index never reached the graph:
`HNSWVectorIndex.index()` on an existing id went to
`_update_embedding_internal`, which only stored the new vector in the
`_embeddings` cache, and the update branch of `index_batch()` and
`update_embedding()` did the same (the docstrings said so). Search kept
matching the memory by its old content.

hnswlib's `add_items` with a label that already exists replaces that
element's vector in place: `addPointWithLevel` looks the label up and
calls `updatePoint` instead of adding a new element (nmslib/hnswlib
`hnswlib/hnswalg.h:1282-1305`, v0.9.0). All three paths now call it with
the memory's existing label. Ids, the id mappings and `size` are
unchanged.

Refs #4362

## 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/adapters/hnsw.py`:
- `_update_embedding_internal` calls `self._index.add_items(embedding,
[existing_label])` before updating the cache (covers `index()` on an
existing id and `update_embedding()`); docstring rewritten.
- `index_batch()`: the update branch writes all updated vectors with one
`add_items` call on their existing labels. Updates are first collapsed
by id, keeping the last entry, so a batch that names an id twice ends
with the graph, the cached embedding and the metadata on the same vector
(review round 2).
- `update_embedding()` docstring no longer says the graph keeps the
original vector.
- `tests/test_memory/test_hnsw_update_replaces_vector.py` (new, skipped
when hnswlib is absent, like the existing HNSW tests): for each of the
three paths, a memory moved from vector A to vector B is the top hit for
B with similarity 1.0, and `size` stays 2. Round 2 adds
`test_index_batch_repeated_id_ends_on_the_last_vector`.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`) (run on
`headroom/memory/adapters/hnsw.py` only, see below)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
# fail before (source at e4a60ed7, new test kept, hnswlib installed)
FAILED ...::test_index_on_existing_id_replaces_the_vector        (assert 'm2' == 'm1')
FAILED ...::test_update_embedding_replaces_the_vector
FAILED ...::test_index_batch_on_existing_id_replaces_the_vector
3 failed

# pass after (head 9668df0f): new test + tests/test_memory/test_hnsw_batch_capacity.py + tests/test_hnsw_only.py
12 passed

# round 2: the repeated-id test against the round-1 head 454c1c10, 20 runs
20 passed   (the out-of-order update did not reproduce here; the dedupe is a guard,
             not a fail-before fix)

# tests/test_memory + test_hnsw_only.py + test_memory_system.py + test_private_state_files.py
#   with hnswlib:    e4a60ed7 87 failed / 797 passed;  this branch 84 failed / 800 passed
#                    the 84 are the same on both sides: "sentence-transformers is required
#                    for LocalEmbedder" (not installed here); the 3 extra on e4a60ed7 are the new tests
#   without hnswlib: this branch 716 passed, 177 skipped

# ruff check / ruff format --check: All checks passed! / 2 files already formatted
# mypy headroom/memory/adapters/hnsw.py: Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: Ubuntu (WSL2) on Windows 11, Python 3.12.15, `headroom`
Python source at `e4a60ed7` and at this branch, offline. hnswlib: the
`chroma-hnswlib` 0.7.6 binary wheel (it installs the `hnswlib` module;
this machine has no C++ toolchain to build `hnswlib>=0.8.0` from
source). The re-add-replaces behaviour it shows is the same code path as
upstream v0.9.0 cited above.
- Exact command / steps: a real `HierarchicalMemory(SQLiteMemoryStore,
HNSWVectorIndex, FTS5TextIndex, embedder)` on a temporary database, with
a deterministic offline embedder that maps each phrase to its own unit
vector. Add `"user prefers tabs"`, `"deploys on fridays"`, `"uses
postgres"`; `update(<first id>, content="user prefers spaces")`; then
`search(query, top_k=1)` for the new and the old phrase.
- Observed result: on `e4a60ed7` the updated memory matches its old
content at similarity 1.000 and its new content at 0.000; on this branch
it is the other way round (table below).

  | query | `e4a60ed7` | this branch |
  |---|---|---|
| `"user prefers spaces"` (new content) | similarity 0.000 | similarity
1.000 |
| `"user prefers tabs"` (old content) | similarity 1.000 | similarity
0.000 |

On `e4a60ed7` the updated memory still matches its old content exactly
and does not match its new content.
- Not tested: `hnswlib` built from source at 0.8.x/0.9.x (only the
chroma wheel ran here), a real embedding model, and `mypy headroom` as a
whole. Persistence is unchanged: `save_index` writes the graph as
before, now with the replaced vector.

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A
- Stable/default behavior changed: Yes, on the opt-in HNSW backend only
(`VectorBackend.HNSW`, the `[vector]` extra): an updated memory is
searched by its new embedding. The default sqlite-vec backend is not
touched.
- Kill switch / disable path: None added; revert.
- Unsafe override required: No
- Qualification impact: None expected
- Rollback path: revert this commit.

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

## Screenshots (if applicable)

N/A

## Additional Notes

One logical change per PR, as CONTRIBUTING asks: this covers item 5 of
#4362 only (item 7 is #4647, item 10 is #4648). It does not touch item 4
(loading a persisted HNSW index at startup, #3308).

Produced with AI assistance (Claude Code) operated by me (HetCreep); the
reproduction was run on my machine against a clone of the repository.

🤖 Generated with [Claude Code](https://claude.com/claude-code)


### Maintainer qualification against current main

Qualified source head `0e798693966d65f3afc445b8f943e36db86e4471` against
upstream main `e4a60ed72f6ef5b28569f8bfbe2163cfda32c948`. 22 focused
tests passed with native hnswlib 0.8.0. An independent
HierarchicalMemory/SQLite/HNSW/FTS runtime with deterministic embeddings
changed an existing memory from tabs to spaces: new-vector similarity
1.0, old-vector similarity 0.0; saving and loading into a fresh index
preserved 1.0. Actual main retained the old vector (new 0.0, old 1.0,
reload new 0.0). Three labels and index size remained unchanged.
Duplicate batch IDs retain the last vector; this is a regression guard,
not a claimed reproduced race.

The maintainer cherry-picked only the shared Gemini test-fixture repair
from #4644: real Starlette Request with two ASGI receive chunks,
preserving the existing test assertions. This addresses the same four
independently verified failures on main; contributor production logic is
unchanged. Ruff, formatting, and whitespace checks passed. Exact-head
hosted CI is being checked before formal approval.

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 13:05:00 -06:00
Vaibhav HajareandJD Davis 4c820e8d51 fix: keep parent predicates when clearing a narrower memory scope (#4327)
## Description

`SQLiteMemoryStore.clear_scope()` used an `if/elif` chain, so it applied
only the deepest id it was given:

```python
if turn_id is not None:      # drops agent_id and session_id
elif agent_id is not None:   # drops session_id
elif session_id is not None:
```

An agent id or turn id reused across sessions therefore deleted memories
outside the requested session. The reproduction in the issue deletes
`s2`'s memory when asked to clear only `s1`:

```text
deleted: 2
s2 preserved: False
```

`session_id`, `agent_id` and `turn_id` are nested scopes, so each
narrower one must keep its parents. The `query` path (`sqlite.py` lines
443-458) already got this right for the same reason; `clear_scope` did
not.

Closes #4303

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

- `clear_scope()` now appends `session_id`, `agent_id` and `turn_id` as
independent narrowing constraints instead of an `if/elif` chain,
matching the query path.
- User-only, session-only and agent-only calls behave exactly as before;
only the over-deletion cases change.

## Testing

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

### Test Output

```text
Not run locally: this machine has no opentelemetry install, so headroom does
not import and the suite cannot be collected:

    ModuleNotFoundError: No module named 'opentelemetry'

Installing a toolchain is out of scope here, so I did not run pytest. GitHub
CI is the judge.
```

## Real Behavior Proof

- Environment: headroom source checkout, no third-party deps installed
- Exact command / steps: read `headroom/memory/adapters/sqlite.py`
`clear_scope` (line 823) and compared it to the `query` scope handling
(lines 443-458)
- Observed result: the `if/elif` chain emitted only the deepest
predicate, reproducing the issue's `deleted: 2` / `s2 preserved: False`
- Not tested: running the test suite (no `opentelemetry`)

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: no; only cases that previously
deleted too much now delete the right rows
- Kill switch / disable path: n/a
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert this commit

## 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
- [ ] 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
- [ ] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md`

## Additional Notes

- The regression test lives next to the existing `test_clear_scope` in
`tests/test_memory/test_hierarchical.py` and asserts the issue's exact
scenario (session `s1` + agent `planner` clears 1, `s2`'s row survives).
- "Unit tests pass locally" is unchecked because the suite cannot be
collected without `opentelemetry`.

## Model Used

MiniMax M3.1 Flash Free via the opencode agent harness
(`minimax-m3.1-flash-free`)

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4327"
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 -->

## Maintainer qualification (2026-11-04)

AI-assisted follow-up on Windows x64 / Python 3.12.13 after syncing main
31dcaf41f. All 98 core/hierarchical-memory tests pass, including the
previously blocked text-index regression. Lint, formatting and
whitespace checks pass. No contributor logic was changed; current main
resolves the inherited text-search interface problem. The existing
native binary was used rather than a fresh build.

I independently ran the standalone probe below with real SQLite, real
text/vector indexes and cached local embeddings, with offline mode
enabled. Clearing alice/planner/t1 deleted one row while t2 remained
stored and discoverable through both text and vector search. Clearing
alice/s1/planner deleted one row and preserved s2. No provider
credentials or production database was used.

Save as qualification.py in the checkout and run `python
qualification.py` with the local embedding model already cached:

```python
import sys,os,asyncio,json,uuid
from pathlib import Path
os.environ.update(HF_HUB_OFFLINE="1",HEADROOM_OFFLINE="1",HEADROOM_TELEMETRY="off")
from headroom.memory.config import MemoryConfig
from headroom.memory.core import HierarchicalMemory
from headroom.memory.ports import MemoryFilter
async def main():
 root=Path(".qualification-scope");root.mkdir(exist_ok=True)
 system=await HierarchicalMemory.create(MemoryConfig(db_path=str(root/(uuid.uuid4().hex+".db"))))
 try:
  memories=await system.add_batch([
   {"content":"planner t1","user_id":"alice","agent_id":"planner","turn_id":"t1"},
   {"content":"planner t2","user_id":"alice","agent_id":"planner","turn_id":"t2"},
   {"content":"s1 planner","user_id":"alice","session_id":"s1","agent_id":"planner"},
   {"content":"s2 planner","user_id":"alice","session_id":"s2","agent_id":"planner"}])
  assert await system.clear_scope(user_id="alice",agent_id="planner",turn_id="t1")==1
  assert await system.count(MemoryFilter(user_id="alice",agent_id="planner",turn_id="t2"))==1
  text=await system.text_search("planner t2",user_id="alice")
  vectors=await system.search("planner t2",user_id="alice",top_k=10)
  assert memories[1].id in [r.memory.id for r in text]
  assert memories[1].id in [r.memory.id for r in vectors]
  assert memories[0].id not in [r.memory.id for r in vectors]
  assert await system.clear_scope(user_id="alice",session_id="s1",agent_id="planner")==1
  assert await system.count(MemoryFilter(user_id="alice",session_id="s2"))==1
  print(json.dumps({"status":"PASS","storage":"real SQLite","embedding":"cached local model","turn_deleted":1,"surviving_turn_text_search":True,"surviving_turn_vector_search":True,"cross_session_survives":True}))
 finally:await system.close()
asyncio.run(main())
```

Observed result: PASS for storage, text-index preservation, vector-index
preservation and cross-session isolation. Hosted CI is tracked
separately.


### Maintainer current-main requalification

Exact head `43150c9fac9b294d3f03efa8d7959441d150c39c`, upstream main
`e4a60ed72f6ef5b28569f8bfbe2163cfda32c948`.

Updated against upstream/main e4a60ed7 and re-reviewed the
scope/index-cleanup discussion. Main now implements the intended fix
more generally: user/session/agent/turn query predicates are
independently applied, and clear_scope derives its deletion predicates
from the same builder with superseded versions included. Resolved the
overlap by retaining that main implementation and both contributor
regression tests. There is now no production-code delta against current
main; the PR retains additional regression coverage rather than
reintroducing a duplicate implementation.

All 106 focused core/hierarchical/scope-consistency tests pass using the
real cached local model. Independently reran the existing real
SQLite/local-embedding probe: clearing one turn preserves the surviving
turn in storage, text and vector search, and clearing one session
preserves the other. Ruff lint/format and whitespace checks pass. An
existing development native extension was used, not rebuilt; no
live-provider qualification is claimed. Applied the shared test-only
Gemini streamed-request fixture repair for independently established
main failures; all ten cases pass. Formal approval awaits exact-head
hosted qualification.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-11-05 10:40:15 -06:00
takiAAandJD Davis a8375a1d26 fix(memory): preserve parent scopes when clearing memories (#4305)
## Description

Closes #4303.

Clearing an agent within one session could also delete that agent's
memories in other sessions, while leaving their search entries behind.
Apply every supplied scope to both the ID query and the delete, so they
target the same records.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)

## Changes Made

- Share scope predicates between queries and clears, including agent +
turn without a session.
- Keep superseded records eligible for clearing.
- Add eight scope combinations using real SQLite, FTS5 and sqlite-vec
stores; check sibling records, cache reads and search results before and
after reopening.

## Testing

- [ ] Unit tests pass (`pytest`) — focused suites verified; no
full-suite claim.
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (repository mypy hook: `mypy headroom
--ignore-missing-imports`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
Unmodified main, new regression: 4 failed, 4 passed
Local fix, focused suites: 102 passed, 8 skipped
make ci-precheck-python: 177 passed, 4 skipped
Rust workspace fmt, clippy and tests: passed
Repository pre-commit hooks, including mypy: passed
ruff check .: All checks passed!
ruff format --check .: 1803 files already formatted
```

Focused command:
```bash
HEADROOM_OFFLINE=1 HEADROOM_BEACON=off python -m pytest \
  tests/test_memory/test_clear_scope_consistency.py \
  tests/test_memory/test_query_conditions.py \
  tests/test_memory/test_hierarchical.py \
  tests/test_memory/test_core_metadata_index_sync.py \
  tests/test_sqlite_vector_index.py \
  tests/test_memory/test_supersession_repair.py \
  tests/test_cli_memory_index_sync.py -q --no-cov
```

## Real Behavior Proof

- Environment: macOS 15.7.4 arm64, Python 3.13.5, temporary on-disk
SQLite/FTS5/sqlite-vec stores. Fixed 3D embeddings for index checks; no
model service or API credentials.
- Exact command / steps: save the standalone code in #4303 as
`/tmp/headroom-clear-scope.py`, then run `PYTHONPATH=. .venv/bin/python
/tmp/headroom-clear-scope.py` from the checkout. It stores two memories
with the same user/agent in different sessions and clears only `s1`.
- Observed result: main prints `deleted: 2` and `s2 preserved: False`;
this patch prints `deleted: 1` and `s2 preserved: True`. A separate
public-API run with real vector/text stores also preserves the sibling
and keeps search results consistent after reopening. User-only and
session-only controls remain correct.
- Not tested: live embedding quality, cloud backends, production proxy
traffic, Windows/Linux, or the entire Python test suite. Optional
HNSW/model-dependent tests were skipped. No claim that default user-wide
CLI clearing is affected.

## Runtime Rollout Safety

- Rollout-managed feature(s): none; existing SQLite memory API.
- Minimum rollout channel: existing memory users; no new channel.
- Stable/default behavior changed: scoped clearing preserves memories
outside the supplied scope.
- Kill switch / disable path: avoid granular clears; no new toggle.
- Unsafe override required: no.
- Qualification impact: scoped storage/index consistency; no model or
routing changes.
- Rollback path: revert this fix; no schema or data migration.

## 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 added tests that prove my fix is effective
- [x] I did not edit CHANGELOG.md

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4305"
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: JD Davis <mxjerrett@gmail.com>
2026-11-04 22:48:52 -06:00
662a7f6fd8 fix(memory): keep learned evidence until persistence succeeds (#4229)
## Description

Closes #4224 and #4226.

A full queue or failed save no longer makes the learner forget a pattern
permanently. Observations received while the save is queued or running
are included too. `min_evidence=1` saves the first sighting.

The review caught another case: SQLite can commit before vector indexing
fails or the task is cancelled. Retrying that save now reuses the
committed row rather than inserting a duplicate. If index repair fails
again, the pattern and its save token stay pending until repair
succeeds.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [x] Documentation update

## Changes Made

- Keep queued patterns as live evidence aggregates until persistence
completes.
- Retain the complete aggregate and its save-attempt token after
failure, cancellation or restart.
- Reconcile only the missing evidence. A delayed SQLite update from a
cancelled task cannot count the same observations twice or move
`last_seen_at` backwards.
- Add real SQLite regressions and document recovery behavior.

## Testing

- [ ] Unit tests pass (pytest) — complete changed learner file verified;
not the entire Python suite locally.
- [ ] Linting passes (ruff check .) — changed-file checks and normal
commit hooks passed.
- [ ] Type checking passes (mypy headroom) — normal mypy commit hook
passed.
- [x] Manual testing performed

### Test Output

```text
Complete tests/test_memory/test_traffic_learner.py:
230 passed in 16.40s
```

The complete learner file ran with the normal installed pytest plugins;
no test selection or warning filters were changed.

The normal full `make ci-precheck` pre-push gate also passed: Rust
formatting, clippy and workspace tests; native extension build; all 181
critical Python tests; commitlint. Rust tests used the supported
`RUST_TEST_THREADS=1` setting; no tests, timeouts or gates were changed
or bypassed.

## Real Behavior Proof

- Environment: Linux x86-64, Python 3.13.14, locally rebuilt native
extension, actual `LocalBackend` with `embedder_backend="onnx"`, SQLite,
and default cache/model settings. No live LLM provider requests.
- Exact command / steps: pass `No, use uv instead of pip for Python
packages.` through the public `TrafficLearner.on_messages` at threshold
three. Make the first three actual vector-index calls raise, then let
the fourth call the original index method. Add observations between
attempts; inspect SQLite, pending ownership and actual search after each
attempt. Persistence, embeddings, cache and retrieval are real; only the
failure boundary is controlled.

The learner tests also cover a rejected SQLite UPDATE, shutdown
continuing after one queued save fails, and index-refresh failure on
already-confirmed evidence.

- Observed result: all phase assertions passed and the standalone
process exited 0.

| Attempt | Rows | SQLite evidence | Pending | Search evidence |
| --- | ---: | ---: | --- | --- |
| Initial index failure | 1 | 3 | yes | not found |
| First repair failure | 1 | 5 | yes | not found |
| Second repair failure | 1 | 6 | yes | not found |
| Successful repair | 1 | 7 | no | 7 |

The original memory ID and save token survive failed repairs. Only the
successful repair marks the pattern saved. Normal evidence-only update
handling is unchanged.

- Not tested: live providers, model quality, Windows/macOS behavior, or
the entire Python suite. Hosted checks for this revision are not claimed
here.

## Runtime Rollout Safety

- Rollout-managed feature(s): none; existing live learning.
- Minimum rollout channel: unchanged.
- Stable/default behavior changed: failed writes retain evidence;
explicitly configured threshold one works; observations during saves are
no longer lost.
- Kill switch / disable path: `--no-learn` or existing memory
configuration.
- Unsafe override required: no.
- Qualification impact: actual persistence and retrieval verified
locally.
- Rollback path: revert the fix; no schema migration.

## 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 made corresponding changes to the documentation
- [x] I did not edit CHANGELOG.md — release-please owns it

## Additional Notes

AI-assisted; no subagents.

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4229"
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: JD Davis <mxjerrett@gmail.com>
Co-authored-by: Tejas Chopra <tejas@headroomlabs.ai>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 22:39:53 -06:00
ee2252a315 feat(mcp)!: port MCP servers to SDK 2.x (#4603)
## Description

Supersedes #2658 (`tejas/mcp-2x-port`, a draft with conflicts against
`main` since 2026-10-20). This is that PR's net diff rebased onto `main`
as one commit (originally `fc1ba891`, now `7e0094d6`; see below),
crediting Tejas Chopra and Jerrett Davis as co-authors, with three
changes needed on current `main`. Both MCP servers
(`headroom/ccr/mcp_server.py`, `headroom/memory/mcp_server.py`) move
from SDK 1's decorator API to SDK 2's constructor callbacks, as #2658
did. The `<2.0.0` cap from #2642 is then lifted.

Why now: current Claude Code tries the modern `server/discover`
handshake first. On SDK 1, `headroom mcp serve` rejects it and logs
`Failed to validate request: 31 validation errors for ClientRequest` on
stderr in every session. Claude Code then falls back to legacy
`initialize`, so the tools still work. On SDK 2 the modern handshake
succeeds and nothing is logged.

Changes relative to #2658:

1. **The floor is `mcp>=2.2.0,<3.0.0`, not `>=2.0.0`.** The GitHub
advisories mark `mcp` `>=2.0.0, <2.2.0` as affected by CVE-2026-59951
(the reason for #4239's `>=1.30.0` floor), CVE-2026-116684,
CVE-2026-116685 and CVE-2026-116686. #2658's lock resolved 2.1.1. The
contract test keeps `main`'s CVE guard for the 2.x line and rejects 3.x
(see #2977).
2. **`tests/test_ccr_mcp_http.py` is ported.** #1773 added it after
#2658 branched, and it fails on SDK 2: `streamable_http_client` now
takes an `httpx2.AsyncClient`, yields `(read, write)` without the
session-id getter, and its types are snake_case (`protocol_version`).
`headroom/ccr/mcp_http.py` itself needs no change.
3. **The lock is regenerated** with uv 0.9.30 (`uv lock
--upgrade-package mcp`, still `revision = 3`).

**Rebased onto main (`7e0094d6`), 2026-11-03.** The branch is now two
linear commits, with no merge commits:

- `ce4d6442` feat(mcp)!: port MCP servers to SDK 2.x (was `39c574c2`)
- `274f0672` fix(mcp): attribute SDK 2 clients by client_info, not
clientInfo (was `c7900848`)

The previous head was the merge `4c1b774f` (main `5c785e69` into the
branch), which carried the resolution against #4525
(GHSA-8g49-pg6g-xgrf, confining `headroom_read` to the workspace). The
rebase replays the port directly on top of #4525 instead. What it
changed:

- `headroom/ccr/mcp_server.py` conflicted with #4525 in two places: the
imports (#4525's `errno` next to the port's `contextvars`) and the tool
list, where #4525's workspace-scoped `headroom_read` schema met the
port's move from the `@list_tools` decorator to `_on_list_tools`. The
resolved file keeps both: SDK 2 callbacks and #4525's confinement and
`HEADROOM_MCP_READ_ROOTS` description. It is byte-identical to the file
in the previous merge head `4c1b774f`.
- `uv.lock` conflicted in one hunk with #4614's `mem0ai` bump: kept this
PR's `mcp>=2.2.0,<3.0.0` for the `mcp` and `proxy` extras and #4614's
`mem0ai>=2.0.18,<3.0`. `uv lock --check` resolves 253 packages.
- Every other file this PR touches is unchanged from `4c1b774f`. The
only difference in `pyproject.toml` and `uv.lock` against the previous
head is #4614's own diff, line for line.

The Strands blocker from the July review no longer applies:
`strands-agents` 1.63.0 declares `mcp<2.4,>=1.23.0`, and the lock
resolves `mcp` 2.3.0 with it.

Dependency justification (CONTRIBUTING, new dep or version bump):

| Package | Change | Source |
|---|---|---|
| `mcp` | 1.30.0 → 2.3.0 | modelcontextprotocol/python-sdk |
| `mcp-types` | new, 2.3.0 | same SDK; `mcp` 2.3.0 pins it `==2.3.0` |
| `httpx2`, `httpcore2` | new, 2.16.0 | pydantic/httpx2 (Tom Christie);
SDK 2's HTTP client |
| `httpx2-jsfetch` | new, 1.0 | only on `sys_platform == 'emscripten'`;
not installed elsewhere |
| `strands-agents` | 1.62.0 → 1.63.0 | first release that accepts `mcp`
2.2+ |
| `httpx-sse` | removed | SDK 1 only |
| `idna` | 3.15 → 3.20 | required by `httpx2` |

## Type of Change

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

## Changes Made

- `headroom/ccr/mcp_server.py`, `headroom/memory/mcp_server.py`:
register handlers as `on_list_tools` / `on_call_tool` constructor
callbacks, return `ListToolsResult` / `CallToolResult`, and read the
request context from the callback argument. These are #2658's changes,
including Jerrett's memory-backend cleanup hook.
- `pyproject.toml`: `mcp>=2.2.0,<3.0.0` in the `proxy` and `mcp` extras.
- `uv.lock`: relocked as described above.
- `tests/test_mcp_dependency_contract.py`: both extras must admit 2.2.0
and reject 1.30.0, 2.1.1 and 3.0.0.
- `tests/test_mcp_sdk2_contract.py`, `tests/_mcp_stub.py`,
`tests/test_mcp_stub.py`, `tests/test_memory/test_mcp_server.py`: from
#2658.
- `tests/test_ccr_mcp_http.py`: ported to the SDK 2 client. It reads the
session id from the `mcp-session-id` response header.
- `headroom/ccr/mcp_server.py` `_current_client`: read `client_info`
(SDK 2) instead of `clientInfo` (SDK 1), so `headroom_compress` savings
events name the client again. `tests/test_mcp_sdk2_contract.py` now
builds the SDK's own `InitializeRequestParams`; its old stand-in used
`clientInfo` and stayed green while every client was recorded as
`unknown`. Before and after, with an SDK 2.3 client named
`attribution-probe` over stdio: the ledger recorded `unknown` on both
`server/discover` and `initialize`, and now records `attribution-probe`
on both (found by Devin's review).

## Testing

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

### Test Output

After the rebase, on `274f0672`:

```text
# Python 3.11.17, mcp 2.3.0, strands-agents 1.63.0
$ pytest -q tests/test_mcp_dependency_contract.py tests/test_mcp_sdk2_contract.py tests/test_mcp_stub.py \
    tests/test_ccr_mcp_http.py tests/test_memory/test_mcp_server.py \
    <every test module that references mcp_server, GHSA or HEADROOM_MCP_READ_ROOTS, incl. tests/test_ccr_mcp_server.py>
840 passed, 2 skipped
$ uv lock --check
Resolved 253 packages
$ ruff check && ruff format --check on every changed .py file (ruff 0.17.2); git diff --check origin/main
clean
```

The wider 40-file mcp/strands run below was not repeated after the
rebase.

Before the rebase:

```text
# Python 3.11.17, uv sync --frozen --extra mcp --extra strands --extra proxy --extra otel (mcp 2.3.0, strands-agents 1.63.0)
$ pytest -q <every test module that references mcp, strands or the MCP servers: 40 files>
1163 passed, 31 skipped
$ pytest -q tests/test_ccr_mcp_http.py tests/test_mcp_dependency_contract.py tests/test_mcp_sdk2_contract.py
9 passed
$ pytest -q tests/integrations/test_strands tests/test_strands_tokenizer.py
80 passed, 25 skipped
$ uv run --with uv==0.9.30 python -m uv lock --check
Resolved 253 packages
$ ruff check && ruff format --check on every changed .py file (ruff 0.16.8); git diff --check origin/main
clean
# [all] export against the union of the extras it includes: no package missing
```

## Real Behavior Proof

- Environment: macOS 27 (arm64), Python 3.11.17; `main` `fc1ba891` (SDK
1.30.0) and this branch (SDK 2.3.0); temporary `HOME`; plus this branch
merged into my local runtime branch and installed as the `headroom` uv
tool.
- Exact command / steps: an SDK 2.3 stdio client starts `headroom mcp
serve`, calls `ClientSession.discover()` (`server/discover`, as Claude
Code does first), falls back to `initialize()` if that is rejected, then
lists tools and calls `headroom_stats`. The server's stderr is captured.
- Observed result: on `main`, `server/discover` is rejected with -32602
and the legacy `initialize` is used; stderr has 94 lines, starting
`WARNING: Failed to validate request: 31 validation errors for
ClientRequest`; 3 tools are listed and the call succeeds. On this branch
the modern `server/discover` is accepted and stderr has 0 lines; 3 tools
are listed and the call succeeds. The installed build behaves the same.
- Not tested: Windows; the memory MCP server against a live client (unit
and contract tests only); Strands agents against a live MCP server
(`tests/integrations/test_strands` and
`tests/test_strands_tokenizer.py`: 80 passed, 25 skipped); a real
network client against the Streamable HTTP transport (the ASGI contract
test only).

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a, dependency and server API change
- Stable/default behavior changed: yes; the MCP servers require SDK 2.2+
and speak the modern handshake; the tools and their JSON results are
unchanged
- Kill switch / disable path: none; pin `headroom-ai` to the previous
release to stay on SDK 1
- Unsafe override required: no
- Qualification impact: environments that pin `mcp<2` alongside
`headroom-ai[mcp]` or `[proxy]` no longer resolve
- Rollback path: revert this commit, which restores the `<2.0.0` cap

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

## Screenshots (if applicable)

N/A

## Additional Notes

Proposed on #2658
(https://github.com/headroomlabs-ai/headroom/pull/2658#issuecomment-6562744017).
If maintainers would rather keep #2658, `ce4d6442` and `274f0672`
(previously `39c574c2` and `c7900848`) can be cherry-picked onto
`tejas/mcp-2x-port` instead, and I'll close this.

`mypy headroom/ccr/mcp_server.py headroom/memory/mcp_server.py
headroom/ccr/mcp_http.py` with SDK 2.3 installed reports one error, in
`headroom/providers/model_metadata.py:79`, which `main` reports too;
none in the changed files. Full `mypy headroom` was not run. No docs
change: the MCP tool names, arguments and results are unchanged.

---------

Co-authored-by: Kenneth Wong <17061293+KennethWKZ@users.noreply.github.com>
Co-authored-by: Tejas Chopra <chopratejas@gmail.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-04 08:46:49 -06:00
d9cee45268 fix: [BUG] DirectMem0Adapter.search_memories calls removed mem0 search API (#4518)
<!-- oss-harness:v2 -->
Fixes #4246.

Focused Python fix for: [BUG] DirectMem0Adapter.search_memories calls
removed mem0 search API

Changed implementation: headroom/memory/backends/direct_mem0.py.
Regression tests: tests/test_memory/test_direct_mem0.py.

Verification (working directory `.`): `.venv/bin/python -m pytest -q -x
-p no:cacheprovider -- /workspace/tests/test_memory/test_direct_mem0.py`
- Patched code: 19 tests, zero failures/errors.
- Original code with the same regression tests: 1 failures, zero
collection/setup errors.
- Base commit: `f10725e6b9940d8bc2fcde950c86f8ac97543cb6`.

AI-assisted contribution: OpenCode using Autoloops wrote this patch. The
automated harness independently ran the tests listed above. No human
review is claimed.

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4518"
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: nandanadileep <116407139+nandanadileep@users.noreply.github.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Nandana Dileep <nandanadileep@users.noreply.github.com>
2026-11-04 08:33:51 -06:00
xiaoheiai4719-collabandJerrettDavis 3b8dfa5e3a fix(memory): dispatch core text search to the async FTS5 adapter (#4365)
## Description

`HierarchicalMemory.text_search()` passes a `TextFilter` to the built-in
FTS5 adapter's synchronous `search(str)` API, so a normal keyword query
fails before returning results.

The first version of this PR preferred `search_memories` whenever that
name existed. Further compatibility review found that this also changes
dispatch for a valid external `TextIndex` with an unrelated helper of
the same name. A synchronous helper raises a TypeError; an asynchronous
helper can silently return the wrong results. This was reproduced with a
constructed, fully conforming adapter, not reported as an incident in a
deployed third-party plugin.

This revision selects a typed search callable when the components are
wired together. The composition helper explicitly recognizes the
built-in FTS5 legacy contract; other adapters always use the declared
async `search(TextFilter)` method. The core search operation no longer
guesses from extra method names.

The factory still returns the same concrete index, and
`system.text_index` retains its identity. Direct FTS5 construction,
legacy synchronous search/index, async `index_memory`, and optional
`close` are unchanged. Method lookup stays lazy, preserving existing
index-only construction and post-construction method replacement. No
schema, dependency, configuration, or protocol change.

This is deliberately a search-only correction. It does not attempt a
broader cleanup of the existing FTS5/TextIndex indexing-signature
mismatch.


## Type of Change

- [x] Bug fix

## Changes Made

- Select a typed search callable at the composition boundary for the
built-in FTS5 legacy contract.
- Preserve declared `search(TextFilter)` dispatch for external adapters
regardless of incidental method names.
- Retain the raw index/factory identity, lazy method lookup, indexing
and close behavior, and legacy synchronous FTS5 API.
- Expand regression coverage for complete protocol adapters, name
collisions, identity/lifecycle controls, and actual SQLite searches.

## Testing

- [x] Expanded regressions fail on the original base and demonstrate
three compatibility failures in the first PR implementation.
- [x] Scoped memory/core/factory-adjacent checks pass with
optional-backend skips disclosed.
- [x] Full repository Ruff lint/format and changed core/factory mypy
pass.
- [x] The unchanged standalone real SQLite/factory/core runtime proof
passes on this corrected tree.
- [ ] Full repository and optional model/vector-backend qualification
completed.

### Test Output

Recorded terminal summaries for the corrected tree:

```text
65 passed, 53 skipped, 254 warnings in 0.89s
458 passed, 151 skipped, 432 warnings in 4.34s
```

- Original base with the expanded regression module: 10 failed, 5
passed.
- Prior PR implementation with the same module: 3 failed, 12 passed.
- Corrected focused memory/core/factory-adjacent run: 65 passed, 53
skipped.
- Three existing text-only factory test method bodies passed when
invoked directly. The factory module's global hnswlib skip otherwise
skips all 45 tests, so this is not a claim that the full factory suite
passed.
- Broader available memory/CLI run, using disposable HOME directories
and an isolated httpx dependency overlay: 458 passed, 151 skipped;
baseline 448 passed, 151 skipped. The broader baseline uses its original
test tree, so the ten additional candidate passes reflect the expanded
regression module. The same final 15-case module was tested separately
against both earlier implementations above. Two modules were excluded
for missing FastAPI/huggingface_hub dependencies.
- Full repository Ruff lint and format checks passed; changed
core/factory mypy passed. Full pytest and full-project mypy remain
unqualified.

The regressions cover factory/direct FTS5 construction, user/session
isolation, limits and unmatched text, result types/ranks, unchanged
synchronous search, external synchronous/asynchronous/noncallable name
collisions, original object identity, indexing, close, and method
replacement after construction.


## Real Behavior Proof

- Environment: Linux, CPython 3.12.14, SQLite FTS5, real temporary
SQLiteMemoryStore and factory-created FTS5TextIndex. No mocks, embedder,
model inference, or provider requests.
- Exact command / steps: Saved this script and ran `PYTHONPATH=. python
/path/to/proof.py` from both original and patched checkouts:

```python
import asyncio
import tempfile
from pathlib import Path

from headroom.memory.adapters.sqlite import SQLiteMemoryStore
from headroom.memory.config import MemoryConfig
from headroom.memory.core import HierarchicalMemory
from headroom.memory.factory import _create_text_index
from headroom.memory.models import Memory

async def main():
    with tempfile.TemporaryDirectory() as directory:
        path = Path(directory) / "memory.db"
        store = SQLiteMemoryStore(path)
        text_index = _create_text_index(MemoryConfig(db_path=path))
        for user, session in [("alice", "one"), ("alice", "two"), ("bob", "one")]:
            memory = Memory(id=f"{user}-{session}", content="Python preferences", user_id=user, session_id=session)
            await store.save(memory)
            await text_index.index_memory(memory)
        # This is the text-only dependency chain; no vector index or embedder is used.
        memory_system = HierarchicalMemory(store, None, text_index, None)
        results = await memory_system.text_search("Python", user_id="alice", session_id="one")
        assert [result.memory.id for result in results] == ["alice-one"]
        print("Filtered core text_search:", [result.memory.id for result in results])
        limited = await memory_system.text_search("Python", user_id="alice", limit=1)
        assert len(limited) == 1 and limited[0].memory.user_id == "alice"
        print("Result limit preserved:", len(limited))
        assert await memory_system.text_search("unmatched", user_id="alice") == []
        print("Unmatched query: []")
        raw = text_index.search("Python", k=10)
        assert len(raw) == 3
        print("Legacy synchronous FTS5 search still returns all three records:", len(raw))

asyncio.run(main())

```

- Observed result: The original base exits with TypeError while FTS5
sanitizes a TextFilter as a string. The same proof was rerun unchanged
against this revised implementation, which returns the correct
user/session-scoped record, honors the limit, returns an empty list for
unmatched text, and preserves the legacy API:

```text
Filtered core text_search: ['alice-one']
Result limit preserved: 1
Unmatched query: []
Legacy synchronous FTS5 search still returns all three records: 3
```

- Not tested: Full repository suite, hnswlib and sentence-transformers
optional suites, live vector/model backends, hosted providers, or full
dependency-wide static analysis. The proof exercises the actual
text-only path without embedding inference.


A separate constructed external adapter implements every TextIndex
method and also defines an unrelated synchronous `search_memories`. The
revised core returns its declared async-search result, forwards all
filter fields unchanged, and never calls that helper. The expanded
regression module also checks asynchronous and noncallable extra
attributes; these are constructed protocol counterexamples, not a
reported deployed-plugin incident.

## Runtime Rollout Safety

- Rollout-managed feature(s): None; existing HierarchicalMemory
text-only search.
- Minimum rollout channel: Normal release after maintainer
qualification.
- Stable/default behavior changed: Built-in FTS5 text searches return
results instead of raising TypeError. External adapters use their
declared protocol search even when they expose unrelated
`search_memories` attributes.
- Kill switch / disable path: No new flag. Existing external text
backend selection remains available.
- Unsafe override required: No.
- Qualification impact: Scoped SQLite/runtime, compatibility, lint and
type checks pass; optional backend and full repository qualification
remain outstanding.
- Rollback path: Revert the PR changes. No schema, dependency, or
configuration changes.

## Review Readiness

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

Ready for human review. The current PR delta was re-reviewed with AI
assistance after upstream main was synchronized; the contributor patch
was unchanged at that review. A subsequent declared-async FTS5
correction has now been independently reviewed with AI assistance; its
validation scope is recorded below. Historical tests and
reviewer-reported checks remain scoped as documented below; this is not
a claim of full-suite/native/provider qualification or merge approval.

## Checklist

- [x] Expanded regression cases demonstrate the original failure and the
first implementation's external-adapter collision.
- [x] Changed source and tests pass lint and formatting.
- [x] CHANGELOG.md was not edited.
- [ ] Full repository qualification completed.

## Additional Notes

Implemented and tested with OpenAI AI assistance. Checked test items
describe executed verification, not a claim that the publication owner
personally ran it. No live model/provider, other operating-system,
full-project mypy, or hosted CI result is claimed for this revision.

## Follow-up verification (2026-10-24)

Follow-up head: ae4db40ed1. Preserve
declared-async FTS5 search overrides and runtime API replacements while
keeping legacy FTS5 dispatch and index identity. AI-assisted
verification: 69 focused tests passed/53 skipped; the available memory
suite passed 438 tests/145 skipped, with two unavailable-dependency
modules excluded. Checks used a cached snapshot with five relevant files
verified against the pre-correction PR head, not a full current-tree or
native/provider qualification. This does not claim compatibility with
arbitrary synchronous functions returning awaitables, wrappers hiding
async behavior, or every external plugin. LocalBackend dispatch is
unchanged. The prior approval covered 7ad8574d, not this new head.

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-04 08:32:27 -06:00
fe69f38116 fix(privacy): turn off Mem0's PostHog telemetry by default (#4619)
## Description

Turns off Mem0's PostHog usage telemetry by default for Headroom's
memory-stack backends.

Mem0 sends `mem0.init`, `mem0.add`, `mem0.search` and
`mem0.notice_displayed` events to `https://us.i.posthog.com` unless
`MEM0_TELEMETRY` is false. The events carry config, OS and version
fields plus hashed entity ids, but no memory text or queries. It is on
by default in every Mem0 release we lock (2.0.5 and 2.2.1). Found while
collecting runtime evidence for #4614.

Same approach as #4602 (ONNX Runtime): `setdefault`, so an explicit
caller value wins.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)

## Changes Made

- `headroom/memory/backends/mem0.py`:
`disable_mem0_telemetry_by_default()` sets `MEM0_TELEMETRY=False` unless
already set. `Mem0Backend._ensure_client` calls it before `from mem0
import Memory`.
- `headroom/memory/backends/direct_mem0.py`: `DirectMem0Adapter` calls
it before its `from mem0 import Memory`. These are the only two mem0
imports in `headroom/`.
- `docs/content/docs/installation.mdx`: the `memory-stack` row says
telemetry is off and how to allow it.

Mem0 reads the variable once, when `mem0.memory.telemetry` is imported.
A host process that imported mem0 before Headroom must set it itself;
the docstring says so.

## Testing

- [x] Unit tests pass (`pytest`):
`tests/test_memory/test_mem0_telemetry.py
tests/test_memory/test_direct_mem0.py
tests/test_memory/test_mem0_system_adapter_deprecation.py` → 28 passed
- [x] Linting passes (`ruff check`, `ruff format --check` on
`headroom/memory tests/test_memory`)
- [x] Type checking: `mypy headroom/memory/backends/mem0.py` reports 9
errors, identical on `main` (`direct_mem0.py:203`, `embedders.py:389`)
- [x] New tests added: backend sets the default before importing mem0,
caller value wins, real mem0 reads the default as disabled
- [x] Manual testing performed

### Test Output

```text
28 passed in 1.62s
# on main (new test file only):
FAILED test_mem0_telemetry.py::test_backend_turns_mem0_telemetry_off_before_importing_mem0
FAILED test_mem0_telemetry.py::test_real_mem0_reads_the_default_as_disabled
2 failed, 1 passed
```

## Real Behavior Proof

- Environment: macOS arm64, Python 3.12.13, mem0ai 2.2.1, posthog
7.81.2, Qdrant 1.15.5 in Docker, OpenAI replaced by a local stub.
- Steps: patched `posthog.Posthog.capture` to record instead of send,
then ran a `Mem0Backend` save and search.
- Observed before: `mem0.init`, `mem0.add`, `mem0.search`,
`mem0.notice_displayed` captured, with properties like `client_version`,
`collection`, `embedding_model`, `encoded_ids`, `os`, `python_version`,
`vector_store`.
- Observed after: `test_real_mem0_reads_the_default_as_disabled` imports
the real `mem0.memory.telemetry` in a clean subprocess and reads
`MEM0_TELEMETRY == False`. Mem0's capture path returns early when it is
false.
- Not tested: Mem0 cloud mode (`Mem0Config(mode="cloud")`), which talks
to Mem0's hosted API regardless.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: N/A
- Stable/default behavior changed: yes, Mem0 telemetry is no longer sent
by default. Memory behavior is unchanged.
- Kill switch / disable path: `MEM0_TELEMETRY=True` restores Mem0's
default
- Unsafe override required: no
- 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] I did **not** edit `CHANGELOG.md`

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4619"
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-03 18:25:49 -06:00
Tejas ChopraandClaude Opus 5.5 7e0094d6c8 fix(deps): bump mem0ai, langgraph and langgraph-sdk past open advisories (#4614)
## Description

Clears Dependabot alerts #546, #547 and #548, which Vanta's dependency
vulnerability test flags.

| Package | Before | After | Advisory |
|---|---|---|---|
| mem0ai | 2.0.18 | 2.2.1 | GHSA-5324-3w58-qpp2 (fixed in 2.0.18) |
| langgraph | 1.2.11 | 1.2.19 | GHSA-3fx2-cqw9-xr3c (fixed in 1.2.14) |
| langgraph-sdk | 0.4.6 | 0.4.11 | GHSA-3fx2-cqw9-xr3c (fixed in 0.4.6)
|

#4537 (Dependabot) has since moved `main` to mem0ai 2.0.18,
langgraph-sdk 0.4.6 and posthog 7.79.0, and fixed `Mem0Backend`'s
identity filters. Merged on top of that, this PR still bumps langgraph
past GHSA-3fx2-cqw9-xr3c (1.2.11 → 1.2.19, plus langgraph-checkpoint
4.2.0 → 4.3.1), raises the install-time floors, passes `top_k` to
`Mem0Backend.search`, and fixes `DirectMem0Adapter`, which #4537 did not
touch. posthog stays at 7.79.0. No package is added or removed from the
lock.

The runtime proof below found that Headroom's Mem0 search was already
broken on `main`. Mem0 2.x (including the 2.0.5 we locked) raises
`ValueError` when `user_id` is passed at the top level of `search()` /
`get_all()`. So the second commit fixes the call sites. Without it, the
upgrade could not be shown to work.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)

## Changes Made

- `uv lock --upgrade-package mem0ai --upgrade-package langgraph
--upgrade-package langgraph-sdk`
- `pyproject.toml`: floors raised to `mem0ai>=2.0.18` (memory-stack
extra) and `langgraph>=1.2.14` (langgraph extra), so a fresh PyPI
install can't resolve a vulnerable version. `langgraph-sdk>=0.4.6` comes
transitively from langgraph 1.2.14+.
- `headroom/memory/backends/direct_mem0.py`, `mem0.py`: pass `user_id`
inside `filters=` and the limit as `top_k=` to Mem0 `search()` /
`get_all()`. Direct Qdrant writes also store the fact under `data`, the
payload key Mem0 search reads. Points without it were skipped.

## Dependency review (CONTRIBUTING.md)

| | mem0ai 2.2.1 | langgraph 1.2.19 / sdk 0.4.11 / checkpoint 4.3.1 |
posthog 7.79.0 |
|---|---|---|---|
| Why this package | Already a dependency of the optional `memory-stack`
extra | Already a dependency of the optional `langgraph` extra | Not
ours: required by mem0ai |
| Who maintains it | Mem0 (Apache-2.0); 8 releases in the last 90 days,
latest 2026-09-25 | LangChain (MIT); 9 langgraph releases in 90 days,
latest 2026-10-30 | PostHog (MIT); very frequent releases (107 in 90
days) |
| Security history | GHSA-5324-3w58-qpp2 fixed in 2.0.18; PyPI lists no
advisories against 2.2.1 | GHSA-3fx2-cqw9-xr3c fixed in 1.2.14 / sdk
0.4.6; none against the locked versions | None listed against 7.79.0 |
| Native code | None (pure-Python wheel) | None (pure-Python wheels) |
None (pure-Python wheel) |
| Install-time network | None beyond the package index | None | None |
| Runtime network | OpenAI (LLM + embeddings) and Qdrant/Neo4j, as
configured. Also anonymous telemetry to `https://us.i.posthog.com`, on
by default unless `MEM0_TELEMETRY=False` (same as 2.0.5, see below) |
None for graph execution; `langgraph-sdk` only talks to a LangGraph
server if a client is created (Headroom does not) | Used only by mem0
telemetry |
| Why this version | Security patch | Security patch | Pulled by the
mem0 security patch |

Lock: the `python-socks` line that now appears under `lean` is uv
flattening the existing `proxy` extra that `lean` already includes. `uv
lock --check` passes on `main`, and the set of resolved packages is
unchanged (only the five versions above differ).

## Testing

- [x] Unit tests pass: `pytest tests/test_memory
tests/test_integrations/langchain/test_langgraph.py
tests/integrations/test_langgraph.py` → 676 passed
- [x] Linting passes: `ruff check` and `ruff format --check` on the
touched paths
- [x] Type checking: `mypy headroom/memory/backends` reports 8 errors at
`direct_mem0.py:202`, identical on `main` (not from this change)
- [x] New test: `test_search_scopes_by_user_through_filters` fails on
`main` (`search` called with top-level `user_id`/`limit`), passes here
- [x] Manual testing performed (below)

## Real Behavior Proof

**Environment:** macOS arm64, Python 3.12.13, uv 0.12.5. Qdrant 1.15.5
in Docker (`qdrant/qdrant:v1.15.5` on 127.0.0.1:16333). Real `mem0ai
2.2.1`, `qdrant-client 1.17.1`, `posthog 7.79.0` (rerun after merging
`main`). The OpenAI API is replaced by a local OpenAI-compatible stub
(`OPENAI_BASE_URL=http://127.0.0.1:18099/v1`) that returns deterministic
bag-of-words embeddings and a canned extraction. So Mem0, Qdrant and
Headroom code are real, and the LLM is not.

**Mem0 round trip through Headroom** (`DirectMem0Adapter` and
`Mem0Backend`, graph disabled):

```text
optimized save: Memory id ok                          # facts written straight to Qdrant
optimized search top: The billing service is written in Rust 0.802
other user sees: 0                                     # user scoping holds
fallback (Mem0 LLM extraction) save: Memory
fallback search top: The deploy region is eu-west-1
delete: True get after delete: None
Mem0Backend save: True
Mem0Backend search top: The deploy region is eu-west-1
Mem0Backend search other user: 0
Mem0Backend get_all_memories: ['The deploy region is eu-west-1']
```

Before the second commit, the same script failed on the first search
with `ValueError: Top-level entity parameters frozenset({'user_id'}) are
not supported in search()`. Unpacking mem0ai 2.0.5 and calling
`search(user_id=..., limit=...)` raises the same error, so this was
broken on `main` too. Once the call was fixed, search returned `[]`
until facts were also written under `data`.

**LangGraph invocation** (`StateGraph` agent → tool →
`create_compress_tool_messages_node()` → model, `InMemorySaver`
checkpointer) on langgraph 1.2.19 / checkpoint 4.3.1:

```text
final: done | checkpoint resumed messages: 5
tool chars before: 30690 after compress node: 17933
```

**Pre/post dependency resolution** (`uv pip compile` of the extra's
requirement with a vulnerable pin as a constraint):

```text
pre   mem0ai>=2.0.0,<3.0     + mem0ai==2.0.17     => resolves
pre   langgraph>=1.0,<2.0    + langgraph==1.2.13  => resolves
post  mem0ai>=2.0.18,<3.0    + mem0ai==2.0.17     => rejected (Because you require mem0ai>=2.0.18,<3.0 and mem0ai==2.0.17 ...)
post  langgraph>=1.2.14,<2.0 + langgraph==1.2.13  => rejected (Because you require langgraph>=1.2.14,<2.0 and langgraph==1.2.13 ...)
```

This is the regression check for the floors. A pytest that reads
`pyproject.toml` would only restate the constants. The behavioural
regression test is the Mem0 search test above.

**Mem0 telemetry, observed** (PostHog `capture` patched to record
instead of send): `mem0.init`, `mem0.add`, `mem0.search` and
`mem0.notice_displayed` events. Properties are config/OS/version fields
plus `encoded_ids` and `keys`; no memory text or query. 2.0.5 has the
same default (`MEM0_TELEMETRY` defaults to `True`, same host), so this
is not new with the bump.

**Remaining limitations**
- Real OpenAI not exercised (stub). Neo4j graph path not exercised
(`enable_graph=False`).
- Existing Qdrant points written by the old direct path lack `data` and
stay invisible to Mem0 search until re-saved.
- Found while testing, not fixed here (pre-existing on langgraph 1.2.11
too): the compress node returns a new `ToolMessage` without the original
`id`, so `add_messages` appends a compressed copy next to the original
instead of replacing it (5 messages instead of 4). Will follow up
separately.
- Headroom does not set `MEM0_TELEMETRY=False` for memory-stack users.
Separate decision.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: N/A
- Stable/default behavior changed: no; optional `memory-stack` /
`langgraph` extras only. Mem0 search goes from always raising to
working.
- Kill switch / disable path: N/A
- Unsafe override required: no
- 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] I did **not** edit `CHANGELOG.md`

## Additional Notes

The undici, ip-address, glob and minimatch npm audit failures
(`e2e/wrap/tools`, `plugins/opencode`) and the
`test_v1_compress_timeout_fails_open_quickly` timing failure also fail
on `main` and are not touched here.

🤖 Generated with [Claude Code](https://claude.com/claude-code)



## Independent review proof

Independently re-reviewed exact head
`3c326036a93a95378114f3f7e47f66471663aaf1` on Windows / CPython 3.12.13.
No new code finding. These checks supplement the author's evidence
above.

Runtime versions: mem0ai 2.2.1, langgraph 1.2.19, langgraph-sdk 0.4.11,
langgraph-checkpoint 4.3.1, langgraph-prebuilt 1.1.0, posthog 7.79.0,
qdrant-client 1.17.1, ormsgpack 1.12.2, xxhash 3.6.0; genuine MiniLM
embeddings through sentence-transformers 5.2.1. The review used an
isolated environment inheriting existing project/embedding dependencies,
with the listed upgrade/framework packages installed separately at their
locked versions. Source imports were verified against the exact-head
checkout. It did not rebuild or recreate every dependency in the full
lock.

For a fresh reproduction, check out the exact head, install/build
Headroom with its `memory-stack`, `langgraph` and development extras
using `uv sync --locked --extra dev --extra memory-stack --extra
langgraph`, and make sentence-transformers 5.2.1 available in the
selected interpreter. This clean bootstrap is a reproduction recipe, not
a claim that the review rebuilt the native extension. Run the following
commands with that interpreter, from the repository root:

```powershell
$env:PYTHONPATH = (Get-Location).Path
python scripts/verify_mem0_agent_scope.py
python scripts/verify_mem0_tenant_scope.py
python scripts/verify_mem0_dependency_boundaries.py
```

All three public committed proof scripts passed: each agent retrieved
its own persisted memory and excluded its sibling; get_all/query
excluded unrelated users; distinct identity tuples generated different
SQLite scope keys and the other tenant retrieved zero messages; SDK
identifiers remained one encoded path segment against an actual loopback
HTTP server; telemetry opt-out created no client/event, and enabled
PostHog capture/shutdown delivered one event to loopback only. MiniLM
weights may require an initial Hugging Face download.

Two additional full diagnostics follow. Save their code as
`review_direct.py` and `review_langgraph.py` outside tracked source,
then run `python review_direct.py` and `python review_langgraph.py` with
the same interpreter and repository-root PYTHONPATH. No OpenAI
credentials are required. These are review diagnostics, not changes to
contributor logic.

<details>
<summary>DirectMem0 actual changed write/search methods: complete
diagnostic</summary>

```python
import asyncio
import os
import tempfile
from importlib.metadata import version

os.environ['MEM0_TELEMETRY'] = 'false'
os.environ['HF_HUB_DISABLE_TELEMETRY'] = '1'
from mem0 import Memory as Mem0
from headroom.memory.backends.direct_mem0 import DirectMem0Adapter, Mem0Config

async def main():
    with tempfile.TemporaryDirectory(prefix='headroom-direct-proof-') as path:
        client = Mem0.from_config({
            'version': 'v1.1',
            'llm': {'provider': 'openai', 'config': {'api_key': 'unused-no-inference'}},
            'embedder': {'provider': 'huggingface', 'config': {
                'model': 'sentence-transformers/all-MiniLM-L6-v2', 'embedding_dims': 384}},
            'vector_store': {'provider': 'qdrant', 'config': {
                'path': path, 'collection_name': 'direct_proof', 'embedding_model_dims': 384}},
            'history_db_path': path + '/history.db'})
        adapter = DirectMem0Adapter(Mem0Config(enable_graph=False, collection_name='direct_proof'))
        adapter._mem0_client = client
        adapter._qdrant_client = client.vector_store.client
        adapter._initialized = True
        # Use the genuine local MiniLM embedder rather than an OpenAI request.
        adapter._embed = lambda text: client.embedding_model.embed(text, 'add')
        fact = 'The billing service is written in Rust'
        ids = await adapter._write_facts_to_qdrant([fact], 'tenant-a', 0.8)
        point = adapter._qdrant_client.retrieve('direct_proof', ids)[0]
        assert point.payload['data'] == fact
        results = await adapter.search_memories(query='billing service programming language', user_id='tenant-a', top_k=1)
        assert len(results) == 1 and results[0].memory.content == fact, results
        assert await adapter.search_memories(query='billing service programming language', user_id='tenant-b', top_k=1) == []
        print(f'mem0ai={version("mem0ai")}: real direct Qdrant data payload, MiniLM search, top_k=1 and tenant isolation PASS')
        client.vector_store.client.close()
        client.db.connection.close()

asyncio.run(main())

```

Observed exit 0: `mem0ai=2.2.1: real direct Qdrant data payload, MiniLM
search, top_k=1 and tenant isolation PASS`. This uses the genuine local
embedder in place of OpenAI transport; it executes Headroom's actual
direct Qdrant write and Mem0 search methods.

</details>

<details>
<summary>Real StateGraph / Headroom compression / checkpoint: complete
diagnostic</summary>

The optional `HEADROOM_REVIEW_NATIVE_CORE` variable lets an existing
compatible native extension be reused. The Windows review pointed it to
an already-built local `_core.pyd`; with a normally built Headroom
checkout, leave it unset. This review did not qualify a fresh native
build.

```python
import importlib.util
import json
import os
import sys
from importlib.metadata import version
import headroom

if os.environ.get('HEADROOM_REVIEW_NATIVE_CORE'):
    spec = importlib.util.spec_from_file_location('headroom._core', os.environ['HEADROOM_REVIEW_NATIVE_CORE'])
    native = importlib.util.module_from_spec(spec)
    sys.modules['headroom._core'] = native
    spec.loader.exec_module(native)
    headroom._core = native

from langchain_core.messages import HumanMessage, AIMessage, ToolMessage
from langgraph.graph import StateGraph, MessagesState, START, END
from langgraph.checkpoint.memory import InMemorySaver
from headroom.integrations.langchain.langgraph import create_compress_tool_messages_node

content = json.dumps([{'id': i, 'status': 'healthy', 'region': 'us-east-1', 'latency_ms': i % 11, 'detail': 'routine health check'} for i in range(300)])
observed = {}
compress = create_compress_tool_messages_node(min_tokens_to_compress=100)

def agent(state):
    return {'messages': [AIMessage(content='', tool_calls=[{'name': 'health', 'args': {}, 'id': 'call-1'}])]}

def tool(state):
    return {'messages': [ToolMessage(content=content, tool_call_id='call-1', name='health')]}

def compression(state):
    out = compress(state)
    tools = [m for m in out['messages'] if isinstance(m, ToolMessage)]
    observed['after'] = len(tools[-1].content)
    assert observed['after'] < len(content), observed
    return out

graph = StateGraph(MessagesState)
graph.add_node('agent', agent)
graph.add_node('tools', tool)
graph.add_node('compress', compression)
graph.add_node('model', lambda state: {'messages': [AIMessage(content='done')]})
graph.add_edge(START, 'agent')
graph.add_edge('agent', 'tools')
graph.add_edge('tools', 'compress')
graph.add_edge('compress', 'model')
graph.add_edge('model', END)
app = graph.compile(checkpointer=InMemorySaver())
config = {'configurable': {'thread_id': 'review-4614'}}
result = app.invoke({'messages': [HumanMessage(content='Check service health')]}, config)
assert result['messages'][-1].content == 'done'
snapshot = app.get_state(config)
assert snapshot.values['messages'][-1].content == 'done'
print(f'langgraph={version("langgraph")}; checkpoint={version("langgraph-checkpoint")}; final=done; restored_messages={len(snapshot.values["messages"])}; tool_chars={len(content)} -> {observed["after"]}; PASS')

```

Observed exit 0: `langgraph=1.2.19; checkpoint=4.3.1; final=done;
restored_messages=5; tool_chars=32317 -> 13791; PASS`. An isolated
baseline environment with langgraph 1.2.11 / checkpoint 4.2.0 / SDK
0.4.6 produced the identical five restored messages and compression
sizes, exit 0. Thus the disclosed duplicate ToolMessage behavior is
inherited rather than introduced by this upgrade.

</details>

Additional validation: focused memory/LangGraph suite yielded 674
passed, 3 skipped, 8 failures. All eight failures reproduced on current
main `74277d47ecfbca349ddb99f81094c4dd30539d43`: six optional
embedding/configuration failures and two Windows/POSIX-path assumptions.
`uv lock --check --offline` and whitespace verification passed. Required
current-head GitHub checks were all successful when this review was
submitted.

Limits: local embedded Qdrant; no real OpenAI inference or Neo4j graph
path. Optional spaCy models were absent and Mem0 emitted warnings. Full
lock/native rebuild and live cloud infrastructure were not exercised by
these independent diagnostics.

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 13:21:42 +05:30
5c785e6938 chore(deps): bump the uv group across 1 directory with 2 updates (#4537)
Mem0's recent-conversation cache can mix distinct Headroom tenant
identities when an agent/user ID contains `&` or `=`. In the published
mem0ai 2.0.5 code, `(agent_id="alpha&user_id=beta", user_id="gamma")`
and `(agent_id="alpha", user_id="beta&user_id=gamma")` produce the same
cache key. Writing the first tenant's messages to Mem0's actual SQLite
conversation store makes them retrievable through the second tenant's
key. Mem0 2.0.18 escapes those delimiters and prevents that collision.

Upgrade the dependency and adapt Headroom to its stricter identity API:
save agent_id as an identity argument, search/list with identity
filters, use get_all's top_k argument, and restore promoted response
identities with a fallback for older metadata layouts. Otherwise the
upgraded library strips scope metadata, rejects search arguments, and
silently breaks the adapter's listing/query paths. Explicit search
user_id retains precedence over the filter's user_id.

## Dependency assessment

- **mem0ai 2.0.5 -> 2.0.18:** fixes the demonstrated tenant-buffer
isolation bug in a path used by the optional conversational-memory
backend. Headroom accepts these identifier strings; assuming they never
contain reserved characters would not be a safe substitute. The two old
Python source files were compared byte-for-byte with the SHA256-verified
public 2.0.5 wheel before reproducing the leak. [Release notes and fix
#6892](https://github.com/mem0ai/mem0/releases/tag/v2.0.18) describe
delimiter escaping and the one-time reset of recent buffers for IDs
containing `%`, `&`, or `=`. Persisted memory records are unaffected.
The independent 2.0.5 reproduction is the reason for this update; it
does not rely on interpreting the narrower version range in the upstream
security advisory as covering 2.0.5.
- **langgraph-sdk 0.4.4 -> 0.4.6:** fixes thread/assistant IDs being
interpreted as URL paths, query strings, or fragments in the stream
state's REST helpers. [Upstream fix
#9213](https://github.com/langchain-ai/langgraph/pull/9213)
percent-encodes these identifiers. A real loopback HTTP test with
`tenant/../other?query#fragment` reproduced wrong paths on 0.4.4 and
verified one encoded path segment on 0.4.6. This is an optional
graph-client dependency; the proof exercises its real transport helpers
directly, not a claim that Headroom's local LangGraph hook calls a cloud
API.
- **posthog 5.4.0 -> 7.79.0:** a required transitive major update, since
the new Mem0 distribution declares `posthog>=7.14.0`. Keep the locked
compatible 7.79.0 resolution rather than retaining a version outside
that requirement. The real 7.79.0 client passes capture/shutdown against
a loopback endpoint, and Mem0's actual opt-out creates no telemetry
client/event. This is not an independent new analytics feature for
Headroom.
- **Maintenance/security:** Mem0 is maintained by mem0ai (2.0.18
released August 11), the graph SDK by LangChain (0.4.6 released October
6), and PostHog's client by PostHog (7.79.0 uploaded October 28). Public
release/source history and Mem0's published security advisory were
reviewed. PyPI's current 0.4.6/7.79.0 responses list no vulnerability
entries; this is not a guarantee about all upstream security history.
Current branch hosted dependency audits passed before the proof-only
follow-up commit; current-head qualification remains required.
- **Install/runtime surface:** these updated distributions have
Python-only wheels; the lock package set is unchanged and these three
are the only Python package-version changes. Existing
embedding/vector/LLM dependencies still have native components, model
downloads and provider/storage network access. LangGraph SDK uses the
existing HTTP/serialization dependencies. PostHog's mandatory runtime
dependencies are requests, backoff, distro and typing-extensions;
optional async, zstd, OpenTelemetry and development/test extras are not
enabled by this update. Mem0 telemetry remains opt-out and can send
metadata/feature-flag requests to PostHog when enabled.
Exception/code-variable autocapture is not enabled by Headroom or this
change. The proof's telemetry opt-outs are test settings, not a
production-default change or a claim of blocked production egress.

The branch also carries the reviewed glob/minimatch remediation from
#4599 (now merged upstream). Its eight exact bundled advisory/path
exceptions and November 15 expiry remain unchanged.

## Real behavior proof

Windows / Python 3.12.13 with mem0ai 2.0.18, langgraph-sdk 0.4.6 and
posthog 7.79.0 explicitly installed. Actual storage proof uses
sentence-transformers/all-MiniLM-L6-v2 embeddings and temporary local
Qdrant/history storage. The existing locally installed project/embedding
dependencies were reused; this is not a claim of a fresh frozen
installation of every optional package. Model files were downloaded from
Hugging Face. No cloud credential or LLM inference request was used.

From the checkout with those exact versions and the project dependencies
installed:

```powershell
$env:PYTHONPATH='.'
python scripts/verify_mem0_tenant_scope.py
python scripts/verify_mem0_dependency_boundaries.py
python scripts/verify_mem0_agent_scope.py
```

Observed, all exit 0:

- Tenant cache: distinct identity tuples share scope key=False; other
tenant retrieved messages=0. The same storage exercise on
source-verified 2.0.5 reports True/1 and fails the isolation assertion.
Plain identifiers retain their existing keys.
- LangGraph 0.4.6 keeps the assistant/thread identifiers in encoded path
segments. Version 0.4.4 sends `/assistants/other` and
`/threads/other?query` instead and fails the path assertions.
- `MEM0_TELEMETRY=false`: no client/event created. PostHog 7.79.0
capture/shutdown sends exactly one deliberately synthetic event to the
loopback server; no event is sent to PostHog's service.
- Each of two agents retrieves exactly its own persisted memory, with
the user/agent identity and original Headroom ID restored. User listing
and filtered queries see the persisted records, while another user sees
none. `infer=False` disables LLM fact inference but retains actual
embedding, add, search, query and listing operations.

`python -m pytest tests/test_memory/test_mem0_agent_scope.py
tests/test_memory/test_direct_mem0.py
tests/test_memory/test_factory_external.py -q --no-cov -o addopts=''`:
**34 passed**, including nine red/green scope regressions. The real
storage proof was repeated with all three updated packages pinned to the
lock versions. `uv lock --check`, changed-file Ruff lint/format and
whitespace checks pass. Independent review previously found the listing
API defect, then verified its fix and reran all nine scope regressions
successfully.

The carried npm fix was separately qualified with 61 OpenCode tests,
typecheck/build, zero OpenCode audit findings, three E2E dependency
regressions on Node 24, and the exact workflow checker accepting only
eight preexisting bundled exceptions.

Untested: Mem0 cloud API, LLM fact extraction, Neo4j or hosted vector
storage, a live LangGraph deployment or event stream, PostHog
production/feature-flag delivery, sampling under load, other Python/OS
combinations, or a production rollout. The loopback tests establish the
stated identifier and transport boundaries without claiming those
external integrations were exercised.

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
Co-authored-by: Kenneth Wong <17061293+KennethWKZ@users.noreply.github.com>
2026-11-02 22:09:52 -06:00
Rudy Mizrahi CelekliandJD Davis 6f958e94c2 fix(memory): compare SQLite timestamps as UTC instants (#4499)
## Description

Compare SQLite memory timestamps as UTC instants instead of their ISO
text spelling. Two `created_after` values representing the same instant
(11:00 UTC and 16:00 +05:00) currently return different memories.
Offset-bearing timestamps already persisted in the database also
sort/filter incorrectly, including at validity-window boundaries.

No issue linked: found by source inspection and reproduced through
actual `SQLiteMemoryStore.save`, reopen, `query` and `count` calls;
duplicate screening covered open and closed PR bodies and issues.

## Type of Change

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

## Changes Made

- Register a deterministic UTC comparison function on each existing
SQLite memory connection. Treat naive timestamps as UTC, matching
`Memory` defaults, and retain full microsecond precision.
- Normalize both stored timestamps and query bounds for
creation/validity filters; use the same representation for chronological
ordering before pagination.
- Keep stored bytes and returned timestamp representations unchanged.
Existing offset-bearing rows work without a migration or schema/index
changes.
- Cover three timezones, naive and aware persisted rows, `query`/`count`
parity, inclusive creation and exclusive validity boundaries,
microseconds, chronological pagination and nullable last-access values.

**Correctness/performance tradeoff:** normalized comparisons cannot use
the existing raw-TEXT timestamp index. In a local actual-API probe with
2,000 synthetic rows and 30 queries, median query time increased from
1.416 ms to 5.384 ms (about 3.8×); maximum observed increased from 1.841
ms to 8.836 ms. This is a correctness fix, not a performance
improvement. These small local timings do not establish production-scale
latency. No expression index or migration is proposed; maintainers
should assess this explicit tradeoff.

## Testing

- [ ] Unit tests pass (`pytest`) — focused tests only, no whole-project
claim.
- [ ] Linting passes (`ruff check .`) — changed-file checks only, full
hook result pending.
- [x] Type checking passes (`mypy headroom`) — normal repository hook
passed.
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
Baseline producer, with new tests fixed:
12 failed, 4 passed

Patched producer, temporal + query-conditions + connection-closure + supersession suites:
29 passed

ruff check <two changed files>: All checks passed!
ruff format --check <two changed files>: 2 files already formatted
```

Exact frozen head: `14dadc4492c696ef9e7c91a8b4a72b2068fa77b4`. Normal
commit hooks passed: plugin sync, Ruff alignment, conflict guard, Ruff
lint/format, whole-package mypy and commitlint. Final-head reruns: 29
focused tests passed and 15/15 standalone runtime checks matched the
independent datetime oracle. Independent review also passed the 29
focused cases and 20 additional actual SQLite API oracle checks
(including year boundaries and raw-row preservation), with no blocker.
No full Rust/Python pre-push gate or hosted CI pass is claimed yet.

## Real Behavior Proof

- Environment: macOS arm64, Python 3.13.5, actual public SQLite memory
adapter, SQLite temporary database, synthetic memory records; no
provider/model, embedding backend or network needed.
- Exact command / steps: `HEADROOM_OFFLINE=1 HEADROOM_TELEMETRY=off
DO_NOT_TRACK=1 HEADROOM_WORKSPACE_DIR=<owned-temp-workspace>
HEADROOM_CONFIG_DIR=<owned-temp-config> PYTHONPATH=.
/opt/anaconda3/bin/python3 temporal_runtime.py`, using the standalone
script below.
- Observed result: baseline `3/15 actual public API checks match
datetime oracle`; patched `15/15 actual public API checks match datetime
oracle`. All rows are saved via the actual production API and the
adapter is reopened before queries. The oracle uses Python
aware-datetime comparisons, not the SQL normalization function.
- Not tested: live LLMs, embeddings, other memory adapters,
Windows/Linux, production-scale database latency, full repository suite
or hosted CI. This change is scoped to SQLite memory timestamps.

<details><summary>Standalone production-API runtime script (no
mocks)</summary>

```python
"""Offline production-API probe; all fixtures synthetic and temporary."""
import asyncio
import json
import tempfile
from datetime import datetime, timedelta, timezone
from pathlib import Path
from headroom.memory.adapters.sqlite import SQLiteMemoryStore
from headroom.memory.models import Memory
from headroom.memory.ports import MemoryFilter

UTC = timezone.utc
PLUS5 = timezone(timedelta(hours=5))
MINUS4 = timezone(timedelta(hours=-4))

def utc(value):
    return value.replace(tzinfo=UTC) if value.tzinfo is None else value.astimezone(UTC)

async def main():
    with tempfile.TemporaryDirectory(prefix='headroom-temporal-public-api-') as root:
        store = SQLiteMemoryStore(Path(root) / 'memories.db')
        memories = [
            Memory(id='naive', user_id='fixture', content='synthetic UTC record',
                   created_at=datetime(2026,1,1,12), valid_from=datetime(2026,1,1,12),
                   valid_until=datetime(2026,1,1,13)),
            Memory(id='aware', user_id='fixture', content='synthetic offset record',
                   created_at=datetime(2026,1,1,17,tzinfo=PLUS5),
                   valid_from=datetime(2026,1,1,8,tzinfo=MINUS4),
                   valid_until=datetime(2026,1,1,18,tzinfo=PLUS5)),
            Memory(id='microsecond', user_id='fixture', content='synthetic precision record',
                   created_at=datetime(2026,1,1,12,0,0,1),
                   valid_from=datetime(2026,1,1,12,0,0,1),
                   valid_until=datetime(2026,1,1,13,0,0,1)),
        ]
        for memory in memories:
            await store.save(memory)
        # Reopen the production adapter, so offset-bearing data is persisted input.
        store = SQLiteMemoryStore(Path(root) / 'memories.db')
        rows=[]
        for field, baseline in [
            ('created_after', datetime(2026,1,1,11,tzinfo=UTC)),
            ('created_before', datetime(2026,1,1,12,tzinfo=UTC)),
            ('valid_at', datetime(2026,1,1,12,30,tzinfo=UTC)),
            ('valid_at', datetime(2026,1,1,13,tzinfo=UTC)),
            ('created_after', datetime(2026,1,1,12,0,0,1,tzinfo=UTC)),
        ]:
            for zone in [UTC,PLUS5,MINUS4]:
                bound=baseline.astimezone(zone)
                def matches(memory):
                    if field=='created_after': return utc(memory.created_at)>=utc(bound)
                    if field=='created_before': return utc(memory.created_at)<=utc(bound)
                    return utc(memory.valid_from)<=utc(bound)<utc(memory.valid_until)
                expected=sorted(m.id for m in memories if matches(m))
                filter=MemoryFilter(user_id='fixture',include_superseded=True,**{field:bound})
                actual=sorted(m.id for m in await store.query(filter))
                count=await store.count(filter)
                rows.append(dict(field=field,bound=bound.isoformat(),expected=expected,
                                 actual=actual,count=count,passed=actual==expected and count==len(expected)))
        print(json.dumps(rows,indent=2))
        print(f"{sum(r['passed'] for r in rows)}/{len(rows)} actual public API checks match datetime oracle")

asyncio.run(main())
```

</details>

## Runtime Rollout Safety

- Rollout-managed feature(s): none; existing SQLite memory adapter.
- Minimum rollout channel: unchanged.
- Stable/default behavior changed: timestamp filters/order now compare
instants consistently across offsets; malformed date representations
still fail rather than becoming valid memories.
- Kill switch / disable path: existing backend selection; no new flag.
- Unsafe override required: none.
- Qualification impact: chronological selection correctness; measured
query overhead disclosed above.
- Rollback path: revert the fix; no database migration or data rewrite
to undo.


### Broader check limits and upload exception

Rust1.95.0 `cargo fmt --all -- --check` and `cargo clippy --workspace --
-D warnings` passed on the unchanged native sources. The cold
workspace-test build was stopped twice by a disk-reserve guard; no full
Rust-test or native-dependent Python-suite pass is claimed. Normal
commit hooks passed, including pinned Ruff0.17.0, whole-package mypy and
commitlint. These patches do not change Rust sources or Cargo
dependencies.

The [installed pre-push
hook](https://github.com/headroomlabs-ai/headroom/blob/17d38e5699b7d7c69ac6addcd762f39e42dd7f00/scripts/install-git-hooks.sh)
documents an occasional `git push --no-verify` upload exception. It was
used for this independently reviewed Python-only fix after the bounded
native-check attempts. Required hosted CI and maintainer review remain
pending; the complete pre-push gate has not passed locally.

Prepared and independently reviewed with AI assistance; actual runtime
proof and its limits are recorded above.

## Review Readiness

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

## Checklist

- [ ] 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
- [ ] I have made corresponding changes to the documentation — no new
public API/config.
- [ ] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes — focused
suites only.
- [x] I did **not** edit `CHANGELOG.md` — generated by release-please.

## Additional Notes

AI-assisted contribution. No dependencies added, external data
contacted, model downloaded, process attached or target authority
expanded. The full Rust pre-push gate remains mandatory and will not be
bypassed.


Scope note from automated review: CLI age-bucket statistics in
`headroom/cli/memory.py` still use their existing text comparisons. This
PR corrects the SQLiteMemoryStore query/count/order contract; it does
not claim to correct CLI chronology. That adjacent existing behavior
requires separate runtime qualification.


### Follow-up native validation

The actual Python extension now builds and imports from the unchanged
native source using Rust1.95.0 and the matching Xcode26.4 SDK. At this
exact PR head, the Makefile pre-push Python test-file selection passes
**177 tests with 4 skips**; one existing Anthropic approximation warning
is reported. Whole-tree pinned Ruff0.17.0 passes. The complete Rust
workspace test build was again stopped by the local disk-reserve guard
before completion; this is not a Rust-test pass. The incomplete
task-owned build cache was removed after all build processes exited,
retaining the source-built extension and logs. Full pytest, complete
pre-push success and required hosted CI remain unclaimed.


<!-- security-sync-20261028 -->
### Security baseline sync — 2026-10-28

Current exact head: `21f7ccb64eb8734d83ad56cf82da3b192da1e0f0`. Normal
history merge of upstream `3c6f82b06091206379106f8fe1a54f2400ed7a93`
brings in the maintainer-owned dependency remediation
[#4517](https://github.com/headroomlabs-ai/headroom/pull/4517),
following the prior npm baseline sync. The authored fix and its
test/example files are unchanged by this sync; no additional dependency
policy or runtime logic was introduced. This imports the maintainer
remediation requested by review; it does not establish audit success or
approval.

Validation on this head (macOS arm64, Python3.13.5, offline mode/beacon
off/DNT, existing source-built native extension):
`PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest -p
pytest_asyncio.plugin tests/test_memory/test_sqlite_temporal_filters.py
tests/test_memory/test_query_conditions.py
tests/test_memory/test_adapters_connection_leak.py
tests/test_memory/test_supersession_repair.py -q` (29 passed; existing
datetime deprecation warnings). This uses persisted SQLite rows,
including offset/microsecond, bounds, ordering/pagination and
nullable-access controls.

`PRE_COMMIT_HOME=<existing task cache> pre-commit run --all-files`
passed, including pinned Ruff, whole-package mypy, version and
merge-conflict checks. Normal commit hooks and commitlint passed.
Existing native sources/Cargo dependencies are unchanged. The documented
occasional `git push --no-verify` exception was used for a normal
fast-forward upload; full Rust workspace tests, full pytest and complete
pre-push qualification were not rerun or claimed.

Hosted security checks and maintainer review remain separate gates.
Existing human-readiness declarations are preserved; this status update
is evidence of local validation and a baseline sync, not human approval
or a claim that hosted CI is green.

As of `2026-10-28T17:40:32.107305+00:00`, hosted pip-audit and all five
npm audits passed on this exact head ([security
workflow](https://github.com/headroomlabs-ai/headroom/actions/runs/40737619736/job/122990316788));
cargo audit also passed. Other hosted jobs remain in progress, and the
human review state remains `CHANGES_REQUESTED`. This is not complete CI
qualification or human approval.

Signed-off-by: Rudy Celekli <rudy@gradiahq.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-10-29 20:25:03 -05:00
xiaoheiai4719-collabandJerrettDavis b50b3eb5ed fix(memory): match compound and null SQLite metadata filters (#4373)
## Description

SQLite metadata filters bind arrays/objects as whitespace-containing
JSON text while `json_extract` returns compact JSON, so matching records
disappear from both query() and count(). Empty compounds can instead
match JSON-looking strings. A None filter matches the string "null"
rather than an explicit JSON null.

Normalize compound values with SQLite's json() and require matching JSON
types. Match None through json_type = 'null', distinguishing an explicit
null from a missing key. String filters require JSON text as well, so
the inverse query cannot select an array/object. Native numeric/boolean
equality is unchanged. Compound comparison remains JSON-text equality:
array order and object member order matter, now documented and tested;
this does not introduce deep structural equality.

This addresses the follow-up identified in [the review of the earlier
scalar-only fix
#3240](https://github.com/headroomlabs-ai/headroom/pull/3240#pullrequestreview-5022019065).
Actual all-state PR searches for metadata/non-scalar,
metadata/json_extract, and metadata/filters/null found that earlier fix
and unrelated changes, not a compound/null fix. metadata_filters issue
search found no match. Base e995eb9f1d.

## Type of Change

- [x] Bug fix

## Changes Made

- Normalize serialized compound filters to the representation SQLite
extracts.
- Require JSON type equality for compound values, excluding JSON-looking
strings.
- Match explicit JSON null without selecting missing keys or the string
"null".
- Restrict string filters to JSON text, preventing the inverse
compound/string confusion.
- Add real-file SQLite query/count regressions and ordering/isolation
controls; retain existing numeric/boolean equality and key-validation
behavior.

## Testing

- [x] Fifteen execution-level regressions fail before and pass after the
fix.
- [x] Existing ordering control and adjacent memory tests pass.
- [x] Security validations, including metadata key-injection handling,
pass.
- [x] Changed-file Ruff lint/format and SQLite adapter mypy pass.
- [x] Standalone real-store persistence proof executed outside pytest.
- [ ] Full repository and optional model/vector qualification completed.

### Test Output

```text
python -m pytest tests/test_memory/test_metadata_matching.py -q -rs -o addopts=''
# Original source: 15 failed, 8 passed, 178 existing warnings

python -m pytest tests/test_memory/test_metadata_matching.py tests/test_memory/test_hierarchical.py tests/test_memory/test_query_conditions.py tests/test_memory/test_supersession_repair.py tests/test_security_validations.py -q -rs -o addopts=''
77 passed, 8 skipped, 354 warnings in 0.71s

ruff check headroom/memory/adapters/sqlite.py tests/test_memory/test_metadata_matching.py
All checks passed!
ruff format --check headroom/memory/adapters/sqlite.py tests/test_memory/test_metadata_matching.py
2 files already formatted
mypy --follow-imports=silent headroom/memory/adapters/sqlite.py
Success: no issues found in 1 source file
git diff --check
exit 0
```

Eight skips are four hnswlib-dependent and four
sentence-transformers-dependent tests. Warnings are existing
datetime.utcnow deprecations. Focused mypy reports unused configuration
sections; dependency-wide static analysis is not claimed.

## Real Behavior Proof

- Environment: Linux, CPython 3.12.14, real file-backed
SQLiteMemoryStore. Public save/query/count operations, reopening the
database before queries. No mocks, model inference, provider service, or
network traffic.
- Exact command / steps: Save the script below outside the checkout,
then run `PYTHONPATH=. python /path/to/proof.py` from original and
patched checkouts:

```python
import asyncio
import json
import tempfile
from pathlib import Path

from headroom.memory.adapters.sqlite import SQLiteMemoryStore
from headroom.memory.models import Memory
from headroom.memory.ports import MemoryFilter


async def main():
    with tempfile.TemporaryDirectory() as directory:
        store = SQLiteMemoryStore(Path(directory) / 'memory.db')
        cases = {
            'array': ['a', 'b'],
            'object': {'priority': 5},
            'nested': {'items': ['café', 'space within a string']},
            'empty': [],
            'null': None,
        }
        for name, value in cases.items():
            await store.save(Memory(id=f'{name}-value', user_id='alice', content='saved', metadata={name: value}))
            await store.save(Memory(id=f'{name}-text', user_id='alice', content='text control', metadata={name: json.dumps(value, separators=(',', ':'))}))
        await store.save(Memory(id='missing', user_id='alice', content='no metadata'))
        # Reopen the real database to exercise persisted serialization and reads.
        store = SQLiteMemoryStore(Path(directory) / 'memory.db')
        observed = {}
        for name, value in cases.items():
            query = MemoryFilter(user_id='alice', metadata_filters={name: value})
            observed[name] = {'ids': [item.id for item in await store.query(query)], 'count': await store.count(query)}
            text_query = MemoryFilter(user_id='alice', metadata_filters={name: json.dumps(value, separators=(',', ':'))})
            observed[f'{name}-inverse'] = {'ids': [item.id for item in await store.query(text_query)], 'count': await store.count(text_query)}
        print(json.dumps(observed, indent=2), flush=True)
        assert all(observed[name] == {'ids': [f'{name}-value'], 'count': 1} for name in cases)
        assert all(observed[f'{name}-inverse'] == {'ids': [f'{name}-text'], 'count': 1} for name in cases)


asyncio.run(main())

```

- Observed result: Before, array/object/nested filters returned no
records; an empty-array filter selected both the array and its string
representation; None selected the string "null". Inverse JSON-looking
string queries also selected compound values. After, each filter returns
exactly its persisted typed value and count() returns 1; inverse string
queries select only the corresponding string. Missing metadata and
JSON-looking strings do not match compound/null filters. The original
proof exits 1; the patched proof exits 0.
- Not tested: Full repository suites, optional model/vector
integrations, live production databases, or alternate memory backends.
Object-member ordering remains significant; no schema/data migration or
structural JSON equality is introduced.

## Runtime Rollout Safety

- Rollout-managed feature(s): None; existing SQLite memory query/count
API.
- Minimum rollout channel: Normal release after maintainer
qualification.
- Stable/default behavior changed: Compound/null filters match their
typed persisted values rather than missing records or matching
JSON-looking strings. Numeric/boolean equality is unchanged;
JSON-looking string filters now match only stored JSON strings.
- Kill switch / disable path: No new flag; omit compound/null metadata
filters if rolling back.
- Unsafe override required: No.
- Qualification impact: Real-store regressions, persistence proof,
security checks, and adjacent suites pass; full repository and optional
model/vector qualification remain outstanding.
- Rollback path: Revert this commit. No schema, dependency,
configuration, or persisted-data changes.

## Review Readiness

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

Ready for human review. The current PR delta was re-reviewed with AI
assistance after upstream main was synchronized; the contributor patch
is unchanged. Historical tests and reviewer-reported checks remain
scoped as documented below; this is not a claim of
full-suite/native/provider qualification or merge approval.

## Checklist

- [x] Regression cases demonstrate the original failures.
- [x] Changed source and tests pass lint and formatting.
- [x] CHANGELOG.md was not edited.
- [ ] Full repository qualification completed.

## Additional Notes

Implemented and tested with OpenAI AI assistance. Checked test items
describe executed verification, not a claim that the publication owner
personally ran it.

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-28 21:22:21 -05:00
59dbe98042 fix(memory): skip the edit-distance retry check on long commands (#4371)
## Description

`_commands_related_as_retry` (`headroom/memory/traffic_learner.py`)
compares a failed and a successful Bash command with `_levenshtein`, an
O(n·m) pure-Python loop, on the request path (`on_tool_result`), with no
cap on command length. `_levenshtein`'s own docstring says callers must
keep input sizes reasonable. This adds that cap: commands longer than
`_RETRY_EDIT_DISTANCE_MAX_CHARS` (512) skip the edit-distance path and
are judged by the existing linear shared-token check.

Review round (2026-10-24): `_bash_binaries_match`, which runs before
that cap, also called `_levenshtein` on the first-token basenames with
no length bound (e.g. a 2,000-character first token). When one name is a
prefix of the other their edit distance is exactly the length
difference, so that check now compares lengths (same result, linear) and
no longer calls `_levenshtein`.

Fixes #4367

## 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/traffic_learner.py`: `_RETRY_EDIT_DISTANCE_MAX_CHARS
= 512`; `_commands_related_as_retry` runs the normalized edit-distance
test only when the longer command is within the cap. The
shared-substantive-token check is unchanged.
- `headroom/memory/traffic_learner.py` (review round):
`_bash_binaries_match` replaces `_levenshtein(a_base, b_base) <= 2` with
`abs(len(a_base) - len(b_base)) <= 2`, guarded by the same `startswith`
prefix test, so the accepted pairs are identical and no edit distance is
computed on a first token. This does not reuse
`_RETRY_EDIT_DISTANCE_MAX_CHARS` because no quadratic comparison remains
to bound.
- `headroom/memory/traffic_learner.py` (review round):
`_paths_related_as_typo` returns False for a basename longer than
`_RETRY_EDIT_DISTANCE_MAX_CHARS` before calling `_levenshtein`; test
`test_oversized_path_basename_skips_the_quadratic_edit_distance`.
- `tests/test_memory/test_traffic_learner.py`:
`test_long_commands_skip_the_quadratic_edit_distance` (wraps
`_levenshtein` so any call on an input over the cap fails the test; a
long related pair is still matched through the token path, a long
unrelated pair is not) and
`test_short_commands_still_use_edit_distance`.
- `tests/test_memory/test_traffic_learner.py` (review round):
`test_oversized_first_token_skips_the_quadratic_edit_distance` (records
every `_levenshtein` call on an input over 512 characters;
`_commands_related_as_retry('x'*2000 + ' execute', 'x'*2000 + '3
execute')` must be related and make no such call),
`test_short_binary_names_keep_the_prefix_tolerance` (the pre-existing
0-2 character prefix tolerance is unchanged), and
`test_oversized_first_token_through_on_tool_result` (same pair of
commands through `TrafficLearner.on_tool_result`: no oversized call, one
retry pattern extracted).

## Testing

- [x] Unit tests pass (`pytest`) —
`tests/test_memory/test_traffic_learner.py`: 223 passed; with the
neighbouring learner/cold-start test files, 256 passed
- [x] Linting passes (`ruff check .`) — on the two changed files, plus
`ruff format --check`
- [ ] Type checking passes (`mypy headroom`) — not run; one module
constant and one extra comparison
- [x] New tests added for new functionality
- [x] Manual testing performed — end-to-end driver through
`TrafficLearner.on_tool_result` (below)

### Test Output

```text
# new tests, source at main 4c7acba5 (fail-before)
$ pytest tests/test_memory/test_traffic_learner.py -q -k long_commands --tb=line
FAILED tests/test_memory/test_traffic_learner.py::test_long_commands_skip_the_quadratic_edit_distance   # edit distance computed on an oversized command
1 failed, 219 deselected in 1.46s

# review round: new tests with ONLY the _bash_binaries_match change reverted (head c5681e22 source)
$ pytest tests/test_memory/test_traffic_learner.py -q
FAILED ...::test_oversized_first_token_skips_the_quadratic_edit_distance   # recorded oversized calls: [(2000, 2001), ...] != []
FAILED ...::test_oversized_first_token_through_on_tool_result              # recorded oversized calls: [(2000, 2001)] != []
2 failed, 221 passed in 8.64s

# with the fix
$ pytest tests/test_memory/test_traffic_learner.py -q
220 passed in 2.82s

# review round, with the fix (2707c5b8)
$ pytest tests/test_memory/test_traffic_learner.py -q
223 passed in 3.20s
$ pytest tests/test_memory/test_traffic_learner.py tests/test_memory/test_learn_flag.py tests/test_openai_responses_traffic_learner.py tests/test_cold_start_fast_pass.py tests/test_cache_mode_cold_start.py -q
256 passed, 1 warning in 13.23s

$ ruff check headroom/memory/traffic_learner.py tests/test_memory/test_traffic_learner.py && ruff format --check headroom/memory/traffic_learner.py tests/test_memory/test_traffic_learner.py
All checks passed!
2 files already formatted

# end to end through the proxy's entry point, TrafficLearner.on_tool_result:
# a failed then a successful Bash tool result whose commands are ~7,880 chars (a heredoc config + a flag change)
[main @ 4c7acba5]                         2nd on_tool_result: 16158.66 ms   patterns: 1 (error_recovery)
[fix-traffic-learner-long-commands @ c5681e22]  2nd on_tool_result:     0.38 ms   patterns: 1 (error_recovery, identical content_hash ca12b320441b0edb)
```

## Real Behavior Proof

- Environment: WSL2 Ubuntu, Python 3.12.15, pytest 9.1.1, ruff 0.17.1; a
clone of this fork at `4c7acba5` with the core runtime dependencies only
- Exact command / steps: add the tests alone and run them (the
long-command test fails: `_levenshtein` is called on an input over 512
characters), apply the source change and run the whole traffic-learner
test file, then ruff, as pasted above
- Observed result: with the fix the edit-distance loop is never entered
for a command longer than 512 characters, a long genuine retry is still
recognised through the token path, and all 218 existing traffic-learner
tests pass unchanged
- End-to-end: a driver awaits `TrafficLearner().on_tool_result(...)`
twice — a failed Bash result, then a successful retry — with
~7,880-character commands, on `git archive` exports of `main` and of
this branch. On `main` the second call takes 16.2 s (the edit-distance
loop); on this branch 0.38 ms. Both extract the same single
`error_recovery` pattern (same `content_hash`), so the recognised retry
is unchanged.
- Review round (oversized first token, unit level only): `_levenshtein`
is wrapped to record any call whose argument is over 512 characters
instead of timing it. On `c5681e22`,
`_commands_related_as_retry('x'*2000 + ' execute', 'x'*2000 + '3
execute')` makes a recorded call with lengths (2000, 2001) from
`_bash_binaries_match`; with `2707c5b8` the record is empty and the pair
is still related. The same two commands through
`TrafficLearner.on_tool_result` behave the same way (`[(2000, 2001)]`
before, `[]` after, one retry pattern extracted). The ~7,880-character
`on_tool_result` timing above (16,158.66 ms on `main`, 0.38 ms here)
covers a long argument body, not a long first token, and was not re-run
for this round.
- Not tested: a live proxy process forwarding real agent traffic (the
driver calls the same entry point the handlers await); a wall-clock
timing of the long-first-token case on `main` or on this branch

## Runtime Rollout Safety

- Rollout-managed feature(s): none (traffic learning is not behind a
rollout flag)
- Minimum rollout channel: n/a (not rollout-managed)
- Stable/default behavior changed: only for command pairs longer than
512 characters, which are now matched by shared tokens alone
- Kill switch / disable path: none added
- Unsafe override required: no
- Qualification impact: none known; no `CHANGELOG.md` edit
(release-please)
- Rollback path: revert this commit

## 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
- [ ] I have made corresponding changes to the documentation (none
needed)
- [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)

## Additional Notes

Produced with AI assistance (Claude Code) operated by me (HetCreep); the
test runs above were executed on my machine on a clone of this fork.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-28 21:20:11 -05:00
xiaoheiai4719-collabandJerrettDavis 51d3cf9369 fix(memory): bound history traversal on cyclic supersession links (#4366)
## Description

`SQLiteMemoryStore.get_history()` follows supersession links without
tracking visited records. A cyclic backward or forward link makes it
repeatedly open/read the database forever. Because the async SQLite
methods perform synchronous I/O without yielding, an enclosing asyncio
timeout cannot reliably interrupt that loop either.

This state is reachable through the public store API: save an original
record, supersede it with a second record, then reuse the original
record as the replacement for the second. Imported or persisted
malformed links can produce the same condition.

Track visited IDs across both traversal directions. Return each
reachable record once, stopping at repeated links just as traversal
already stops at missing links. Valid chains keep their ordering, and
reading history does not rewrite stored lineage.

Found by source inspection and reproduced outside pytest with an actual
SQLite file. Actual all-state searches for get_history/cycle and
supersession/cycle found no matching PR. A broader get_history search
found only PR2143, which removes superseded records from secondary
search indexes, not history traversal. Issue search found no match. Base
e995eb9f1d.

## Type of Change

- [x] Bug fix

## Changes Made

- Share one visited-ID set across backward and optional forward history
traversal.
- Stop before refetching a record already present in history.
- Add real SQLite regression coverage for self-cycles, multi-record
cycles, overlapping directions, valid chains, backward-only requests,
and dangling links.
- Assert persisted lineage fields remain unchanged after history reads.

## Testing

- [x] Five regression cases fail on the original implementation and pass
after the fix.
- [x] Three existing-behavior controls pass on both implementations.
- [x] Adjacent storage/hierarchy/supersession suites pass.
- [x] Changed-file Ruff lint/format and SQLite adapter mypy pass.
- [x] Standalone unmodified-store runtime proof performed outside
pytest.
- [ ] Full repository and optional model/vector qualification completed.

### Test Output

Before the fix:

```text
python -m pytest tests/test_memory/test_history_cycles.py -q -o addopts=''
5 failed, 3 passed, 28 warnings in 0.83s
```

The regression tests wrap the real SQLite get method with a
repeated-fetch assertion so a broken traversal fails promptly instead of
hanging pytest. They do not fabricate records or query results. The
standalone proof below has no such wrapper and demonstrates the actual
hang.

After the fix:

```text
python -m pytest tests/test_memory/test_history_cycles.py tests/test_memory/test_hierarchical.py tests/test_memory/test_supersession_repair.py tests/test_memory/test_query_conditions.py -q -rs -o addopts=''
51 passed, 8 skipped, 202 warnings in 0.68s
ruff check headroom/memory/adapters/sqlite.py tests/test_memory/test_history_cycles.py
All checks passed!
ruff format --check headroom/memory/adapters/sqlite.py tests/test_memory/test_history_cycles.py
2 files already formatted
mypy --follow-imports=silent headroom/memory/adapters/sqlite.py
Success: no issues found in 1 source file
git diff --check
exit 0
```

Eight skips are four hnswlib-dependent and four
sentence-transformers-dependent tests. Warnings come from existing
datetime.utcnow calls in memory models. Mypy notes unused configuration
sections because only the changed adapter file is checked.

## Real Behavior Proof

- Environment: Linux, CPython 3.12.14, real SQLiteMemoryStore in a
temporary directory. Public save/supersede/get_history methods; no
mocks, provider service, model inference, or network traffic.
- Exact command / steps: Saved the script below and ran `PYTHONPATH=.
timeout 2 python /path/to/proof.py` from original and patched source
checkouts:

```python
import asyncio
import tempfile
from pathlib import Path

from headroom.memory.adapters.sqlite import SQLiteMemoryStore
from headroom.memory.models import Memory

async def main():
    with tempfile.TemporaryDirectory() as directory:
        store = SQLiteMemoryStore(Path(directory) / 'memory.db')
        first = Memory(id='first', user_id='alice', content='original preference')
        second = Memory(id='second', user_id='alice', content='new preference')
        await store.save(first)
        await store.supersede(first.id, second)
        # Reusing the original record creates reciprocal backward links through
        # the public store API. History must not loop forever on this state.
        await store.supersede(second.id, first)
        print('Created first -> second -> first supersession cycle', flush=True)
        history = await store.get_history(first.id, include_future=True)
        ids = [memory.id for memory in history]
        assert ids == ['second', 'first'], ids
        print('Bounded unique history:', ids)

asyncio.run(main())

```

- Observed result: Original checkout prints that the cycle was created,
then never returns history before the operating-system timeout
terminates it with exit124. The patched checkout exits0 and prints:

```text
Created first -> second -> first supersession cycle
Bounded unique history: ['second', 'first']
```

- Not tested: Full repository tests, model/vector services, production
databases, concurrent lineage mutation, or dependency-wide static
analysis. The fix bounds traversal of repeated IDs; it does not repair
malformed records or prohibit creating them.

## Runtime Rollout Safety

- Rollout-managed feature(s): None; existing SQLite history API.
- Minimum rollout channel: Normal release after maintainer
qualification.
- Stable/default behavior changed: Cyclic or overlapping links yield a
bounded unique history rather than hanging or duplicating records. Valid
chains and missing-link handling remain unchanged.
- Kill switch / disable path: No new flag; avoid history queries on
malformed lineage if rolling back.
- Unsafe override required: No.
- Qualification impact: Real storage regression/runtime proof and
adjacent suites pass; full repository and optional model/vector
qualification remain outstanding.
- Rollback path: Revert this commit. No schema, dependency,
configuration, or persisted-data changes.

## Review Readiness

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

Ready for human review. The current PR delta was re-reviewed with AI
assistance after upstream main was synchronized; the contributor patch
is unchanged. Historical tests and reviewer-reported checks remain
scoped as documented below; this is not a claim of
full-suite/native/provider qualification or merge approval.

## Checklist

- [x] Regression cases demonstrate the original failure.
- [x] Changed source and tests pass lint and formatting.
- [x] CHANGELOG.md was not edited.
- [ ] Full repository qualification completed.

## Additional Notes

Implemented and tested with OpenAI AI assistance. Checked test items
describe executed verification, not a claim that the publication owner
personally ran it.

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-28 21:19:12 -05:00
Mansurshakh Japarov 8c07cf4a0f fix(memory): bound retrieval queries before embedding (#4244)
## Description

Closes #4223.

The proxy now embeds a bounded, user-first retrieval query instead of
concatenating entire tool outputs into a deadline-limited lookup. The
raw `MemoryQuery` and its default SDK rendering still retain the full
sources.

Memory failures use the exception representation, so an empty
`TimeoutError` is no longer a blank warning. The existing Anthropic
deadline is unchanged and documented; this does not promise that a cold
model or slow embedding server will finish within it.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [x] Documentation update

## Changes Made

- Bound proxy embedding input to 4096 characters, including delimiters;
spend the budget on the latest user question and recent context tails.
- Reserve question and context space inside the active local tokenizer's
window, rather than relying on a character cap to prevent truncation.
- Keep the full-fidelity SDK behavior when no budget is requested.
- Make generic memory errors identifiable in the shared handler and
provider handlers.
- Cover Unicode, newest-context precedence, zero character budget and
actual tokenizer-window retention; keep the full-fidelity SDK tests.

## Testing

- [ ] Unit tests pass (pytest) — all 67 affected query, memory-handler
and tokenizer-window regressions passed locally, not the entire Python
suite.
- [ ] Linting passes (ruff check .) — normal changed-file Ruff hooks
passed.
- [ ] Type checking passes (mypy headroom) — normal mypy hook passed.
- [x] Manual testing performed

### Test Output

```text
Affected query/native-memory/tool/auto-tail/tokenizer suites: 67 passed, 1 warning
Ordinary make ci-precheck: PASS (181 critical Python tests, 6 warnings)
```

The focused-suite warning concerns assertion rewriting of the
already-imported `asyncio` name; it was not suppressed. All five
installed pytest plugins were loaded explicitly. Normal Ruff
formatting/checking, mypy and commitlint hooks passed on `8eb10bfd`. The
ordinary full pre-push gate passed on that same commit, including Rust
workspace checks/tests, the native build and critical Python suites; the
normal fast-forward fork push completed without a bypass.

## Real Behavior Proof

- Environment: Linux x86-64, Python 3.13.14, the actual local ONNX
model/session, SQLite and vector retrieval. The optional
sentence-transformers CPU backend was also exercised in a separate
complete CPU-wheel environment; no project dependency changes.
- Exact command / steps: save a SQLite-corruption memory and an
unrelated cooking memory through the real `LocalBackend`. Call
`MemoryHandler.search_and_format_context` under a two-second
`asyncio.wait_for` with the same long repeated question and SQLite tool
error before and after the change. Record the real ONNX session's input
IDs/attention mask without replacing inference; decode those IDs to
check the final question and tool error. Verify the original
`MemoryQuery` fields stay intact.
- Observed result: both fragments now reach the model and the relevant
memory is retrieved. Same synthetic input and default cache behavior; no
fake embedding or search result:

| Measurement | Before | After |
| --- | ---: | ---: |
| Submitted characters | 2594 | 1146 |
| Tokens before model truncation | 560 | 256 |
| Question tail and tool error reach model | No | Yes |
| Relevant memory retrieved | No | Yes |
| Warm lookup seconds | 0.076 | 0.241 |

A separately configured 96-token ONNX model also retained both
fragments. The real sentence-transformers CPU model and a previously
uninitialized local ONNX backend passed the same retention check and
generated real embeddings. The legacy messages-only path still submitted
4096 characters; the empty-timeout diagnostic still logged
`TimeoutError()` and failed open.

- Not tested: the reporter's Granite embedding server, cold-start
deadlines or network latency, arbitrary remote tokenizer windows, live
provider requests, Windows/macOS or GPU/MPS. Only the diagnostic failure
was injected; successful persistence, embeddings and retrieval used real
backends.

## Runtime Rollout Safety

- Rollout-managed feature(s): existing automatic memory lookup; no new
feature gate.
- Minimum rollout channel: unchanged.
- Stable/default behavior changed: proxy lookups use the bounded
representation; the SDK's default full rendering is unchanged.
- Kill switch / disable path: existing `--no-memory-context` or memory
configuration.
- Unsafe override required: no.
- Qualification impact: actual retrieval, raw-input preservation and
diagnostics checked locally.
- Rollback path: revert the fix; no schema migration.

## 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 made corresponding changes to the documentation
- [x] I did not edit CHANGELOG.md — release-please owns it

## Additional Notes

AI-assisted; no subagents.
2026-10-24 08:45:33 -07:00
4e6e955cad fix(memory): log storage and SQLite failures that currently make retrieval miss silently (#4111)
## Description

Several storage paths turn a real failure into a quiet miss. They either
log nothing, or log a line that does not say which operation or file
failed. When CCR or memory retrieval misses, an operator cannot tell
corruption or a broken plugin from a genuine "not found". This PR adds
the missing log lines. Return values and control flow do not change.

Refs #4136

## 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/storage/__init__.py` (`create_storage`):
- A `headroom.storage_backend` plugin that raised on load was swallowed
by `except Exception: pass`. So was a scheme with no plugin. Both then
fell back to `SQLiteStorage(store_url)`, which opens a SQLite file named
after the URL.
- Both cases now log a warning that names the scheme. The URL itself is
not logged, because it can carry credentials.
- A plugin that raises is logged with the exception type only, because
its text can echo the URL. A separate DEBUG line gives
`log_safety.describe_exception` (exception types and code locations,
never the message), so no level carries the URL or its password.
  - The module gets a `logger`.
- `headroom/cache/backends/sqlite.py` (CCR store):
- `_entry_from_json` returned `None` with no log for a row that fails to
decode or rebuild. So `get()` reported a plain miss for an entry that
exists but is unreadable.
- It now logs a warning with the hash, the db path and the exception
type. `items()` decodes every row on each eviction pass, so the warning
fires once per hash.
- The once-per-hash guard is `log_safety.WarnOnce`. Within a one-hour
window it warns for at most 1,000 hashes, then logs one overflow
warning, and later rows log at DEBUG only, so repeated eviction scans
over many bad rows cannot flood the log. When the window ends, a row
that is still broken warns again, about once an hour. A hash is used up
only while WARNING is enabled.
- CCR keys come from model-issued retrieve calls, so they are logged
through `log_safety.safe_id`: a repr (newlines escaped) capped at 80
characters.
- Failed `delete`/`exists`/`clear`/`count`/`keys`/`items`/`get_stats`
all logged as `"op"`. Each now logs its real name, with the key for
`get`/`set`/`delete`/`exists`.
  - The transient-error warning now includes the db path.
- `headroom/memory/traffic_learner.py`: the two read-only SQLite reads
returned `[]` on `OperationalError`/`DatabaseError` with no log: the
hydrate path and `_load_persisted_patterns_from_sqlite`. Both now warn
with the db path. Also:
- dropped a redundant `conn.close()` in an `except` whose `finally`
already closes;
- the two best-effort `conn.close()` calls now catch `sqlite3.Error` and
log at debug, instead of `except Exception: pass`.
- `headroom/memory/backends/direct_mem0.py`:
`get_memory`/`delete_memory` turned any Qdrant/Neo4j exception into "not
found". They now warn with the memory id and the exception type first.
- The exception text is not logged at any level, because backend errors
can carry stored memory or connection details. A DEBUG line gives
`describe_exception`.
- Memory ids come from the model, so they are logged through
`log_safety.safe_id`, which escapes newlines and caps the length.
- mem0 2.x `Memory.delete` raises exactly `ValueError(f"Memory with id
{memory_id} not found")` for an unknown id. Only that message, for the
requested id, logs at DEBUG; the delete is model-driven, so it is
expected. Any other `ValueError`, such as a missing collection, still
warns.
- When a corrupt CCR store is recreated, the unreadable-row guard starts
fresh, because the new file has no rows.
- `headroom/learn/registry.py`: a built-in learn plugin that fails to
import was logged at debug, so `headroom learn --agent <name>` only said
"Unknown agent". It is now a warning with the traceback. Built-in
plugins use only the stdlib, so this never fires on a healthy install.
- `headroom/cache/compression_store.py`: the "Failed to load CCR
backend" warning now says it falls back to the in-process store, and
what that costs. This matches the SQLite branch next to it. It logs the
exception type only, because the backend's text can echo
`HEADROOM_REDIS_URL`. DEBUG gets `describe_exception`.

## 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 -q -p no:cacheprovider tests/test_storage_backends.py tests/test_storage tests/test_ccr_sqlite_backend.py tests/test_compression_store.py tests/test_learn/test_registry.py tests/test_memory/test_traffic_learner.py tests/test_memory/test_direct_mem0.py tests/test_private_state_files.py tests/test_adapter_hooks.py tests/test_cache/test_backends.py tests/test_learn/test_opencode_scanner.py tests/test_openai_responses_traffic_learner.py tests/test_learn/test_section_lifecycle.py tests/test_learn/test_worktree_merge.py tests/test_memory_handler_native_ops.py
================= 537 passed, 1 skipped, 5 warnings in 34.37s ==================
# The three new tests against origin/main (product code reverted):
FAILED tests/test_storage_backends.py::test_create_storage_warns_when_a_backend_plugin_fails_to_load
FAILED tests/test_ccr_sqlite_backend.py::TestSQLiteBackend::test_unreadable_row_is_logged_once_and_healthy_rows_are_not
FAILED tests/test_learn/test_registry.py::TestBuiltinLoadFailure::test_broken_builtin_plugin_is_logged_as_a_warning
$ uvx ruff@0.16.8 check <changed files>
All checks passed!
# Added in review: the hydration-failure warning; mem0 delete/get paths (only mem0's exact missing-memory message is quiet; a missing collection warns); newline and 100,000-char model ids; two scans over more bad rows than the cap; and storage-plugin, CCR-backend and mem0 failures whose records are rendered with logging.Formatter at DEBUG and WARNING and checked for credential and content canaries.
# Those tests against the previous head 6c1ad49c, in a scratch worktree:
FAILED tests/test_ccr_sqlite_backend.py::TestSQLiteBackend::test_repeated_scans_over_the_cap_stay_bounded
FAILED tests/test_storage_backends.py::test_create_storage_warns_when_a_backend_plugin_fails_to_load
FAILED tests/test_memory/test_direct_mem0.py::test_backend_failures_warn_without_exception_text[delete_memory-exc1-True]
FAILED tests/test_memory/test_direct_mem0.py::test_backend_failures_warn_without_exception_text[delete_memory-exc4-True]
FAILED tests/test_memory/test_direct_mem0.py::test_backend_failures_warn_without_exception_text[get_memory-exc5-True]
FAILED tests/test_adapter_hooks.py::TestCCREntryPointLoading::test_failing_backend_plugin_logs_no_credentials_at_any_level
$ mypy <6 changed product files> --ignore-missing-imports
Success: no issues found in 6 source files
```

## Real Behavior Proof

- Environment: macOS, Python 3.12.13, repo .venv, branch checkout at
72a166cb (base a9815bbb plus main and #4138 merged in), temp HOME /
HEADROOM_WORKSPACE_DIR / CODEX_HOME, offline.
- Exact command / steps: two runs from this checkout, listed below.
- Ran the shared smoke harness, which starts a real proxy from this
checkout against a local fake upstream and sends one Anthropic and one
OpenAI request with a compressible tool result.
- Ran a direct, unmocked script at DEBUG. A storage plugin raises an
error that quotes its `pg://user:CRED_CANARY@...` URL. Then 5 unreadable
rows are written into a real CCR SQLite store (the cap is lowered to 3
for the run), and `items()` scans it twice.
- Observed result: as listed below. The raw output is in the blocks
after this list.
- Both proxy requests return HTTP 200 with savings, and the proxy log
has no new warnings.
- The storage fallback logs the scheme and exception type at WARNING,
and only types and code locations at DEBUG. `CRED_CANARY` appears
nowhere in the output.
- The CCR store warns for 3 rows, then once for the overflow, and the
second scan (inside the same hour) adds nothing. All 5 rows are kept,
and reads miss as before.
- Not tested: the two paths listed below.
- A live Qdrant/Neo4j outage on the DirectMem0 path. Unit tests with a
raising client cover it.
  - A real third-party storage or CCR plugin.

```text
$ bash smoke.sh <worktree>
branch: cleanup/memory-cache-storage-logging @ 72a166cb
health: 200
POST /v1/messages        -> HTTP200 smoke-ok
POST /v1/chat/completions -> HTTP200 smoke-ok
stats: requests=2 failed=0 tokens_saved=13574 savings_percent=99.82
proxy.log WARNING/ERROR lines:
   2 headroom.proxy - WARNING - event=proxy_offline_mode air-gap active — every connection Headroom initiates is refused (telemetry, update check, license reporter, model/tokenizer/binary/dataset downloads, remote Kompress, OTLP/Langfuse export, Copilot auth, subscription polling, OpenAI embedders, Headroom Cloud compression). Still allowed on purpose: forwarding your requests to the upstream you 
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch found no usable file for chopratejas/kompress-v2-base
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch refused for chopratejas/kompress-v2-base (HEADROOM_OFFLINE is set): HEADROOM_OFFLINE is set: refusing outbound network access for HuggingFace download of chopratejas/kompress-v2-base/onnx/kompress-int8-wo.onnx to huggingface.co. Unset HEADROOM_OFFLINE, or turn off the feature that needs this connection.

$ HOME=$TMP/home HEADROOM_WORKSPACE_DIR=$TMP/ws CODEX_HOME=$TMP/codex python -u run.py   # logging at DEBUG
INFO headroom._ort - Pinned ORT_DYLIB_PATH to bundled ONNX Runtime: /Users/tejas/headroom/.venv/lib/python3.12/site-packages/onnxruntime/capi/libonnxruntime.1.26.0.dylib
WARNING headroom.storage - Failed to load storage backend for scheme 'pg' (<ValueError>); falling back to SQLite storage
DEBUG headroom.storage - Storage backend 'pg' load failure: ValueError at run.py:11 in factory <- headroom/storage/__init__.py:70 in create_storage
WARNING headroom.cache.backends.sqlite - CCR SQLite entry 'bad0' in $TMP/ws/ccr_store.db is unreadable (JSONDecodeError); treating as a miss
WARNING headroom.cache.backends.sqlite - CCR SQLite entry 'bad1' in $TMP/ws/ccr_store.db is unreadable (JSONDecodeError); treating as a miss
WARNING headroom.cache.backends.sqlite - CCR SQLite entry 'bad2' in $TMP/ws/ccr_store.db is unreadable (JSONDecodeError); treating as a miss
WARNING headroom.cache.backends.sqlite - More than 3 distinct unreadable CCR SQLite entries; further ones are logged at debug only
scan 1 -> []
scan 2 -> []
rows kept: 5
```

Update 2026-10-15 (head `4e78ca73`). Plugin-load warnings now name the
exception through `safe_id`, which renders `<ValueError>`, or `<object>`
for a class whose name is not a plain identifier. The learn-plugin
failures no longer put a traceback in the WARNING. This is a direct,
unmocked run at DEBUG with `HEADROOM_DEBUG_DUMP` unset. A storage plugin
and an external learn plugin raise errors quoting
`pg://user:CRED_CANARY@db`, one of them through a class named
`PRIVATE_CREDENTIAL_CANARY\nFORGED_LOG_ENTRY`. `grep -c 'CANARY|FORGED'`
on the output gives 0.

```text
WARNING headroom.storage - Failed to load storage backend for scheme 'pg' (<ValueError>); falling back to SQLite storage
DEBUG headroom.storage - Storage backend 'pg' load failure: ValueError at headroom/storage/__init__.py:70 in create_storage
WARNING headroom.storage - Failed to load storage backend for scheme 'pg' (<object>); falling back to SQLite storage
DEBUG headroom.storage - Storage backend 'pg' load failure: <exception> at headroom/storage/__init__.py:70 in create_storage
WARNING headroom.learn.registry - Failed to load external learn plugin 'broken' (<object>)
DEBUG headroom.learn.registry - External learn plugin 'broken' failure: <exception> at headroom/learn/registry.py:52 in _discover
learn plugins: ['claude', 'codex', 'gemini', 'grok', 'opencode']
```

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A; logging only.
- Stable/default behavior changed: No. Only log output changes. All
return values and fallbacks are as before.
- Kill switch / disable path: Standard logging level configuration for
the `headroom.*` loggers.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this commit.

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

## Screenshots (if applicable)

N/A.

## Additional Notes

Part of maintainer-requested cleanup #4136 (dead code, duplication,
debuggability), split into small PRs for review.

- Documentation: N/A, because no user-facing option changes.
- On the DirectMem0 path, deleting an unknown id stays quiet at the
default level. Only real backend failures warn.
- Depends on #4138; its two files show in this diff until it merges.
- The `describe_exception` calls run only when
`logger.isEnabledFor(logging.DEBUG)`, so a failure path does no
formatting work at INFO. That PR also touches
`headroom/proxy/handlers/_debug_dump.py`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-16 14:30:34 -07:00
Tejas ChopraandClaude Opus 5.5 e6eaa41179 fix(learn): make live traffic learning use the shared error classifier (#4110)
## Description

Live traffic learning (`--learn`) decides whether a tool result failed,
and why, with its own copy of the learn error patterns in
`memory/traffic_learner.py`. OpenAI-format tool results carry no
`is_error` flag, so on the OpenAI/Responses path the learner sniffs the
output text. The copy has two bugs:

1. **"exit code 0" counted as an error.** Codex, Grok and opencode
append `exit code 0` to the output of every successful shell command.
The copy matched any `exit code` text. So every successful Codex shell
call through the OpenAI path was recorded as a failure, which can turn
into bogus "command X fails, use Y" recovery patterns.
2. **Timeouts and connection errors filed as `runtime_error`.** Every
Python exception repr is `XxxError: ...`. The copy checked its generic
`Error:` pattern before `TimeoutError`, so `TimeoutError: ...` became
`runtime_error`, and it had no connection-error category at all. The
shared `classify_error` in `learn/_shared.py` checks those first.

**Exactly what changes:**
- **Category** (which kind of error) now comes from the shared
`headroom.learn._shared.classify_error`. Timeouts become `timeout`,
connection errors `connection_error`, and an error that matches no
pattern becomes `unknown` instead of `None`.
- **Detection** (whether it is an error at all) keeps the old patterns:
case-insensitive, over the first 2000 characters. Only the exit-code
rule changes:
- an exit code or exit status counts as an error only when it is
nonzero, so `exit code 0` and `exited with exit code 0` are not errors;
  - `exit code 2`, `Exit code: 1` and `exited with status 1` still are;
- `non-zero` still counts, and so does an `exited with ...` line that
carries no code of its own.
- The shared `is_error_content` is **not** used for detection. It is
narrower (a case-sensitive substring list over 1000 characters) and
would miss lowercase `no such file` and `permission denied`, `EACCES`,
`EPERM`, `does not exist`, `Exception:`, `non-zero` and `exited with`.
- I checked a 55-row truth table from review, over real tool-output
strings. Detection matches the old detector on every row except the two
`exit code 0` rows, which flip from error to not-an-error.
- Category changes on that table:
  - `TimeoutError: ...` and `rpc error: deadline exceeded` → `timeout`;
  - `ConnectionError: ...` → `connection_error`;
- a traceback mentioning `net/network_utils.py` → `connection_error`.
This comes from the shared `network` pattern; see Additional Notes.

Refs #4136

## 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/traffic_learner.py`:
  - Replace the copied `_ERROR_PATTERNS`/`_classify_error` with these:
- `_ERROR_SIGNALS`, the old detection patterns minus the exit-code one;
- `_exit_status_is_error`, the nonzero-only exit-code rule. Signed codes
such as `-9` count, and `exit code 0` never hides another failure in the
same output: a second nonzero code, `exited with signal` or `killed by
signal`. Status evidence belongs to its own line: an `exited with ...`
line with no code of its own is a failure even when another line says
`exit code 0`. A line that ends at `exited with` continues on the next
line, so `Process exited with\nexit code 0` stays one zero status. A
standalone `Killed` line (the shell's SIGKILL message) counts only when
no exit status is reported, since a successful command can print that
word, and it is recognized even below the 10-character short-content
cut-off;
    - `_is_error`, the same length and 2000-character window as before.
  - `on_tool_result` records `classify_error(output).value`.
- Both extractors keep calling `_is_error`: the Anthropic fallback sniff
and the OpenAI sniff.
- `headroom/learn/_shared.py`: `classify_error` maps signal kills
(`killed by signal`, a standalone `Killed` or `Killed: 9` line) to
`exit_code`, since a shell reports them as status 128+N. They were
`unknown`.
- `tests/test_memory/test_traffic_learner.py`:
  - `TestErrorClassification` drives `TrafficLearner` itself.
- A parametrized detection table covers: the exit-code-0 rows; signed
codes; `exit code 0` next to a nonzero code, a signal or `Killed`;
nonzero, `non-zero` and `exited with status 1`; an exit code and a
traceback after 1500 characters; the lowercase, `EACCES`, `EPERM`, `does
not exist`, `Exception:` and `deadline exceeded` signals; and clean
outputs.
- A parametrized category table includes `timeout`, `connection_error`
and the signal kills.
- An end-to-end table runs the OpenAI extractor's result through
`on_tool_result` and checks the recorded `is_error` and category. It
covers a bare `Killed`, `worker exited with an error` plus a wrapper
`exit code 0`, `Killed` plus `exit code 0`, and the controls: clean
`exit code 0`, a signal kill plus a wrapper zero, and `-9`.

## 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
# New tests against origin/main's traffic_learner.py:
FAILED tests/test_memory/test_traffic_learner.py::TestErrorClassification::test_error_detection[Process exited with exit code 0\nall tests passed-False]
FAILED tests/test_memory/test_traffic_learner.py::TestErrorClassification::test_error_detection[README.md\nsrc\nexit code 0-False]
FAILED tests/test_memory/test_traffic_learner.py::TestErrorClassification::test_error_category_recorded[TimeoutError: deadline exceeded after 30s-timeout]
FAILED tests/test_memory/test_traffic_learner.py::TestErrorClassification::test_error_category_recorded[ConnectionError: [Errno 111] Connection refused-connection_error]
================= 4 failed, 33 passed, 159 deselected in 0.50s =================
# With this change:
$ pytest -q -p no:cacheprovider tests/test_memory/test_traffic_learner.py tests/test_openai_responses_traffic_learner.py tests/test_learn/test_section_lifecycle.py tests/test_learn/test_worktree_merge.py tests/test_learn/test_error_classification.py tests/test_openai_codex_routing.py tests/test_openai_codex_ws_timings.py tests/test_cache_mode_cold_start.py
============================= 290 passed in 39.55s =============================
# The new bare-Killed and wrapper-zero rows against the previous commit (50723621), in a scratch worktree: 4 FAILED. `Killed\nexit code 0` already passed there.
# 55-row truth table (detection must equal the old _is_error except the two "exit code 0" rows):
mismatches: 0
$ mypy headroom/memory/traffic_learner.py --ignore-missing-imports
Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: macOS, Python 3.12.13, repo .venv, branch checkout at
e063c64b (re-checked at 98f9ea57) (base a9815bbb), temp HOME /
HEADROOM_WORKSPACE_DIR / CODEX_HOME, offline.
- Exact command / steps:
- Ran the shared smoke harness, which starts a real proxy from this
checkout against a local fake upstream and sends one Anthropic and one
OpenAI request with a compressible tool result.
- Ran a direct script that feeds seven OpenAI tool messages through
`TrafficLearner.extract_tool_results_from_openai_messages` and then
`on_tool_result`, as the proxy does, and prints what the learner
recorded.
- Ran a script over the reviewer's 55 tool-output strings that compares
the new `_is_error` with the old one.
- Observed result:
- Both proxy requests return HTTP 200 with savings, with no new
warnings.
- `exit code 0` alone is a success, and so is a `Killed` line printed by
a command that reports `exit code 0`.
- A signed code (`-9`), a signal kill, or a worker's `exited with an
error` is a failure, even next to a wrapper's `exit code 0`. So is a
bare `Killed`.
- Signal kills are categorized as `exit_code`, and a real error keeps
its own category.
  - 0 detection mismatches outside the intended rows.
- Not tested: A live Codex session through the proxy with `--learn`. The
smoke run does not send shell tool outputs, so the direct script covers
that path.

```text
$ bash smoke.sh <worktree>
branch: cleanup/memory-cache-traffic-error-classifier @ e063c64b
health: 200
POST /v1/messages        -> HTTP200 smoke-ok
POST /v1/chat/completions -> HTTP200 smoke-ok
stats: requests=2 failed=0 tokens_saved=13574 savings_percent=99.82
proxy.log WARNING/ERROR lines:
   2 headroom.proxy - WARNING - event=proxy_offline_mode air-gap active — every connection Headroom initiates is refused (telemetry, update check, license reporter, model/tokenizer/binary/dataset downloads, remote Kompress, OTLP/Langfuse export, Copilot auth, subscription polling, OpenAI embedders, Headroom Cloud compression). Still allowed on purpose: forwarding your requests to the upstream you 
   2 headroom.transforms.kompress_compressor - WARNING - Kompress: 'onnx/kompress-int8-wo.onnx' for chopratejas/kompress-v2-base is not cached and HEADROOM_OFFLINE forbids fetching it (HEADROOM_OFFLINE is set: refusing outbound network access for HuggingFace download of chopratejas/kompress-v2-base/onnx/kompress-int8-wo.onnx to huggingface.co. Unset HEADROOM_OFFLINE, or turn off the feature that n
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch found no usable file for chopratejas/kompress-v2-base
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch refused for chopratejas/kompress-v2-base (HEADROOM_OFFLINE is set): HEADROOM_OFFLINE is set: refusing outbound network access for HuggingFace download of chopratejas/kompress-v2-base/onnx/kompress-int8-wo.onnx to huggingface.co. Unset HEADROOM_OFFLINE, or turn off the feature that needs this connection.

$ HOME=$TMP/home HEADROOM_WORKSPACE_DIR=$TMP/ws CODEX_HOME=$TMP/codex python run.py
'ok: 3 files\nexit code 0'                                 is_error=False category=None
'command terminated\nexit code -9'                         is_error=True  category=exit_code
'worker killed by signal SIGKILL\nwrapper exit code 0'     is_error=True  category=exit_code
'Killed'                                                   is_error=True  category=exit_code
'Killed\nexit code 0'                                      is_error=False category=None
'worker exited with an error\nwrapper exit code 0'         is_error=True  category=exit_code
"ModuleNotFoundError: No module named 'foo'\nexit code 1"  is_error=True  category=module_not_found
```

## Runtime Rollout Safety

- Rollout-managed feature(s): None. This only affects `--learn` (live
traffic learning), which is opt-in.
- Minimum rollout channel: Stable; this is a classification bug fix on
an opt-in path.
- Stable/default behavior changed:
- Default proxy behaviour is unchanged. Only runs with `--learn` on see
a difference.
- Output whose only failure signal is an exit code of 0 is no longer
counted as a failure.
  - Error categories use the shared classifier.
  - An unmatched error is labelled `unknown`.
- Kill switch / disable path: Run without `--learn`.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this commit.

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

## Screenshots (if applicable)

N/A.

## Additional Notes

Part of maintainer-requested cleanup #4136 (dead code, duplication,
debuggability), split into small PRs for review.

- Documentation: the behaviour change is recorded in the cleanup docs
ledger for the separate docs PR.
- Detection and categorisation stay separate on purpose. Making the
shared `is_error_content` as broad as this detector would also change
the `headroom learn` scanners, so that belongs in its own PR.
- Follow-up, pre-existing in `learn/_shared.py`: its `network` pattern
files a traceback that mentions a path like `net/network_utils.py` as
`connection_error`.
- Patterns already persisted with a category from the old copy are left
as they are.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 09:06:10 -07:00
Tejas ChopraandClaude Opus 5.5 7387b8cc11 refactor(memory): deprecate the orphaned Mem0SystemAdapter (#4114)
## Description

`Mem0SystemAdapter` (`headroom/memory/backends/mem0_system_adapter.py`)
adapts `Mem0Backend` to the `MemorySystem` backend protocol. In that
design Mem0 runs its own LLM extraction: 3-4 LLM calls per save.
`DirectMem0Adapter` replaced it. Nothing in Headroom constructs it, and
no test covers it.

It is listed in `headroom.memory.backends.__all__` and lazily exported
from that package, so it is public API. This PR deprecates it instead of
deleting it: constructing it now emits a `DeprecationWarning`. It stays
in the subpackage `__all__` and in the lazy export, and importing
`headroom.memory.backends` stays quiet.

**What to use instead:**
- Local mode (Qdrant + Neo4j): `DirectMem0Adapter`, from
`headroom.memory.backends.direct_mem0` or the `headroom.memory.backends`
lazy export. It satisfies the same `MemoryBackend` protocol.
`save_memory` skips Mem0's LLM extraction only when the caller passes
non-empty pre-extracted `facts`, `extracted_entities` or
`extracted_relationships`. Passing only `content` with
`entities`/`relationships` still runs Mem0's extraction.
- Cloud mode (`Mem0Config(mode="cloud")`): there is no replacement in
Headroom, because `DirectMem0Adapter` has no cloud or API-key path. Use
the `mem0` client directly.

Evidence: `grep -rn Mem0SystemAdapter` across `headroom crates plugins
sdk docs wiki scripts benchmarks examples e2e .github tests` and the
consumer repos finds only the module itself and its lazy export in
`backends/__init__.py`.

Refs #4136

## Type of Change

- [ ] 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
- [x] Code refactoring (no functional changes)

## Changes Made

- `headroom/memory/backends/mem0_system_adapter.py`:
- `Mem0SystemAdapter.__init__` emits a `DeprecationWarning` with the
guidance above, shown in the proof below.
  - The module and class docstrings get `.. deprecated::`.
- `headroom/memory/backends/__init__.py`: the package docstring marks it
deprecated. `__all__` and the lazy export are unchanged, so the name
stays importable during the deprecation period.
- `tests/test_memory/test_mem0_system_adapter_deprecation.py` (new):
- asserts the warning fires. `Mem0Backend` is stubbed so the test does
not need the optional mem0 install;
- pins the migration guidance with spies on the Mem0 client and the
direct Qdrant/Neo4j writers. Non-empty `facts`, `extracted_entities` or
`extracted_relationships` skip Mem0's `add()`. `entities` alone,
`relationships` alone, or empty pre-extracted lists call it. The adapter
code is unchanged, so this test locks in current behaviour and passes
before and after.

## 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 -q -p no:cacheprovider tests/test_memory/test_mem0_system_adapter_deprecation.py tests/test_proxy_healthchecks.py tests/test_memory/test_direct_mem0.py tests/test_memory/test_qdrant_env.py
============================= 74 passed in 15.04s ==============================
$ python -W error::DeprecationWarning -c "import headroom.memory.backends; from headroom.memory.backends import mem0_system_adapter"
import ok, quiet
$ mypy headroom/memory/backends/mem0_system_adapter.py headroom/memory/backends/__init__.py --ignore-missing-imports
Success: no issues found in 2 source files
```

## Real Behavior Proof

- Environment: macOS, Python 3.12.13 (mem0 not installed), repo .venv,
branch checkout at 2aff9be2 (base a9815bbb), temp HOME /
HEADROOM_WORKSPACE_DIR / CODEX_HOME, offline.
- Exact command / steps:
- Ran the shared smoke harness, which starts a real proxy from this
checkout against a local fake upstream and sends one Anthropic and one
OpenAI request with a compressible tool result.
- Ran `python -W always`, which constructs the adapter with a local
`Mem0Config`. Construction is lazy, so it needs no services.
  - Ran the deprecation, health-check, DirectMem0 and Qdrant env tests.
- Observed result:
  - Both proxy requests return HTTP 200 with savings.
- Construction emits the new warning with the local and cloud guidance,
and the adapter is still built.
  - The tests pass.
- Not tested: Using the adapter against a live Mem0 install, local or
cloud. Behaviour after the warning is unchanged.

```text
$ bash smoke.sh <worktree>
branch: cleanup/memory-cache-deprecate-mem0-system-adapter @ dab5f560
health: 200
POST /v1/messages        -> HTTP200 smoke-ok
POST /v1/chat/completions -> HTTP200 smoke-ok
stats: requests=2 failed=0 tokens_saved=13574 savings_percent=99.82
proxy.log WARNING/ERROR lines:
   2 headroom.proxy - WARNING - event=proxy_offline_mode air-gap active — every connection Headroom initiates is refused (telemetry, update check, license reporter, model/tokenizer/binary/dataset downloads, remote Kompress, OTLP/Langfuse export, Copilot auth, subscription polling, OpenAI embedders, Headroom Cloud compression). Still allowed on purpose: forwarding your requests to the upstream you 
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch found no usable file for chopratejas/kompress-v2-base
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch refused for chopratejas/kompress-v2-base (HEADROOM_OFFLINE is set): HEADROOM_OFFLINE is set: refusing outbound network access for HuggingFace download of chopratejas/kompress-v2-base/onnx/kompress-int8-wo.onnx to huggingface.co. Unset HEADROOM_OFFLINE, or turn off the feature that needs this connection.

$ HOME=$TMP/home HEADROOM_WORKSPACE_DIR=$TMP/ws CODEX_HOME=$TMP/codex python -W always -c "<Mem0SystemAdapter(Mem0Config(mode='local'))>"
<string>:4: DeprecationWarning: Mem0SystemAdapter is deprecated and will be removed in a future release; for local mode use DirectMem0Adapter (headroom.memory.backends.direct_mem0), which skips Mem0's LLM extraction only when given pre-extracted facts, extracted_entities or extracted_relationships; cloud mode has no Headroom replacement, so use the mem0 client directly.
constructed: Mem0SystemAdapter
```

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A; deprecation notice only.
- Stable/default behavior changed: No. The adapter works as before and
additionally warns when constructed.
- Kill switch / disable path: Standard `warnings` filters.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this commit.

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

## Screenshots (if applicable)

N/A.

## Additional Notes

Part of maintainer-requested cleanup #4136 (dead code, duplication,
debuggability), split into small PRs for review.

- The audit first proposed deleting the module and its subpackage
`__all__` entry. Under the deprecate-first rule for public API, it is
deprecated here instead.
- Removal from `headroom.memory.backends.__all__` and from the lazy
export is deferred to the removal release.
- No user docs mention it.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 09:04:25 -07:00
Tejas ChopraandClaude Opus 5.5 235043d39b refactor(memory): deprecate unused SQLiteMemoryStore.count_sync (#4113)
## Description

`SQLiteMemoryStore.count_sync` has no callers in Headroom or in the
org's other repos. The class is re-exported from
`headroom.memory.adapters`, so the method is public API. This PR
deprecates it instead of deleting it. It keeps working and now emits a
`DeprecationWarning`.

**What to use instead:** the async `await
store.count(MemoryFilter(include_superseded=True))`. It runs the same
unfiltered `COUNT(*)`, superseded rows included.

`HNSWVectorIndex.set_ef_search` is left as it is. Review pointed out
that `MemoryConfig.hnsw_ef_search` and the `ef_search` constructor
argument only set ef when the index is built, and nothing else tunes a
live index.

Evidence: `grep -rnw` for `count_sync` across `headroom crates plugins
sdk docs wiki scripts benchmarks examples e2e .github tests` and the
consumer repos finds only the definitions.

Refs #4136

## Type of Change

- [ ] 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
- [x] Code refactoring (no functional changes)

## Changes Made

- `headroom/memory/adapters/sqlite.py`: `count_sync` warns. Its
docstring gets `.. deprecated::` and names the replacement.
- `tests/test_memory/test_adapter_deprecations.py` (new):
  - asserts the warning fires and `count_sync` still returns the count.

## 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 -q -p no:cacheprovider -rs tests/test_memory/test_adapter_deprecations.py tests/test_hnsw_only.py tests/test_memory/test_hierarchical.py tests/test_memory/test_adapters_connection_leak.py
======================= 52 passed, 503 warnings in 7.87s =======================
$ mypy headroom/memory/adapters/sqlite.py --ignore-missing-imports
Success: no issues found in 1 source file
$ uvx ruff@0.16.8 check <changed files>
All checks passed!
```

## Real Behavior Proof

- Environment: macOS, Python 3.12.13 with hnswlib installed, repo .venv,
branch checkout at 0d4286df (base a9815bbb), temp HOME /
HEADROOM_WORKSPACE_DIR / CODEX_HOME, offline.
- Exact command / steps:
- Ran the shared smoke harness, which starts a real proxy from this
checkout against a local fake upstream and sends one Anthropic and one
OpenAI request with a compressible tool result.
- Ran `python -W always`. It calls `count_sync()` and the replacement on
a real SQLite store, then calls `set_ef_search(64)` on a real HNSW
index.
- Observed result:
  - Both proxy requests return HTTP 200 with savings.
- `count_sync` warns once and returns the same count as the replacement.
  - `set_ef_search` applies the value with no warning.
- Not tested: Nothing else. No runtime path calls `count_sync`.

```text
$ bash smoke.sh <worktree>
branch: cleanup/memory-cache-deprecate-adapter-methods @ 0d4286df
health: 200
POST /v1/messages        -> HTTP200 smoke-ok
POST /v1/chat/completions -> HTTP200 smoke-ok
stats: requests=2 failed=0 tokens_saved=13574 savings_percent=99.82
proxy.log WARNING/ERROR lines:
   2 headroom.proxy - WARNING - event=proxy_offline_mode air-gap active — every connection Headroom initiates is refused (telemetry, update check, license reporter, model/tokenizer/binary/dataset downloads, remote Kompress, OTLP/Langfuse export, Copilot auth, subscription polling, OpenAI embedders, Headroom Cloud compression). Still allowed on purpose: forwarding your requests to the upstream you 
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch found no usable file for chopratejas/kompress-v2-base
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch refused for chopratejas/kompress-v2-base (HEADROOM_OFFLINE is set): HEADROOM_OFFLINE is set: refusing outbound network access for HuggingFace download of chopratejas/kompress-v2-base/onnx/kompress-int8-wo.onnx to huggingface.co. Unset HEADROOM_OFFLINE, or turn off the feature that needs this connection.

$ HOME=$TMP/home HEADROOM_WORKSPACE_DIR=$TMP/ws CODEX_HOME=$TMP/codex python -W always -c "<count_sync(); await count(MemoryFilter(include_superseded=True)); HNSWVectorIndex(dimension=8).set_ef_search(64)>"
<string>:6: DeprecationWarning: SQLiteMemoryStore.count_sync is deprecated and will be removed in a future release; use the async count(MemoryFilter(include_superseded=True)) instead.
count_sync -> 0
count(MemoryFilter(include_superseded=True)) -> 0
set_ef_search(64) -> 64 (no warning)
```

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A; deprecation notice only.
- Stable/default behavior changed: No. The methods behave as before and
additionally warn.
- Kill switch / disable path: Standard `warnings` filters.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this commit.

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

## Screenshots (if applicable)

N/A.

## Additional Notes

Part of maintainer-requested cleanup #4136 (dead code, duplication,
debuggability), split into small PRs for review.

- The audit first proposed deleting these methods together with other
dead symbols. Under the deprecate-first rule for public API, they are
split out and deprecated here.
- Neither method is documented. Docs impact is recorded in the cleanup
docs ledger.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 09:04:12 -07:00
Tejas ChopraandClaude Opus 5.5 2e497cbec3 refactor(memory): deprecate the never-wired agent memory writers (#4101)
## Description

`headroom/memory/writers/` exports memories to agent files (CLAUDE.md,
`.cursor/rules`, AGENTS.md, generic markdown). It arrived in 0fd6dfca,
and no product code has ever imported it. `headroom learn` writes agent
context files through `headroom.learn.writer`, a separate writer. The
package lists its classes in `__all__`, so it is public API. This PR
deprecates it instead of deleting it. Importing
`headroom.memory.writers` now emits a `DeprecationWarning`.

**What to use instead:** there is no replacement. For writing agent
context files, `headroom learn` (`headroom.learn.writer`) is the
supported path.

Evidence:
- `grep -rnE 'memory\.writers|MemoryWriter|AgentWriter|ExportResult'`
finds only the package itself, `memory/budget.py` (removed in a separate
PR) and tests. The search covered `headroom crates plugins sdk docs wiki
scripts benchmarks examples e2e .github pyproject.toml` and the consumer
repos.
- The package is not re-exported from `headroom.memory` and not
documented.

Refs #4136

## Type of Change

- [ ] 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
- [x] Code refactoring (no functional changes)

## Changes Made

- `headroom/memory/writers/__init__.py`:
- Emit `DeprecationWarning("headroom.memory.writers is deprecated and
will be removed in a future release; it has no replacement …")` when the
package is imported. Importing any submodule, such as
`headroom.memory.writers.base`, runs the package first, so that warns
too.
  - Add `.. deprecated::` to the docstring.
- `tests/test_memory/test_writers.py`: add one test that asserts the
warning fires on import. The existing writer tests stay.
- Unchanged: `import headroom.memory`, `headroom.memory.sync` and the
sync adapters stay quiet. Checked with `-W error::DeprecationWarning`.

## Testing

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

### Test Output

```text
$ pytest -q -p no:cacheprovider tests/test_memory/test_writers.py tests/test_managed_block_injection.py tests/test_memory/test_budget.py tests/test_memory_sync.py
======================== 92 passed, 1 warning in 1.21s =========================
$ python -W error::DeprecationWarning -c "import headroom.memory, headroom.memory.sync, headroom.memory.sync_adapters.claude_code; print('quiet')"
quiet
$ uvx ruff@0.16.8 check headroom/memory/writers/__init__.py tests/test_memory/test_writers.py
All checks passed!
```

## Real Behavior Proof

- Environment: macOS, Python 3.12.13, repo .venv, branch checkout at
58e5702d (base a9815bbb), temp HOME / HEADROOM_WORKSPACE_DIR /
CODEX_HOME, offline.
- Exact command / steps:
- Ran the shared smoke harness, which starts a real proxy from this
checkout against a local fake upstream and sends one Anthropic and one
OpenAI request with a compressible tool result.
- Ran `python -W always`. It imports `headroom.memory` (the live path),
then imports a writer from the deprecated package directly.
  - Ran the full `tests/test_memory` suite.
- Observed result:
- Both proxy requests return HTTP 200 with savings, and the proxy log
has no deprecation warning.
- `headroom.memory` imports quietly. The direct writers import emits the
new warning, and the writer still loads.
  - 615 passed.
- Not tested: No runtime path imports the package.
`headroom/memory/budget.py` imports it, and #4099 deletes that file.

```text
$ bash smoke.sh <worktree>
branch: cleanup/memory-cache-memory-writers @ 58e5702d
health: 200
POST /v1/messages        -> HTTP200 smoke-ok
POST /v1/chat/completions -> HTTP200 smoke-ok
stats: requests=2 failed=0 tokens_saved=13574 savings_percent=99.82
proxy.log WARNING/ERROR lines:
   2 headroom.proxy - WARNING - event=proxy_offline_mode air-gap active — every connection Headroom initiates is refused (telemetry, update check, license reporter, model/tokenizer/binary/dataset downloads, remote Kompress, OTLP/Langfuse export, Copilot auth, subscription polling, OpenAI embedders, Headroom Cloud compression). Still allowed on purpose: forwarding your requests to the upstream you 
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch found no usable file for chopratejas/kompress-v2-base
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch refused for chopratejas/kompress-v2-base (HEADROOM_OFFLINE is set): HEADROOM_OFFLINE is set: refusing outbound network access for HuggingFace download of chopratejas/kompress-v2-base/onnx/kompress-int8-wo.onnx to huggingface.co. Unset HEADROOM_OFFLINE, or turn off the feature that needs this connection.

$ HOME=$TMP/home HEADROOM_WORKSPACE_DIR=$TMP/ws CODEX_HOME=$TMP/codex python -u -W always -c "import headroom.memory; print(...); from headroom.memory.writers import GenericMemoryWriter; print(...)"
headroom.memory imported
<string>:4: DeprecationWarning: headroom.memory.writers is deprecated and will be removed in a future release; it has no replacement (headroom learn writes agent context files through headroom.learn.writer).
writer: GenericMemoryWriter
```

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A; deprecation notice only.
- Stable/default behavior changed: No. The writers behave as before.
Importing them additionally emits a DeprecationWarning, which Python
hides by default outside `__main__` and tests.
- Kill switch / disable path: Standard `warnings` filters.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this commit.

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

## Screenshots (if applicable)

N/A.

## Additional Notes

Part of maintainer-requested cleanup #4136 (dead code, duplication,
debuggability), split into small PRs for review.

- The audit first proposed deleting the package. Under the
deprecate-first rule for public API, it is deprecated here. Deletion can
follow in a later release.
- The unused budget manager (`memory/budget.py`), which depends on this
package, is removed in a separate PR.
- "My changes generate no new warnings" refers to code that is used. The
only new warning is the intended DeprecationWarning.
- mypy was not run, because no types changed.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 09:03:14 -07:00
Tejas ChopraandClaude Opus 5.5 6d23895dc0 refactor(memory): drop the unused extraction prompts and tool schemas (#4100)
## Description

`headroom/memory/extraction.py` (546 lines) has one product consumer.
`memory/wrapper_tools.py` imports `EXTRACTION_SYSTEM_PROMPT` and injects
it when `with_memory_tools(..., optimized=True)` is used. Everything
else in the module is used only by its own tests. This PR keeps that
prompt and removes the rest:
- three Mem0-derived extraction prompts;
- a conversation-prompt generator;
- an answer prompt;
- an "enhanced" `memory_save` tool schema, a stale duplicate of
`MEMORY_TOOLS_OPTIMIZED` in `memory/tools.py`;
- `get_extraction_tools`.

Evidence:
- `grep -rnE` for each removed name across `headroom crates plugins sdk
docs wiki scripts benchmarks examples e2e .github pyproject.toml` and
the consumer repos finds only the definitions.
- In `tests`, the only hits are `tests/test_memory/test_extraction.py`
and one test in `tests/test_memory_integration.py`.
- `headroom.memory.extraction` is not in `headroom.memory.__all__` and
not in the docs.

Refs #4136

## Type of Change

- [ ] 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
- [x] Code refactoring (no functional changes)

## Changes Made

- `headroom/memory/extraction.py`: keep `EXTRACTION_SYSTEM_PROMPT`,
unchanged byte for byte. Remove these:
- `FACT_EXTRACTION_PROMPT`, `ENTITY_EXTRACTION_PROMPT` and
`RELATIONSHIP_EXTRACTION_PROMPT`;
- `get_conversation_extraction_prompt` and
`CONVERSATION_EXTRACTION_PROMPT_BASIC`;
- `get_memory_answer_prompt`, `MEMORY_SAVE_TOOL_WITH_EXTRACTION` and
`get_extraction_tools`.

  The module docstring now describes what is left.
- `tests/test_memory/test_extraction.py`: keep
`TestExtractionSystemPrompt`. Remove the tests of the deleted names.
- `tests/test_memory_integration.py`:
`test_extraction_prompts_exist_and_valid` now checks only the remaining
prompt.

## Testing

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

### Test Output

```text
$ pytest -q -p no:cacheprovider tests/test_memory/test_extraction.py tests/test_memory_integration.py tests/test_memory_system.py
================ 111 passed, 10 skipped, 512 warnings in 15.86s ================
$ uvx ruff@0.16.8 check headroom/memory/extraction.py tests/test_memory/test_extraction.py tests/test_memory_integration.py
All checks passed!
$ grep -rnE '<each removed name>' headroom tests
(no output)
```

## Real Behavior Proof

- Environment: macOS, Python 3.12.13, repo .venv, branch checkout at
80129a50 (base a9815bbb), temp HOME / HEADROOM_WORKSPACE_DIR /
CODEX_HOME, offline.
- Exact command / steps:
- Ran the shared smoke harness, which starts a real proxy from this
checkout against a local fake upstream and sends one Anthropic and one
OpenAI request with a compressible tool result.
- Ran a direct script. It hashes `EXTRACTION_SYSTEM_PROMPT` from main's
`extraction.py` and from this branch, then runs the real
`with_memory_tools` message preparation
(`MemoryToolsCompletions._prepare_messages`, optimized mode) on a chat.
  - Ran the extraction, memory-integration and memory-system tests.
- Observed result:
  - Both proxy requests return HTTP 200 with savings.
- The prompt hash is identical on main and on this branch, and the
prepared system message ends with that prompt.
- 111 passed. The 10 skips are optional-dependency skips that also skip
on main.
- Not tested: A live LLM call with `optimized=True`. The injected prompt
text is byte-identical.

```text
$ bash smoke.sh <worktree>
branch: cleanup/memory-cache-extraction-prompts @ 80129a50
health: 200
POST /v1/messages        -> HTTP200 smoke-ok
POST /v1/chat/completions -> HTTP200 smoke-ok
stats: requests=2 failed=0 tokens_saved=13574 savings_percent=99.82
proxy.log WARNING/ERROR lines:
   2 headroom.proxy - WARNING - event=proxy_offline_mode air-gap active — every connection Headroom initiates is refused (telemetry, update check, license reporter, model/tokenizer/binary/dataset downloads, remote Kompress, OTLP/Langfuse export, Copilot auth, subscription polling, OpenAI embedders, Headroom Cloud compression). Still allowed on purpose: forwarding your requests to the upstream you 
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch found no usable file for chopratejas/kompress-v2-base
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch refused for chopratejas/kompress-v2-base (HEADROOM_OFFLINE is set): HEADROOM_OFFLINE is set: refusing outbound network access for HuggingFace download of chopratejas/kompress-v2-base/onnx/kompress-int8-wo.onnx to huggingface.co. Unset HEADROOM_OFFLINE, or turn off the feature that needs this connection.

$ HOME=$TMP/home HEADROOM_WORKSPACE_DIR=$TMP/ws CODEX_HOME=$TMP/codex python -u -c "<sha256 of main vs branch prompt; MemoryToolsCompletions(..., optimized=True, inject_extraction_prompt=True)._prepare_messages(chat)>"
prompt sha256 main   8e238b94c784a3ae
prompt sha256 branch 8e238b94c784a3ae
system message ends with the prompt: True | length 846
```

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A; dead-code removal.
- Stable/default behavior changed: No. The one prompt that is used is
unchanged.
- Kill switch / disable path: N/A.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this commit.

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

## Screenshots (if applicable)

N/A.

## Additional Notes

Part of maintainer-requested cleanup #4136 (dead code, duplication,
debuggability), split into small PRs for review.

- This is a pure deletion (−1324 lines, about 510 product), so it is
larger than the 400-line guide.
- `headroom.memory.extraction` stays importable, but anything outside
this repo that imported the removed names would break. Nothing in the
org's repos does.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 08:59:08 -07:00
Tejas ChopraandClaude Opus 5.5 e7ac6ca6f8 refactor(memory): remove the unused memory budget manager (#4099)
## Description

`headroom/memory/budget.py` (`MemoryBudgetManager`, `BudgetConfig`,
`BudgetReport`) ranks, prunes and merges exported memories against a
token budget. It came in with the agent memory writers in 0fd6dfca, and
product code has never imported it. This PR removes it and its tests.

It meets none of the public-API criteria:
- it has no `__all__`;
- it is not re-exported from `headroom.memory` or any lazy map;
- it is not documented;
- no consumer repo imports it.

Evidence: `grep -rnE
'memory\.budget|MemoryBudgetManager|BudgetConfig|BudgetReport'` across
`headroom crates plugins sdk docs wiki scripts benchmarks examples e2e
.github pyproject.toml tests` and the consumer repos finds only the
module and `tests/test_memory/test_budget.py`.

Refs #4136

## Type of Change

- [ ] 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
- [x] Code refactoring (no functional changes)

## Changes Made

- Delete `headroom/memory/budget.py` (302 lines).
- Delete `tests/test_memory/test_budget.py` (215 lines).

## Testing

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

### Test Output

```text
$ pytest -q -p no:cacheprovider tests/test_memory
===================== 600 passed, 1000 warnings in 54.16s ======================
$ grep -rnE 'memory\.budget|MemoryBudgetManager|BudgetConfig|BudgetReport' headroom tests
(no output)
```

## Real Behavior Proof

- Environment: macOS, Python 3.12.13, repo .venv, branch checkout at
a89ea78e (base a9815bbb), temp HOME / HEADROOM_WORKSPACE_DIR /
CODEX_HOME, offline.
- Exact command / steps:
- Ran the shared smoke harness, which starts a real proxy from this
checkout against a local fake upstream and sends one Anthropic and one
OpenAI request with a compressible tool result.
- Ran a direct script with DeprecationWarning promoted to an error. It
resolves every name in `headroom.memory.__all__`, including the lazy
exports, and checks that the budget module is gone.
  - Ran the full `tests/test_memory` package.
- Observed result:
  - Both proxy requests return HTTP 200 with savings.
- All 48 `headroom.memory` exports resolve, and `headroom.memory.budget`
no longer exists.
  - 600 passed.
- Not tested: No runtime path imported the module.

```text
$ bash smoke.sh <worktree>
branch: cleanup/memory-cache-memory-budget @ a89ea78e
health: 200
POST /v1/messages        -> HTTP200 smoke-ok
POST /v1/chat/completions -> HTTP200 smoke-ok
stats: requests=2 failed=0 tokens_saved=13574 savings_percent=99.82
proxy.log WARNING/ERROR lines:
   2 headroom.proxy - WARNING - event=proxy_offline_mode air-gap active — every connection Headroom initiates is refused (telemetry, update check, license reporter, model/tokenizer/binary/dataset downloads, remote Kompress, OTLP/Langfuse export, Copilot auth, subscription polling, OpenAI embedders, Headroom Cloud compression). Still allowed on purpose: forwarding your requests to the upstream you 
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch found no usable file for chopratejas/kompress-v2-base
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch refused for chopratejas/kompress-v2-base (HEADROOM_OFFLINE is set): HEADROOM_OFFLINE is set: refusing outbound network access for HuggingFace download of chopratejas/kompress-v2-base/onnx/kompress-int8-wo.onnx to huggingface.co. Unset HEADROOM_OFFLINE, or turn off the feature that needs this connection.

$ HOME=$TMP/home HEADROOM_WORKSPACE_DIR=$TMP/ws CODEX_HOME=$TMP/codex python -u -W error::DeprecationWarning -c "<getattr(headroom.memory, n) for n in __all__; find_spec('headroom.memory.budget')>"
headroom.memory: resolved all 48 names in __all__
headroom.memory.budget spec -> None
```

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A; dead-code removal.
- Stable/default behavior changed: No.
- Kill switch / disable path: N/A.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this commit.

## 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
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] 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)

## Screenshots (if applicable)

N/A.

## Additional Notes

Part of maintainer-requested cleanup #4136 (dead code, duplication,
debuggability), split into small PRs for review.

- This is a pure deletion of two whole files, so ruff and mypy have
nothing to check.
- The agent memory writers that this module used are deprecated, not
deleted, in a separate PR, because they are listed in the package
`__all__`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 08:58:59 -07:00
ChesterandJerrettDavis 1631cde686 fix(learn): preserve stable traffic pattern items (#2293)
## Description

Fixes #2294. Follow-up to #231.

TrafficLearner can re-surface a learned section with only a subset of
previously written patterns. The writer currently replaces a same-named
section as one unit, so a valid prior preference, environment fact, or
architecture rule can disappear even though it was not contradicted.

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

- Add opt-in same-section markdown-item preservation to Recommendation.
- Render stable pattern IDs for TrafficLearner preference, environment,
and architecture bullets.
- Prefer new text when a stable ID reappears and deduplicate legacy
ID-less bullets by visible content.
- Keep error-recovery sections authoritative so expiry and refinement
still remove stale entries.
- Leave every other Headroom Learn analyzer on the existing same-section
replacement behavior.

## 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
170 focused writer and TrafficLearner tests passed
full tests/test_learn plus TrafficLearner run completed without failures
ruff check: passed
ruff format --check: passed
```

## Real Behavior Proof

- Environment: macOS, Python 3.13, current Headroom main.
- Exact command / steps: write a prior Learned: preference section
containing a stable-ID item and a legacy ID-less item, merge a new
recommendation with the same section and stable ID, then inspect the
rebuilt marker block.
- Observed result: new text wins for the repeated stable ID, the
unrelated prior bullet remains, and the legacy duplicate appears only
once. Error-recovery recommendations retain replacement behavior.
- Not tested: full repository suite, live proxy traffic, or migration of
arbitrary non-list markdown sections.

## Review Readiness

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

## Checklist

- [x] My code follows the project style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented code where the behavior is not self-explanatory
- [x] I have made corresponding documentation changes
- [x] My changes generate no new warnings
- [x] I have added tests that prove the fix is effective
- [x] New and existing focused unit tests pass locally
- [x] I have updated CHANGELOG.md if applicable

## Screenshots (if applicable)

Not applicable.

## Additional Notes

Draft for maintainer feedback on the opt-in merge boundary and stable-ID
representation. Already persisted incorrect rules are intentionally not
deleted automatically.

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-02 23:34:27 -05:00
gglucassandClaude Fable 5 4257ed4df3 feat(memory): persist TrafficLearner pending evidence across restarts + expose learner stats (#3104)
## Description

Pending (sub-threshold) TrafficLearner evidence lives only in
`_pattern_counts`, so every proxy restart zeroes the counters. A user
who accumulates 4 sightings of a pattern loses all of them on the next
app update or quit, which makes `min_evidence=5` effectively unreachable
for short or restart-heavy sessions - auto-learning looks dead even
though it is working. (Surfaced by a beta tester who used Claude Code ~6
hours across several days behind the proxy and saw zero learnings.)

This PR persists pending evidence across restarts via a
`pending_patterns.json` sidecar next to `memory.db`, and exposes learner
progress in the `/stats` payload so dashboards can show that learning is
alive before the first pattern crosses the threshold.

Follow-up to #2579, which bounded the same accumulator (the LRU cap is
respected on load).

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] 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

- `TrafficLearner._save_pending_state()`: snapshot `_pattern_counts` to
`pending_patterns.json` (atomic tmp+rename), called on `stop()` and on
each debounced flush cycle so a crash loses at most one debounce window.
- `TrafficLearner._load_pending_state()`: rehydrate on `start()` after
`_hydrate_persisted_state()`; skips entries whose hash is already
persisted (re-sightings bump the existing row instead), tolerates
corrupt/unreadable sidecars, and respects `max_pending_patterns`.
- `get_stats()` now includes `min_evidence` so consumers can render
progress like "seen 3 of 5 times".
- `/stats` payload gains a `traffic_learner` block
(`proxy.traffic_learner.get_stats()`, `null` when learning is disabled).
- 3 new tests: restart survival end to end, corrupt sidecar ignored,
already-saved hash not rehydrated.

## 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
$ uv run --frozen --extra dev pytest tests/test_memory/test_traffic_learner.py
============================= 157 passed in 2.82s ==============================

$ uvx ruff check headroom/memory/traffic_learner.py headroom/proxy/server.py tests/test_memory/test_traffic_learner.py
All checks passed!
$ uvx ruff format --check headroom/memory/traffic_learner.py headroom/proxy/server.py tests/test_memory/test_traffic_learner.py
3 files already formatted

$ uv run --frozen --extra dev mypy headroom/memory/traffic_learner.py
Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: macOS 15.6 (Darwin 24.6.0), Python 3.12, branch at
8895e054
- Exact command / steps: scripted two learner "processes" against the
same memory.db in a temp dir: process 1 accumulates 4 sightings of one
ENVIRONMENT pattern (min_evidence=5) and stops; process 2 starts fresh,
then sees the pattern a 5th time.
- Observed result: process 1 stats `{'patterns_extracted': 4,
'patterns_saved': 0, 'pending_patterns': 1, 'min_evidence': 5, ...}`;
sidecar after stop contains the pattern with `"count": 4`; process 2
stats after restart show `'pending_patterns': 1` before any traffic;
after the 5th sighting the DB row is saved with `evidence_count == 5`.
- Not tested: the full proxy path over live agent traffic (learner unit
surface only); mem0/remote backends, where `_resolve_backend_db_path`
returns None and persistence is a silent no-op (pre-existing behavior
for hydrate as well).

## Runtime Rollout Safety

- Rollout-managed feature(s): none - not behind a rollout flag.
- Minimum rollout channel: n/a
- Stable/default behavior changed: pending evidence now survives
restarts (the intended change); a small `pending_patterns.json` appears
next to memory.db. No change when learning is disabled or no local
backend is configured.
- Kill switch / disable path: disabling the traffic learner (existing
toggle) stops both writes and reads; deleting the sidecar restores
per-process behavior.
- Unsafe override required: no
- Qualification impact: none - `/stats` gains one additive key.
- Rollback path: revert the commit; stale sidecars are ignored dead
weight for older builds (never read).

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

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-10-01 16:09:01 -05:00
Ashish 231a627702 fix(memory): close SQLite connections in memory/fts5/graph adapters (#3153)
## Description

`_get_conn()` in
`headroom/memory/adapters/{sqlite,fts5,sqlite_graph}.py` opens a fresh
`sqlite3.Connection` on every call, and every call site uses `with
self._get_conn() as conn:`. In Python's stdlib,
`Connection.__enter__`/`__exit__` only commit/rollback the transaction
on exit — they never close the connection. None of these three files
ever call `.close()`, so every memory save/query/search/delete leaks one
OS file descriptor. In a long-lived proxy process this exhausts the FD
ulimit and eventually fails with `OSError: [Errno 24] Too many open
files`. The sibling `adapters/sqlite_vector.py` gets this right
(explicit per-thread cached connections + `close()`), which is what made
the omission here stand out.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)

## Changes Made

- `headroom/memory/adapters/sqlite.py`: `_get_conn()` is now a
`@contextlib.contextmanager` that commits/rolls back via `with conn:`
and closes the connection in a `finally` block.
- `headroom/memory/adapters/fts5.py`: same fix.
- `headroom/memory/adapters/sqlite_graph.py`: same fix, preserving the
existing page-cache/foreign-key PRAGMA setup before the connection is
yielded.
- No call sites changed — `with self._get_conn() as conn:` still works
identically against a context-manager-returning method.
- Added `tests/test_memory/test_adapters_connection_leak.py` covering
all three adapters.

## Testing

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

### Test Output

```text
$ uv run pytest tests/test_memory/test_adapters_connection_leak.py -v
tests/test_memory/test_adapters_connection_leak.py::test_sqlite_memory_store_closes_connections PASSED
tests/test_memory/test_adapters_connection_leak.py::test_fts5_text_index_closes_connections PASSED
tests/test_memory/test_adapters_connection_leak.py::test_sqlite_graph_store_closes_connections PASSED
3 passed in 0.34s

$ uv run pytest tests/test_sqlite_graph_store.py tests/test_memory/ tests/cli/test_memory.py \
    tests/test_security_validations.py tests/test_cli_memory_index_sync.py -q
689 passed, 6 skipped, 79 warnings in 24.41s

$ uv run ruff check headroom/memory/adapters/sqlite.py headroom/memory/adapters/fts5.py \
    headroom/memory/adapters/sqlite_graph.py tests/test_memory/test_adapters_connection_leak.py
All checks passed!

$ uv run mypy headroom/memory/adapters/sqlite.py headroom/memory/adapters/fts5.py \
    headroom/memory/adapters/sqlite_graph.py
Success: no issues found in 3 source files
```

## Real Behavior Proof

- Environment: macOS, Python 3.11 (uv-managed venv), headroom repo at
`main` (post-#3094)
- Exact command / steps: added
`tests/test_memory/test_adapters_connection_leak.py`, which
monkeypatches `sqlite3.connect` to record every connection created by
`SQLiteMemoryStore`, `FTS5TextIndex`, and `SQLiteGraphStore` during
construction + one real operation (`save`/`index_raw`/`add_entity`),
then asserts each recorded connection raises `sqlite3.ProgrammingError`
on use (i.e. is closed). Ran it against the pre-fix code, then against
the fix.
- Observed result: against pre-fix code all 3 tests failed with `Failed:
DID NOT RAISE <class 'sqlite3.ProgrammingError'>` (connections stayed
open). Against the fix all 3 pass, and the full `test_memory/` +
`test_sqlite_graph_store.py` suites (689 tests) still pass unchanged.
- Not tested: a real FD-exhaustion soak test (thousands of connections
against a live proxy until `ulimit -n` is hit) — the monkeypatched
close-assertion is an equivalent, much faster proxy for the same fact,
so I didn't run a soak test.

## Runtime Rollout Safety

- Rollout-managed feature(s): none — this is unconditional bug-fix
behavior, not gated by any rollout flag.
- Minimum rollout channel: N/A
- Stable/default behavior changed: connections now close after each
operation (previously leaked); transaction commit/rollback semantics are
unchanged.
- Kill switch / disable path: N/A (no flag; revert the commit if needed)
- Unsafe override required: N/A
- Qualification impact: none
- Rollback path: revert this commit

## 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
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] 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)

## Additional Notes

Found while auditing the codebase for unreported bugs (not an existing
GitHub issue). Two more candidates from the same audit (unbounded
`by_model` dict growth in `savings_tracker.py`, and a `CompressionCache`
leak contradicting its own docstring in `content_router.py`) will follow
as separate PRs.
2026-09-30 23:54:43 -05:00
TrîggeredandJD Davis 143a38d56f fix(memory): ignore leading cd prefix when pairing Bash error recoveries (#3776)
## Description

`TrafficLearner` pairs unrelated Bash commands into `Learned: error
recovery` rules when both commands start with the same `cd <dir> &&`
prefix. Coding agents add that prefix to almost every Bash call, so most
Bash recoveries written to `MEMORY.md` are bogus. Two examples written
to my `MEMORY.md`:

```
- Command `cd "C:\...\repo" && grep -rn "shopping-vintage" ... -l .` fails (timeout).
  Use `cd "C:\...\repo" && cat components/places/categoryIcons.ts && ...` instead.
- Command `cd "C:\...\repo" && npx vitest run "...SubmitPlaceForm.test.tsx" 2>&1 | tail -40` fails (runtime_error).
  Use `cd "C:\...\repo" && git add -A && git commit -F - <<'EOF' ...` instead.
```

The second rule tells the agent to commit instead of running the tests.

Two defects compound:

1. **Matcher false positives.** `_commands_related_as_retry` requires
the same first binary, plus either ≤40% edit distance or a shared
substantive token. When both commands share a `cd <dir> &&` prefix, the
first binary is always `cd` and the directory path is always a shared
token of ≥5 characters, so any two such commands pass.
2. **Hash collapse inflates evidence.** `_normalize_bash_for_hash` cuts
at the first `&&`, so every cd-prefixed pair hashes to
`error_recovery|Bash|cd <dir>|cd <dir>`. Unrelated pairs in one project
merge into a single row whose evidence is the sum of all of them. That
is how they get past the `min_evidence` gate.

This is a follow-up to #326, which introduced the retry matcher and the
evidence gate. I found no existing issue or PR for this.

Closes # (no existing issue)

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

- Add `_strip_leading_cd()` in `headroom/memory/traffic_learner.py`. It
removes leading `cd <dir> &&` / `cd <dir>;` segments, including quoted
paths, backslash-escaped spaces (`cd /home/dev/my\ project && ...`) and
repeated segments. A bare `cd <dir>` with no chain is left unchanged.
- Apply it in `_commands_related_as_retry` before the binary,
edit-distance and token-overlap checks.
- Apply it in `_normalize_bash_for_hash`, so the hash key reflects the
command that actually ran.
- Tests in `tests/test_memory/test_traffic_learner.py`:
- `test_shared_cd_prefix_alone_is_not_retry` and
`test_strips_leading_cd` fail on `main` and pass with this change.
- `test_cd_prefixed_retry_still_matches` guards against rejecting real
retries.
- **Changed expectation:** `test_cuts_at_first_chain` previously
asserted `_normalize_bash_for_hash("cd /tmp && ls") == "cd /tmp"`. That
assertion encoded the bug. It now uses `make build && ls`, and the cd
case moved to `test_strips_leading_cd`, which asserts `"cd /tmp && ls"`
normalizes to `"ls"`.

## Testing

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

### Test Output

```text
$ pytest tests/test_memory/test_traffic_learner.py -k "CommandsRelatedAsRetry or NormalizeBashForHash or RefineErrorRecovery or NormalizedHash"
=============== 35 passed, 122 deselected, 39 warnings in 0.80s ===============

# New tests on main (fix reverted), full file:
FAILED tests/test_memory/test_traffic_learner.py::TestCommandsRelatedAsRetry::test_shared_cd_prefix_alone_is_not_retry
FAILED tests/test_memory/test_traffic_learner.py::TestNormalizeBashForHash::test_strips_leading_cd

$ ruff check .
All checks passed!

$ mypy headroom/memory/traffic_learner.py
Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.14, headroom 0.38.0, Claude Code via
`headroom proxy --learn --memory`.
- Exact command / steps: Read every persisted `traffic_learner` Bash
`error_recovery` row from my own `memory.db` (read-only). Run
`_commands_related_as_retry` and `_normalize_bash_for_hash` on each
row's `failed_cmd` / `success_cmd`, first with `main` and then with this
branch.
- Observed result: 72 of 96 Bash rows had a cd prefix on both sides, and
`main` accepted all 72 as retries; on this branch 16 are accepted. On
`main` those rows also shared hash keys (e.g. 6 unrelated pairs on one
`cd <repo>|cd <repo>` key); on this branch every row gets its own key.
- Not tested: A full proxy session on Linux or macOS. I also did not
check how long existing polluted rows take to disappear from a live
`MEMORY.md` after upgrading.

## Runtime Rollout Safety

- Rollout-managed feature(s): None
- Minimum rollout channel: dev
- Stable/default behavior changed: Yes, narrowly. Bash error-recovery
pairing and hash keys ignore a leading `cd <dir>` segment. Nothing else
changes.
- Kill switch / disable path: N/A (existing `--learn` opt-in is
unchanged)
- Unsafe override required: No
- Qualification impact: None
- Rollback path: Revert commit

## 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
- [ ] 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
- [ ] New and existing unit tests pass locally with my changes (see
Additional Notes)
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A

## Additional Notes

- **Unit tests.** On my Windows machine, 45 tests in
`test_traffic_learner.py` already fail on `main`. Examples are
`TestProjectForPattern` (POSIX path fixtures) and
`TestUserAuthoredPreferenceFiltering`. The set of failing tests is
identical before and after this change, apart from the new tests. I have
not run the suite on Linux/macOS and am relying on CI for that.
- **Type checking.** `mypy headroom` reports one error on Windows, in
`headroom/fileperms.py:71` (`os.fchmod` does not exist on Windows). That
file is untouched here. The changed module passes mypy.
- **Documentation.** N/A, this is an internal matcher fix.
- **Out of scope.** 16 remaining accepted pairs include some that are
still questionable, where commands share a binary and a file name, e.g.
`git status --short lib/x.ts` → `git add lib/x.ts && git commit`. That
is a broader weakness of the token-overlap rule for compound commands.
- **Existing hash keys move.** Any Bash command with a leading `cd
<dir>` segment now normalizes to a different hash key, so rows persisted
under the old key are not re-keyed. Their accumulated evidence counts
are orphaned and learning for those commands restarts from zero. This is
intentional: the old keys merged unrelated pairs, so their evidence was
inflated.
- **Existing rows.** Rows already persisted with the collapsed hash are
not rewritten. They split into separate hashes on load, so most should
fall below `min_evidence`, and the 21-day hard floor retires the rest. I
did not add render-time re-validation for Bash rows, because
`test_bash_recoveries_not_revalidated` documents that as intentional.

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-09-30 22:41:13 -05:00
Abhay SinghandJerrettDavis 7e73438dc5 perf(memory): bound traffic-learner _persisted_ids with the dedup window (#3341)
## Description

`HeadroomTrafficLearner._persisted_ids` (a `dict[content_hash,
memory_id]`) grew **one entry per distinct persisted pattern for the
whole process lifetime** and was never trimmed, while its sibling dedup
set `_saved_hashes` **is** trimmed to `dedup_window`:

```python
self._saved_hashes.add(h)
if len(self._saved_hashes) > self._dedup_window:
    self._saved_hashes.pop()          # trimmed
# ...
self._persisted_ids[pattern.content_hash] = memory_id   # never trimmed
```

`_persisted_ids` is only ever *read* behind an `if h in
self._saved_hashes:` guard (the dedup shortcut at the top of
`_accumulate`). So once a hash leaves the dedup window, its
`_persisted_ids` entry can never be read again — it's pure dead weight
on the long-lived learner (which owns background save/flush tasks). The
asymmetry is the tell: `_saved_hashes` is trimmed and `_pattern_counts`
is LRU-capped right next to this, but `_persisted_ids` was missed.

The fix keeps the two in lockstep:
- When `_saved_hashes` evicts a hash, drop its `_persisted_ids` entry in
the same step.
- The async save worker records an id only while its hash is still
tracked in `_saved_hashes` (it may have been evicted between enqueue and
persist).

Neither changes the dedup/bump semantics — a hash evicted from
`_saved_hashes` was already re-learnable and could already produce a
duplicate row; these only stop `_persisted_ids` from leaking.

Reproduction (before): 200 distinct persisted patterns with
`dedup_window=4` → `_persisted_ids` holds ~200 entries while
`_saved_hashes` holds ≤4. After: `_persisted_ids` stays a subset of
`_saved_hashes`, bounded to ≤4.

## Type of Change

- [ ] 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
- [x] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/memory/traffic_learner.py`: on `_saved_hashes` eviction in
`_accumulate`, capture the popped hash and `_persisted_ids.pop(evicted,
None)`; in `_save_worker`, guard the id record with `and
pattern.content_hash in self._saved_hashes`.
- `tests/test_memory/test_traffic_learner.py`: added
`test_persisted_ids_bounded_in_lockstep_with_saved_hashes` — feeding 200
distinct patterns through a `dedup_window=4` learner leaves
`_persisted_ids` a subset of `_saved_hashes` and bounded to ≤4 (not
200).

## Testing

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

### Test Output

```text
tests/test_memory/test_traffic_learner.py  ->  153 passed, 2 failed
  (the 2 failures are pre-existing on main in TestProjectForPattern — project-root
   path matching, unrelated to this change; confirmed they fail without this patch)
uvx ruff@0.16.2 check headroom/memory/traffic_learner.py tests/test_memory/test_traffic_learner.py  ->  All checks passed!
uvx mypy@1.20.2 headroom/memory/traffic_learner.py  ->  Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.12.11, project venv, pytest 9.1.1,
ruff 0.16.2 and mypy 1.20.2 via uvx.
- Exact command / steps: drove `_accumulate` with 200 distinct patterns
(each corroborated to `min_evidence=1`) through a `dedup_window=4`
learner, recording an id for each still-tracked hash. Without the fix
`_persisted_ids` held ~200 entries and was not a subset of the 4-element
`_saved_hashes` (test fails). With the fix it stays a subset and ≤4.
Confirmed the two `TestProjectForPattern` failures pre-date this change
by stashing the patch.
- Observed result: `_persisted_ids` no longer grows without bound; it
tracks the dedup window. Dedup/bump behavior for in-window hashes is
unchanged.
- Not tested: an end-to-end run against a live memory backend (the async
`_save_worker` path needs a backend); the eviction/record invariant is
exercised directly, and the worker guard mirrors it.

## Runtime Rollout Safety

- Rollout-managed feature(s): none.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: no. Dedup shortcut and evidence-bump
behavior are unchanged for any hash still in the dedup window; only
stale `_persisted_ids` entries (already unreadable) are dropped.
- Kill switch / disable path: N/A.
- Unsafe override required: no.
- Qualification impact: none.
- Rollback path: revert this commit; `_persisted_ids` goes back to
unbounded growth.

## 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
- [ ] I have made corresponding changes to the documentation (N/A:
internal memory bound)
- [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`

## Additional Notes

This mirrors the bounding already applied to `_saved_hashes`
(dedup_window trim) and `_pattern_counts` (LRU cap) in the same class,
closing the one companion structure that was left uncapped.

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-09-30 11:16:58 -05:00
Tejas ChopraandClaude Opus 5 b10dd8db6e fix(memory): pin LF on memory writers and guard the learn-writer newline contract (#3706)
Closes #3698. Follow-up to #3594, which fixed `headroom/learn/writer.py`
correctly but left three gaps.

## 1. The write half had no regression guard

`test_apply_does_not_accumulate_carriage_returns_on_crlf_file` passes on
`main` with the fix reverted — its assertion (`raw.count(b"\r") ==
raw.count(b"\r\n")`) holds for a CRLF-preserving file too. So the
`newline="\n"` pins, which *are* the fix, were unguarded.

This cannot be caught by asserting on file bytes on POSIX: CPython's C
`TextIOWrapper` picks the newline translation target at compile time
(`#ifdef MS_WINDOWS`), so monkeypatching `os.linesep` does not simulate
Windows.

The new test spies on `Path.write_text` and drives the real writer
`.write()` methods. Stripping the kwargs from all seven sites:

```
tests/test_learn/test_writer.py ................................F
E   AssertionError: learn writers wrote without newline='\n': [
E     .../data/memory/MEMORY.md, .../instructions.md, .../myproject/AGENTS.md,
E     .../myproject/CLAUDE.local.md, .../myproject/CLAUDE.md,
E     .../myproject/GEMINI.md, .../myproject/GROK.md]
=================== 1 failed, 32 passed ===================
```

All seven named — and note the other 32 pass, including the old test,
confirming it was never a guard.

## 2. The same bug was still live in the memory writers

Ten call sites, all nine from the issue plus
**`headroom/memory/sync.py:137`** (`_save_sync_state`), which the issue
missed:

`writers/base.py:168` · `writers/claude_writer.py:119` ·
`writers/cursor_writer.py:130` · `bridge.py:126, 394, 650` ·
`sync.py:137` · `sync_adapters/codex_agent.py:124` ·
`sync_adapters/claude_code.py:196, 239`

These write files that **overlap** with the learn writers
(`~/.claude/CLAUDE.md`, `AGENTS.md`), so on Windows a file flipped
between LF and CRLF depending on which subsystem wrote last.

**No live accumulation bug:** every reader of these files uses
`read_text()`, which normalizes — that is the key difference from
`learn/writer.py`'s `read_bytes().decode()`, which is what let `\r` pile
up. Checked all of them (`bridge.py:114, 222, 617`,
`writers/base.py:193`, `writers/cursor_writer.py:103`,
`sync_adapters/claude_code.py:106, 163, 178, 216`,
`sync_adapters/codex_agent.py:48, 83`, `sync.py:127`).

**But the churn is more than cosmetic**, which the issue did not note:
`claude_code.py:252` and `codex_agent.py:135` read via `read_bytes()`
for `fingerprint()` change-detection hashing. An EOL flip changes the
hash, so a CRLF/LF flip reads as a content change and triggers a
spurious re-sync.

Three new tests cover the writer, bridge and sync-adapter paths; all
three fail with the pins stripped.

## 3. No unit test had ever run on Windows

The sharded `test` job is ubuntu-only, and `build-wheel-windows` builds
without testing — which is how a Windows-only bug shipped twice. Added
`test-windows-newline`: consumes the existing `headroom-wheel-windows`
artifact and runs only tests marked `windows_newline`. Marker registered
in `pyproject.toml`.

**Known limitation, documented in the job comment:** it is gated on the
`packaging` paths-filter (that is what builds the wheel), so a
pure-Python PR skips it. The ubuntu shards still run the same marked
tests — they assert the kwarg, which fails on any platform — so this is
the Windows-side backstop, not the only guard. Making it fire on every
writer change would mean gating the Windows Rust wheel build on `code`,
which is too expensive to do unasked.

## Verification

- 4 guards proven to fail before, pass after.
- `tests/test_learn/ tests/test_memory/ tests/test_memory_sync.py` →
**950 passed, 4 skipped**.
- Adjacent suites → 168 passed. `pytest tests -m windows_newline` → 4
passed, no marker warning.
- `actionlint .github/workflows/*.yml` → exit 0. Action versions match
the file's conventions (`checkout@v7`, `setup-python@v7`,
`download-artifact@v8`).

`CONTRIBUTING.md` states the invariant once under Coding standards:
Headroom writes LF and normalizes on read, on every platform.

## Not in this PR

Issue section 3's release-note line about the one-time EOL churn on
Windows (the first `--apply` rewrites the whole file to LF). Harmless
under `autocrlf=true`, but worth a release note; `CHANGELOG.md` edits
are blocked by `changelog-guard.yml`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-29 11:18:03 -05:00
Abhay Singh e911496463 fix(memory/sqlite): match numeric and boolean metadata filters, not just strings (#3240)
## Description

`SQLiteMemoryStore._build_query_conditions` binds a metadata filter
value as JSON text for anything that isn't a `str`:

```python
conditions.append(f"json_extract(metadata, '$.{key}') = ?")
params.append(json.dumps(value) if not isinstance(value, str) else value)
```

But `json_extract` returns a **native** SQLite value (INTEGER / REAL /
TEXT). Comparing that against `json.dumps(value)` — `"5"`, `"true"`,
`"1.5"` — never matches, because SQLite does not equate `5 = '5'`. So a
metadata filter on any numeric or boolean value silently returns
**nothing**; only string filters work.

Reproduction (memory stored with `metadata={"priority": 5, "archived":
True, "score": 1.5, "tag": "x"}`):

```python
await store.query(MemoryFilter(user_id="u", metadata_filters={"priority": 5}))    # -> [] (want 1)
await store.query(MemoryFilter(user_id="u", metadata_filters={"archived": True}))  # -> [] (want 1)
await store.query(MemoryFilter(user_id="u", metadata_filters={"score": 1.5}))      # -> [] (want 1)
await store.query(MemoryFilter(user_id="u", metadata_filters={"tag": "x"}))        # -> [1]  (only strings work)
```

This affects both `query()` and `count()` (they share the builder), on
the public `MemoryFilter(metadata_filters=...)` API.

## 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/adapters/sqlite.py`: bind the **native** Python value
for scalar metadata filters (`str` / `int` / `float`; `bool` is an `int`
subclass, and a JSON `true` extracts to `1`, which `True` binds to). A
non-scalar value (`dict`/`list`) — not a bindable SQLite type — keeps
the JSON-text comparison so the query does not raise. The JSON-path key
validation (injection guard) is unchanged.
- `tests/test_memory/test_query_conditions.py`: added
`test_metadata_scalar_filters_bind_native_values` (int/bool/float/str
bind natively, not as `"5"`/`"true"`) and
`test_metadata_non_scalar_filter_keeps_json_text` (a list value keeps
`json.dumps`).

## Testing

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

### Test Output

```text
tests/test_memory/test_query_conditions.py  ->  5 passed in 1.27s
(the scalar test FAILS on pre-fix code, verified via git stash)
uvx ruff@0.16.2 check headroom/memory/adapters/sqlite.py tests/test_memory/test_query_conditions.py  ->  All checks passed!
uvx mypy@1.20.2 headroom/memory/adapters/sqlite.py  ->  Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.12.11, project venv, pytest 9.1.1,
ruff 0.16.2 and mypy 1.20.2 via uvx.
- Exact command / steps: saved a memory with
`metadata={"priority":5,"archived":True,"score":1.5,"tag":"x"}` and
queried each field. Before the fix, `priority=5`, `archived=True`, and
`score=1.5` each returned 0 rows while `tag="x"` returned 1; after the
fix all four return 1, a non-matching `priority=6` returns 0, and a
dict-valued filter runs without raising.
- Observed result: numeric/boolean/string metadata filters all match
correctly; non-matching values still exclude; non-scalar values do not
crash.
- Not tested: no change to the JSON-path key-injection validation
(covered by existing security tests) — only the bound value is
corrected.

## Runtime Rollout Safety

- Rollout-managed feature(s): none. This is a SQLite memory-store query
builder, not a rollout-channel-gated runtime feature.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: string filters are unchanged;
numeric/boolean filters change from silently returning nothing to
correctly matching. No schema or API change.
- Kill switch / disable path: N/A.
- Unsafe override required: no.
- 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
- [ ] I have made corresponding changes to the documentation (N/A:
internal behavior)
- [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`
2026-09-25 10:29:37 -05:00
Abhay Singh 3aa5012857 perf(memory/budget): precompute word sets once in _merge_similar (#3275)
## Description

`MemoryBudgetManager._merge_similar` collapses near-duplicate memories
with an O(n^2) pairwise Jaccard scan. But `_text_similarity` rebuilt the
word set for **both** sides on every comparison:

```python
for i, m1 in enumerate(memories):
    for j, m2 in enumerate(memories[i + 1:], start=i + 1):
        if self._text_similarity(m1.content, m2.content) > threshold:  # re-splits both sides
            ...

@staticmethod
def _text_similarity(a, b):
    words_a = set(a.lower().split())   # m1.content re-tokenized on every inner j
    words_b = set(b.lower().split())
    ...
```

So each memory's content was `lower().split()` into a set O(n) times per
optimization pass. The pairwise structure is inherent to the greedy
grouping, but the re-tokenization is pure waste.

This tokenizes each memory's word set **once** up front and compares the
cached sets. `_text_similarity` now delegates to a module-level
`_jaccard(set_a, set_b)` helper, and the Jaccard skips materializing the
union set (`|A| + |B| - |A ∩ B|`). Results are unchanged — the merged
output is identical to the original per-pair scan.

Benchmark (`_merge_similar`, 250 candidate memories of ~80 words each,
mean of 10 passes):

```
before : 662.8 ms/pass
after  :  57.4 ms/pass   (~11.5x faster)
```

## Type of Change

- [ ] 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
- [x] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/memory/budget.py`: added a module-level `_jaccard(words_a,
words_b)` helper. `_merge_similar` precomputes `word_sets =
[set(m.content.lower().split()) for m in memories]` once and compares
cached sets via `_jaccard`. `_text_similarity` now delegates to
`_jaccard`, so its behavior (including the empty-input -> 0.0 guard) is
unchanged.
- `tests/test_memory/test_budget.py`: added
`test_merge_groups_transitively_like_pairwise_scan` (three
identical-content entries collapse to the highest-importance
representative; an unrelated entry survives) and
`test_text_similarity_matches_explicit_jaccard` (value equals an
explicit Jaccard; empty side yields 0.0, not a ZeroDivisionError).

## Testing

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

### Test Output

```text
tests/test_memory/test_budget.py  ->  13 passed
uvx ruff@0.16.2 check headroom/memory/budget.py tests/test_memory/test_budget.py  ->  All checks passed!
uvx mypy@1.20.2 headroom/memory/budget.py  ->  Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.12.11, project venv, pytest 9.1.1,
ruff 0.16.2 and mypy 1.20.2 via uvx.
- Exact command / steps: (1) checked `_text_similarity` equals the
original two-set formula over 1000 random string pairs; (2) ran
`_merge_similar` against a reference implementation using the original
per-pair `_text_similarity` on 120 memories with real content overlap
and confirmed byte-identical merge output (same surviving-entry
identities); (3) benchmarked `_merge_similar` on 250 memories at 662.8ms
before vs 57.4ms after; (4) ran the full
`tests/test_memory/test_budget.py` suite.
- Observed result: identical merge results (same entries merged, same
highest-importance representative kept, same entity-ref/access-count
aggregation) with each memory tokenized once instead of O(n) times,
cutting the merge step ~11x on a 250-memory batch.
- Not tested: end-to-end optimize() against a live memory backend (this
exercises `_merge_similar` directly and through `optimize`, which the
existing suite already covers).

## Runtime Rollout Safety

- Rollout-managed feature(s): none — no feature flag or rollout channel
involved.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: no. Merge output is identical; only
redundant re-tokenization is removed.
- Kill switch / disable path: N/A (no config surface added).
- Unsafe override required: no.
- Qualification impact: none.
- Rollback path: revert this commit; `_merge_similar` goes back to
re-tokenizing per comparison.

## 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
- [ ] I have made corresponding changes to the documentation (N/A:
internal behavior, merge output unchanged)
- [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`

## Additional Notes

The `_jaccard` helper is deliberately module-level so the same
tokenize-once pattern is reusable, and `_text_similarity` stays as a
thin public wrapper for callers/tests that pass raw strings.
2026-09-25 00:01:16 -05:00
Abhay SinghandTejas Chopra 8208a4e759 fix(memory): clamp memory age so a future created_at can't crash or invert ranking (#3139)
## Description

Two paired memory-ranking helpers compute an age from `created_at`
without guarding against a **future** timestamp (clock skew, or a
`created_at` written on another machine than the proxy):

`MemoryEntry.score` (`headroom/memory/writers/base.py`):

```python
age_days = (time.time() - self.created_at) / 86400
recency = 1.0 / (1.0 + age_days * 0.1)   # Decay over ~10 days
```

For a `created_at` about **10 days** in the future, `age_days = -10` and
the denominator is `1.0 + (-10)*0.1 = 0.0` — a `ZeroDivisionError`. Past
10 days, the denominator is negative, so `recency` (and the whole score)
goes negative and the memory sorts *below* everything.

`MemoryBudgetManager._apply_decay` (`headroom/memory/budget.py`) has the
paired defect:

```python
age_days = (now - m.created_at) / 86400
decayed_importance = m.importance * math.exp(-rate * age_days)
```

A negative `age_days` makes `exp(-rate × negative) > 1`, so the decayed
importance rises *above* the original (measured at `10.04` from a
starting `0.5` for a 30-day-future entry). That inflated importance is
written back to `m.importance` and flows into `m.score`, so a single
future-dated memory outranks every genuinely-important one and dominates
budget selection.

The codebase's other recency helper,
`proxy/memory_rank_policy.memory_recency_factor`, already clamps (`if
age_days <= 0: return 1.0`). This change brings both writers/base and
budget into line by clamping `age_days` to `>= 0`, so a future memory is
treated as brand new (no decay, no crash, no inflation).

Reproduction:

```python
import time
from headroom.memory.writers.base import MemoryEntry
MemoryEntry(content="x", created_at=time.time() + 10*86400).score   # ZeroDivisionError
MemoryEntry(content="x", importance=0.9, created_at=time.time() + 30*86400).score   # -0.225
```

## 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/writers/base.py` (`MemoryEntry.score`): `age_days =
max(0.0, (time.time() - self.created_at) / 86400)`.
- `headroom/memory/budget.py` (`MemoryBudgetManager._apply_decay`):
`age_days = max(0.0, (now - m.created_at) / 86400)`.
- `tests/test_memory/test_writers.py`: added
`test_score_handles_future_timestamp` (no ZeroDivisionError at +10 days,
non-negative past it, future scores like brand-new).
- `tests/test_memory/test_budget.py`: added
`test_decay_does_not_inflate_future_timestamps` (a future entry's
decayed importance is never inflated above the original / above 1.0).

## Testing

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

### Test Output

```text
tests/test_memory/test_writers.py tests/test_memory/test_budget.py  ->  37 passed
uvx ruff@0.16.2 check <changed files>  ->  All checks passed!
uvx mypy@1.20.2 headroom/memory/writers/base.py headroom/memory/budget.py  ->  Success: no issues found in 2 source files
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.12.11, project venv, pytest 9.1.1,
ruff 0.16.2 and mypy 1.20.2 via uvx.
- Exact command / steps: reverted both clamps and ran the two new tests
-> failed (`MemoryEntry(created_at=now+10d).score` raised
`ZeroDivisionError`; `_apply_decay` returned `importance = 10.04` for a
30-day-future entry); restored the `max(0.0, ...)` clamps and re-ran
both files -> 37 passed.
- Observed result: before, a future `created_at` crashed `score` at +10
days, produced a negative score past that, and inflated budget
importance ~20x; after, a future memory decays like a brand-new one
(recency 1.0, importance unchanged).
- Not tested: a live memory store populated across machines with skewed
clocks; the score/decay functions are exercised directly with future
`created_at` values, which is the exact trigger.

## Runtime Rollout Safety

- Rollout-managed feature(s): none. This is ranking math in the memory
writers/budget, not a rollout-channel-gated runtime feature.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: only for future-dated memories, which
previously crashed or ranked pathologically. Past/now timestamps are
unchanged (`max(0.0, positive)` is the positive value).
- Kill switch / disable path: N/A.
- Unsafe override required: no.
- Qualification impact: memory ranking is now robust to clock skew
instead of crashing or letting a future-dated memory dominate.
- Rollback path: revert this PR; both sites return to the unclamped age.

## 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
- [ ] I have made corresponding changes to the documentation (N/A:
internal ranking math)
- [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`

## Additional Notes

Both sites are fixed together because they are the same defect on the
two code paths that rank memories (`score` for display/export ranking,
`_apply_decay` for budget selection), and `_apply_decay` writes its
result back into `importance`, which then feeds `score`. Clamping
matches the existing `memory_rank_policy` convention rather than
introducing a new rule.

Co-authored-by: Tejas Chopra <chopratejas@gmail.com>
2026-09-09 22:47:16 -05:00
2d1e96b85c fix(memory): sanitize entity_refs to prevent dict-shaped entries crashing search (#2951)
## Description

Closes #2947

`entity_refs` is annotated `list[str]` everywhere, but nothing enforced
that at runtime. `LocalBackend.save_memory`'s `entities` argument is
filled straight from LLM-supplied `memory_save` tool input
(`headroom/memory/system.py:575` into `memory_handler.py:1242`), so a
caller can pass the typed `{"entity": ..., "entity_type": ...}` shape,
which is the format `extracted_entities` expects, into it by mistake.
Those dicts were then persisted verbatim into `entity_refs`, both in the
`memories` table and in the duplicated copy the vector index keeps for
post-filtering.

Every later `search_memories` call does
`set().update(memory.entity_refs)` while collecting entities for graph
expansion. Hashing a dict raises `TypeError: unhashable type: 'dict'`,
and because that happens inside the vector-result loop rather than
per-item, **one** poisoned row aborted the **entire** search. The
proxy's memory handler catches the exception and returns no memories, so
recall went quietly dark rather than failing loudly, and the bad row
kept re-appearing in top-k for related queries, so it stayed dark. The
issue reporter hit this in production: 4 bad rows disabled memory search
for a whole project for a day, with nothing visible to the end user
beyond a swallowed warning in `proxy.log`.

The same root cause has two more crash modes, both confirmed below:
`AttributeError: 'dict' object has no attribute 'lower'` during graph
linking on the save path, and the same error in the `entities` search
filter (`ref.lower()`).

The fix adds one helper and applies it at both ends of the data flow.
Dicts are **unwrapped to their `entity` name** rather than dropped, so
rows that are already corrupted keep contributing to graph expansion
instead of silently losing their entities.

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

- **New helper `normalize_entity_refs()` in
`headroom/memory/models.py`.** Coerces a raw entity-reference list into
the `list[str]` it claims to be: strings pass through, dicts are
unwrapped via their `entity` (or `name`) key, and anything with no
recoverable name is dropped rather than stringified, since a ref like
`"{'entity_type': 'project'}"` would only pollute the graph. Order is
preserved and duplicate names are collapsed.
- **Write path, to stop new corruption at the door.**
`LocalBackend.save_memory` normalizes `entities` before it reaches
`entity_refs` and graph linking. `LocalBackend.search_memories`
normalizes the `entities` *filter* argument too, since it arrives from
the same untrusted tool input (`memory_handler.py:1320`).
- **Read path, to heal rows that were written before this fix.** Applied
at the three deserialization boundaries, so no data migration is needed
and corrupted rows normalize themselves the next time they are loaded:
`Memory.from_dict` (`headroom/memory/models.py`),
`SQLiteMemoryStore._row_to_memory`
(`headroom/memory/adapters/sqlite.py`), and the vector indexes' own
`entity_refs` copies used for post-filtering, `VectorMetadata.from_json`
(`headroom/memory/adapters/sqlite_vector.py`) and
`IndexedMemoryMetadata.from_dict` (`headroom/memory/adapters/hnsw.py`).
- **Defensive normalization on emitted results.** `search_memories` and
`text_search` normalize the refs they return as `related_entities`, so a
backend that produces `Memory` objects by some path not covered above
still cannot take a whole query down, and callers never receive a dict
where they expect an entity name.

**Note on scope versus the patch proposed in the issue.** The issue
proposed normalizing in two places (`save_memory` plus the
`set().update()` line). I widened it slightly because that pair leaves
three related failures live: the `entities` filter still crashes on
`ref.lower()`, `related_entities` still hands dicts back to the caller,
and, most importantly, already-poisoned rows stay poisoned in storage.
Normalizing at the deserialization boundaries fixes all three at once
and is what makes existing corrupted databases recover on their own.

**Behavior change worth flagging.** `entity_refs` is now de-duplicated
(case-sensitively) on both save and load. Refs were already treated as a
set for graph expansion, so this is semantically a no-op, but it is a
visible difference if anything asserts on exact list contents.

## Testing

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

New file `tests/test_memory/test_entity_ref_sanitization.py` adds 10
tests covering the helper, both write paths, all three deserialization
boundaries, and the three crash modes.

### Test Output

```text
$ python -m pytest tests/test_memory/test_entity_ref_sanitization.py -q
..........                                                               [100%]
10 passed, 17 warnings in 0.34s
```

Full memory suite, plus a before/after comparison of the failure set to
prove no regressions:

```text
$ python -m pytest tests/test_memory/ -q
13 failed, 576 passed, 3 skipped, 1072 warnings, 25 errors in 44.74s

# the same run with the source changes stashed (baseline on upstream/main @ 941c25d3):
13 failed, 566 passed, 3 skipped, 1055 warnings, 25 errors in 44.92s

# diff of the failing/erroring test IDs, before versus after:
$ diff baseline.txt after.txt && echo "NO NEW FAILURES vs baseline"
NO NEW FAILURES vs baseline
```

576 passed equals the 566 baseline plus the 10 new tests. The 13
failures and 25 errors are pre-existing on `upstream/main` and unrelated
to this change: they are Windows-only temp-directory cleanup failures in
this local environment.

```text
E   PermissionError: [WinError 32] The process cannot access the file because it is being
    used by another process: 'C:\Users\...\Temp\tmp_qnqtami\test.db'
```

Adjacent suites that construct `Memory` objects:

```text
$ python -m pytest tests/test_memory_system.py tests/test_memory_eval.py tests/test_critical_gaps.py -q
158 passed, 1 skipped, 514 warnings in 20.58s
```

Lint and format on the changed files:

```text
$ ruff check headroom/memory tests/test_memory/test_entity_ref_sanitization.py
All checks passed!

$ ruff format --check headroom/memory tests/test_memory/test_entity_ref_sanitization.py
48 files already formatted
```

`mypy headroom --ignore-missing-imports --python-version 3.13` reports
12 errors, all pre-existing on `upstream/main` and all in files this PR
does not touch (`headroom/ccr/mcp_server.py`,
`headroom/memory/mcp_server.py`, `headroom/release_version.py`; they
come from a local MCP SDK version mismatch). Zero errors in any changed
file.

## Real Behavior Proof

- Environment: Windows 11, Python 3.13.11, pytest 9.1.1, ruff 0.15.17,
local `headroom._core` built. Branched from `upstream/main` at
`941c25d3`, the same branch point the issue reports.
- Exact command / steps: Ran a standalone script (not a mock-only test)
driving `LocalBackend.search_memories` and `LocalBackend.save_memory`
with `entity_refs=[{"entity": "Project X", "entity_type": "project"}]`,
first against unmodified `941c25d3` and then against this branch. Three
scenarios: vector search with graph expansion, search with an `entities`
filter, and a save carrying dict-shaped `entities`.
- Observed result: on unmodified `941c25d3` all three crashed, printing
`SEARCH: TypeError: unhashable type: 'dict'`, `FILTER: TypeError:
unhashable type: 'dict'`, and `SAVE: AttributeError: 'dict' object has
no attribute 'lower'`. With this branch applied all three succeed:
search returns both the poisoned and the clean memory with
`related_entities == ["Project X"]`, the filter matches the recovered
name, and the save persists `entity_refs == ["Project X"]`. Those three
scenarios are now the regression tests in
`test_entity_ref_sanitization.py`.
- Not tested: no live end-to-end run through the MCP `memory_save` tool
against a real LLM, and no test against a real pre-existing SQLite
database containing dict-shaped rows. The healing-on-load path is
covered at the deserialization functions (`Memory.from_dict`,
`VectorMetadata.from_json`, `IndexedMemoryMetadata.from_dict`) rather
than through an actual corrupted `.db` file. The non-local backends
(`mem0`, `direct_mem0`, `qdrant-neo4j`, `cognee`) were not exercised;
this PR only changes the local backend and the shared models and
adapters.

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

## Additional Notes

Documentation was not changed because `normalize_entity_refs()` is an
internal helper and no public API or user-facing behavior changes;
`entity_refs` still behaves exactly as its existing `list[str]` contract
always documented.

Credit for the diagnosis, the root-cause analysis, and the original
repro goes to @apacheco-RT in #2947, who could not open a PR directly
because GitHub blocks Enterprise Managed User accounts from forking
outside their enterprise.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-08-13 11:46:44 -05:00
Chester c471800e8e fix(memory): keep vector metadata in sync (#2295)
## Description

Fixes #2296.

Metadata-only memory updates can leave the primary store, vector-index
metadata, and cache inconsistent. TrafficLearner also performs an atomic
SQLite evidence increment that bypasses normal secondary-index refresh.

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

- Refresh vector metadata for HierarchicalMemory metadata-only,
importance, and entity-reference updates.
- Add a LocalBackend path that reloads a memory from the primary store
and refreshes vector metadata plus cache state.
- Preserve the atomic TrafficLearner SQL evidence increment, then
refresh secondary state only when a row was updated.
- Keep refresh failures fail-open and distinguish them from
primary-store increment failures in logs.
- Add backend-neutral contract tests instead of inspecting a specific
vector adapter private field.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`) — verified locally: mypy
1.20.2, no issues in 504 source files
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
141 passed, 1 skipped
ruff check: passed
ruff format --check: passed
```

The first CI run exposed one backend-specific test assertion against
HNSW private state while CI used SQLiteVectorIndex. Commit a1aff399
removes that assertion and keeps the backend-neutral mock contract test.

## Real Behavior Proof

- Environment: macOS, Python 3.13, current Headroom main.
- Exact command / steps: update a Memory with metadata only through
HierarchicalMemory, assert the vector index receives the updated Memory,
then perform a TrafficLearner evidence bump and assert LocalBackend
refresh is called only for an existing row.
- Observed result: metadata-only update refreshes vector metadata
without re-embedding content; evidence bump remains atomic and refreshes
vector/cache state; an unknown memory ID triggers no refresh.
- Not tested: remote memory backends, full repository suite, or live
multi-process writers against one SQLite database.

## Review Readiness

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

## Checklist

- [x] My code follows the project style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented code where the behavior is not self-explanatory
- [x] I have made corresponding documentation changes (N/A — internal
bug fix, no user-facing docs/changelog impact)
- [x] My changes generate no new warnings
- [x] I have added tests that prove the fix is effective
- [x] New and existing focused unit tests pass locally
- [x] I have updated CHANGELOG.md if applicable (N/A — internal bug fix,
no user-facing docs/changelog impact)

## Screenshots (if applicable)

Not applicable.

## Additional Notes

Draft for storage-owner feedback on the refresh API and write overhead.
The refresh reuses the existing embedding and does not invoke the
embedder.
2026-08-11 23:46:13 -05:00
Abhinav Kumar SinghandTejas Chopra 65961827cf fix(memory): close DirectMem0 resources
## Description

`DirectMem0Adapter.close()` now deterministically drains or cancels
background writes and releases every initialized client/driver.

Fixes #2897

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

- Initialize the OpenAI client field to `None` so cleanup is safe before
or after initialization.
- Drain background tasks within a configurable 60-second default, cancel
tasks that exceed the timeout, await cancellation, and retain
completed/cancelled task status.
- Close Mem0, OpenAI, Qdrant, Neo4j, embedder, and graph resources
independently, including async close methods, while continuing cleanup
if one resource fails.
- Clear task and client references and keep `close()` idempotent.
- Add regression tests for task draining, timeout cancellation, all
resource cleanup, and repeated close calls.

## 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
python -m pytest -q tests/test_memory/test_direct_mem0.py tests/test_memory/test_qdrant_env.py
52 passed

ruff check .
All checks passed!

ruff format --check .
1383 files already formatted

python -m mypy headroom
Success: no issues found in 515 source files

python -m pytest -q
Collection blocked in this Windows environment by 174 errors, primarily missing compiled headroom._core; 18 tests skipped.
```

## Real Behavior Proof

- Environment: Windows, Python 3.12, local DirectMem0Adapter instance
using real `httpx.Client` resources.
- Exact command / steps: Assigned real `httpx.Client()` instances to the
adapter's OpenAI and Qdrant resource slots, registered an asynchronous
background task, awaited `adapter.close(timeout=1.0)`, then checked both
clients' `is_closed` state and the task status.
- Observed result: `real httpx clients closed and background task
drained`; both clients reported closed, no pending task IDs remained,
and the task status was `completed`.
- Who maintains it: Headroom Labs maintains this active upstream
repository and memory backend.
- Install surface: No dependencies or install behavior changed. The fix
uses the standard-library asyncio/inspect modules and existing resource
close methods; no native code or runtime network access is introduced.
- Not tested: The complete test suite could not run past collection
because this Windows environment lacks the compiled `headroom._core`
extension.

## 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
- [ ] New and existing unit tests pass locally with my changes (full
suite blocked by missing native extension; targeted tests pass)
- [x] I did not edit `CHANGELOG.md` - it is generated by release-please
from my Conventional Commit PR title.

## Screenshots (if applicable)

Not applicable.

## Additional Notes

The default close timeout is 60 seconds and can be overridden by callers
that need a shorter shutdown budget.

---------

Co-authored-by: Tejas Chopra <tejas@Tejass-MacBook-Pro.local>
2026-08-11 14:25:32 -07:00
Abhinav Kumar Singh 4bd8ecd1e3 fix(memory): close MCP backend on shutdown
## Description

Closes the initialized LocalBackend and cancels in-flight initialization
whenever the memory MCP stdio transport exits.

Fixes #2898

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

- Added an explicit server cleanup callback that cancels and awaits
pending backend initialization.
- Closes an initialized backend exactly once and clears the backend/task
references.
- Runs cleanup in `_run()` through a `finally` block after the stdio
transport exits, including transport errors.
- Added regression coverage for initialized cleanup, pending
initialization cancellation, idempotence, and `_run()` shutdown
behavior.

## 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
python -m pytest -q tests/test_memory/test_mcp_server.py
15 passed, 20 warnings

ruff check .
All checks passed!

ruff format --check .
1382 files already formatted

python -m mypy headroom
Success: no issues found in 515 source files

python -m pytest -q
Collected 8881 items / 174 errors / 18 skipped.
Interrupted during collection because this Windows environment lacks the compiled headroom._core extension.
```

## Real Behavior Proof

- Environment: Windows, Python 3.12, async MCP server lifecycle test
with the real `create_memory_server()` closure and an embedded server
transport stub.
- Exact command / steps: Ran `python -m pytest -q
tests/test_memory/test_mcp_server.py`; the regression tests initialized
a backend through the server's registered tool lifecycle, returned the
stdio transport, and invoked the cleanup callback from `_run()`'s
`finally` path.
- Observed result: 15 tests passed. Initialized backends were closed
once, pending initialization was cancelled and awaited, and transport
exit invoked cleanup even when the server run returned.
- Who maintains it: Headroom Labs maintains this active upstream
repository and memory MCP server.
- Install surface: No dependencies or install behavior changed. The fix
uses existing asyncio lifecycle handling and `LocalBackend.close()`; no
native code or runtime network access is introduced.
- Not tested: The complete repository suite could not run past
collection because this Windows environment lacks the compiled
`headroom._core` extension.

## 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
- [ ] New and existing unit tests pass locally with my changes (full
suite blocked by missing native extension; targeted tests pass)
- [x] I did not edit `CHANGELOG.md` - it is generated by release-please
from my Conventional Commit PR title.

## Screenshots (if applicable)

Not applicable.

## Additional Notes

Cleanup is attached to each created memory MCP server and is idempotent,
so embedded callers can invoke the same lifecycle callback safely if
needed.
2026-08-11 09:55:20 -07:00
Abhay Singh 1f5fefffd3 fix(memory): bound the TrafficLearner pending-pattern accumulator (memory leak) (#2579)
## Description

`TrafficLearner` (the memory/learning subsystem that accumulates
patterns from proxy traffic) has an unbounded in-memory accumulator.

`_pattern_counts` maps `content_hash -> (pattern, count)`. A pattern is
added on first sighting, its count is bumped on each re-sighting, and it
is **removed only when it reaches `min_evidence`** (default 5), at which
point it is promoted and its hash moves to `_saved_hashes`:

```python
if h in self._pattern_counts:
    existing, count = self._pattern_counts[h]
    count += 1
    self._pattern_counts[h] = (existing, count)
else:
    self._pattern_counts[h] = (pattern, 1)
    return  # first sighting — wait for more evidence
...
if count >= self._min_evidence:
    del self._pattern_counts[h]          # only removal path
    self._saved_hashes.add(h)
    if len(self._saved_hashes) > self._dedup_window:  # sibling IS trimmed
        self._saved_hashes.pop()
```

A pattern seen **once but never corroborated** — the common case for
one-off traffic (a unique error string, an ad-hoc shell command, a
distinct file path) — never reaches `min_evidence`, so it is **never
removed**. Over a long-lived proxy processing varied traffic,
`_pattern_counts` grows without bound and RSS climbs. The sibling
`_saved_hashes` is explicitly trimmed to `dedup_window` ("prevent
unbounded growth"); `_pattern_counts` was missed.

Reproduced directly: feeding 500 distinct one-off patterns leaves 500
entries in `_pattern_counts` (one per pattern, forever).

## Fix

Make `_pattern_counts` an LRU-ordered `OrderedDict` capped at a new
`max_pending_patterns` (default 2048):

- On each corroboration, `move_to_end(h)` so an actively-accumulating
pattern stays "fresh" and is never evicted before it can be promoted.
- On a first sighting when the accumulator is full, evict the
least-recently-corroborated pending entry (`popitem(last=False)`).

Evicting a stale one-off is safe: if it recurs it simply restarts
accumulation (delayed promotion at worst) — the same tradeoff
`_saved_hashes` already makes. Promotion at `min_evidence` is unchanged,
and the cap (2048) is generous enough that any pattern receiving repeat
sightings within a normal window reaches `min_evidence=5` long before
eviction.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring

## Changes Made

- `headroom/memory/traffic_learner.py`: `_pattern_counts` becomes a
capped LRU `OrderedDict`; add `max_pending_patterns` (default 2048);
`move_to_end` on corroboration and evict-oldest on overflow.
- `tests/test_memory/test_traffic_learner.py`: a regression that 500
one-off patterns keep the accumulator at its cap, and one that a
corroborated pattern still promotes into `_saved_hashes` (both sync via
`asyncio.run` so they run without the pytest-asyncio plugin).

## Testing

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

### Test Output

```text
$ python -m pytest tests/test_memory/test_traffic_learner.py -q
35 failed, 109 passed

# the 35 failures are pre-existing @pytest.mark.asyncio tests that need
# pytest-asyncio (not configured in this environment); they fail identically
# on clean main (35 failed, 107 passed) and pass in CI. My two new tests are
# synchronous and pass; they add +2 passing with no new failures.

# with the fix reverted, test_pending_accumulator_is_bounded fails
# (the accumulator holds all 500 one-off patterns)

$ uvx ruff@0.15.17 check headroom/memory/traffic_learner.py tests/test_memory/test_traffic_learner.py
All checks passed!
$ uvx mypy@1.20.2 --ignore-missing-imports headroom/memory/traffic_learner.py
Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.12, project venv (`uv sync --extra
proxy`), `uvx ruff@0.15.17` / `uvx mypy@1.20.2`, pytest in the venv.
- Exact command / steps: built a `TrafficLearner(backend=None,
min_evidence=5, max_pending_patterns=8)` and drove `_accumulate` with
500 distinct one-off `ExtractedPattern`s; separately corroborated one
pattern to `min_evidence`; then reverted the source and re-ran.
- Observed result: with the fix `len(_pattern_counts)` stays at the cap
(8) after 500 one-offs, the corroborated pattern is removed from pending
and present in `_saved_hashes`, and an actively-bumped pattern survives
LRU eviction; with the fix reverted the accumulator holds all 500
one-off entries (the unbounded leak). Ran against the actual module.
- Not tested: a live multi-day proxy run measuring RSS (the leak is
inferred from the removed unbounded-growth path; the accumulator bound
is verified directly).

## 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
- [ ] 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
- [ ] I have updated the CHANGELOG.md if applicable
2026-08-06 19:21:59 -07:00
gglucass a70e5ff78d fix(learn): run project discovery off the event loop (#2731)
## Description

`TrafficLearner.flush_to_file` is a coroutine, but it called
`plugin.discover_projects()` inline. That function walks the filesystem
to decode escaped project directory names — in
`learn/plugins/claude.py`, `_greedy_path_decode` recurses through
`iterdir()` at every level and tries each tokenization of each child,
backtracking on a miss — so on a large home tree it runs for minutes.

Doing that on the event loop freezes uvicorn for the whole window. The
port keeps accepting TCP, but `/readyz` never answers, so a supervisor
health-checking the proxy kills a process that is merely busy.

Field thread dumps show exactly that:

```
Current thread (most recent call first):
  File "python3.12/pathlib.py", line 1056 in iterdir
  File "headroom/learn/plugins/claude.py", line 454 in _greedy_path_decode
  File "headroom/learn/plugins/claude.py", line 478 in _greedy_path_decode
  File "headroom/learn/plugins/claude.py", line 478 in _greedy_path_decode
  File "headroom/learn/plugins/claude.py", line 426 in _decode_project_path
  File "headroom/learn/plugins/claude.py", line 71 in discover_projects
  File "headroom/memory/traffic_learner.py", line 591 in flush_to_file
  File "headroom/memory/traffic_learner.py", line 535 in _flush_worker
  File "python3.12/asyncio/events.py", line 88 in _run
  File "python3.12/asyncio/base_events.py", line 1999 in _run_once
  File "python3.12/asyncio/base_events.py", line 645 in run_forever
  File "uvicorn/server.py", line 75 in run
  File "headroom/proxy/server.py", line 4992 in run_server
```

Accompanying signals from the same incidents: port accepts TCP,
`/readyz` times out, process CPU 2-13s across the window (I/O bound, not
spinning), proxy log silent 66-336s.

## Type of Change

- [x] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which 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/traffic_learner.py`: `flush_to_file` now awaits
`asyncio.to_thread(plugin.discover_projects)` instead of calling it
inline. `asyncio` was already imported. The result is cached per learner
(`_project_roots_cache`), so the steady-state flush path pays nothing
for the thread hop.
- `tests/test_memory/test_traffic_learner.py`: added
`test_discover_projects_does_not_block_the_event_loop`.

## Testing

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

### Test Output

```text
$ uv run --frozen --extra dev pytest tests/test_memory/test_traffic_learner.py -q
..................................................                       [100%]
============================= 152 passed in 2.93s ==============================

$ uvx ruff check headroom/memory/traffic_learner.py tests/test_memory/test_traffic_learner.py
All checks passed!

$ uvx ruff format --check headroom/memory/traffic_learner.py tests/test_memory/test_traffic_learner.py
2 files already formatted

$ uv run --frozen --extra dev mypy headroom/memory/traffic_learner.py
Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: macOS 15.6 arm64, Python 3.10.18, pytest 9.0.3, branch
off `main` @ `01df2452`.
- Exact command / steps: reverted only the one-line source change in the
working tree (`await asyncio.to_thread(plugin.discover_projects)` back
to `plugin.discover_projects()`), left the new test in place, ran `uv
run --frozen --extra dev pytest
tests/test_memory/test_traffic_learner.py -k does_not_block -q`, then
restored the line and re-ran the full file.
- Observed result: without the change the test fails — `flush_to_file`
runs to completion synchronously the moment the task is created, so the
loop never regains control while `discover_projects` is parked on a
`threading.Event`. With the change the loop stays responsive and the
flush completes once discovery returns. Full file: 152 passed.
- Not tested: no live proxy run against a multi-minute real home tree;
the blocking behaviour is reproduced deterministically in the test
instead. The thread dump above is captured field evidence, not a run in
this environment.

Failing output with the fix reverted:

```text
$ uv run --frozen --extra dev pytest tests/test_memory/test_traffic_learner.py -k does_not_block -q
tests/test_memory/test_traffic_learner.py:1254: in test_discover_projects_does_not_block_the_event_loop
    assert not flush.done()
E   AssertionError: assert not True
E    +  where True = <built-in method done of _asyncio.Task object at 0x10882dff0>()
E    +    where <built-in method done of _asyncio.Task object at 0x10882dff0> = <Task finished name='Task-1' coro=<TrafficLearner.flush_to_file() done ...>>.done
========================= 1 failed, 151 deselected in 5.51s =========================
```

## 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
- [ ] 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
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md`

## Additional Notes

- Documentation: N/A — no user-facing behaviour or interface change.
- Bounding `_greedy_path_decode`'s backtracking is the real cost fix and
belongs in its own change. This one only stops a slow walk from taking
the server's liveness with it.
2026-08-03 06:00:52 -07:00
Chester 3eb0122068 fix(learn): filter ambient user-role scaffolding (#2275)
## Description

Fixes #2274.

Headroom Learn currently trusts `role=user` as sufficient preference
provenance. Agent harnesses can transport ambient UI and orchestration
context in user-role messages, and OpenAI Responses normalization also
promotes missing roles to `user`. Correction-like text in those inputs
can therefore become durable user preferences.

This change keeps preference learning fail-closed for known non-user
sources while preserving genuine user corrections.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Refactoring only

## Changes Made

- Preserve missing OpenAI Responses roles as `unknown` instead of
promoting them to `user`.
- Canonicalize user-role text before preference extraction.
- Remove proxy-appended `## Relevant Memories` suffixes from preference
evidence.
- Reject strict ambient-only harness prefixes such as heartbeat,
environment, workspace-instruction, delegation, and app-context
envelopes.
- Apply the same guard in `on_messages` and `_extract_preferences` for
defense in depth.
- Add regression coverage for system/developer/unknown roles,
ambient-only user messages, memory-only messages, and mixed
genuine-user-plus-memory input.

## 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
149 passed, 1 warning
ruff check: passed
ruff format --check: passed
git diff --check: passed
```

Focused test files:

```text
tests/test_memory/test_traffic_learner.py
tests/test_openai_responses_traffic_learner.py
```

## Real Behavior Proof

- Environment: macOS; Python 3.13; current Headroom main; direct
invocation of the real `TrafficLearner` class, with no proxy or database
mocks
- Exact command / steps: create `TrafficLearner(backend=None,
min_evidence=1)`; feed system, developer, heartbeat user-role, and
memory-only user-role messages; read `patterns_extracted`; feed a
genuine user correction followed by a `## Relevant Memories` suffix;
read `patterns_extracted` again
- Observed result: `ambient_patterns=0`, `after_user_patterns=1` — the
ambient batch produced no preference evidence; the genuine correction
produced one pattern, while the appended memory content did not become
evidence
- Not tested: live provider traffic against a remote OpenAI endpoint;
every possible third-party harness envelope; migration or cleanup of
already-persisted noisy memories

## Review Readiness

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

## Checklist

- [x] No new dependency
- [x] Fail-open proxy behavior is unchanged
- [x] Regression tests added
- [x] Public examples contain no real user data
- [x] CHANGELOG update, if requested (not requested — N/A)

## Additional Notes

This extends the source filtering introduced by #466 rather than
replacing it. The prefix checks are deliberately strict and anchored at
the start of a canonicalized message. The intended failure mode is a
missed preference, not durable storage of non-user instructions.

Note: the strict prefix set was discussed and confirmed in
JerrettDavis's review approvals.
2026-08-02 19:40:14 -07:00
Abhay SinghandJerrettDavis 6cdfd3f64d fix(proxy/openai): feed chat/completions traffic into the traffic learner (#2333)
## Description

Addresses the chat/completions portion of #2060.

The live traffic learner is wired into the Anthropic `/v1/messages`
handler and, since then, the OpenAI Responses HTTP handler
(`_observe_openai_responses_traffic`, called from
`handle_openai_responses`). But `handle_openai_chat` has **no**
ingestion call site:

```text
headroom/proxy/handlers/openai.py
  handle_openai_responses -> _observe_openai_responses_traffic   (wired)
  handle_openai_chat       -> (no traffic_learner call)           (gap)
```

So OpenAI-compatible clients that route through `/v1/chat/completions` —
GitHub Copilot CLI, opencode, OpenAI SDKs — run through an apparently
healthy proxy with Learn enabled while producing no learned patterns:
the learner starts, but it never receives their tool results or user
messages.

## Fix

Observe the original client payload (before memory/compression mutates
it) at the top of `handle_openai_chat`, mirroring the Responses and
Anthropic ingestion paths:

```python
await self._observe_openai_chat_traffic(original_client_messages, request_id=request_id)
```

`_observe_openai_chat_traffic` is the chat counterpart of
`_observe_openai_responses_traffic`: same lazy backend wiring, same
`on_tool_result` / `on_messages` lifecycle, same fail-soft `try/except`.

The one format-specific piece is tool-result extraction.
chat/completions encodes tool calls differently from Anthropic — the
call is on an assistant message's `tool_calls` array (`id` -> function
`name` + `arguments`) and each result is a separate `role: "tool"`
message keyed by `tool_call_id`, so the existing
`extract_tool_results_from_messages` (which scans for Anthropic
`tool_use`/`tool_result` blocks) finds nothing. A new
`TrafficLearner.extract_tool_results_from_openai_messages`:

- builds the `tool_call_id -> function` map from assistant `tool_calls`;
- for each `role: "tool"` message, resolves the tool name and joins
string-or-list content;
- parses the OpenAI `arguments` JSON string into a dict, so the
downstream environment/recovery extractors (which call
`input.get("command")`, `input.get("file_path")`, ...) see the same
shape as an Anthropic `tool_use.input` instead of a raw string;
- sniffs `is_error` from the output (chat tool messages carry no error
flag).

It returns the same `{tool_name, input, output, is_error}` shape as the
Anthropic extractor, so `on_tool_result` stays format-agnostic.
User-message preference extraction (`on_messages`) already reads plain
`role`/`content`, so it consumes chat messages unchanged.

Scope: this wires the **chat/completions** path. Codex WebSocket
ingestion (`handle_openai_responses_ws`) additionally needs
per-`response.create` evaluation plus transcript-replay baselining on
reconnect, so it is intentionally left as a follow-up rather than
half-implemented here.

## 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/traffic_learner.py`: add
`extract_tool_results_from_openai_messages` (OpenAI chat tool-result
extraction with `arguments` JSON parsed to a dict).
- `headroom/proxy/handlers/openai.py`: add
`_observe_openai_chat_traffic` and call it from `handle_openai_chat` on
the original client payload.
- `tests/test_memory/test_traffic_learner.py`: cover the OpenAI
extractor (name resolution, arguments parsing, list content, error
sniff, malformed/orphan handling, empty case).
- `CHANGELOG.md`: Bug Fixes entry.

## Testing

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

### Test Output

```text
$ uvx ruff@0.15.17 check headroom/memory/traffic_learner.py headroom/proxy/handlers/openai.py tests/test_memory/test_traffic_learner.py
All checks passed!
$ uvx ruff@0.15.17 format --check <same files>
3 files already formatted
$ uvx mypy@1.20.2 --ignore-missing-imports headroom/memory/traffic_learner.py
# clean for this file (the one reported error is a pre-existing
# headroom/_subprocess.py:18 no-any-return, unrelated to this change and
# present on main with these edits stashed)
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.12, `uvx ruff@0.15.17` / `uvx
mypy@1.20.2`. A full `pytest` OOMs this box (ML-stack import), so I
reproduced the extractor with a dependency-free script and left the full
pytest to CI.
- Exact command / steps: replicated
`extract_tool_results_from_openai_messages` and ran it over a typical
chat round-trip (assistant `tool_calls` for `bash` + `read_file`, then
two `role: "tool"` results, one erroring and one with list content),
plus malformed-`arguments`, orphan-`tool_call_id`, and no-tool cases.
- Observed result: tool names resolved from the call-id map; `arguments`
parsed to a dict so `input.get("command")` works; list content joined;
`is_error` sniffed from output; malformed arguments degrade to `{}` and
an orphan id yields `unknown` without raising. The added unit tests
assert the same through a real `TrafficLearner`.
- Not tested: a live Copilot CLI session end to end; the added tests
drive `TrafficLearner.extract_tool_results_from_openai_messages`
directly, matching the existing
`test_extract_tool_results_from_messages` pattern.

## 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
- [ ] 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
- [ ] New and existing unit tests pass locally with my changes
- [x] I have updated the CHANGELOG.md if applicable

## Additional Notes

The "unit tests pass locally" box is unchecked because a local pytest
run imports the ML stack and OOMs this box; the added tests reuse the
existing `TrafficLearner(backend=None, ...)` harness in
`test_traffic_learner.py` (no real backend) and run under the normal CI
pytest job, and the extractor behavior is corroborated by the standalone
proof above. This PR is deliberately scoped to `/v1/chat/completions`;
I'm happy to follow up with the Codex WebSocket ingestion path (which
needs the transcript-replay baselining discussed in the issue) as a
separate change if useful.

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-07-18 10:09:01 -07:00
Gautam SharmaandTejas Chopra 0924755591 fix(memory): serialize MCP backend initialization (#2309)
## Description

The Memory MCP server previously assigned its backend before
asynchronous embedder and vector-index warm-up completed. A tool call
arriving
during the handshake could therefore receive a partially initialized
backend.

Backend initialization is now atomic and shared between concurrent
callers. The backend is published only after warm-up succeeds. Failed
candidates are closed and discarded so later calls can retry with a
fresh backend.

  ## Type of Change

  - [x] Bug fix
  - [ ] New feature
  - [ ] Breaking change
  - [ ] Documentation-only change
  - [ ] Refactoring

  ## Changes Made

- Keep the initializing backend local until warm-up completes
successfully.
- Share one initialization task between handshake and concurrent tool
calls.
  - Await the shared task before exposing the backend to tool handlers.
- Shield shared initialization from cancellation by an individual tool
caller.
  - Close failed or cancelled backend candidates.
  - Clear failed initialization state so subsequent calls can retry.
  - Retrieve and log background initialization failures.
- Add regression tests for handshake races, failure recovery, and
concurrent initialization.
  - Add an Unreleased changelog entry.

  ## Testing

  - [x] Added regression tests
  - [x] Focused test suite passes
  - [x] Ruff checks pass
  - [x] Mypy passes
  - [x] Changed files pass formatting checks
  - [ ] Entire repository test suite passes without baseline failures

  Commands and results:

- `uv run --extra dev --frozen pytest
tests/test_memory/test_mcp_server.py -q`
    - `12 passed`
  - `uv run --extra dev --frozen ruff check .`
    - Passed
- `uv run --extra dev --frozen ruff format --check
headroom/memory/mcp_server.py tests/test_memory/test_mcp_server.py`
    - Passed
  - `uv run --extra dev --frozen mypy headroom --ignore-missing-imports`
    - Success across 504 source files
  - `uv run --extra dev --frozen pytest -q`
    - `9363 passed, 565 skipped, 4 failed`
- The four failures are existing, unrelated failures outside the changed
code:
      - `test_l2_appends_transform_label`
      - `test_recovery_records_sockets_and_secures_both_backups`
      - `test_dashboard_uses_cached_stats_and_lazy_history_feed_polling`
      - `test_smart_crusher_log_fallback_runs_for_valid_json`

Repository-wide `ruff format --check .` also identifies pre-existing
formatting drift in the untouched
`headroom/proxy/handlers/anthropic.py`.

  ## Real Behavior Proof

  The regression tests exercise the affected lifecycle directly:

  1. Start backend initialization through the MCP handshake.
  2. Suspend warm-up before it completes.
  3. Issue a memory tool call and verify its handler is not invoked.
4. Release warm-up and verify the tool receives the initialized backend.
5. Force background initialization to fail and verify the candidate is
closed.
6. Issue another tool call and verify initialization retries with a
fresh backend.
7. Start two tool calls concurrently and verify only one backend is
constructed.

  Observed behavior:

  - Tool calls remain pending while handshake warm-up is incomplete.
  - A partially initialized backend never reaches a tool handler.
  - Failed candidates are closed and discarded.
  - A later tool call successfully retries initialization.
  - Concurrent calls share one initialization task and backend.

  Environment: macOS arm64, CPython 3.12.13.
  
Not tested: a live stdio MCP client using the real ONNX model and
database. The affected initialization lifecycle is covered with
  deterministic asynchronous regression tests.

  ## Review Readiness

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

  ## Checklist

- [x] The implementation follows the repository’s existing style and
error-handling conventions.
- [x] Tests cover the reported race, concurrent initialization, and
failure recovery.
- [x] Failed initialization does not leave a partially published
backend.
  - [x] Failed backend candidates are closed before retry.
  - [x] No unrelated files or formatting changes are included.
  - [x] No temporary logging, debug code, or commented-out code remains.
  - [x] Public behavior changes are documented in the changelog.
- [x] The branch has been rebased from the intended base and is ready
for review.

  ## Additional Notes

The four full-suite failures listed above occur outside the changed
Memory MCP code and are unrelated to this PR. All tests covering the
  modified initialization lifecycle pass.

---------

Co-authored-by: Tejas Chopra <chopratejas@gmail.com>
2026-07-16 14:38:53 -07:00
ChesterandJerrettDavis aa4515cf7a fix(memory): filter inactive graph-expanded results (#2210)
## DescriptionKeep graph-expanded local-memory results consistent with
the current-only contract already applied by vector search.Closes
#2209## 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- Reject graph-expanded memories whose `valid_until` is set.- Reject
graph-expanded memories whose `superseded_by` is set.- Add focused
coverage for active, expired, and superseded related memories.##
Testing- [x] Unit tests pass (`pytest`)- [x] Linting passes (`ruff check
.`)- [ ] Type checking passes (`mypy headroom`)- [x] New tests added for
new functionality- [ ] Manual testing performed### Test Output```text$
uv run --with pytest --with pytest-asyncio --with numpy pytest
tests/test_memory/test_local_backend_search.py -q3 passed$ uv run --with
ruff ruff check headroom/memory/backends/local.py
tests/test_memory/test_local_backend_search.pyAll checks passed!$ uv run
--with ruff ruff format --check headroom/memory/backends/local.py
tests/test_memory/test_local_backend_search.py2 files already
formatted```## Real Behavior Proof- Environment: Python 3.13, synthetic
in-memory test doubles- Exact command / steps: run the focused test file
above- Observed result: active graph-linked memory is returned; records
with `valid_until` or `superseded_by` are excluded- Not tested: full
repository suite, external vector/graph implementations## 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- [ ] I have
commented my code, particularly in hard-to-understand areas- [ ] I have
made corresponding changes to the documentation- [ ] 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- [ ] I have updated the CHANGELOG.md if applicable##
Screenshots (if applicable)N/A## Additional NotesDocumentation and
changelog changes are not needed for this narrow internal behavior fix.
The existing temporal-history APIs remain unchanged.

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-07-15 19:58:13 +00:00
ChesterandJerrettDavis 6d897e8eaa fix(memory): require explicit updates for supersession (#2188)
## Description

The standalone Memory MCP `memory_save` handler currently treats vector
similarity as update identity. A score of `0.70` can therefore supersede
a valid but distinct memory that merely shares domain vocabulary.

This change makes `memory_save` append-only. Supersession remains
available through explicit update paths that receive an existing memory
ID.

Closes #2187.

## 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 causes existing functionality
to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- Remove vector-similarity-based auto-supersession from the standalone
MCP `memory_save` handler.
- Clarify in the tool description that corrections require an explicit
update path with the existing memory ID.
- Add a regression test proving that a high-scoring but distinct memory
is neither searched for replacement nor updated.
- Preserve the existing save result summary shape for compatibility.

## Testing

- [x] Focused unit tests pass
- [x] Linting passes (`ruff check` on changed files)
- [ ] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual focused test execution performed

### Test Output

```text
uv run --with pytest --with numpy pytest tests/test_memory/test_mcp_server.py -q
9 passed, 21 warnings in 0.70s

uvx ruff check headroom/memory/mcp_server.py tests/test_memory/test_mcp_server.py
All checks passed!

uvx ruff format --check headroom/memory/mcp_server.py tests/test_memory/test_mcp_server.py
2 files already formatted
```

The warnings are pre-existing pytest configuration and
`datetime.utcnow()` deprecation warnings in the test environment.

## Real Behavior Proof

- Environment: Python 3.13 with the MCP module stub and an async
recording backend.
- Exact command / steps: run `tests/test_memory/test_mcp_server.py`; the
new regression supplies a search result with similarity `0.91`, then
saves a distinct fact.
- Observed result: `search_memories` and `update_memory` are not called;
`save_memory` is called once with the new fact and requested importance.
- Not tested: live embedding backends or migration of supersession
chains created by earlier versions.

## Review Readiness

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

## Checklist

- [x] My code follows the project style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented the non-obvious identity boundary
- [ ] Documentation changes are limited to the MCP tool description
- [x] My changes generate no new warnings
- [x] I have added tests that prove the fix is effective
- [ ] New and existing unit tests pass locally; the focused MCP suite
passes and full CI is pending
- [ ] CHANGELOG update is not included because release notes are
generated from conventional commits

## Screenshots (if applicable)

Not applicable.

## Additional Notes

This patch intentionally does not infer replacement identity from
category, entity references, or a higher vector threshold: none of those
alone proves that two statements are versions of the same fact. Exposing
an explicit update tool from the standalone MCP server can be considered
separately without retaining the unsafe automatic behavior.

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-07-15 18:18:41 +00:00
ChesterandJerrettDavis ce52b30c8f feat(memory): add explicit supersession repair (#2217)
## Description

Add an explicit, reviewable way to detach one incorrect supersession
edge while preserving both memories and all neighboring version history.

Closes #2216

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] 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

- Add an atomic SQLite `detach_supersession(old_id, new_id)` primitive
that requires reciprocal direct lineage.
- Restore only the old memory's validity and clear only the selected
edge.
- Re-index both affected memories and refresh cache state through
`HierarchicalMemory`.
- Expose the operation through `LocalBackend`.
- Add `headroom memory repair-supersession OLD_ID NEW_ID`, dry-run by
default with explicit `--apply`.
- Resolve unambiguous partial IDs for preview but pass full IDs to the
mutation.
- Add chain-locality, rejection, index/cache, dry-run, and apply-path
tests.

## Testing

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

### Test Output

```text
$ uv run --with pytest --with pytest-asyncio --with numpy --with fastapi --with httpx pytest \
    tests/test_memory/test_supersession_repair.py \
    tests/test_memory/test_hierarchical.py::TestSQLiteMemoryStore \
    tests/test_cli/test_main_help_version.py -q
22 passed

$ uv run --with ruff ruff check <touched Python files>
All checks passed!

$ uv run --with ruff ruff format --check <touched Python files>
6 files already formatted
```

## Real Behavior Proof

- Environment: Python 3.13, temporary SQLite databases, synthetic two-
and three-version chains
- Exact command / steps: run the focused test set above
- Observed result: detaching `v1 -> v2` restores `v1` as current, leaves
`v2 -> v3` intact, re-indexes both records, refreshes cache, and keeps
CLI preview read-only until `--apply`
- Not tested: live proxy process, external MemoryStore/VectorIndex
plugins, full repository suite

## Review Readiness

- [x] I have performed a self-review
- [ ] 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
- [ ] I have made corresponding changes to the documentation
- [ ] 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
- [ ] I have updated the CHANGELOG.md if applicable

## Screenshots (if applicable)

N/A

## Additional Notes

This is intentionally separate from #2188: that PR prevents new false
edges, while this PR repairs historical data.

The CLI help requires stopping any proxy that is actively using the same
database before `--apply`, because another process can retain an old
in-memory index snapshot. External backend semantics and stronger
cross-store rollback behavior are left visible for maintainer review
before this Draft is marked ready.

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-07-15 18:17:17 +00:00
fa330f3e2b fix(memory): remove a superseded memory from the search indexes (#2143)
## Description

Superseding a memory leaves the old version live in the search indexes,
so outdated content can still come back from search after supersession.

`HierarchicalMemory.supersede` updates the store and indexes the new
memory, but previously never removed the old entry from the vector/text
indexes. The store sets the old row's `valid_until` and `superseded_by`,
but the indexes keep their own cached metadata copy from first indexing.
Default search filters superseded rows from that cached metadata, so the
old entry could still look live and be returned with stale content.

Concretely: `add("User prefers Python")`, then `supersede(id, "User now
prefers JavaScript frameworks")`, then `search("Python")` could return
the superseded "prefers Python" entry alongside the new one. That
defeats supersession and can recall contradictory facts.

## Fix

After `store.supersede`, remove the old id from the vector and text
indexes, mirroring `delete`. The store keeps the old row for
`get_history`; only the search indexes are corrected. The new memory is
indexed as before.

## 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/core.py`: `supersede` removes the old id from the
vector and text indexes after the store supersession, before indexing
the new memory.
- `tests/test_memory/test_core_operations.py`: adds
`test_superseded_memory_does_not_resurface_in_search`.
- `CHANGELOG.md`: adds a bug-fix entry.
- Merged current `main` to pick up the repository-wide memory factory
type annotation fix that was breaking the PR lint job.

## Testing

- [x] Unit tests pass (`pytest` in CI on the pre-merge head; fresh CI is
running on the main-merged head)
- [x] Linting passes (`ruff check` focused locally; previous CI `ruff
check` and `ruff format` passed before hitting unrelated mypy)
- [x] Type checking passes for the prior mypy blocker after merging
current `main`
- [x] New tests added for new functionality
- [ ] Manual testing performed

### Test Output

```text
uvx ruff@0.15.17 check headroom/memory/core.py tests/test_memory/test_core_operations.py headroom/memory/factory.py
All checks passed!

uvx ruff@0.15.17 format --check headroom/memory/core.py tests/test_memory/test_core_operations.py headroom/memory/factory.py
3 files already formatted

git diff --check headroomlabs/main...HEAD
# no output

uv run --extra dev python -m pytest tests/test_memory/test_core_operations.py::TestSupersede::test_superseded_memory_does_not_resurface_in_search -q
# assertion passed; local Windows teardown hit a locked temp SQLite file during fixture cleanup
```

## Real Behavior Proof

- Environment: Windows 11 review worktree, plus GitHub Actions on the
pre-merge head.
- Exact command / steps: ran focused ruff/format/diff checks; ran the
new supersede regression test directly.
- Observed result: focused checks passed; the new test body passed and
confirmed the old memory id does not resurface when searching for old
content while the new memory remains searchable. The local run then
errored during Windows temp SQLite cleanup after the assertion
completed.
- Not tested: full memory suite, because it pulls the ML embedding
stack. CI already passed the broader test matrix on the pre-merge head;
fresh checks are queued after the main merge.

## 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
- [ ] 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
- [ ] New and existing unit tests pass locally with my changes
- [x] I have updated the CHANGELOG.md if applicable

## Additional Notes

Removing the old entry from indexes is intentionally aligned with
`delete`; the store row remains available for `get_history`.

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
Co-authored-by: Tejas Chopra <chopratejas@gmail.com>
2026-07-14 04:24:00 -04:00
b0afee85b3 fix(memory): size HNSW index_batch resize off the id high-water mark (#2139)
## Description

`HNSWVectorIndex.index_batch()` used the live memory map size to decide
whether to resize hnswlib before adding new labels. hnswlib does not
reclaim capacity slots when labels are removed with `mark_deleted`, so
after delete/evict churn the live count can be much lower than the
assigned-id high-water mark. That lets a batch add skip resizing and
then fail in `add_items` with `number of elements exceeds the specified
limit`.

## Fix

- Size the batch resize check from `self._next_hnsw_id`, which has
already been incremented for the new batch labels.
- Match the single-item `index()` path's high-water-mark capacity
behavior.
- Add a regression test that deletes most entries from a small index and
then batch-adds enough new memories to require a resize.
- Merge current `main` to refresh mergeability and stale lint results.

## Testing

```text
uvx ruff@0.15.17 check headroom/memory/adapters/hnsw.py tests/test_memory/test_hnsw_batch_capacity.py headroom/memory/factory.py
All checks passed!

uvx ruff@0.15.17 format --check headroom/memory/adapters/hnsw.py tests/test_memory/test_hnsw_batch_capacity.py headroom/memory/factory.py
3 files already formatted

git diff --check headroomlabs/main...HEAD
# no output

uv run --extra dev python -m pytest tests/test_memory/test_hnsw_batch_capacity.py -q
1 passed, 18 warnings
```

## Review Readiness

- [x] Ready for review
- [x] Regression test added
- [x] CHANGELOG updated

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
Co-authored-by: Tejas Chopra <chopratejas@gmail.com>
2026-07-13 23:43:12 -04:00
9e38905a7d fix(memory): apply turn_id scope filter even without agent_id (#2130)
## Description

`SQLiteMemoryStore._build_query_conditions()` dropped `turn_id` when a
query specified `session_id` and `turn_id` without also specifying
`agent_id`. That made a single-turn scope return every memory in the
session, and `count()` uses the same helper.

## Fix

- Apply `agent_id` and `turn_id` as independent narrowing predicates
inside the `session_id` branch.
- Preserve the existing `agent_id`-only behavior.
- Add direct query-condition regression tests for turn-only, agent+turn,
and agent-only scopes.
- Merge current `main` to refresh mergeability and stale lint results.

## Testing

```text
uvx ruff@0.15.17 check headroom/memory/adapters/sqlite.py tests/test_memory/test_query_conditions.py headroom/memory/factory.py
All checks passed!

uvx ruff@0.15.17 format --check headroom/memory/adapters/sqlite.py tests/test_memory/test_query_conditions.py headroom/memory/factory.py
3 files already formatted

git diff --check headroomlabs/main...HEAD
# no output

uv run --extra dev python -m pytest tests/test_memory/test_query_conditions.py -q
3 passed
```

## Review Readiness

- [x] Ready for review
- [x] Regression tests added
- [x] CHANGELOG updated

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
Co-authored-by: Tejas Chopra <chopratejas@gmail.com>
2026-07-13 23:41:40 -04:00