Skip to content

Commit 7ac79b3

Browse files
authored
Merge pull request #863 from cdeust/fix/706-user-tags-never-hide-recall
2 parents b65030b + 9e9657f commit 7ac79b3

8 files changed

Lines changed: 179 additions & 36 deletions

‎CHANGELOG.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,13 @@ adheres to [Semantic Versioning](https://semver.org/).
4444

4545
### Fixed
4646

47+
- A user's own tags no longer hide a memory from default recall (#706,
48+
ADR-1123). The low-signal filter of `recall` and of trigger injection now
49+
drops only capture markers (`auto-captured`, `tool:<name>`, `_backfill`,
50+
`imported`, `session-summary`, emitted by Cortex writers, and `tool-output`,
51+
listed in #706);
52+
`audit`, `automated`, `wip`, `progress`, `code-review` and `stage-1` to
53+
`stage-11` no longer drop the memory. The wiki admission list is unchanged.
4754
- The benchmark machine-load snapshot records no load average on Windows
4855
instead of raising: `os.getloadavg` does not exist there, and the
4956
`AttributeError` escaped the `except OSError` (#692 class 4, 13 tests).
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
<!-- Generated by Cortex wiki_reindex from wiki/adr/cortex/1123-user-tags-never-hide-a-memory-from-default-recall.md; ADR-1123. Read-only mirror: edit the canonical wiki page. -->
2+
3+
---
4+
created: 2026-11-04T18:00:00Z
5+
kind: adr
6+
number: 1123
7+
status: accepted
8+
tags: [recall, low-signal, tags, issue-706, amends-adr-0431]
9+
title: User tags never hide a memory from default recall
10+
---
11+
# ADR-1123: User tags never hide a memory from default recall
12+
13+
## Status
14+
15+
accepted. Amends ADR-0431 (the low-signal tag filter of `recall_helpers.py`): the filter stays, its tag set is narrowed to capture markers.
16+
17+
## Context
18+
19+
Issue #706: `LOW_SIGNAL_TAGS` (ADR-0431) mixed two kinds of tags. Some are capture markers a Cortex writer puts on memories it records by itself: `auto-captured` and `tool:<name>` (`hooks/post_tool_capture.py`), `_backfill` (`handlers/backfill_memories.py`), `imported` (`core/session_extractor.py`, `handlers/wiki_seed_codebase.py`), `session-summary` (`handlers/record_session_end_memory.py`). The others, `audit`, `automated`, `wip`, `progress`, `code-review` and `stage-1` to `stage-11`, are copied from the wiki admission list `AUDIT_TAGS` (ADR-0296); no Cortex writer emits them (`grep` over `mcp_server/` and `scripts/` on main at 1de07f9). They are words a user may choose for their own memories, and a memory carrying one of them was dropped from default recall (`filter_low_signal`) and from trigger injection (`_injectable`).
20+
21+
The owner's rule in #706: user tags are never used to hide a user's own memories; the filter keys on a capture marker the system writes.
22+
23+
## Decision
24+
25+
1. `LOW_SIGNAL_TAGS` holds capture markers only: the tags listed above that a Cortex writer emits, the `tool:<name>` tags the filter already listed, and `tool-output`, which #706 lists among the capture tags.
26+
2. `audit`, `automated`, `wip`, `progress`, `code-review` and `stage-1` to `stage-11` leave the recall filter. A memory carrying them is returned by default recall and can be injected by a trigger like any other memory.
27+
3. The wiki admission list `AUDIT_TAGS` (ADR-0296) is unchanged: keeping a stage report out of the wiki is a different decision from hiding it from recall.
28+
4. Not decided here, left on #706: whether default recall returns auto-captured memories labelled as such, whether the filter keys on the `source` column instead of tags, and the gap between `auto_recall` injection and `recall`.
29+
30+
## Consequences
31+
32+
Positive: a user's memory tagged `audit`, `wip` or `stage-3` is found by default recall; the filter no longer depends on vocabulary a user may choose.
33+
34+
Negative: memories that agents stored with stage-report tags (`stage-N`, `code-review`, `audit`) are now ranked in default recall with every other memory. If they crowd out curated memories, the fix is a system-written marker on those writes, not a user word in the filter.
35+
36+
Tests: `tests_py/handlers/test_recall_low_signal_filter.py` (each user-vocabulary tag is kept, the set is pinned to the capture markers) and `tests_py/handlers/test_inject_triggered_memories.py` (a trigger memory with a user-vocabulary tag is injected).

‎mcp_server/handlers/recall.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -267,9 +267,9 @@
267267
"include_low_signal": {
268268
"type": "boolean",
269269
"description": (
270-
# source: ADR-0430
270+
# source: ADR-0430 (filter), ADR-1123 (scope)
271271
"When false (default), drops memories tagged as auto-captures "
272-
"(``auto-captured``, ``tool:edit``, ``_backfill``, ``stage-N``, "
272+
"(``auto-captured``, ``tool:edit``, ``_backfill``, ``imported``, "
273273
"``session-summary``, …) so curated content (ADRs, lessons, "
274274
"conventions) surfaces in the first few results. Set true for "
275275
"debugging / replay tooling that needs the raw memory feed."

‎mcp_server/handlers/recall_helpers.py‎

Lines changed: 8 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -156,15 +156,21 @@ def parse_tags(tags: Any) -> list:
156156
return tags if tags else []
157157

158158

159-
# source: ADR-0431
159+
# Capture markers only: tags a Cortex writer puts on the memories it records
160+
# by itself (post_tool_capture, backfill_memories, session_extractor,
161+
# wiki_seed_codebase, record_session_end_memory), plus ``tool-output``, which
162+
# no writer emits but issue #706 lists among the capture tags. Ordinary words
163+
# (audit, wip, stage-N, ...) no longer hide a memory. A user can still choose
164+
# a marker itself (``imported`` is also a wiki provenance alias); keying the
165+
# filter on a system-written field instead of tags is left on #706.
166+
# source: ADR-0431 (the filter), ADR-1123 (its scope), issue #706
160167
LOW_SIGNAL_TAGS: frozenset[str] = frozenset(
161168
{
162169
"auto-captured",
163170
"_backfill",
164171
"imported",
165172
"session-summary",
166173
"tool-output",
167-
"code-review",
168174
"tool:edit",
169175
"tool:bash",
170176
"tool:read",
@@ -175,21 +181,6 @@ def parse_tags(tags: Any) -> list:
175181
"tool:webfetch",
176182
"tool:websearch",
177183
"tool:notebookedit",
178-
"stage-1",
179-
"stage-2",
180-
"stage-3",
181-
"stage-4",
182-
"stage-5",
183-
"stage-6",
184-
"stage-7",
185-
"stage-8",
186-
"stage-9",
187-
"stage-10",
188-
"stage-11",
189-
"audit",
190-
"automated",
191-
"wip",
192-
"progress",
193184
}
194185
)
195186

‎tests_py/handlers/test_inject_triggered_memories.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,12 @@ def test_low_signal_tagged_memories_not_injected(self):
4343
out = inject_triggered_memories([], "ship the deploy", store)
4444
assert out == []
4545

46+
def test_user_vocabulary_tag_does_not_block_injection(self):
47+
"""Issue #706: a user's tag such as ``wip`` never hides the memory."""
48+
store = _store([_trigger()], {1: _mem(tags=["wip", "stage-3"])})
49+
out = inject_triggered_memories([], "ship the deploy", store)
50+
assert len(out) == 1
51+
4652
def test_clean_memory_injected_with_flag(self):
4753
store = _store([_trigger()], {1: _mem()})
4854
out = inject_triggered_memories([], "ship the deploy", store)

‎tests_py/handlers/test_recall_low_signal_filter.py‎

Lines changed: 82 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,20 @@
22
33
Spike 2026-05-13 found that recall results for design-decision queries
44
were dominated by ``# Tool: Edit`` auto-captures from unrelated repos.
5-
The filter drops memories tagged ``auto-captured`` / ``tool:edit`` /
6-
``_backfill`` / ``stage-N`` etc. unless the caller opts in.
5+
The filter drops memories carrying a capture marker a Cortex writer emits
6+
(``auto-captured`` / ``tool:edit`` / ``_backfill`` etc.) unless the caller
7+
opts in. Words a user may choose (``audit``, ``wip``, ``stage-N``) never hide
8+
a memory (issue #706, ADR-1123).
79
"""
810

911
from __future__ import annotations
1012

13+
import pytest
14+
1115
from mcp_server.handlers.recall_helpers import (
1216
LOW_SIGNAL_TAGS,
1317
filter_low_signal,
18+
parse_tags,
1419
)
1520

1621

@@ -41,8 +46,31 @@ def test_backfill_import_is_dropped() -> None:
4146
assert dropped == 1
4247

4348

44-
def test_stage_report_is_dropped() -> None:
45-
results = [_mem("stage 3 research verdict", "stage-3", "research")]
49+
# Tags no Cortex writer emits: before #706 each one hid the memory.
50+
USER_VOCABULARY_TAGS = (
51+
"audit",
52+
"automated",
53+
"wip",
54+
"progress",
55+
"code-review",
56+
"stage-1",
57+
"stage-3",
58+
"stage-11",
59+
)
60+
61+
62+
@pytest.mark.parametrize("tag", USER_VOCABULARY_TAGS)
63+
def test_user_vocabulary_tag_does_not_hide_memory(tag: str) -> None:
64+
"""Issue #706: a user's own memory tagged with an ordinary word is kept."""
65+
results = [_mem(f"my note tagged {tag}", tag, "research")]
66+
kept, dropped = filter_low_signal(results)
67+
assert len(kept) == 1
68+
assert dropped == 0
69+
70+
71+
def test_user_vocabulary_tag_beside_capture_marker_still_dropped() -> None:
72+
"""The capture marker, not the user word, decides."""
73+
results = [_mem("# Tool: Bash\nls", "auto-captured", "tool:bash", "audit")]
4674
kept, dropped = filter_low_signal(results)
4775
assert kept == []
4876
assert dropped == 1
@@ -129,19 +157,32 @@ def test_missing_tags_key_kept() -> None:
129157
# ── Set membership invariants ─────────────────────────────────────────
130158

131159

132-
def test_low_signal_tags_covers_known_polluters() -> None:
133-
"""Pin the canonical set so a refactor can't silently shrink it."""
134-
must_include = {
135-
"auto-captured",
136-
"tool:edit",
137-
"tool:bash",
138-
"_backfill",
139-
"imported",
140-
"session-summary",
141-
"stage-1",
142-
"stage-11",
143-
}
144-
assert must_include.issubset(LOW_SIGNAL_TAGS)
160+
def test_low_signal_tags_are_exactly_the_capture_markers() -> None:
161+
"""Pin the canonical set so a refactor can neither shrink it nor add
162+
a word a user may choose (ADR-1123)."""
163+
assert LOW_SIGNAL_TAGS == frozenset(
164+
{
165+
"auto-captured",
166+
"_backfill",
167+
"imported",
168+
"session-summary",
169+
"tool-output",
170+
"tool:edit",
171+
"tool:bash",
172+
"tool:read",
173+
"tool:write",
174+
"tool:grep",
175+
"tool:glob",
176+
"tool:search",
177+
"tool:webfetch",
178+
"tool:websearch",
179+
"tool:notebookedit",
180+
}
181+
)
182+
183+
184+
def test_low_signal_tags_exclude_user_vocabulary() -> None:
185+
assert not (set(USER_VOCABULARY_TAGS) & LOW_SIGNAL_TAGS)
145186

146187

147188
def test_low_signal_tags_does_not_include_knowledge_signals() -> None:
@@ -157,3 +198,27 @@ def test_low_signal_tags_does_not_include_knowledge_signals() -> None:
157198
"standard",
158199
}
159200
assert not (must_exclude & LOW_SIGNAL_TAGS)
201+
202+
203+
# ── parse_tags: every input shape the filter receives ─────────────────
204+
205+
206+
def test_parse_tags_decodes_a_json_string() -> None:
207+
assert parse_tags('["auto-captured", "tool:edit"]') == [
208+
"auto-captured",
209+
"tool:edit",
210+
]
211+
212+
213+
def test_parse_tags_returns_empty_for_an_undecodable_string() -> None:
214+
assert parse_tags("not json") == []
215+
216+
217+
def test_parse_tags_returns_a_list_unchanged() -> None:
218+
tags = ["wip", "audit"]
219+
assert parse_tags(tags) is tags
220+
221+
222+
@pytest.mark.parametrize("empty", [None, [], ""])
223+
def test_parse_tags_returns_an_empty_list_for_empty_input(empty) -> None:
224+
assert parse_tags(empty) == []
Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
created: 2026-11-04T18:00:00Z
3+
kind: adr
4+
number: 1123
5+
status: accepted
6+
tags: [recall, low-signal, tags, issue-706, amends-adr-0431]
7+
title: User tags never hide a memory from default recall
8+
---
9+
# ADR-1123: User tags never hide a memory from default recall
10+
11+
## Status
12+
13+
accepted. Amends ADR-0431 (the low-signal tag filter of `recall_helpers.py`): the filter stays, its tag set is narrowed to capture markers.
14+
15+
## Context
16+
17+
Issue #706: `LOW_SIGNAL_TAGS` (ADR-0431) mixed two kinds of tags. Some are capture markers a Cortex writer puts on memories it records by itself: `auto-captured` and `tool:<name>` (`hooks/post_tool_capture.py`), `_backfill` (`handlers/backfill_memories.py`), `imported` (`core/session_extractor.py`, `handlers/wiki_seed_codebase.py`), `session-summary` (`handlers/record_session_end_memory.py`). The others, `audit`, `automated`, `wip`, `progress`, `code-review` and `stage-1` to `stage-11`, are copied from the wiki admission list `AUDIT_TAGS` (ADR-0296); no Cortex writer emits them (`grep` over `mcp_server/` and `scripts/` on main at 1de07f9). They are words a user may choose for their own memories, and a memory carrying one of them was dropped from default recall (`filter_low_signal`) and from trigger injection (`_injectable`).
18+
19+
The owner's rule in #706: user tags are never used to hide a user's own memories; the filter keys on a capture marker the system writes.
20+
21+
## Decision
22+
23+
1. `LOW_SIGNAL_TAGS` holds capture markers only: the tags listed above that a Cortex writer emits, the `tool:<name>` tags the filter already listed, and `tool-output`, which #706 lists among the capture tags.
24+
2. `audit`, `automated`, `wip`, `progress`, `code-review` and `stage-1` to `stage-11` leave the recall filter. A memory carrying them is returned by default recall and can be injected by a trigger like any other memory.
25+
3. The wiki admission list `AUDIT_TAGS` (ADR-0296) is unchanged: keeping a stage report out of the wiki is a different decision from hiding it from recall.
26+
4. Not decided here, left on #706: whether default recall returns auto-captured memories labelled as such, whether the filter keys on the `source` column instead of tags, and the gap between `auto_recall` injection and `recall`.
27+
28+
## Consequences
29+
30+
Positive: a user's memory tagged `audit`, `wip` or `stage-3` is found by default recall; the filter no longer depends on vocabulary a user may choose.
31+
32+
Negative: memories that agents stored with stage-report tags (`stage-N`, `code-review`, `audit`) are now ranked in default recall with every other memory. If they crowd out curated memories, the fix is a system-written marker on those writes, not a user word in the filter.
33+
34+
Tests: `tests_py/handlers/test_recall_low_signal_filter.py` (each user-vocabulary tag is kept, the set is pinned to the capture markers) and `tests_py/handlers/test_inject_triggered_memories.py` (a trigger memory with a user-vocabulary tag is injected).

‎wiki/manifest.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3659,6 +3659,10 @@
36593659
"ADR-9852": {
36603660
"mirror": "ADR-9852-restore-the-previous-head-when-a-superseding-memory-is-deleted.md",
36613661
"path": "adr/cortex/9852-restore-the-previous-head-when-a-superseding-memory-is-deleted.md"
3662+
},
3663+
"ADR-1123": {
3664+
"mirror": "ADR-1123-user-tags-never-hide-a-memory-from-default-recall.md",
3665+
"path": "adr/cortex/1123-user-tags-never-hide-a-memory-from-default-recall.md"
36623666
}
36633667
},
36643668
"project": "cortex",

0 commit comments

Comments
 (0)