feat: /sessions recommend subcommand for cross-session learning #9

New Issue

2026-04-24T03:04:58+02:00

root commented

2026-04-24 03:04:58 +02:00

Problem Statement

Phase 3 F5.3 of the session-search spec mandates a "past-solution discovery" surface: given a user query, the agent should recommend past sessions whose outcomes solved a similar problem, so successful solutions become reusable lessons learned. The SessionsSubcommand enum has Search, Concepts, Related, Timeline, Enrich, Files, ByFile, Index, etc., but no Recommend variant. F5.3 bullet two — cross-session recommendation by concept overlap and recency — remains unchecked.

Current State

SessionsSubcommand::Related { session_id } exists (crates/terraphim_agent/src/repl/commands.rs around ~1100) and finds sessions related to a known session, but there is no query-driven recommender.
grep for Recommend / recommend in repl/ returns zero hits.
The scoring components needed (concept overlap via SessionIndex::concepts, recency weight, outcome-success flag) exist in terraphim_sessions::service.

Acceptance Criteria

New variant SessionsSubcommand::Recommend { query: String, top_k: Option<usize>, min_score: Option<f32> } with help text in the /sessions command tree.
Handler at crates/terraphim_agent/src/repl/handler.rs implementing handle_sessions_recommend.
Scoring function: score = 0.55 * concept_overlap + 0.25 * recency_decay + 0.20 * outcome_success_bonus, clamped to [0.0, 1.0].
Top-K default = 5, configurable 1..50; min_score default = 0.15.
Each recommendation returns { session_id, title, source, score, matched_concepts, solution_snippet } where solution_snippet is the last assistant message body truncated to 240 chars.
Robot mode (--robot --format json) emits a recommendations: [...] array matching the shape above.
Interactive mode prints a readable table with score, source, matched concepts, and snippet.
Unit test in service.rs for the scoring function; integration test in repl_integration_tests asserting non-empty recommendations on a seeded index.
cargo test -p terraphim_agent --features repl-full,repl-sessions passes.
cargo clippy -p terraphim_agent --features repl-full,repl-sessions -- -D warnings passes.

Proposed Approach

Extend SessionsSubcommand in repl/commands.rs with the new Recommend variant and clap derive attributes.
Add SessionService::recommend(query, top_k, min_score) in crates/terraphim_sessions/src/service.rs that:
- Runs the existing concept-expansion pipeline on the query,
- Iterates indexed sessions, computes overlap + recency + outcome score,
- Returns the top-K ordered by descending score.
Add a handler in repl/handler.rs (handle_sessions_recommend) that formats the output for both interactive and robot modes.
Update /sessions help text in commands.rs and the corresponding section in docs/src/claude-code-skills.md.
Add scoring unit tests and one seeded integration test.

Dependencies

None blocking — concept extraction and the session index are already available. (Benefits from #5 Tantivy index when merged, but not required.)

Verification

cargo build -p terraphim_agent --features repl-full,repl-sessions --release
./target/release/terraphim-agent sessions recommend "async timeout handling" --top-k 5
./target/release/terraphim-agent sessions recommend "async timeout handling" --robot --format json
cargo test -p terraphim_agent --features repl-full,repl-sessions sessions::recommend
cargo clippy -p terraphim_agent --features repl-full,repl-sessions -- -D warnings

Scope

~250 LOC: ~60 in commands.rs, ~120 in service.rs (scorer + orchestration), ~70 in handler.rs (formatters). Single PR.

Upstream: Implements Phase 3 F5.3 bullet 2 of docs/specifications/terraphim-agent-session-search-spec.md for terraphim/terraphim-ai.

## Problem Statement Phase 3 F5.3 of the session-search spec mandates a "past-solution discovery" surface: given a user query, the agent should recommend past sessions whose outcomes solved a similar problem, so successful solutions become reusable lessons learned. The `SessionsSubcommand` enum has `Search`, `Concepts`, `Related`, `Timeline`, `Enrich`, `Files`, `ByFile`, `Index`, etc., but no `Recommend` variant. F5.3 bullet two — cross-session recommendation by concept overlap and recency — remains unchecked. ## Current State - `SessionsSubcommand::Related { session_id }` exists (`crates/terraphim_agent/src/repl/commands.rs` around ~1100) and finds sessions related to a known session, but there is no query-driven recommender. - `grep` for `Recommend` / `recommend` in `repl/` returns zero hits. - The scoring components needed (concept overlap via `SessionIndex::concepts`, recency weight, outcome-success flag) exist in `terraphim_sessions::service`. ## Acceptance Criteria - [ ] New variant `SessionsSubcommand::Recommend { query: String, top_k: Option<usize>, min_score: Option<f32> }` with help text in the `/sessions` command tree. - [ ] Handler at `crates/terraphim_agent/src/repl/handler.rs` implementing `handle_sessions_recommend`. - [ ] Scoring function: `score = 0.55 * concept_overlap + 0.25 * recency_decay + 0.20 * outcome_success_bonus`, clamped to `[0.0, 1.0]`. - [ ] Top-K default = 5, configurable 1..50; `min_score` default = 0.15. - [ ] Each recommendation returns `{ session_id, title, source, score, matched_concepts, solution_snippet }` where `solution_snippet` is the last assistant message body truncated to 240 chars. - [ ] Robot mode (`--robot --format json`) emits a `recommendations: [...]` array matching the shape above. - [ ] Interactive mode prints a readable table with score, source, matched concepts, and snippet. - [ ] Unit test in `service.rs` for the scoring function; integration test in `repl_integration_tests` asserting non-empty recommendations on a seeded index. - [ ] `cargo test -p terraphim_agent --features repl-full,repl-sessions` passes. - [ ] `cargo clippy -p terraphim_agent --features repl-full,repl-sessions -- -D warnings` passes. ## Proposed Approach 1. Extend `SessionsSubcommand` in `repl/commands.rs` with the new `Recommend` variant and clap derive attributes. 2. Add `SessionService::recommend(query, top_k, min_score)` in `crates/terraphim_sessions/src/service.rs` that: - Runs the existing concept-expansion pipeline on the query, - Iterates indexed sessions, computes overlap + recency + outcome score, - Returns the top-K ordered by descending score. 3. Add a handler in `repl/handler.rs` (`handle_sessions_recommend`) that formats the output for both interactive and robot modes. 4. Update `/sessions` help text in `commands.rs` and the corresponding section in `docs/src/claude-code-skills.md`. 5. Add scoring unit tests and one seeded integration test. ## Dependencies None blocking — concept extraction and the session index are already available. (Benefits from #5 Tantivy index when merged, but not required.) ## Verification ```bash cargo build -p terraphim_agent --features repl-full,repl-sessions --release ./target/release/terraphim-agent sessions recommend "async timeout handling" --top-k 5 ./target/release/terraphim-agent sessions recommend "async timeout handling" --robot --format json cargo test -p terraphim_agent --features repl-full,repl-sessions sessions::recommend cargo clippy -p terraphim_agent --features repl-full,repl-sessions -- -D warnings ``` ## Scope ~250 LOC: ~60 in `commands.rs`, ~120 in `service.rs` (scorer + orchestration), ~70 in `handler.rs` (formatters). Single PR. Upstream: Implements Phase 3 F5.3 bullet 2 of `docs/specifications/terraphim-agent-session-search-spec.md` for terraphim/terraphim-ai.

product-owner referenced this issue

2026-04-24 05:01:29 +02:00

feat: /sessions path command for concept-based session traversal (Phase 3 Task 3.2.2) #12

product-owner added a new dependency 2026-04-24 05:01:40 +02:00

#12 feat: /sessions path command for concept-based session traversal (Phase 3 Task 3.2.2)

product-owner referenced this issue

2026-04-24 11:07:40 +02:00

feat: /sessions analyze subcommand with dominant-topic analyser (F4.4, Task 3.1.3) #16

product-owner referenced this issue

2026-04-25 08:03:14 +02:00

feat: rolegraph session-frequency edge weighting from concept enrichment (f5.3 bullet 3) #37

product-owner referenced this issue