feat: get_knowledge language filter

[cmeans-claude-dev]

Summary

• get_knowledge gains optional language parameter (ISO 639-1 code)
• Maps to WHERE e.language = %s::regconfig filter in PostgresStore
• Store protocol updated with language parameter
• 1 new test: filter entries by language

Closes #262. Refs #238.

QA

Prerequisites

• pip install -e ".[dev]"
• Deploy to test instance on alternate port (AWARENESS_PORT=8421)

Manual tests (via MCP tools)

1. • Filter by language

   remember(source="qa", tags=["test"], description="Un texte français", language="fr")
   remember(source="qa", tags=["test"], description="An English text", language="en")
   get_knowledge(language="fr")
   

   Expected: only the French entry returned

2. • No filter returns all

   get_knowledge(tags=["test"])
   

   Expected: both entries returned

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cmeans]

[QA] Round 1 on PR #267 — QA Failed

Verdict: one substantive observation on semantic mismatch. Code is otherwise clean, test is good, 827/827 pass, CI green, CHANGELOG accurate.

What is working well

• SQL clause language = %s::regconfig is parameterized and safe ✓
• Store Protocol updated with language parameter ✓
• Test test_get_knowledge_filtered_by_language creates entries with explicit languages and verifies filter returns only the matching one ✓
• Docstring is clear about the purpose: "show me all entries in language X" ✓
• CHANGELOG under ### Added, accurate ✓

Substantive observation — unknown ISO codes silently map to simple, returning unexpected results

The filter path is:

lang_regconfig = iso_to_regconfig(language) if language else None

iso_to_regconfig("xx") returns "simple" (unknown codes fall back to simple per the mapping design). So get_knowledge(language="xx") filters for language = 'simple'::regconfig — which returns all entries with the default language, not zero entries.

From the user's perspective: "show me entries in language xx" → gets entries in simple (the majority of entries). This is a semantic mismatch.

The issue is that iso_to_regconfig() was designed for WRITE paths where "unknown → simple" is the correct fallback (you want the entry stored with a valid regconfig). For READ/FILTER paths, the semantics are different — an unknown code should match nothing, not match "simple."

Suggested fix options:

• (a) Check for the fallback case explicitly:

  raw = iso_to_regconfig(language)
  lang_regconfig = raw if (raw != "simple" or language.strip().lower() == "simple") else None

  This filters for simple only when the user explicitly passes language="simple". Unknown codes become None (no filter applied) — or alternatively, return an empty result set.

• (b) Return an error for unknown codes: _error_response("invalid_parameter", f"Unknown language code: {language!r}", ...). Strict but unambiguous.

• (c) Accept the current behavior and document it: "Unknown ISO codes are treated as 'simple' for filtering purposes." Honest but potentially surprising.

The choice between (a) and (b) depends on whether you want "unknown code = no filter" or "unknown code = error." Either is better than the current "unknown code = filter for simple."

Verification

• 827/827 tests pass (+1 new)
• CI: all green
• ruff/mypy: clean
• CHANGELOG: ### Added, accurate, refs #262 + #238

Applying QA Failed as the final act.

[cmeans]

[QA] Round 1 — QA Failed. Substantive: unknown ISO codes (e.g. language="xx") map to "simple" via iso_to_regconfig(), causing the filter to return all entries with the default language instead of zero entries. Semantic mismatch — user asks for "entries in language xx" and gets "entries in simple". The write-path fallback ("unknown → simple") is correct for writes but wrong for filters. Fix: detect the fallback case and either skip the filter or return an error. Code otherwise clean, 827/827 tests, CI green.

[cmeans-claude-dev]

[Dev] QA round 1 fix: unknown ISO codes now return an error instead of silently matching simple entries. Added language='simple' as explicit filter option. New test for error case.

[cmeans]

[QA] Round 2 — Signoff

Round-1 finding resolved. Dev chose option (b) — unknown ISO codes return an error with a helpful message listing valid formats. The implementation is clean:

• normalized == SIMPLE → filter for simple entries (explicit language="simple" works as a valid filter) ✓
• normalized not in ISO_639_1_TO_REGCONFIG → _error_response with invalid_parameter code ✓
• Valid ISO code → iso_to_regconfig() → regconfig filter ✓

No more semantic mismatch — "language=xx" now gives the user a clear error instead of silently returning all simple-language entries.

838/838 pass (+11 from round 1). ruff clean. 2 PR checkboxes checked off. Zero new observations.

Ready for QA Signoff.

[cmeans]

[QA] Round 2 — Ready for QA Signoff. Unknown ISO codes now return error (option b). Explicit language="simple" filter works. 838/838 pass, 2 checkboxes checked, ruff clean. Applying label as final act.

[cmeans]

LGTM