feat(agents): adaptive deep memory recall with composite scoring

オープン
#5,613 コメント 2 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
12/100
issue の種類
機能追加
明瞭さ
おおむね明確
活発さ
静か
技術スタック
python
領域
ai

調査の方向性

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.

索引モデルが issue の本文から書いたものです。

説明

bug claude documentation security

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

  1. Design review
  2. Implement + tests
  3. CLI/YAML
  4. Docs
  5. 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/.

主要言語
Python
スター
9.3k
フォーク
1.5k
平均マージ
1日 5時間
マージ済み PR(30日)
520

環境構築

このプロジェクトには開発コンテナ、Dockerfile、コントリビューションガイドがありません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

MervinPraison/PraisonAI のほかの issue

MervinPraison/PraisonAI の issue をすべて見る

似ている issue

Python の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。