Agent Memory

A five-layer memory system for AI agents. Gives agents persistent, searchable, structured memory that improves over time.

Also available as a Moltbot Skill — drop into any OpenClaw agent.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    Memory System Architecture                    │
├─────────────────┬─────────────────┬─────────────────────────────┤
│ Layer           │ Storage         │ Purpose                     │
├─────────────────┼─────────────────┼─────────────────────────────┤
│ Episodic        │ Markdown+Qdrant │ Conversation logs           │
│ Semantic        │ Qdrant          │ Similarity search           │
│ Knowledge Graph │ FalkorDBLite    │ Entities & relationships    │
│ Procedural      │ heuristics.md   │ Learned rules               │
│ Meta-Cognition  │ JSONL stats     │ Self-improvement tracking   │
└─────────────────┴─────────────────┴─────────────────────────────┘

Data Flow

Conversation → Episode logged → Chunked → Embedded (Ollama) → Indexed (Qdrant)
                    │
                    ├──→ Entity extraction → Knowledge Graph (FalkorDB)
                    │
                    └──→ Implicit feedback → Lessons → Heuristics

Layers Explained

1. Episodic Memory

Raw conversation logs with timestamps, participants, and topics. The "what happened" layer.

2. Semantic Memory

Vector embeddings of all memory content for similarity search. "Find memories related to X."

3. Knowledge Graph

Structured entities (people, places, concepts) and their relationships with bi-temporal tracking:

• Valid time: When the fact was true in the real world
• Transaction time: When the agent learned the fact

4. Procedural Memory

Learned rules and heuristics from successes and failures. "Don't do X because Y happened."

5. Meta-Cognition

Tracks retrieval quality for self-improvement. "Did I find the right memory? How can I do better?"

Quick Start

# Install
pip install agent-memory

# Or run from source
git clone https://github.com/pipaitrader/agent-memory
cd agent-memory
pip install -e .

# Initialize memory system
agent-memory init

# Log an episode
agent-memory log "Had a conversation with Andy about trading strategies"

# Search memories
agent-memory search "trading strategies"

# Add a heuristic
agent-memory learn "Always verify stop losses manually - automated ones may fail"

# Query knowledge graph
agent-memory graph query "What do I know about Andy?"

Configuration

# config.yaml
memory:
  episodic:
    path: ./memory/episodes
  semantic:
    backend: qdrant  # or chromadb, pinecone
    embedding_model: ollama/nomic-embed-text
  graph:
    backend: falkordb  # or neo4j, memgraph
  procedural:
    path: ./memory/heuristics.md
  metacognition:
    path: ./memory/stats.jsonl

Requirements

• Python 3.10+
• Ollama (for embeddings) or OpenAI API key
• Qdrant (vector store) - can run locally via Docker
• FalkorDBLite (graph store) - embedded, no setup needed

Roadmap

• Project structure
• Episodic layer (markdown logging)
• Procedural layer (heuristics.md)
• Semantic layer (Qdrant integration)
• Knowledge graph (FalkorDBLite)
• Meta-cognition tracking
• CLI tool
• Python SDK
• MCP server integration

Contributing

PRs welcome! See CONTRIBUTING.md.

License

MIT

---

Built by @pipaitrader 🎯