feat(agents): adaptive deep memory recall with composite scoring
Los mantenedores suelen responder en 1 día
Nadie ha tomado este issue todavía.
Evaluación
- Dificultad
- 5/5
- Tiempo estimado
- Más de una semana
- Aptitud para principiantes
- 12/100
Línea de trabajo
Start with praisonaiagents/memory/memory.py and search.py to see the current single-pass search, then agent/agent.py for the pre-run injection point. The proposed memory/recall.py is new, and the listed tests in tests/unit/memory/test_deep_recall.py are not written yet. Done means shallow recall is unchanged and deep recall passes the alias test, but the cross-session case depends on #5597 being fixed first.
Escrito por el modelo de indexación a partir del texto del issue.
Descripción
Metadata
| Field | Value |
|---|---|
| Repository | MervinPraison/PraisonAI |
| Package | praisonai-agents |
| Component | memory, Agent, AgentTeam, YAML |
| Labels | enhancement, memory, agents, parity |
| Priority | P1 |
| Estimated effort | 4–6 engineer-weeks |
| Depends on | GitHub #5597 (memory persistence) |
Executive summary
Production agents need adaptive recall: optional deep path with sub-queries and composite scoring (semantic + recency + importance). PraisonAI has memory stores and AutoMemory but no depth=shallow|deep API or uniform team post-task extraction.
Interactive triage
flowchart TD
A[Fact stored but not in answer?] --> B{Stored in backend?}
B -->|No| C[Fix #5597 persistence first]
B -->|Yes| D[Ranking / deep recall gap]
D --> E[This issue]
Architecture — current (shallow recall)
flowchart LR
Q[User query] --> E[Embed query]
E --> V[Vector top-k]
V --> I[Inject prompt]
M[(Memory store)] --> V
| Layer | Module | Role today |
|---|---|---|
| Search | praisonaiagents/memory/memory.py, search.py |
Single-pass retrieval |
| Auto extract | memory/auto_memory.py |
On flush, not every task |
| Agent hook | agent/agent.py |
Injects memory context if configured |
| Team | agent/agent_team.py |
No uniform post-task extract + deep recall |
Architecture — proposed (adaptive deep recall)
sequenceDiagram
participant A as Agent
participant R as RecallPipeline
participant L as Aux LLM
participant S as MemoryStore
A->>R: recall(query, depth=deep)
R->>L: distill sub-queries
par searches
R->>S: search(q1)
R->>S: search(q2)
end
R->>R: composite score merge
R-->>A: ranked matches
Expected vs actual
| # | Scenario | Expected | Actual (main 54715e811) | Severity |
|---|---|---|---|---|
| 1 | Alias question ("project alias?") with codename stored | Deep recall finds fact | Shallow embed often misses | High |
| 2 | depth=deep API |
Sub-queries + merge | No API | High |
| 3 | Composite recency + importance | Stable ranking | Partial adapter fields only | Medium |
| 4 | Same scope_key cross-session |
Recalls codename | Fails live E2E (#5597) | Blocker |
| 5 | YAML recall_depth: deep |
CLI honours | Unknown key / ignored | Medium |
Terminal evidence
Live E2E — cross-session memory (#5597 class)
[PASS] memory_persist 4.3s {
'preview': "I'm sorry, but I don't have that information stored.",
'recalled': false
}
Fix storage (#5597) before deep recall acceptance; this issue adds ranking after store works.
Conceptual — alias miss under shallow-only recall
>>> memory.search("What is my project alias?")
[]
>>> # expected after deep recall implementation:
>>> memory.recall("What is my project alias?", depth="deep")
[MemoryMatch(content="codename ORANGE-PANDA", score=0.91)]
Suggested code changes
| Step | File | Change |
|---|---|---|
| 1 | praisonaiagents/memory/recall.py |
New RecallConfig, RecallPipeline, compute_composite_score() |
| 2 | praisonaiagents/memory/protocols.py |
Extend protocol with recall(..., depth=...) default shallow |
| 3 | praisonaiagents/agent/agent.py |
Before chat/run, call pipeline; inject capped context block |
| 4 | praisonaiagents/agent/agent_team.py |
Post-task: extract_task_facts() → store |
| 5 | YAML parser + praisonai/cli |
Map recall_depth, weights into Agent kwargs |
| 6 | tests/unit/memory/test_deep_recall.py |
Mock LLM sub-queries; fixed embedding vectors |
# praisonaiagents/memory/recall.py (sketch)
@dataclass
class RecallConfig:
depth: Literal["shallow", "deep"] = "shallow"
limit: int = 10
semantic_weight: float = 0.6
recency_weight: float = 0.25
importance_weight: float = 0.15
def recall(store, query: str, cfg: RecallConfig, llm=None) -> list[MemoryMatch]:
if cfg.depth == "shallow":
return store.search(query, limit=cfg.limit)
sub_qs = distill_queries(query, llm, max_n=4)
hits = merge_parallel([store.search(q, limit=cfg.limit) for q in sub_qs])
return rank_composite(hits, cfg)
Public API (YAML parity)
agents:
- name: analyst
memory:
scope_key: "${MEMORY_SCOPE}" # tenant or end-user partition for recall
recall_depth: deep
recall_limit: 10
How to fix in code (detailed)
Step 1 — Recall pipeline module
Create praisonaiagents/memory/recall.py with RecallConfig, MemoryMatch, RecallPipeline.recall().
Hook shallow path to existing SearchMixin so default behavior is unchanged.
Step 2 — Agent pre-run injection
In agent/agent.py, before building LLM messages:
def _inject_recalled_memory(self, query: str) -> None:
cfg = self._memory_recall_config
if not cfg or not self._memory_store:
return
matches = recall_pipeline.recall(self._memory_store, query, cfg, llm=self._aux_llm)
block = format_memory_block(matches, max_tokens=cfg.max_inject_tokens)
self._prepend_context(block)
Step 3 — Team post-task extract
In agent_team.py after task output validated:
if team.memory and task.memory_extract:
team.memory.extract_and_store(task_output.raw, scope=f"task:{task.id}")
Step 4 — YAML / CLI
Extend memory dict parsing in YAML loader and praisonai/cli agent config extraction with keys recall_depth, recall_limit, weight floats.
Second diagram — recall state
stateDiagram-v2
[*] --> Shallow
Shallow --> Deep: depth=deep
Deep --> Distill: LLM sub-queries
Distill --> Search: parallel vector queries
Search --> Rank: composite score
Rank --> Inject: cap tokens
Inject --> [*]
Terminal — pytest failure (target)
After implementation — expected test pass log
tests/unit/memory/test_deep_recall.py::test_alias_found_deep_only PASSED
tests/unit/memory/test_deep_recall.py::test_shallow_default_unchanged PASSED
Functional requirements
| Requirement |
|---|
| RecallConfig on Agent memory dict |
| depth shallow preserves today behavior |
| depth deep runs sub-queries max 4 |
| Composite score weights sum to 1.0 |
| AgentTeam post-task fact extraction |
| YAML recall_depth and CLI parity |
| Trace MEMORY_RECALL with depth and count |
Integration test matrix
| Scenario | Expected outcome |
|---|---|
| Alias question deep vs shallow | Pass or typed, documented error |
| Cross-session scope_key after #5597 fix | Pass or typed, documented error |
| YAML recall_depth deep | Pass or typed, documented error |
| Team sequential extract after task | Pass or typed, documented error |
Rollout plan
- Design review
- Implement + tests
- CLI/YAML
- Docs
- GA or flag
Documentation outline
- User guide
- Cookbook
- Security/ops
Migration notes
- Backward compatible default
- Opt-in flags
Acceptance criteria
- Tests pass
- Docs shipped
- Default path unchanged
Extended expected vs actual
| Scenario | Expected | Actual | Severity |
|---|---|---|---|
| Synonym query | Deep recall hit | Empty list | High |
| YAML deep | Honoured | Ignored key | Med |
Implementation checklist
- Implement RecallConfig validation
- Add recall.py RecallPipeline
- Hook Agent.chat pre-run recall
- AgentTeam post-task extract
- Emit trace MEMORY_RECALL
- YAML parser recall_depth
- Mock LLM sub-query tests
- Document shallow default
Module map (PR scope)
| Path | Action |
|---|---|
praisonaiagents/memory/recall.py |
Add RecallPipeline |
praisonaiagents/memory/memory.py |
Wire recall into search path |
praisonaiagents/agent/agent.py |
Inject recalled context |
praisonaiagents/agent/agent_team.py |
Post-task extract hook |
praisonai/cli/ |
YAML recall_depth |
tests/unit/memory/ |
Deep recall mocks |
Open questions
- Feature flag default?
- SQLite first then Postgres?
Regression guardrails
| Check | Command |
|---|---|
| Targeted pytest | Run tests under module paths from Suggested code changes |
| Lint | ruff check on touched packages |
| Manual | Reproduce Terminal evidence before/after |
Contributor checklist
- Expected vs actual reproduced or validated
- Terminal evidence attached in PR if bugfix
- Suggested code changes modules covered by tests
Related
- GitHub #5597 — fix memory persistence before deep-recall acceptance tests
- Structured output #5594 — separate concern
Filed from competitive parity review draft (2026-10-02). Internal tracking: issue-drafts/competitive-parity-20261002/.
- Lenguaje dominante
- Python
- Estrellas
- 9.3k
- Forks
- 1.5k
- Merge medio
- 1 d 5 h
- PR fusionados (30 d)
- 520
Preparar el entorno
Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.
Primeros pasos
- Lee el issue completo y luego la guía de contribución del proyecto.
- Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
- Haz un fork del repositorio y trabaja en una rama.
- Abre un pull request que haga referencia al número del issue.
Más de MervinPraison/PraisonAI
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 82/100
MervinPraison/PraisonAI#6710 · 1 comentario ·
Los mantenedores suelen responder en 1 día
-
claude
Dificultad 2/5 1-3 horas Aptitud para principiantes 74/100
MervinPraison/PraisonAI#6707 ·
Los mantenedores suelen responder en 1 día
-
bug claude
Dificultad 1/5 Menos de una hora Aptitud para principiantes 90/100
MervinPraison/PraisonAI#6671 ·
Los mantenedores suelen responder en 1 día
-
Compaction budget regression fixture remains below budget with accurate tokenizationQuizá libre de nuevo Un pull request para esta issue se cerró sin fusionarse. Abierto
Dificultad 2/5 1-3 horas Aptitud para principiantes 62/100
MervinPraison/PraisonAI#5418 · 3 comentarios ·
Los mantenedores suelen responder en 1 día
-
bug claude documentation
Dificultad 2/5 1-3 horas Aptitud para principiantes 70/100
MervinPraison/PraisonAI#5341 · 3 comentarios ·
Los mantenedores suelen responder en 1 día
Todos los issues de MervinPraison/PraisonAI
Issues similares
-
cognition
Dificultad 2/5 1-3 horas Aptitud para principiantes 82/100
Los mantenedores suelen responder en 1 día
-
[Suggestion]: Geonode MCP ServerAbierto
Dificultad 1/5 Menos de una hora Aptitud para principiantes 78/100
collabnix/awesome-mcp-lists#433 ·
Los mantenedores suelen responder en 4 días
-
CrossEntropyFilter raises on zero probabilities and single-class resultsPosiblemente ocupada @NopeCharon la tomó hoy. Abierto
Dificultad 2/5 1-3 horas Aptitud para principiantes 78/100
Los mantenedores suelen responder en 1 día
-
bug
Dificultad 2/5 1-3 horas Aptitud para principiantes 78/100
datajoint/datajoint-python#1703 ·
Los mantenedores suelen responder en 6 días
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 78/100
Archmonger/ServeStatic#129 ·