pi-smart-context-manager

Intelligent Context Management for Long-Session AI Agents

Solves the context decay problem identified in academic research by implementing a multi-level memory hierarchy with decay detection, intelligent compression, and retrieval augmentation.

🎯 The Problem

Larger context windows do not solve the memory problem.

Research from "Agent Harness Engineering: A Survey" reveals two critical phenomena:

1. U-Shaped Attention Curve

Accuracy
  ^
  |     ╱╲
  |    ╱  ╲
  |   ╱    ╲
  |  ╱      ╲
  | ╱        ╲
  |╱          ╲
  +-----------------> Information Position
  Start  Middle  End

Information in the middle of context gets ignored, with 30%+ accuracy drop.

2. Context Decay

Early information gradually gets "forgotten" even within the context window. Critical details from 20+ rounds ago are often lost.

---

💡 The Solution

Smart Context Manager implements a four-level memory hierarchy:

┌─────────────────────────────────────────┐
│  Level 1: Working Memory                │  ← Current task
│  - Active information                    │
│  - Position: Begin/End (U-curve aware)  │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  Level 2: Short-term Memory             │  ← Session context
│  - Recent conversation history           │
│  - Rolling window with compression      │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  Level 3: Medium-term Memory            │  ← Session summary
│  - Key decisions and rationale          │
│  - Structured, retrievable format       │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  Level 4: Long-term Memory              │  ← Cross-session
│  - User preferences and constraints     │
│  - High-value persistent knowledge      │
└─────────────────────────────────────────┘

---

✨ Core Features

1. Decay Detector 🔍

Automatically detects when critical information is decaying

2. Position Optimizer 📍

Leverages U-shaped attention curve to place information optimally

3. Smart Compressor 🗜️

Compresses context while preserving key information

4. Retrieval Enhancer 🔎

Augments current context with relevant information from memory

5. Memory Synchronizer 🔄

Automatically promotes high-value information to long-term memory

---

📦 Installation

pi install npm:pi-smart-context-manager

Or add to your project settings (.pi/settings.json):

{
  "packages": ["npm:pi-smart-context-manager"]
}

---

🚀 Usage

Once installed, the skill automatically activates during long conversations. The agent will:

1. Detect decay - Monitor when critical information hasn't been referenced
2. Check positions - Warn if important info is in the middle danger zone
3. Proactively refresh - Restate critical information before it decays
4. Compress intelligently - Preserve decisions while summarizing conversations
5. Retrieve context - Pull relevant information from memory when needed

---

🐍 Python Script Example

This package includes a complete Python implementation for demonstration and local testing.

Available Commands

# Detect information decay
python scripts/context_manager.py detect-decay --current-round 45

# Register critical information
python scripts/context_manager.py register \
  --id "pref1" \
  --type "user_preference" \
  --content "Use Feishu for notifications"

# Check position safety (U-curve awareness)
python scripts/context_manager.py check-position \
  --id "pref1" \
  --position 500 \
  --total 1000

# Smart compression demo
python scripts/context_manager.py compress --ratio 0.3

# Retrieval augmentation from memory
python scripts/context_manager.py enhance --query "user preferences"

# Session summary
python scripts/context_manager.py session-summary

Script Location

After installation, the Python script is available at:

node_modules/pi-smart-context-manager/scripts/context_manager.py

---

📊 Performance Impact

Based on the research findings:

Metric	Without Management	With Smart Context Manager
Information Retrieval Accuracy	~60% (middle position)	~90% (position optimized)
Critical Information Retention	Decays after 20 rounds	Proactively refreshed
Context Size	Grows linearly	Smart compression (30% target)
Session Length Support	Limited by context window	Multi-level memory extends capacity

---

🔬 Academic Foundation

This implementation is based on the comprehensive survey:

"Agent Harness Engineering: A Survey" (2026)

• Authors: Junjie Li, Xi Xiao, Yunbei Zhang, Chen Liu, Lin Zhao, Xiaoying Liao, Yingrui Ji, Janet Wang, Jianyang Gu, Yingqiang Ge, Weijie Xu, Xi Fang, Xiang Xu, Tianchen Zhao, Youngeun Kim, Tianyang Wang, Jihun Hamm, Smita Krishnaswamy, Jun Huan, Chandan K Reddy
• Institutions: CMU, Yale, JHU, NEU, Tulane, UAB, OSU, Virginia Tech, Amazon
• Analyzed: 170+ open-source projects
• Key Findings:
  • U-shaped attention curve causes 30%+ accuracy drop for middle-positioned information
  • Context decay: early information gets "forgotten" even within window
  • Larger context windows do not solve memory problems
  • Proactive management is essential for long-session reliability

Project Page: Awesome-Agent-Harness

---

📖 Best Practices

1. Layer Your Information - Use four memory levels based on importance and persistence needs

2. Optimize Position - Place critical info at beginning/end, avoid middle danger zone

3. Proactive Refresh - Don't assume the model remembers—periodically restate critical information

4. Smart Compression - Preserve decisions and rationale, summarize processes

5. Retrieval Augmentation - When context is insufficient, actively retrieve from memory

---

📝 License

MIT License - See LICENSE for details.

---

🙏 Acknowledgments

• The academic research community behind the "Agent Harness Engineering" survey
• OpenAI, Anthropic, and LangChain for production deployment insights
• The 170+ open-source projects analyzed in the research

---

📮 Links

• npm: https://www.npmjs.com/package/pi-smart-context-manager
• GitHub: https://github.com/bailianfa/smart-context-manager
• Pi Package: https://pi.dev/packages/pi-smart-context-manager

---

Remember: Larger context windows ≠ Better memory. Proactive management is key.