|
| 1 | +# ProllyTree Versioned Memory for AI Agents |
| 2 | + |
| 3 | +This example demonstrates how to use ProllyTree as a versioned memory backend for AI agents using the Rig framework. It showcases time-travel debugging, memory branching, and complete audit trails for reproducible AI behavior. |
| 4 | + |
| 5 | +## Features |
| 6 | + |
| 7 | +- **Versioned Memory**: Every interaction creates a new version, enabling rollback to any previous state |
| 8 | +- **Memory Types**: Short-term (conversation), long-term (facts), and episodic (experiences) memory |
| 9 | +- **Memory Branching**: Experiment with different agent behaviors without affecting the main memory |
| 10 | +- **Audit Trails**: Track every decision and memory access for debugging and compliance |
| 11 | +- **Rig Integration**: Seamless integration with Rig's LLM completion API |
| 12 | + |
| 13 | +## Prerequisites |
| 14 | + |
| 15 | +1. Rust (latest stable version) |
| 16 | +2. OpenAI API key |
| 17 | +3. ProllyTree library (included as local dependency) |
| 18 | + |
| 19 | +## Setup |
| 20 | + |
| 21 | +1. Set your OpenAI API key: |
| 22 | + ```bash |
| 23 | + export OPENAI_API_KEY="your-api-key-here" |
| 24 | + ``` |
| 25 | + |
| 26 | + Or create a `.env` file: |
| 27 | + ``` |
| 28 | + OPENAI_API_KEY=your-api-key-here |
| 29 | + ``` |
| 30 | + |
| 31 | +2. Build the project: |
| 32 | + ```bash |
| 33 | + cd examples/rig_versioned_memory |
| 34 | + cargo build |
| 35 | + ``` |
| 36 | + |
| 37 | +## Running the Demo |
| 38 | + |
| 39 | +### Interactive Chat Mode (Default) |
| 40 | +```bash |
| 41 | +cargo run |
| 42 | +``` |
| 43 | + |
| 44 | +### Custom Storage Location |
| 45 | +```bash |
| 46 | +# Use custom storage directory |
| 47 | +cargo run -- --storage ./my_agent_memory |
| 48 | + |
| 49 | +# Use absolute path |
| 50 | +cargo run -- --storage /tmp/agent_data |
| 51 | + |
| 52 | +# Short form |
| 53 | +cargo run -- -s ./custom_location |
| 54 | +``` |
| 55 | + |
| 56 | +### Specific Demos |
| 57 | + |
| 58 | +1. **Memory Learning & Rollback**: |
| 59 | + ```bash |
| 60 | + cargo run -- learning |
| 61 | + cargo run -- --storage ./custom_path learning |
| 62 | + ``` |
| 63 | + Shows how the agent learns preferences and can rollback to previous states. |
| 64 | + |
| 65 | +2. **Memory Branching**: |
| 66 | + ```bash |
| 67 | + cargo run -- branching |
| 68 | + ``` |
| 69 | + Demonstrates experimental memory branches for safe behavior testing. |
| 70 | + |
| 71 | +3. **Audit Trail**: |
| 72 | + ```bash |
| 73 | + cargo run -- audit |
| 74 | + ``` |
| 75 | + Shows decision tracking and memory access logging. |
| 76 | + |
| 77 | +4. **Episodic Learning**: |
| 78 | + ```bash |
| 79 | + cargo run -- episodic |
| 80 | + ``` |
| 81 | + Demonstrates learning from experiences and outcomes. |
| 82 | + |
| 83 | +5. **Run All Demos**: |
| 84 | + ```bash |
| 85 | + cargo run -- all |
| 86 | + ``` |
| 87 | + |
| 88 | +## Interactive Mode Commands |
| 89 | + |
| 90 | +- `/quit` - Exit interactive mode |
| 91 | +- `/new` - Start a new conversation (clears session memory) |
| 92 | +- `/version` - Show current memory version |
| 93 | +- `/learn <concept> <fact>` - Teach the agent a new fact |
| 94 | + |
| 95 | +## Architecture |
| 96 | + |
| 97 | +### Memory Types |
| 98 | + |
| 99 | +1. **Short-term Memory**: Current conversation context |
| 100 | + - Stores user inputs and agent responses |
| 101 | + - Session-based storage |
| 102 | + - Used for maintaining conversation flow |
| 103 | + |
| 104 | +2. **Long-term Memory**: Learned facts and preferences |
| 105 | + - Persistent across sessions |
| 106 | + - Concept-based organization |
| 107 | + - Access count tracking for relevance |
| 108 | + |
| 109 | +3. **Episodic Memory**: Past experiences and outcomes |
| 110 | + - Records actions and their results |
| 111 | + - Includes reward signals for reinforcement |
| 112 | + - Used for learning from experience |
| 113 | + |
| 114 | +### Key Components |
| 115 | + |
| 116 | +- `VersionedMemoryStore`: Core storage backend using ProllyTree |
| 117 | +- `VersionedAgent`: Rig-based agent with memory integration |
| 118 | +- `Memory`: Data structure for storing memories with metadata |
| 119 | +- `MemoryContext`: Retrieved memories for context building |
| 120 | + |
| 121 | +## Example Usage |
| 122 | + |
| 123 | +```rust |
| 124 | +// Initialize agent with versioned memory |
| 125 | +let mut agent = VersionedAgent::new(api_key, "./agent_memory").await?; |
| 126 | + |
| 127 | +// Process a message (automatically stores in memory) |
| 128 | +let (response, version) = agent.process_message("Hello!").await?; |
| 129 | + |
| 130 | +// Learn a fact |
| 131 | +agent.learn_fact("user_preference", "Likes concise responses").await?; |
| 132 | + |
| 133 | +// Create a memory branch for experimentation |
| 134 | +agent.create_memory_branch("experiment_1").await?; |
| 135 | + |
| 136 | +// Rollback to a previous version |
| 137 | +agent.rollback_to_version(&version).await?; |
| 138 | +``` |
| 139 | + |
| 140 | +## Memory Storage |
| 141 | + |
| 142 | +### Storage Location |
| 143 | +By default, the agent stores memory in `./demo_agent_memory/`. You can customize this with: |
| 144 | +```bash |
| 145 | +cargo run -- --storage /path/to/your/storage |
| 146 | +``` |
| 147 | + |
| 148 | +### Storage Structure |
| 149 | +The storage directory contains: |
| 150 | +- `.git/` - Git repository for version control |
| 151 | +- `.git-prolly/` - ProllyTree metadata and configuration |
| 152 | +- SQL database files with the following tables: |
| 153 | + - `short_term_memory`: Conversation history |
| 154 | + - `long_term_memory`: Learned facts and knowledge |
| 155 | + - `episodic_memory`: Experiences and outcomes |
| 156 | + - `memory_links`: Relationships between memories |
| 157 | + |
| 158 | +### Storage Options |
| 159 | +- **Relative paths**: `./my_memory`, `../shared_memory` |
| 160 | +- **Absolute paths**: `/tmp/agent_data`, `/Users/name/agents/memory` |
| 161 | +- **Different agents**: Use different storage paths for separate agent instances |
| 162 | + |
| 163 | +## Benefits |
| 164 | + |
| 165 | +1. **Reproducibility**: Replay agent behavior from any historical state |
| 166 | +2. **Debugging**: Complete audit trail of decisions and memory access |
| 167 | +3. **Experimentation**: Safe testing with memory branches |
| 168 | +4. **Compliance**: Maintain required audit logs and data lineage |
| 169 | +5. **Learning**: Agents can learn and improve from experiences |
| 170 | + |
| 171 | +## Future Enhancements |
| 172 | + |
| 173 | +- Embedding-based semantic search |
| 174 | +- Distributed memory sharing between agents |
| 175 | +- Memory compression for old conversations |
| 176 | +- Advanced attention mechanisms for memory retrieval |
0 commit comments