PHPackages                             tivins/llm-memory - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. tivins/llm-memory

ActiveLibrary[Database & ORM](/categories/database)

tivins/llm-memory
=================

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

0.4.0(1mo ago)06↓50%MITPHP ^8.3

Since Jun 21Compare

[ Source](https://github.com/tivins/llm-memory)[ Packagist](https://packagist.org/packages/tivins/llm-memory)[ RSS](/packages/tivins-llm-memory/feed)WikiDiscussions Synced 2w ago

READMEChangelogDependencies (4)Versions (4)Used By (0)

tivins/llm-memory
=================

[](#tivinsllm-memory)

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

Overview
--------

[](#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
------------

[](#requirements)

- PHP 8.3+
- PostgreSQL with [pgvector](https://github.com/pgvector/pgvector)
- [llama.cpp](https://github.com/ggml-org/llama.cpp) embedding server (port 8081, e.g. `bge-m3`)
- [llama.cpp](https://github.com/ggml-org/llama.cpp) rerank server (port 8082, e.g. `Qwen3-Reranker`) — optional

Installation
------------

[](#installation)

```
composer require tivins/llm-memory
```

Quick start
-----------

[](#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->forgetInCollection('user:42', $entryId);
$memory->forgetCollection('user:42');
```

Agent integration
-----------------

[](#agent-integration)

Wire memory tools into an [llm-lib](https://github.com/tivins/llm-lib) agent:

```
use Tivins\LlmLib\Agent;
use Tivins\LlmLib\ToolRegistry;
use Tivins\LlmMemory\Tools\MemoryTools;

$memoryTools = new MemoryTools($memory, collection: 'user:42');
$agent = new Agent($chatLlm, new ToolRegistry(...$memoryTools->all()));

$result = $agent->runTurn($conversation, $options);
```

Collections are typically namespaced (`user:{id}`, `{app}:{scope}`). See `examples/agent.php` for a full runnable demo.

API
---

[](#api)

MethodDescription`ensureCollection(id, model, dim)`Create a collection if it doesn't exist`remember(collection, content, kind?, metadata?)`Store a text fragment (embeds automatically, deduplicates)`rememberMany(collection, items)`Batch store — one embedding call for N fragments`recall(collection, query, topN?, annTopK?, minRerankScore?)`Retrieve relevant entries (ANN + optional rerank)`recallAnnOnly(collection, query, topN?)`ANN search only — skips rerank even when a reranker is configured`listEntries(collection, limit?, offset?, idFrom?, idTo?)`List entries (latest N or ID range)`getById(id)`Fetch a single entry by ID`forget(id)`Soft-delete a single entry (any collection)`forgetInCollection(collection, id)`Soft-delete within a collection; returns `false` if not found`forgetCollection(id)`Soft-delete all entries in a collection`count(collection)`Count active entries in a collection`migrate()`Run SQL migrationsTesting
-------

[](#testing)

```
composer test
```

Integration tests require PostgreSQL with pgvector (see `install.md`). Unit tests for DTOs run without a database. Embedding/rerank calls use `StubLLM` from llm-lib — no llama.cpp server needed.

Dependencies
------------

[](#dependencies)

PackageRole[tivins/llm-lib](https://github.com/tivins/llm-lib)Embedding & rerank HTTP clients[tivins/pdow](https://github.com/tivins/pdow)PDO database wrapperLicense
-------

[](#license)

MIT.

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance90

Actively maintained with recent releases

Popularity6

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

45d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/13aae62b30274178dfd8d18ce4b6bee1a7d7bcbc9db17c2d22b2be5c7b51edc4?d=identicon)[Tivins](/maintainers/Tivins)

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/tivins-llm-memory/health.svg)

```
[![Health](https://phpackages.com/badges/tivins-llm-memory/health.svg)](https://phpackages.com/packages/tivins-llm-memory)
```

###  Alternatives

[jdorn/sql-formatter

a PHP SQL highlighting library

3.8k117.8M121](/packages/jdorn-sql-formatter)[propel/propel1

Propel is an open-source Object-Relational Mapping (ORM) for PHP5.

8351.6M87](/packages/propel-propel1)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)