Download the PHP package mauricioperera/php-agent-memory without Composer

PHPAgentMemory

Agentic memory system for AI agents — built on php-vector-store. Zero external dependencies beyond php-vector-store itself.

Inspired by RepoMemory's philosophy: save, search, recall, and consolidate knowledge — but pragmatic PHP instead of Git-like versioning.

Why

AI agents lose context between sessions. PHPAgentMemory gives them persistent, searchable memory with:

• 3 entity types: memories (what happened), skills (how to do things), knowledge (facts about the world)
• Hybrid search: vector similarity + BM25 full-text, fused with RRF
• Matryoshka progressive search: 128d→384d→768d — 5.6x faster than brute force at 5K vectors
• Recall engine: pools all collections, ranks by score, formats as context
• Dream cycle: 4-phase AI consolidation — orient, analyze, consolidate, verify — the agent "sleeps" and wakes up with cleaner memory
• Neuron AI integration: 4 adapters (VectorStore, Toolkit, Retrieval, PreProcessor)
• HTTP API: REST server with Bearer auth, ready for any agent framework
• Zero dependencies: only PHP 8.1+ and php-vector-store

Quick Start

As PHP Library

As HTTP API

Architecture

The Dream Cycle

The dream is a 4-phase reflective pass over the agent's memory — like how the brain consolidates memories during sleep.

Usage

What the LLM Does During the Dream

Given these 14 memories:

Result: 14 memories → 7 memories. Same knowledge, less noise.

Programmatic Access to the Report

Or Use the Low-Level Pipeline Directly

Entity Types

Memory

What happened — scoped by agentId + userId.

Skill

How to do things — scoped by agentId only (no userId).

Knowledge

Facts about the world — scoped by agentId only.

Scoping Model

Entities are isolated by scope using php-vector-store collections:

The special agent ID _shared enables cross-agent shared skills and knowledge. The recall engine automatically searches both the agent's own collections and _shared.

Deduplication

Every saveOrUpdate() call:

1. Flushes pending writes
2. Runs hybrid search for similar existing entities
3. If score >= threshold (default 0.85): updates existing entity, merges tags
4. Otherwise: creates new entity

This prevents memory bloat from repeated saves of similar content.

Configuration

CloudflareLlmProvider (included)

Zero-dependency LLM provider using Cloudflare Workers AI:

Any Workers AI text generation model works. Recommended:

• @cf/ibm-granite/granite-4.0-h-micro — fastest, cheapest, good JSON output
• @cf/meta/llama-3.1-8b-instruct — better reasoning, slower

Custom LLM Provider

Neuron AI Integration

PHPAgentMemory integrates with Neuron AI — the PHP agentic framework. Four adapters give any Neuron agent persistent memory:

Option 1: Memory Tools (agent decides when to remember)

The toolkit exposes 4 tools the LLM can call:

• memory_save — Save facts, decisions, preferences, corrections
• memory_recall — Multi-collection recall (memories + skills + knowledge)
• memory_search — Search a specific collection
• memory_store_skill — Save reusable procedures

Option 2: VectorStore Adapter (for RAG pipelines)

Option 3: Memory Retrieval (replaces default retrieval)

Option 4: PreProcessor (automatic context injection)

Combining Everything

HTTP API Reference

Auth: Authorization: Bearer <token> (timing-safe comparison). /health is public. CORS: Configurable via --cors-origin (default *).

Benchmarks

Tested with AG News dataset and Cloudflare EmbeddingGemma-300m (768d Matryoshka, Int8 quantized).

Search Performance

Dream Performance

Other Metrics

Embedding Providers

PHPAgentMemory is embedding-agnostic — you pass pre-computed vectors to every save() and search() call. Use any provider:

Cloudflare Workers AI (free)

OpenAI

Ollama (local)

Storage Format

Testing

Project Structure

RepoMemory Comparison

PHPAgentMemory trades RepoMemory's Git-like versioning for simplicity. No commit chains, no tombstones, no audit log — just vectors, metadata, and soft-deletes. The core value (save, search, recall, dream) is preserved.

License

MIT