PHPackages                             clarion-app/llm-client - 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. [API Development](/categories/api)
4. /
5. clarion-app/llm-client

ActiveLibrary[API Development](/categories/api)

clarion-app/llm-client
======================

Handles interactions with Large Language Models

052PHP

Since Mar 31Pushed 1mo ago1 watchersCompare

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

READMEChangelogDependenciesVersions (11)Used By (0)

clarion-app/llm-client
======================

[](#clarion-appllm-client)

Memory Scopes
-------------

[](#memory-scopes)

The package provides four memory scopes for agents:

ScopeTableRetentionEvictionEntry CapScratch—Cleared per turnN/AN/AShort-term—Cleared on conversation endN/AN/ALong-term`llm_memory_entries`PermanentLRU evictionConfigurable capEpisodic`episodic_memories`Configurable (`retention_days`)Time-based cleanupNone**Declarative**`declarative_memories`**Permanent****None****None**### Declarative Memory (Permanent Facts, Preferences, Rules)

[](#declarative-memory-permanent-facts-preferences-rules)

The declarative scope stores explicit user-created facts, preferences, and behavioral rules that must be reliably available in every conversation. Unlike long-term (LRU-evicted) and episodic (time-expiring) scopes, declarative entries are **permanent by design**:

- **No retention config** — no `retention_days`, no expiration
- **No eviction** — no LRU, no cleanup command, no scheduled task
- **No entry cap** — deliberately unbounded (user-managed, expected to stay small)
- **Strict per-user scoping** — no cross-user access, no admin override
- **Confirmation gate** — agent-sourced writes require explicit user confirmation before persistence
- **Semantic conflict detection** — reworded restatements supersede existing entries in place
- **Immediate edit/delete** — edits and deletes take effect in the same and all later conversations

Entries record a `type` (`fact` | `preference` | `rule`) and `source` (provenance: `user_stated` | `agent_learned`).

#### Learned Patterns and Confidence

[](#learned-patterns-and-confidence)

The store holds both user-stated entries and patterns learned on the user's behalf, in a single table (no parallel model). A learned pattern (`source = agent_learned`) carries a `confidence_level` — a nullable integer from 0 to 100 reflecting how much consistent evidence supports it:

- **`confidence_level` is `NULL` for user-stated entries** and set to 0–100 for learned patterns. Values outside 0–100 are rejected at the service layer.
- **User-stated always wins** — when a learned pattern semantically conflicts with a user-stated entry, the user-stated entry is never superseded. A higher-confidence learned pattern may supersede an older learned pattern; a lower-confidence one does not.
- **Editing a learned entry converts it** to `source = user_stated` and clears `confidence_level` to `NULL`.
- **Confidence is visible everywhere** — surfaced on recall, in every API response, and carried in the `ConfirmationRequiredException` payload so the confirmation prompt can show it.

`applyAgentWrite()` accepts an optional `$confidenceLevel` parameter; the confirmation gate still throws before any DB access when the write is not confirmed.

See `specs/041-declarative-memory-store/quickstart.md` for base API usage and `specs/046-learned-patterns-store/quickstart.md` for learned-pattern behavior verification.

Testing
-------

[](#testing)

### Test Suites

[](#test-suites)

The package maintains three test suites:

- **Unit** — Fast unit tests for individual classes.
- **Feature** — Feature-level tests with mocked dependencies.
- **Integration** — Assembled-system tests that exercise the full stack (container-resolved services, real database, scripted HTTP boundary) without mocks on `llm-client` classes.

### Running Tests

[](#running-tests)

```
# All suites
composer test

# Specific suite
./vendor/bin/phpunit --testsuite Integration

# Single test file
./vendor/bin/phpunit tests/Integration/ToolUseJourneyTest.php
```

### Integration Suite

[](#integration-suite)

The Integration suite verifies end-to-end behavior through the container-wired composition chain. One rule: **no mocks on `llm-client` classes** — the suite exercises real services through a scripted HTTP boundary. This catches wiring defects, missing service registrations, and integration failures that unit tests with mocks cannot detect.

###  Health Score

25

—

LowBetter than 35% of packages

Maintenance59

Moderate activity, may be stable

Popularity10

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity21

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

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.

### Community

Maintainers

![](https://www.gravatar.com/avatar/544de7b46960eb87f0f60bc59cb8bd4dccd2679622adf0c8ed82b75df9f65685?d=identicon)[timschwartz](/maintainers/timschwartz)

---

Top Contributors

[![timschwartz](https://avatars.githubusercontent.com/u/13080528?v=4)](https://github.com/timschwartz "timschwartz (72 commits)")

### Embed Badge

![Health badge](/badges/clarion-app-llm-client/health.svg)

```
[![Health](https://phpackages.com/badges/clarion-app-llm-client/health.svg)](https://phpackages.com/packages/clarion-app-llm-client)
```

###  Alternatives

[exsyst/swagger

A php library to manipulate Swagger specifications

35816.5M7](/packages/exsyst-swagger)[lucasdotvin/laravel-soulbscription

A straightforward interface to handle subscriptions and features consumption.

709209.3k](/packages/lucasdotvin-laravel-soulbscription)[pimax/fb-messenger-php

Facebook Messenger Bot PHP API

313188.5k2](/packages/pimax-fb-messenger-php)

PHPackages © 2026

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