Agentic Context Engineering: A Practical Guide to Giving Claude Code Long-Term Memory
Repository: https://github.com/greatyingzi/agentic_context_engineering
01 The Pain: How Frustrating is an AI Assistant’s “Amnesia”?
When using conversational assistants for coding daily, you’re definitely familiar with these three scenarios:
Scenario One: Project Context is Always Forgotten
You: Help me modify the user authentication logic
AI: Sure, please provide the current user authentication implementation...
You: We just discussed this last week!
AI: Apologies, I need to re-understand your project structure...
Scenario Two: Same Problems Repeatedly Appear
You: This API is timing out again
AI: I suggest checking network connections, increasing timeout...
You: Last month we determined this was a database connection pool issue
AI: Please elaborate on the specific configuration...
Scenario Three: Team Habits are Hard to Preserve When new members join, the entire team needs to “re-teach” the AI to understand project architecture, coding standards, and best practices.
The core of these problems lies in: AI assistants lack persistent project memory mechanisms.
The “Agentic Context Engineering” (ACE) project aims to equip Claude Code with “long-term memory,” making it a true partner that understands your project.
02 What is the ACE System?
ACE (Agentic Context Engineering) is an open-source Claude Code extension system with only one core goal: making the AI “smarter with every conversation.”
Core Philosophy
Traditional RAG solutions require complex vector databases and embedding calculations, while ACE takes a different approach:
Leveraging Claude Code’s Hook events to create a lightweight closed loop of “extract → evaluate → merge → inject.”
Technical Architecture Overview
┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐
│ User Chat │ │ Hook Events │ │ Knowledge Engine │
│ │───▶│ │───▶│ │
│ Claude Code │ │ │ │ Extract→Eval→Merge│
└─────────────────┘ └──────────────┘ └─────────────────┘
│
┌─────────────────┐ ┌──────────────┐ ▼
│ Knowledge Base│◀───│ Context Inject│◀─────────────────┤
│playbook.json │ │ │ │
└─────────────────┘ └──────────────┘ │
▼
┌─────────────────┐
│ Smarter AI │
│ Claude Code │
└─────────────────┘
Lightweight and Efficient Design
- Single File Storage: Entire knowledge base is just one
playbook.json - Smart Self-Cleaning: Low-score entries automatically eliminated, maximum 250 entries
- Semantic Aggregation: Similar knowledge points automatically merged, avoiding redundancy
Comparison with traditional solutions:
| Solution | Storage Complexity | Deployment Difficulty | Real-time | Accuracy |
|---|---|---|---|---|
| RAG + Vector DB | High | Complex | Medium | High |
| ACE | Extremely Low | Simple | Real-time | High |
03 Core Technical Implementation
Hook Event Flow Engine
ACE achieves a closed loop by listening to three key Hook events from Claude Code:
1. UserPromptSubmit - Intelligent Context Injection
# Before user提问, the system automatically:
1. Analyzes current conversation and user intent
2. Generates 3-6 precise tags
3. Matches up to 6 relevant knowledge points
4. Injects into Claude's context
Key Optimization: Avoids irrelevant noise, only injects the most relevant knowledge, preventing AI from “getting sidetracked.”
2. SessionEnd - Conversation Summary and Learning
# At conversation end, the system automatically:
1. Asks LLM to extract new knowledge points
2. Evaluates usefulness of existing entries
3. Merges entries with semantic similarity ≥0.8
4. Updates knowledge base
3. PreCompact - Knowledge Protection Mechanism
Before Claude compresses conversation history, it extracts key information again, minimizing the risk of knowledge loss.
Knowledge Extraction and Merging Algorithms
Semantic Aggregation Strategy
def merge_knowledge_points(old_points, new_points):
for new_point in new_points:
# Calculate semantic similarity
similarity = calculate_similarity(new_point, old_points)
if similarity >= 0.8:
# High similarity: merge and update
merge_and_update(new_point, target_point)
else:
# New knowledge: add directly
add_new_point(new_point)
Scoring System Design
- Useful: +1 point (solved actual problems)
- Harmful: -3 points (caused errors or misleading)
- Neutral: 0 points (no significant impact)
Automatic Cleanup: Entries with score ≤-5 are directly eliminated, maintaining knowledge base quality.
Standardized Output
Each knowledge point follows strict format:
- Single sentence expression, ≤180 characters
- Must include tags for easy retrieval
- Record sources for traceability
04 Practical Deployment and Usage
One-Click Installation (Globally Effective)
# Clone the project
git clone https://github.com/greatyingzi/agentic_context_engineering
cd agentic_context_engineering
# Automatic installation and configuration
npm install
The installation script will automatically complete:
- File Deployment: Copy core files to
~/.claude/ - Environment Configuration: Create Python virtual environment, install dependencies
- Configuration Integration: Automatically update
~/.claude/settings.json
Restart Claude Code to take effect, one deployment, global usage.
Historical Session Replay: Quick Knowledge Base Building
If you already have extensive conversation history, you can quickly build a knowledge base through commands:
# Replay all historical conversations
/init-playbook
# Only process the latest 10 records
/init-playbook --limit 10
# Start processing from newest
/init-playbook --order newest
# Force rebuild from empty database
/init-playbook --force
The system will automatically traverse ~/.claude/projects/*.jsonl, replay all conversations in order, processing while persisting to disk.
Diagnostic Mode and Tuning
Enable diagnostic mode to deeply understand the system’s working process:
touch .claude/diagnostic_mode
The system will save each:
- Generated prompts
- AI response results
- Injected/deleted knowledge points
to the .claude/diagnostic/ directory, helping you analyze why certain knowledge was selected or deleted.
Configuration Switches
You can adjust in ~/.claude/settings.json:
{
"playbook_update_on_exit": true, // Update on session end
"playbook_update_on_clear": false // Don't update when clearing conversation
}
05 Usage Effects and Best Practices
Actual User Experience
First Week: Adaptation Period
- AI starts remembering basic project structure
- Occasionally injects irrelevant knowledge
- Need to tune through diagnostic mode
Second Week: Effect Period
- AI can accurately recall previous solutions
- Repetitive questions significantly reduced
- Team coding habits begin to settle
After One Month: Maturity Period
- New technical issues are remembered upon first resolution
- Team knowledge naturally transfers to new members
- AI truly becomes a “project-aware” partner
Recommended Configuration Strategy
Initial Phase
- Enable diagnostic mode
- Frequently check injection quality
- Promptly correct incorrect scoring
Stable Phase
- Disable diagnostic mode to reduce overhead
- Regularly clean knowledge base
- Supplement key business tags
Team Collaboration
- Share playbook.json file
- Establish team scoring standards
- Regularly sync important knowledge points
Best Practice Recommendations
1. Tag System Design
"Recommended Tags": [
"architecture", "database", "authentication",
"performance", "security", "deployment"
]
2. Unified Scoring Standards
- Solved actual problems: +1
- Provided useful references: +1
- Caused incorrect code: -3
- Provided outdated information: -2
- Irrelevant information: 0
3. Regular Maintenance
# Check knowledge base status monthly
cat ~/.claude/playbook.json | jq '.knowledge_points | length'
# View low-score entries, consider cleanup
cat ~/.claude/playbook.json | jq '.knowledge_points[] | select(.score <= -2)'
06 Team Collaboration Value
Automated Knowledge Transfer
Traditional team knowledge transfer:
Senior Employee → New Employee
Verbal Guidance + Document Reading → Understand Project
Repeated Questions → Gradual Familiarity
After ACE enhancement:
Team Conversations → Knowledge Base
New Employee Usage → Automatic Inheritance
Personalized Questions → Continuous Optimization
Collaboration Efficiency Improvement
Quantitative Metrics:
- Repetitive questions reduced by 60%+
- New employee onboarding time shortened by 40%+
- Team knowledge retention rate increased by 80%+
Real Case Study: A frontend team after introducing ACE, new employees who originally needed 2 weeks to familiarize with the project could independently handle routine issues by day 3, because the AI had “remembered” the project’s architectural patterns, coding standards, and common solutions.
07 Future Outlook
Technical Evolution Directions
- Multimodal Support: Not just text, but also code screenshots, design diagrams, etc.
- Cross-Project Migration: General programming knowledge can be reused across different projects
- Intelligent Prediction: Proactively push potentially needed knowledge based on current context
- Team Knowledge Graph: Build team-level knowledge networks supporting more complex reasoning
Ecosystem Development
ACE’s open-source nature means:
- Community can contribute better prompt templates
- Can be optimized for different programming languages
- Can be integrated into more development tools
Why This Project Matters
In today’s increasingly popular AI assistants, “memory” capability is becoming a watershed:
- AI without memory: Every conversation is new, forever停留在 surface level
- AI with memory: Continuous learning and deepening, truly becoming a productivity tool
ACE provides a simple, efficient, and scalable solution, allowing every developer to enjoy AI assistants with “memory.”
08 Quick Start
# 1. Install ACE
git clone https://github.com/greatyingzi/agentic_context_engineering
cd agentic_context_engineering
npm install
# 2. Import historical conversations (optional)
/init-playbook --limit 20
# 3. Enable diagnostic mode (optional)
touch .claude/diagnostic_mode
# 4. Restart Claude Code, start enjoying an AI assistant with memory!
Remember: The future of AI assistants lies not only in smarter answers, but also in longer memory.
Let Claude Code remember your habits, pitfalls, and best practices, no more repetitive low-value communication. Give it a try and let AI truly become your project-aware partner.
Project Repository: https://github.com/greatyingzi/agentic_context_engineering