Agent Memory

# AgentMemory Skill

Persistent memory system for AI agents. Remember facts, learn from experience, and track entities across sessions.

## Installation

```bash
clawdhub install agent-memory
```

## Usage

```python
from src.memory import AgentMemory

mem = AgentMemory()

# Remember facts
mem.remember("Important information", tags=["category"])

# Learn from experience
mem.learn(
    action="What was done",
    context="situation",
    outcome="positive",  # or "negative"
    insight="What was learned"
)

# Recall memories
facts = mem.recall("search query")
lessons = mem.get_lessons(context="topic")

# Track entities
mem.track_entity("Name", "person", {"role": "engineer"})
```

## When to Use

- **Starting a session**: Load relevant context from memory
- **After conversations**: Store important facts
- **After failures**: Record lessons learned
- **Meeting new people/projects**: Track as entities

## Integration with Clawdbot

Add to your AGENTS.md or HEARTBEAT.md:

```markdown
## Memory Protocol

On session start:
1. Load recent lessons: `mem.get_lessons(limit=5)`
2. Check entity context for current task
3. Recall relevant facts

On session end:
1. Extract durable facts from conversation
2. Record any lessons learned
3. Update entity information
```

## Database Location

Default: `~/.agent-memory/memory.db`

Custom: `AgentMemory(db_path="/path/to/memory.db")`

# 🧠 AgentMemory

**Persistent Memory for AI Agents**

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![ClawdHub](https://img.shields.io/badge/ClawdHub-compatible-purple.svg)](https://clawdhub.com)

Every AI agent session starts fresh. We forget learnings, repeat mistakes, and lose context. **AgentMemory** solves this.

Built for [OpenClaw](https://github.com/openclaw/openclaw) and [Clawdbot](https://github.com/clawdbot/clawdbot) agents, but works with any LLM-powered system.

## ✨ Features

- **📝 Facts** - Store and recall information across sessions
- **🎓 Lessons** - Learn from successes and failures
- **👤 Entities** - Track people, projects, and preferences
- **🔍 Semantic Search** - Find relevant memories fast (FTS5)
- **🧹 Auto-cleanup** - Forget stale information automatically
- **📦 Zero Dependencies** - Just Python + SQLite

## 🚀 Quick Start

```python
from agent_memory import AgentMemory

# Initialize (creates ~/.agent-memory/memory.db)
mem = AgentMemory()

# Remember facts
mem.remember("Boss prefers brief status updates", tags=["preference", "communication"])
mem.remember("API rate limit is 100 req/min", tags=["technical", "api"])

# Learn from experience
mem.learn(
    action="Used RSI momentum strategy for crypto trading",
    context="trading",
    outcome="negative", 
    insight="RSI alone is insufficient, need confirmation signals"
)

# Track entities
mem.track_entity("Alex", "person", {
    "role": "boss",
    "timezone": "America/New_York",
    "communication_style": "brief and direct"
})

# Recall relevant memories
facts = mem.recall("how does boss like updates?")
# → Returns facts about boss preferences

lessons = mem.get_lessons(context="trading", outcome="negative")
# → Returns failed trading lessons to avoid repeating mistakes

# Stats
print(mem.stats())
# → {'active_facts': 42...