recordor 1.0.0
Recordor - Enterprise AI agent memory infrastructure on Azure NetApp Files. Latin: 'I remember'
License: Apache-2.0
Requires Python: >=3.9
Keywords: ai, agents, memory, langchain, autogen, crewai, llamaindex, vector-database, rag, azure, netapp, enterprise, weaviate, postgresql, redis, soul, persistence, agent-memory

# Recordor - Complete Agentic Memory Solution

<div align="center">
  <img src="https://via.placeholder.com/800x200/0078D4/FFFFFF?text=Recordor+-+Where+AI+Agents+Own+Their+Memories" alt="Recordor Banner" />

  **The Industry's First Plug-and-Play Agentic Memory Solution for AI Agents**

  *Working memory, short-term, long-term, episodic, semantic, procedural — all managed autonomously*

  [![PyPI](https://img.shields.io/badge/PyPI-recordor-blue)](https://pypi.org/project/recordor/)
  [![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/downloads/)
  [![Azure NetApp Files](https://img.shields.io/badge/Azure-NetApp%20Files-0078D4)](https://azure.microsoft.com/en-us/services/netapp/)
  [![License](https://img.shields.io/badge/License-Apache%202.0-green)](https://github.com/DwirefS/Recordor/blob/main/LICENSE)
  [![Status](https://img.shields.io/badge/Status-Experimental%2FResearch-orange)](https://github.com/DwirefS/Recordor)
</div>

> **IMPORTANT NOTICE**: This project is in an **experimental/research state**. It is provided for educational and research purposes. Use in production environments is at your own risk. See [NOTICE](NOTICE) for full disclaimers.

> **DISCLAIMER**: This project uses various enterprise infrastructure components but is **NOT affiliated with, endorsed by, or sponsored by** any of the vendors mentioned (Microsoft, NetApp, etc.). All trademarks are property of their respective owners. See [NOTICE](NOTICE) for details.

---

## 🤖 The Agentic Paradigm

> **"AI agents are microservice-based applications with generative AI capabilities. They should own and manage their own memory."**

Recordor represents a fundamental shift in how we think about AI agent infrastructure:

| Traditional Approach | Recordor Agentic Approach |
|---------------------|----------------------------|
| Users deploy and manage memory | **Agents self-manage** after initial deployment |
| User-centric operations | **Agent-centric** with human oversight |
| Manual memory lifecycle | **Automated** versioning, archival, cleanup |
| Single-agent focus | **Multi-agent coordination** built-in |
| Memory as data | **Memory as intelligence substrate** |

### Why This Matters

The world is moving towards **agentic AI automation** where agents manage:
- Their own code and deployments
- Their own memory and learning
- Their own infrastructure
- Their own coordination with other agents

**Recordor provides the memory substrate** that enables this autonomous operation, while maintaining **human-in-the-loop** capabilities for oversight, debugging, and compliance.

### The Human Paradigm Connection

> **"The agent paradigm is the human paradigm applied to microservices with generative AI."**

Recordor builds agent memory the way human memory works:

| Human Memory | Recordor Equivalent | Why It Matters |
|--------------|----------------------|----------------|
| **Short-term memory** | Working memory (Redis) | Current task context, quick access |
| **Long-term memory** | Persistent memory (ANF) | Survives beyond the task, builds wisdom |
| **Episodic memory** | Experience storage | "What happened last time I did this?" |
| **Semantic memory** | Knowledge facts | "What do I know about this topic?" |
| **Procedural memory** | Skills and workflows | "How do I do this task?" |
| **People permanence** | **Agent Permanence** | "Who helped me well before?" |
| **Object permanence** | **Object Permanence** | "Which tools work best?" |
| **Sleep consolidation** | Memory consolidation | Organize, deduplicate, learn after tasks |

**Just like humans:**
- Agents process much during a task, but **results** are what get stored in long-term memory
- After work, agents can "reflect" — consolidating learnings, optimizing prompts
- Agents develop **relationships** (Agent Permanence) with other agents who help them succeed
- Agents remember **tools** (Object Permanence) that get the job done efficiently
- Agents can **time-travel** (snapshots) to recall exactly what they knew at any point

**The key insight**: Memory is more than data storage — it's the substrate of intelligence. An agent without persistent memory is like a human who forgets everything when they sleep. With Recordor, agents accumulate wisdom over time, building expertise that makes them more valuable.

### The Soul of AI Agents

> **"Recordor captures the soul of AI agents — their memories, personality, and learned experiences."**

In humans, the body and brain are physical, but the **mind** — the neural networks and memories — is what constitutes the "soul." The personality, the accumulated experiences, the learned behaviors: this is what makes each person unique. It's **software** in a sense — data stored in the physical substrate.

Likewise, **an AI agent is software**, and its soul is its memory:
- **Skills** (soul.md, skills.md files) — what the agent knows how to do
- **Personality** — how the agent communicates and behaves
- **Experiences** — episodes the agent has lived through
- **Relationships** — other agents and tools it has learned to trust

Recordor captures and protects this soul:
- **Persistence**: The soul survives beyond any single conversation
- **Versioning**: Time-travel through the agent's evolution (ANF snapshots)
- **Protection**: Enterprise-grade security for the agent's identity
- **Portability**: The soul can move to where compute awaits (teleport)
- **Inheritance**: New agents can inherit wisdom from experts (clone)

This is the foundation layer that was missing in the AI agent ecosystem. Many say AI agents aren't ready for production — but that's because they lacked proper **memory management**. Recordor provides that solution, with Azure NetApp Files as the enterprise storage foundation.

### Agent Soul Preservation

> **"The LLM models may change, but the memory (the soul) persists and evolves."**

Traditional database backups protect **data**. Agent Soul Preservation protects **identity**. The key insight:

| Database Backup | Soul Preservation |
|-----------------|-------------------|
| Protects data files | Protects agent identity |
| Point-in-time recovery | Agent evolution history |
| Disaster recovery | Personality continuity |
| Data is replaceable | Soul is irreplaceable |

**Nurturing AI Agents Like Raising Children**:

Just as children are raised to adulthood through guidance, correction, and accumulated experiences, AI agents must be **nurtured to production readiness**:

1. **Supervised phase**: Human-in-the-loop for every decision
2. **Guided autonomy**: Agent proposes, human approves
3. **Selective autonomy**: Trusted tasks run autonomously
4. **Full autonomy**: Production agent with human oversight

The agent's memory captures this growth journey:
```python
# Agent soul preservation - not just backup, but identity versioning
await agent.preserve_soul("pre-training-v1", description="Before customer service training")

# After weeks of learning with humans-in-the-loop
await agent.preserve_soul("trained-v1", description="Completed supervised training")

# The soul (memory) evolved, even if the LLM changed
# Old LLM + memories = same agent
# New LLM + same memories = same agent, better capabilities
```

**Why This Matters for Enterprise AI**:

The world needs **autonomous automation**, not just automation:
- **Automation**: Scripts execute predefined steps
- **Autonomous automation**: AI agents make decisions, learn, improve

For autonomous agents to be trusted, they must:
- Remember their training (soul preservation)
- Maintain their personality across sessions (persistence)
- Accumulate expertise over time (memory evolution)
- Be auditable for their decisions (memory versioning)

Recordor provides the foundation for this transition from chatbots to autonomous agents with persistent, evolving souls.

### Agent Self-Management Capabilities

```python
# Agents manage their own memory lifecycle
await agent.store_learning("User prefers Python for data science")
await agent.consolidate_memories()  # Self-deduplicate
await agent.snapshot("pre-decision-v1")  # Self-checkpoint
await agent.archive_old_memories(days=90)  # Self-archive

# Multi-agent coordination
await shared_memory.publish("market_analysis", results)
await shared_memory.subscribe("competitor_*", callback)
```

### Human Oversight

```bash
# Humans can inspect agent memories
recordor agent memory agent-001 --search "customer preferences"

# Restore agent to known-good state
recordor agent restore agent-001 --snapshot "last-good"

# View agent's thought process
recordor dashboard  # Full memory visibility
```

---

## 🧠 RAG + Agentic Memory: The Winning Combination

> **"RAG helps your agent know more. Memory helps your agent remember better. Together, they create agents that truly understand."**

Recordor is **not a replacement for RAG** — it's the **complementary memory layer** that makes AI agents truly intelligent:

```
┌─────────────────────────────────────────────────────────────────────────┐
│                   Enterprise AI Agent Architecture                      │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   User Query: "What's my order status?"                                 │
│                         │                                               │
│                         ▼                                               │
│   ┌─────────────────────────────────────────────────────────────────┐  │
│   │  Step 1: Check Agent Memory (Recordor)                         │  │
│   │  "What do I know about this customer?"                           │  │
│   │  → Customer: John, prefers email, had delay issue in January     │  │
│   └─────────────────────────────────────────────────────────────────┘  │
│                         │                                               │
│                         ▼                                               │
│   ┌─────────────────────────────────────────────────────────────────┐  │
│   │  Step 2: Query RAG for Business Data                             │  │
│   │  "What's the order status in our system?"                        │  │
│   │  → Order #12345: Shipped, arrives tomorrow by 5pm                │  │
│   └─────────────────────────────────────────────────────────────────┘  │
│                         │                                               │
│                         ▼                                               │
│   ┌─────────────────────────────────────────────────────────────────┐  │
│   │  Step 3: Generate PERSONALIZED Response                          │  │
│   │  "Hi John! Your order arrives tomorrow. Given your past          │  │
│   │   experience, I've flagged it for priority tracking..."          │  │
│   └─────────────────────────────────────────────────────────────────┘  │
│                         │                                               │
│                         ▼                                               │
│   ┌─────────────────────────────────────────────────────────────────┐  │
│   │  Step 4: Update Agent Memory (Recordor)                        │  │
│   │  "John inquired about order, responded positively to proactive   │  │
│   │   support offer"                                                 │  │
│   └─────────────────────────────────────────────────────────────────┘  │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
```

### The Key Difference

| RAG | Agentic Memory (Recordor) |
|-----|----------------------------|
| Query **business documents** | Store **agent experiences** |
| **Stateless** - forgets between sessions | **Persistent** - remembers forever |
| **Read-only** knowledge retrieval | **Read-write** learning and evolution |
| "What does the policy say?" | "What did I learn about this customer?" |
| Same response every time | **Personalized** responses based on history |

### Why Both Are Essential

- **RAG alone**: Agent knows company policies but treats every customer the same
- **Memory alone**: Agent remembers customers but can't answer policy questions
- **RAG + Memory**: Agent that **knows** AND **remembers** — truly intelligent

### Microsoft Agent Lightning Connection

[Microsoft Agent Lightning](https://github.com/microsoft/agent-lightning) enables **reinforcement learning** for AI agents. For RL to work, agents need persistent memory to store:
- **Experience trajectories** - What actions led to what outcomes
- **Reward signals** - What worked well, what didn't
- **State history** - Context for decision making

**Recordor provides this experience storage foundation** for agents that learn and improve over time.

See [RAG vs Agentic Memory](docs/RAG_VS_AGENTIC_MEMORY.md) for a detailed explanation.

---

## 🆕 What's New: Plug-and-Play Memory Adapter (January 2026)

Recordor has evolved into the **industry's first plug-and-play persistent memory adapter** for AI agents. Instead of requiring users to deploy complex infrastructure end-to-end, we now provide a **one-line install** experience that spins up all necessary components.

### 🎯 New Vision

```
pip install recordor && recordor-memory deploy
```

This single command deploys:
- **Weaviate** vector database (Microsoft-benchmarked on Azure NetApp Files)
- **PostgreSQL + PGVector** for relational + vector storage
- **Redis** caching layer for hot data
- **Memory versioning** via storage snapshots and clones
- **Cross-region replication** via SnapMirror

### 🔌 Supported AI Agent Frameworks

Recordor now provides **drop-in memory adapters** for all major AI agent frameworks:

| Framework | Adapter | Status | Key Features |
|-----------|---------|--------|--------------|
| **LangChain / LangGraph** | `LangChainMemoryAdapter` | ✅ Production | BaseMemory interface, state machine support |
| **AutoGen** | `AutoGenMemoryBank` | ✅ Production | Memory Bank pattern, Memory Protocol |
| **CrewAI** | `CrewAIMemoryAdapter` | ✅ Production | STM/LTM/Entity memory replacement |
| **LlamaIndex** | `LlamaIndexAdapter` | ✅ Production | ChatMemoryBuffer, VectorStoreIndex, RAG |
| **Microsoft Agent Framework** | `MSAgentFrameworkAdapter` | ✅ Production | IStorage interface, Session storage |
| **Azure AI Foundry** | `AzureAIFoundryAdapter` | ✅ Production | Memory stores, Thread persistence |
| **NVIDIA NIM/NeMo** | `NVIDIANIMAdapter` | ✅ Production | GPU-optimized embeddings, NeMo Guardrails |

### 🧠 Complete Memory Type Coverage

Recordor supports **all agentic memory types** — not just long-term storage:

| Memory Type | Purpose | Backend | Latency |
|-------------|---------|---------|---------|
| **WORKING** | Current LLM context | Redis L1/L2 Cache | <0.1ms |
| **SHORT_TERM** | Session-specific | Redis | <0.1ms |
| **LONG_TERM** | Cross-session persistent | Weaviate/PostgreSQL | <1ms |
| **EPISODIC** | Events & experiences | Weaviate | <1ms |
| **SEMANTIC** | Knowledge & facts | Weaviate | <1ms |
| **PROCEDURAL** | Skills & workflows | Weaviate | <1ms |
| **ENTITY** | People, places, things | Weaviate | <1ms |
| **CONVERSATION** | Chat history | PostgreSQL | <1ms |
| **MULTIMODAL** | Images, audio, video | Weaviate + ANF | <1ms |

**Tiered Architecture (MemGPT/Letta-inspired):**
- **Core Tier** - Always in LLM context (persona, user, active facts)
- **Working Tier** - Recently accessed, quick swap to core
- **Archival Tier** - Long-term storage, vector search retrieval
- **Recall Tier** - Conversation history

**Automatic Memory Lifecycle:**
```python
# Memory automatically flows through tiers
# Working → Core → Archival based on usage and importance

# Before Clone/Teleport, explicitly commit working memory
await tiered_memory.commit_all()  # Persists all in-memory data
await clone_manager.clone(agent_id, "new-agent")
```

### 🏗️ Storage Architecture

```
+-----------------------------------------------------------------------------+
|                     Recordor Memory Adapter                                |
+-----------------------------------------------------------------------------+
|                                                                              |
|  +-----------+ +-----------+ +-----------+ +------------+ +---------------+ |
|  | LangChain | |  AutoGen  | |  CrewAI   | | LlamaIndex | | Azure AI      | |
|  | /LangGraph| |  /MS Agent| |  Adapter  | |   Adapter  | | Foundry       | |
|  +-----+-----+ +-----+-----+ +-----+-----+ +-----+------+ +-------+-------+ |
|        |             |             |             |                 |         |
|        +-------------+-------------+-------------+-----------------+         |
|                                    |                                         |
|                           +--------v--------+                                |
|                           |   Unified API   |                                |
|                           | Memory Manager  |                                |
|                           +--------+--------+                                |
|                                    |                                         |
|               +--------------------+--------------------+                    |
|               |                    |                    |                    |
|         +-----v-----+        +-----v-----+        +-----v-----+             |
|         |  Weaviate |        |   Redis   |        |PostgreSQL |             |
|         |  (Vector) |        |  (Cache)  |        | +PGVector |             |
|         +-----+-----+        +-----+-----+        +-----+-----+             |
|               |                    |                    |                    |
|               +--------------------+--------------------+                    |
|                                    |                                         |
|                           +--------v--------+                                |
|                           | Azure NetApp    |                                |
|                           |    Files        |                                |
|                           |  NFS/SMB/S3-compliant |                           |
|                           +-----------------+                                |
+-----------------------------------------------------------------------------+
```

### ⚠️ Critical: NFS/SMB Compatibility
**All Recordor backends use client-server architecture**, fully compatible with Azure NetApp Files.

### 🧠 Memory Versioning

```
Agent Timeline:

-----*-------*-------*-------*-------*-------*-------->
     |       |       |       |       |       |
     v1.0    v1.1    v1.2    v1.3    v1.4    v1.5  (current)
     |       |       |       |       |       |
  Snapshot Snapshot Snapshot Clone  Snapshot Snapshot
                            |
                     +------v------+
                     | Test Clone  |
                     | (isolated)  |
                     +-------------+

Use Cases:
- Agent aging analysis: Compare behavior at v1.0 vs v1.5
- Personality drift detection: How memory affects behavior
- Regression testing: Does new training improve or degrade?
- Disaster recovery: Restore agent to known-good state
```

### 📦 New Files Added

#### Framework Adapters (`src/adapters/`)
| File | Description |
|------|-------------|
| `base_memory_adapter.py` | Abstract base with `RecordorMemory`, `MemoryEntry`, `MemorySnapshot` |
| `langchain_adapter.py` | LangChain/LangGraph with BaseMemory support |
| `autogen_adapter.py` | AutoGen Memory Bank pattern |
| `crewai_adapter.py` | CrewAI STM/LTM/Entity memory replacement |
| `llamaindex_adapter.py` | LlamaIndex chat and document memory |
| `microsoft_agent_framework_adapter.py` | MS Agent Framework IStorage implementation |
| `azure_ai_foundry_adapter.py` | Azure AI Foundry memory stores and threads |

#### Storage Backends (`src/backends/`)
| File | Description |
|------|-------------|
| `weaviate_backend.py` | Production Weaviate with vector search, HNSW indexing |
| `postgresql_backend.py` | PostgreSQL + PGVector with HNSW, ACID transactions |
| `redis_backend.py` | Redis cache for working memory, session state, pub/sub |

#### Advanced Memory Modules (`src/memory/`) - Mem0/MemGPT/LangMem-Inspired
| File | Description |
|------|-------------|
| `smart_extractor.py` | LLM-based fact extraction with ADD/UPDATE/DELETE/NONE operations |
| `memory_graph.py` | Entity/relationship extraction using Weaviate cross-references |
| `procedural_memory.py` | Skills, workflows, and strategies storage with execution tracking |
| `shared_memory.py` | Multi-agent coordination with scoped access and pub/sub |
| `memory_history.py` | Complete audit trail with time-travel and rollback |
| `tiered_memory.py` | Core/Archival memory tiers with automatic eviction (MemGPT/Letta) |
| `prompt_optimizer.py` | Learn from feedback to improve prompts (LangMem pattern) |
| `memory_consolidation.py` | Automatic deduplication, merging, and compression |
| `memory_tools.py` | Agent-callable tools for self-editing memory (OpenAI/Anthropic/LangChain) |

#### Proactive Memory Modules (`src/proactive/`) - OpenClaw/MemU-Inspired
| File | Description |
|------|-------------|
| `heartbeat.py` | Scheduled autonomous monitoring with cron-like tasks |
| `anticipation.py` | Context pre-loading based on predicted agent needs |
| `auto_inject.py` | Automatic memory injection before every LLM call |
| `pre_compaction.py` | Save important facts before context window compaction |
| `resource_monitor.py` | Background pattern detection and alerting |

### 🧠 Advanced Memory Features (Mem0-Inspired)

Recordor now includes advanced memory capabilities inspired by [Mem0](https://github.com/mem0ai/mem0) and other AI agent memory research:

#### Smart Memory Extraction
```python
from recordor.memory import SmartMemoryExtractor, MemoryOperation

# Create extractor with LLM-based fact extraction
extractor = SmartMemoryExtractor(llm_provider="openai", api_key="...")

# Extract facts from conversation
updates = await extractor.process(
    text="User mentioned they prefer Python for data science and work at Acme Corp",
    existing_memories=[]
)

for update in updates:
    if update.operation == MemoryOperation.ADD:
        print(f"New fact: {update.fact.content} (confidence: {update.fact.confidence})")
```

#### Memory Graph (Entity/Relationship)
```python
from recordor.memory import MemoryGraph

# Create graph for entity/relationship tracking
graph = MemoryGraph(llm_provider="openai", api_key="...")

# Extract and store entities/relationships
entities, relationships = await graph.extract_and_store(
    text="Alice works at Acme Corp with Bob. They use Python for data analysis.",
    agent_id="my-agent"
)

# Find path between entities
path = await graph.find_path("Alice", "Python", "my-agent")
```

#### Procedural Memory (Skills/Workflows)
```python
from recordor.memory import ProceduralMemory, ProcedureType, ProcedureStep

memory = ProceduralMemory(llm_provider="openai", api_key="...")

# Store a skill
skill = await memory.create_procedure(
    name="data_analysis",
    description="Analyze data and generate insights",
    procedure_type=ProcedureType.SKILL,
    steps=[
        ProcedureStep(order=1, action="load_data", tool="pandas"),
        ProcedureStep(order=2, action="clean_data", tool="pandas"),
        ProcedureStep(order=3, action="analyze", tool="numpy"),
    ],
    agent_id="my-agent"
)

# Learn from execution trajectory
learned = await memory.learn_from_trajectory(
    task_description="Process customer feedback",
    execution_log=[...],
    agent_id="my-agent"
)
```

#### Multi-Agent Shared Memory
```python
from recordor.memory import SharedMemoryPool, MemoryScope

pool = SharedMemoryPool(project_id="my-project")

# Agent 1 writes to shared memory
pool.register_agent("agent-1", team_id="research")
await pool.set(
    key="task_status",
    value={"progress": 0.5},
    agent_id="agent-1",
    scope=MemoryScope.TEAM
)

# Agent 2 reads from shared memory
pool.register_agent("agent-2", team_id="research")
status = await pool.get("task_status", agent_id="agent-2")

# Subscribe to updates
async for event in pool.subscribe(agent_id="agent-2"):
    print(f"Memory updated: {event.memory_key}")
```

#### Memory History (Audit Trail)
```python
from recordor.memory import MemoryHistory, OperationType

history = MemoryHistory()

# Record operations
await history.record(
    memory_id="mem-123",
    agent_id="agent-1",
    operation=OperationType.UPDATE,
    old_value={"key": "old"},
    new_value={"key": "new"}
)

# Time-travel: get value at specific time
value = await history.get_value_at("mem-123", datetime(2025, 1, 15))

# Rollback to previous version
await history.rollback("mem-123", version=3)
```

#### Tiered Memory (MemGPT/Letta Pattern)
```python
from recordor.memory import TieredMemoryManager, EvictionPolicy

# Create tiered memory with automatic context management
manager = TieredMemoryManager(
    agent_id="my-agent",
    max_context_tokens=8000,
    eviction_policy=EvictionPolicy.IMPORTANCE
)

# Set persona (always in context)
await manager.set_persona("You are a helpful data analyst...")
await manager.set_user_info("User works at Acme Corp, prefers Python")

# Add to core memory (evicts low-importance if full)
await manager.add_to_core(
    name="current_task",
    content="Analyzing Q4 sales data",
    importance=0.9
)

# Search archival memory
results = await manager.search_archival("previous analysis methods")

# Get context window for LLM
context = await manager.get_context_window()
messages = context.get_messages()
```

#### Prompt Optimizer (LangMem Pattern)
```python
from recordor.memory import PromptOptimizer, FeedbackType

optimizer = PromptOptimizer(
    agent_id="my-agent",
    llm_provider="openai",
    api_key="..."
)

# Set base prompt and rules
await optimizer.set_base_prompt("You are a helpful assistant...")
await optimizer.add_rule("Always be concise", category="behavior", priority=2)

# Record feedback
await optimizer.record_feedback(
    feedback_type=FeedbackType.POSITIVE,
    user_message="What's the weather?",
    agent_response="Sunny, 72°F.",
    session_id="session-123"
)

# Analyze and get suggestions
suggestions = await optimizer.analyze_feedback()
await optimizer.apply_suggestion(suggestions[0].id)

# Get optimized prompt
prompt = await optimizer.get_current_prompt()
```

#### Memory Consolidation
```python
from recordor.memory import MemoryConsolidator, ConsolidationStrategy

consolidator = MemoryConsolidator(
    llm_provider="openai",
    similarity_threshold=0.85
)

# Find and merge similar memories
result = await consolidator.consolidate(
    memories=memory_list,
    strategy=ConsolidationStrategy.MERGE
)
print(f"Compression ratio: {result.compression_ratio:.2f}")

# Deduplicate memories
keep_ids, remove_ids = await consolidator.deduplicate(memory_list)

# Apply importance decay to old memories
await consolidator.apply_decay(memories, older_than_days=7)
```

#### Memory Tools (Agent Self-Editing)
```python
from recordor.memory import MemoryToolkit, ToolFormat

toolkit = MemoryToolkit(
    agent_id="my-agent",
    tiered_memory=manager,  # Connect to tiered memory
    memory_graph=graph       # Connect to memory graph
)

# Get tools in OpenAI format for function calling
tools = toolkit.get_tools(format=ToolFormat.OPENAI)

# Execute a tool call from LLM
result = await toolkit.execute(
    tool_name="core_memory_append",
    arguments={"key": "user_preferences", "content": "Prefers dark mode"}
)

# Use with LangChain
langchain_tools = toolkit.as_langchain_tools()
```

### 🔮 Proactive Memory Features (OpenClaw/MemU-Inspired)

Recordor introduces a **proactive memory paradigm** — agents don't just respond to explicit memory requests, they **anticipate needs and act autonomously**:

#### HeartbeatEngine (Scheduled Autonomous Monitoring)
```python
from recordor.proactive import HeartbeatEngine, HeartbeatConfig, HeartbeatTask, TaskSchedule

# Create heartbeat engine for autonomous monitoring
engine = HeartbeatEngine(
    config=HeartbeatConfig(
        enable_memory_health_check=True,
        enable_outstanding_tasks_review=True,
        memory_health_interval_seconds=300  # Every 5 minutes
    ),
    memory_manager=memory_manager
)

# Start autonomous monitoring
await engine.start()

# Register custom heartbeat tasks
engine.register_task(HeartbeatTask(
    name="calendar_check",
    description="Check upcoming meetings for context preloading",
    schedule=TaskSchedule(interval_seconds=600),
    handler=my_calendar_handler
))
```

#### AnticipationEngine (Context Pre-Loading)
```python
from recordor.proactive import AnticipationEngine, AnticipationConfig

# Create anticipation engine
engine = AnticipationEngine(
    memory_manager=memory_manager,
    config=AnticipationConfig(min_confidence=0.6)
)

# Anticipate context based on current activity
context = await engine.anticipate(
    current_activity="preparing for meeting with John",
    agent_id="agent-001"
)

# Context is preloaded before agent even asks!
print(f"Preloaded {len(context.preloaded_memories)} memories")
# → John's preferences, past meetings, action items
```

#### AutoContextInjector (No Tool Calls Needed)
```python
from recordor.proactive import AutoContextInjector, InjectionConfig

# Create injector - memories automatically appear in prompts
injector = AutoContextInjector(
    memory_manager=memory_manager,
    config=InjectionConfig(
        max_injection_tokens=500,  # Token budget
        default_strategy=InjectionStrategy.HYBRID
    )
)

# Before sending to LLM, enrich the prompt
enriched_prompt = await injector.enrich_prompt(
    original_prompt="What did John say about the project?",
    agent_id="agent-001"
)
# → Prompt now contains relevant John/project memories automatically!
```

#### PreCompactionSaver (Save Before Context Fills)
```python
from recordor.proactive import PreCompactionSaver, CompactionConfig

# Create pre-compaction saver
saver = PreCompactionSaver(
    memory_manager=memory_manager,
    config=CompactionConfig(
        compaction_threshold=0.75,  # Save when 75% full
        extract_facts=True,
        extract_commitments=True
    )
)

# Automatically monitor and save before compaction
await saver.start_monitoring(agent_id="agent-001")

# Or manually trigger before LLM compaction
event = await saver.save_before_compaction(
    context_tokens=6000,
    max_context_tokens=8000,
    agent_id="agent-001",
    context_content=conversation_text
)
print(f"Saved {event.memories_saved} important facts before compaction")
```

#### ResourceMonitor (Pattern Detection & Alerting)
```python
from recordor.proactive import ResourceMonitor, MonitorConfig, AlertType

# Create resource monitor
monitor = ResourceMonitor(
    memory_manager=memory_manager,
    config=MonitorConfig(
        storage_warning_threshold=0.80,
        read_latency_warning_ms=100.0,
        pattern_detection_enabled=True
    )
)

# Register alert handlers
monitor.on_alert(AlertType.HIGH_LATENCY, async_latency_handler)
monitor.on_alert(AlertType.STORAGE_WARNING, async_storage_handler)

# Start monitoring
await monitor.start()

# Get detected patterns for optimization
patterns = monitor.get_patterns(agent_id="agent-001")
for pattern in patterns:
    print(f"{pattern.description}: {pattern.recommendations}")
```

### 🚀 Quick Start with New Adapters

#### LangChain Integration
```python
from recordor.adapters import LangChainMemoryAdapter

memory = LangChainMemoryAdapter(
    anf_config={
        "account_name": "recordor-prod-anf",
        "pool_name": "premium-pool",
        "volume_name": "langchain-memory"
    }
)

# Use with LangChain
chain = ConversationChain(llm=llm, memory=memory.as_langchain_memory())

# Snapshot agent state for versioning
await memory.snapshot("my-agent", "before-update-v1")
```

#### LlamaIndex Integration
```python
from recordor.adapters import LlamaIndexAdapter

adapter = LlamaIndexAdapter(
    agent_id="rag-agent",
    anf_config={"account_name": "recordor-prod-anf", ...}
)
await adapter.initialize()

# Store and search documents for RAG
await adapter.store_document(text="Policy document...", metadata={"source": "policy.pdf"})
results = await adapter.search_documents(query="vacation policy", k=5)
```

#### Azure AI Foundry Integration
```python
from recordor.adapters import AzureAIFoundryAdapter

adapter = AzureAIFoundryAdapter(
    project_name="customer-service-ai",
    anf_config={"account_name": "recordor-prod-anf", ...}
)
await adapter.initialize()

# Create memory store (matches Foundry patterns)
preferences_store = adapter.create_memory_store("user-preferences", scope="user")

# Add and search memories
await preferences_store.add_memory(content="User prefers email", user_id="user-123")
results = await preferences_store.search(query="notification preferences", user_id="user-123")
```

### 🔬 Key Research Findings (January 2026)

1. **ANF Object REST API** - S3-compatible access to ANF data (file/object duality)
2. **Weaviate on ANF** - Microsoft-benchmarked, 30Ti PVC, Ultra storage class
3. **Microsoft Agent Framework** - Merged Semantic Kernel + AutoGen, Apache 2.0
4. **Mem0 Architecture** - LLM-driven fact extraction, two-phase pipeline (Extract + Update), 26% accuracy improvement
5. **Zep/Graphiti** - Bi-temporal knowledge graphs, 94.8% temporal reasoning accuracy
6. **Multi-Agent Memory** - Research shows 15x token usage, shared memory essential for coordination
7. **Procedural Memory** - Case-based (trajectories), Strategy-based (workflows), Skill-based (executable)
8. **Letta/MemGPT** - Core memory (in-context) + Archival memory (out-of-context), self-editing memory
9. **LangMem SDK** - Semantic, Episodic, Procedural memory types with LangGraph integration
10. **Azure AI Foundry** - Managed agent service with native memory (Public Preview)
11. **ANF Flexible Service Level** - Up to 12.8 Gbps throughput, 10-40% cost savings

### 📊 Recordor vs Other Memory Frameworks

| Feature | Recordor | Mem0 | Letta/MemGPT | LangMem | Zep |
|---------|------------|------|--------------|---------|-----|
| **Storage Backend** | ANF (Enterprise NFS) | SQLite/Postgres | SQLite/Postgres | In-Memory/Custom | Cloud/Self-hosted |
| **NFS Compatible** | ✅ Yes | ❌ SQLite fails | ❌ SQLite fails | ✅ Configurable | ⚠️ Depends |
| **Fact Extraction** | ✅ LLM-based | ✅ LLM-based | ⚠️ Manual | ✅ LLM-based | ✅ LLM-based |
| **Memory Graph** | ✅ Weaviate | ✅ Neo4j | ❌ No | ❌ No | ✅ Graph |
| **Procedural Memory** | ✅ Skills/Workflows | ❌ No | ❌ No | ✅ Prompt updates | ❌ No |
| **Multi-Agent** | ✅ Shared pools | ⚠️ Limited | ❌ No | ❌ No | ❌ No |
| **Time-Travel** | ✅ ANF Snapshots | ❌ No | ❌ No | ❌ No | ⚠️ Limited |
| **Audit Trail** | ✅ Complete | ⚠️ Basic history | ❌ No | ❌ No | ⚠️ Limited |
| **Framework Support** | 7 frameworks | 4 frameworks | 2 frameworks | 1 framework | 3 frameworks |
| **Enterprise Storage** | ✅ ANF | ❌ No | ❌ No | ❌ No | ❌ No |

### 🎯 Why Recordor? Key Differentiators

Recordor stands apart from other AI memory solutions. Here's why:

#### 🏆 Most Comprehensive Memory System

Recordor is the **only solution that combines all major memory paradigms** in a single platform:

| Memory Paradigm | Source Inspiration | Recordor Implementation |
|-----------------|-------------------|---------------------------|
| **LLM-based Fact Extraction** | Mem0 | `SmartMemoryExtractor` with ADD/UPDATE/DELETE/NONE |
| **Entity/Relationship Graphs** | Mem0g, Zep/Graphiti | `MemoryGraph` with bi-temporal relationships |
| **Tiered Context Management** | MemGPT/Letta | `TieredMemoryManager` with Core/Archival tiers |
| **Feedback-based Optimization** | LangMem SDK | `PromptOptimizer` that learns from interactions |
| **Procedural Memory** | Academic research | `ProceduralMemory` for skills/workflows/strategies |
| **Multi-Agent Coordination** | Industry need | `SharedMemoryPool` with scoped access control |
| **Memory Consolidation** | Cognitive science | `MemoryConsolidator` for deduplication and merging |
| **Agent Self-Editing** | MemGPT/Letta | `MemoryToolkit` for OpenAI/Anthropic/LangChain |

**Other solutions implement 1-3 of these. Recordor implements all 8.**

#### 🔌 Broadest Framework Support

| Framework | Recordor | Mem0 | Letta | LangMem | Zep |
|-----------|------------|------|-------|---------|-----|
| LangChain/LangGraph | ✅ | ✅ | ✅ | ✅ | ✅ |
| AutoGen | ✅ | ✅ | ❌ | ❌ | ❌ |
| CrewAI | ✅ | ✅ | ❌ | ❌ | ✅ |
| LlamaIndex | ✅ | ❌ | ❌ | ❌ | ❌ |
| MS Agent Framework | ✅ | ❌ | ❌ | ❌ | ❌ |
| Azure AI Foundry | ✅ | ❌ | ❌ | ❌ | ❌ |
| NVIDIA NIM/NeMo | ✅ | ❌ | ❌ | ❌ | ❌ |
| **Total** | **7** | **3** | **1** | **1** | **2** |

#### 🏢 Enterprise-Grade Storage (Unique)

Recordor is the **only AI memory solution built on enterprise storage infrastructure**:

| Capability | Recordor (ANF) | Competitors |
|------------|------------------|-------------|
| **Latency** | <0.1ms (Ultra tier) | 10-100ms typical |
| **Throughput** | Up to 12.8 Gbps | Limited by cloud DB |
| **Snapshots** | Instant, space-efficient | Manual backups |
| **Cloning** | Writable copies for A/B testing | Not available |
| **Cross-Region DR** | SnapMirror replication | Custom implementation |
| **NFS/SMB/S3 Access** | All three protocols | Usually one |
| **Compliance** | HIPAA, SOC2, FedRAMP | Varies |

**Why this matters**: Enterprise AI deployments need reliability, compliance, and performance that cloud-native databases alone can't provide.

#### ⏰ Memory Versioning via Snapshots

**Unique capability**: Use storage-level snapshots for agent memory versioning.

```
Agent Timeline with Snapshots:
─────*───────*───────*───────*───────*───────*────────>