PHPackages elephpantmemory/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. [Utility & Helpers](/categories/utility) 4. / 5. elephpantmemory/memory ActiveLibrary[Utility & Helpers](/categories/utility) elephpantmemory/memory ====================== An ultra-lightweight, zero-dependency local memory and context manager for AI chatbots. v1.0.0(today)00GPL-3.0-or-laterPHPPHP >=8.4 Since Jun 13Pushed todayCompare [ Source](https://github.com/rpnfernandes/ElePHPantMemory)[ Packagist](https://packagist.org/packages/elephpantmemory/memory)[ RSS](/packages/elephpantmemory-memory/feed)WikiDiscussions main Synced today READMEChangelog (1)DependenciesVersions (2)Used By (0) ElePHPantMemory 🐘💬 ================== [](#elephpantmemory-) [![Version](https://camo.githubusercontent.com/97f85f046265623c4b26076add9bcc55f9608152c20e78f07076369977c77d05/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d312e302e302d677265656e2e737667)](#)[![License: GPL v3](https://camo.githubusercontent.com/48bf9b56d44f38db53ce21294cf0b9487d0a3734ab3ba1fe4c69858ae20db2c1/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d47504c76332d626c75652e737667)](LICENSE)[![PHP Version](https://camo.githubusercontent.com/3a1b280ab7672f9ae08c93a083aa42ce8d0c82ff079314d77f5fea924e84927c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e342532422d3838393242462e737667)](https://www.php.net) An ultra-lightweight, zero-dependency local memory and context manager for AI chatbots. Written in pure, modern PHP 8.4+. *Gestor de memoria e contexto local para chatbots de IA, ultra leve e sem dependencias. Escrito em PHP 8.4+ puro e moderno.* --- 💡 The Problem / O Problema -------------------------- [](#-the-problem--o-problema) ### English [](#english) LLM APIs (OpenAI, Claude, Gemini) are **stateless** and **expensive**. To maintain a conversation, developers usually send the entire chat history back and forth. As conversations grow, token consumption skyrockets, API bills explode, and the AI starts to lose track of the core topic. ### Portugues (Portugal) [](#portugues-portugal) As APIs de IA sao **stateless** (nao guardam estado) e **caras**. Para manter uma conversa, os programadores enviam todo o historico para a API a cada nova mensagem. Conforme a conversa cresce, o consumo de tokens dispara, a fatura da API explode e a IA comeca a perder o fio à meada. --- 🚀 The Solution: How ElePHPantMemory Works / A Solucao ----------------------------------------------------- [](#-the-solution-how-elephpantmemory-works--a-solucao) ### English [](#english-1) ElePHPantMemory sits between your application and the AI API. It manages chat context using a two-tier architecture running entirely inside your host project's existing database: 1. **The Short-Term Memory:** Keeps only the most recent messages to maintain natural conversation flow. 2. **The Long-Term Fact Sheet:** Extracts and preserves permanent business facts (e.g., user preferences, order IDs, VAT numbers) in a dedicated local table, injecting them as system prompts. ### Portugues (Portugal) [](#portugues-portugal-1) O ElePHPantMemory funciona como um filtro inteligente entre a tua aplicacao e a API de IA. Ele gere o contexto usando uma arquitetura de duas camadas que corre inteiramente dentro da base de dados existente do teu projeto: 1. **Memoria de Curto Prazo:** Mantem apenas as mensagens mais recentes para garantir a fluidez natural da conversa. 2. **Ficha de Factos de Longo Prazo:** Extrai e preserva factos permanentes do negocio (ex: preferencias, IDs de encomendas, NIFs) numa tabela local, injetando-os como prompts de sistema. --- 📊 Features & Comparison / Carateristicas e Comparacao --------------------------------------------------------- [](#-features--comparison--carateristicas-e-comparacao) Feature / FuncionalidadeStandard AI Chat FlowWith ElePHPantMemory 🐘**API Token Costs** / *Custos de Tokens*📈 Increases exponentially📉 Flat and optimized**Memory Retention** / *Retencao de Memoria*❌ Forgets when context limits hitNever forgets core facts**Dependencies** / *Dependencias*📦 Heavy framework overhead❌ Zero (Vanilla PHP)**Database Setup** / *Configuracao de BD*⚙️ Requires external Vector DBReuses your active connection**GDPR Compliance** / *Pronto para RGPD*🛠️ Manual code required⚡ Automated local TTL purging--- 🛠️ Quick Start / Guia Rapido ---------------------------- [](#️-quick-start--guia-rapido) ### Installation / Instalacao [](#installation--instalacao) #### Option A: Composer (Recommended / Recomendado) [](#option-a-composer-recommended--recomendado) ``` composer require ElePHPantMemory/memory ``` #### Option B: Manual Include / Importacao Manual [](#option-b-manual-include--importacao-manual) Download the package files and include the main manager file: *Descarrega os ficheiros do pacote e importa o ficheiro do gestor principal:* ``` require_once 'ElePHPantMemory/ChatManager.php'; ``` ### Usage / Utilizacao [](#usage--utilizacao) ``` use ElePHPantMemory\ChatManager; // 1. Grab your project's active database connection (PDO or mysqli) // 1. Usa a ligacao ativa do teu projeto (PDO ou mysqli) $memory = new ChatManager( existingConnection: $myActivePDO, maxTokens: 2000, purgeAfterDays: 15 // Auto-GDPR cleanup ); $session = 'whatsapp_user_912345678'; // 2. Log messages normally (automatically respects maxTokens sliding window) // 2. Regista as mensagens normalmente (respeita automaticamente a janela de maxTokens) $memory->addMessage($session, 'user', 'Hello, my name is Ze Povinho and my VAT is 123456789.'); // 3. Save extracted metadata (Use your AI function-calling to extract these) // 3. Guarda metadados extraidos (Usa o function-calling da tua IA para extrair isto) $memory->saveFact($session, 'user_name', 'Ze Povinho'); $memory->saveFact($session, 'vat_number', '123456789'); // 4. Build the tight, optimized payload ready for your AI API call // 4. Constroi o payload otimizado e leve pronto para enviar para a API da IA $aiPayload = $memory->getOptimizedContext($session); // 5. Memory Lifecycle Operations / Gestao do Ciclo de Vida da Memoria // Delete a specific fact / Apaga um facto especifico $memory->deleteFact($session, 'vat_number'); // Clear all facts / Limpa todos os factos $memory->clearFacts($session); // Clear message history / Limpa o historico de mensagens $memory->clearHistory($session); // Delete entire session data / Apaga todos os dados da sessao $memory->deleteSession($session); ``` --- 🏗️ Requirements / Requisitos ---------------------------- [](#️-requirements--requisitos) - PHP 8.4+ (Utilizes cutting-edge property hooks and asymmetric visibility). - An active database connection instance using `PDO` (MySQL, SQLite, SQL Server, PostgreSQL) or `mysqli`. --- 🛡️ Error Handling / Tratamento de Erros --------------------------------------- [](#️-error-handling--tratamento-de-erros) ### English [](#english-2) ElePHPantMemory throws custom exceptions under the `ElePHPantMemory` namespace: - **`ValidationException`**: Thrown when configuration parameters are invalid (e.g. `maxTokens` limit is below 500). - **`StorageException`**: Thrown when database connection types are unsupported, queries fail, or prepared statement operations fail. ### Portugues (Portugal) [](#portugues-portugal-2) O ElePHPantMemory lanca excecoes customizadas sob o namespace `ElePHPantMemory`: - **`ValidationException`**: Lancada quando os parametros de configuracao sao invalidos (ex: limite de `maxTokens` inferior a 500). - **`StorageException`**: Lancada quando a ligacao de base de dados nao e suportada, as queries falham, ou ocorrem erros ao preparar statements. ``` try { $memory = new ChatManager($db, 400); // Throws ValidationException / Lanca ValidationException } catch (\ElePHPantMemory\ValidationException $e) { echo "Validation failed / Validacao falhou: " . $e->getMessage(); } catch (\ElePHPantMemory\StorageException $e) { echo "Database error / Erro de base de dados: " . $e->getMessage(); } ``` --- 🧪 Testing / Testes ------------------ [](#-testing--testes) ### English [](#english-3) You can run the built-in, zero-dependency test suite using the following command: ### Portugues (Portugal) [](#portugues-portugal-3) Podes correr a suite de testes integrada e sem dependencias usando o seguinte comando: ``` php run_tests.php ``` --- 🤝 Contributing / Contribuir --------------------------- [](#-contributing--contribuir) ### English [](#english-4) Contributions are welcome! Please check [CONTRIBUTING.md](CONTRIBUTING.md) for architecture guidelines. Keep it dependency-free and ASCII-clean. ### Portugues (Portugal) [](#portugues-portugal-4) Contribuicoes sao bem-vindas! Verifica o ficheiro [CONTRIBUTING.md](CONTRIBUTING.md) para diretrizes de arquitetura. Mantem o codigo livre de dependencias e limpo de acentos. --- ⚖️ License / Licenca -------------------- [](#️-license--licenca) ### English [](#english-5) This project is licensed under the **GNU General Public License v3.0 (GPL-3.0)** - see the [LICENSE](LICENSE) file for details. Copyleft protects your work: anyone distributing modifications to this library must share them openly under the same terms. ### Portugues (Portugal) [](#portugues-portugal-5) Este projeto esta licensed sob a **GNU General Public License v3.0 (GPL-3.0)** - consulta o ficheiro [LICENSE](LICENSE) para mais detalhes. O Copyleft protege o teu trabalho: qualquer pessoa que distribua modificacoes desta biblioteca e obrigada a partilha-las abertamente sob os mesmos termos. ### Health Score 40 — FairBetter than 86% of packages Maintenance100 Actively maintained with recent releases Popularity0 Limited adoption so far Community2 Small or concentrated contributor base Maturity50 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 Unknown Total 1 Last Release 0d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/55018323?v=4)[RFernandes](/maintainers/rpnfernandes)[@rpnfernandes](https://github.com/rpnfernandes) ### Embed Badge ![Health badge](/badges/elephpantmemory-memory/health.svg) ``` [![Health](https://phpackages.com/badges/elephpantmemory-memory/health.svg)](https://phpackages.com/packages/elephpantmemory-memory) ``` ### Alternatives [sitegeist/archaeopteryx The missing link editor for Neos 2585.0k3](/packages/sitegeist-archaeopteryx)[heptacom/heptaconnect-portal-base HEPTAconnect base dataset that every other portal is based on 1025.2k15](/packages/heptacom-heptaconnect-portal-base) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)