README

Semantic memory store for LLM applications — embed, store, and recall text fragments via pgvector.

Overview

A PHP library that provides a RAG-style retrieval pipeline:

1. Store text fragments in PostgreSQL + pgvector with automatic embedding.
2. Recall relevant fragments using a two-stage pipeline: vector ANN search → cross-encoder reranking.
3. Deduplicate entries via SHA-256 content hashing per collection.

Requirements

• PHP 8.3+
• PostgreSQL with pgvector
• llama.cpp embedding server (port 8081, e.g. bge-m3)
• llama.cpp rerank server (port 8082, e.g. Qwen3-Reranker) — optional

Installation

composer require tivins/llm-memory

Quick start

use Tivins\LlmLib\LLM;
use Tivins\LlmMemory\MemoryStore;
use Tivins\Pdow\Database;

$db       = Database::connect('pgsql:host=127.0.0.1;dbname=memory_project', 'user', 'pass');
$embedder = new LLM('http://127.0.0.1:8081', defaultModel: 'bge-m3-Q8_0.gguf');
$reranker = new LLM('http://127.0.0.1:8082', defaultModel: 'Qwen3-Reranker-4B-Q4_K_M.gguf');

$memory = new MemoryStore($db, $embedder, $reranker);
$memory->migrate();
$memory->ensureCollection('user:42', 'bge-m3-Q8_0.gguf', 1024);

// Store
$memory->remember('user:42', 'Marie is allergic to peanuts.', kind: 'fact');

// Recall
$results = $memory->recall('user:42', 'What foods should Marie avoid?', topN: 3);

foreach ($results as $hit) {
    echo $hit->entry->content . ' (score: ' . $hit->rerankScore . ")\n";
}

// Forget
$memory->forget($entryId);
$memory->forgetCollection('user:42');

API

Dependencies

License

MIT.