Commit Graph
3 Commits
Author SHA1 Message Date
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
chopratejas 7cf10675ea Add centralized ML model configuration
- Create headroom/models/config.py as single source of truth for all ML model defaults
- Support environment variable overrides (HEADROOM_SENTENCE_TRANSFORMER, etc.)
- Update all components to use ML_MODEL_DEFAULTS instead of hardcoded values
- Switch LLMLingua default to smaller bert-base model (~350MB vs 1GB)
- Total memory footprint reduced from ~1.6GB to ~980MB

Updated files:
- MLModelRegistry now resolves defaults from config
- EmbeddingScorer, LocalEmbedder, TrainedRouter use config
- All dataclass configs use field(default_factory=...) for consistency
- Tests updated to handle auto-selected vector backends
2026-02-01 23:47:42 -08:00
chopratejas da74341858 Add hierarchical memory system with graph + vector storage
Implement comprehensive memory system supporting:
- Local backend (SQLite + FTS5 + HNSW) for zero-dependency operation
- Mem0 backends (Neo4j + Qdrant) for production graph memory
- DirectMem0Adapter for optimized pre-extracted data (bypasses LLM)
- Memory extraction with facts, entities, and relationships
- Proxy integration with --memory flag for automatic memory injection

Key components:
- headroom/memory/backends/: LocalBackend, Mem0Backend, DirectMem0Adapter
- headroom/memory/system.py: MemorySystem with tool-based interface
- headroom/memory/extraction.py: Entity and relationship extraction
- headroom/proxy/memory_handler.py: Proxy integration layer
- headroom/prediction/feature_extractor.py: Content analysis features

Testing:
- 217 new memory system tests covering all backends
- LoCoMo evaluation framework for memory quality assessment
- Integration tests for proxy memory functionality

Also removes deprecated example files in favor of focused test coverage.
2026-01-26 21:58:47 -08:00