Metadata-Version: 2.4
Name: lexigram-ai-memory
Version: 0.1.1
Summary: AI memory system for the Lexigram Framework — episodic, semantic, and working memory
Project-URL: Homepage, https://github.com/lexigram-dev/lexigram
Project-URL: Repository, https://github.com/lexigram-dev/lexigram
Project-URL: Documentation, https://docs.lexigram.dev
Project-URL: Issues, https://github.com/lexigram-dev/lexigram/issues
Project-URL: Changelog, https://github.com/lexigram-dev/lexigram/blob/main/CHANGELOG.md
Author-email: Lexigram Framework Team <team@lexigram.dev>
Maintainer-email: Lexigram Framework Team <team@lexigram.dev>
License: MIT
License-File: LICENSE
Keywords: ai,ai-memory,async,episodic,framework,lexigram,memory,python,semantic
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: lexigram-contracts>=0.1.0
Requires-Dist: lexigram>=0.1.1
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Provides-Extra: redis
Requires-Dist: redis[asyncio]>=5.0; extra == 'redis'
Provides-Extra: test
Requires-Dist: lexigram-testing>=0.1.1; extra == 'test'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# lexigram-ai-memory

AI memory system for the Lexigram Framework — episodic, semantic, and working memory

---

## Overview

Three-tier AI memory system for the Lexigram Framework. Provides working, episodic, and semantic memory with pluggable backends, automatic consolidation scheduling, token-aware context assembly, and multi-source retrieval — all wired through the DI container via `MemoryModule`. Zero-config usage starts with sensible defaults.


> Full documentation: [docs.lexigram.dev](https://docs.lexigram.dev)
## Install

```bash
uv add lexigram-ai-memory
# Optional extras
uv add "lexigram-ai-memory[redis]"
```

## Quick Start

```python
from lexigram import Application
from lexigram.di.module import Module, module

from lexigram.ai.memory import MemoryModule
from lexigram.ai.memory.config import MemoryConfig

@module(imports=[
    MemoryModule.configure(
        MemoryConfig(default_backend="in_memory")
    )
])
class AppModule(Module):
    pass

app = Application(modules=[AppModule])
if __name__ == "__main__":
    app.run()
```

## Configuration

> **Zero-config usage:** Call `MemoryModule.configure()` with no arguments to use defaults.

### Option 1 — YAML file

```yaml
# application.yaml
ai_memory:
  default_backend: "vector"
  ttl_seconds: 2592000
  consolidation:
    enabled: true
    interval_seconds: 3600.0
```

### Option 2 — Profiles + Environment Variables *(recommended)*

```bash
export LEX_AI_MEMORY__DEFAULT_BACKEND=vector
# Environment variables for each field
```

### Option 3 — Python

```python
from lexigram.ai.memory.config import MemoryConfig
from lexigram.ai.memory import MemoryModule

config = MemoryConfig(
    default_backend="vector",
)
MemoryModule.configure(config)
```

### Config reference

| Field | Default | Env var | Description |
|-------|---------|---------|-------------|
| `enabled` | `True` | `LEX_AI_MEMORY__ENABLED` | Enable the AI memory subsystem |
| `default_backend` | `"in_memory"` | `LEX_AI_MEMORY__DEFAULT_BACKEND` | Backend type: `in_memory`, `cache`, `database`, `vector` |
| `ttl_seconds` | `0` | `LEX_AI_MEMORY__TTL_SECONDS` | Default entry TTL in seconds (0 = never expire) |
| `working.system_prompt_tokens` | `500` | `LEX_AI_MEMORY__WORKING__SYSTEM_PROMPT_TOKENS` | Fixed token allocation for system prompt |
| `working.recent_turns_fraction` | `0.4` | `LEX_AI_MEMORY__WORKING__RECENT_TURNS_FRACTION` | Fraction of remaining budget for recent turns |
| `episodic.default_top_k` | `5` | `LEX_AI_MEMORY__EPISODIC__DEFAULT_TOP_K` | Default number of episodes to retrieve |
| `semantic.min_confidence` | `0.6` | `LEX_AI_MEMORY__SEMANTIC__MIN_CONFIDENCE` | Minimum confidence score for stored facts |
| `consolidation.enabled` | `True` | `LEX_AI_MEMORY__CONSOLIDATION__ENABLED` | Whether automatic background consolidation is active |
| `consolidation.interval_seconds` | `3600.0` | `LEX_AI_MEMORY__CONSOLIDATION__INTERVAL_SECONDS` | How often to run a consolidation pass |

## Module Factory Methods

| Method | Description |
|--------|-------------|
| `MemoryModule.configure(config, enable_consolidation)` | Production-ready module with full consolidation pipeline |
| `MemoryModule.stub(config)` | Test-friendly module with in-memory backends |

## Key Features

- **Three-tier memory**: Working (context assembly), Episodic (conversation episodes), Semantic (entity facts)
- **Pluggable backends**: In-memory, Redis, SQLAlchemy, Qdrant/Chroma/PGVector
- **Token budget allocation**: Distributes available tokens across memory sources
- **Automatic consolidation**: Background scheduler promotes episodic to semantic storage
- **Multi-source retrieval**: Unified `MemoryRetriever` queries all tiers with relevance ranking
- **Dynamic pruning**: `DynamicContextPruner` fits context into hard token limits

## Testing

```python
async with Application.boot(modules=[MemoryModule.stub()]) as app:
    # your test code
    ...
```

## Key Source Files

| File | What it contains |
|------|-----------------|
| `src/lexigram/ai/memory/module.py` | `MemoryModule` — DI module factory methods |
| `src/lexigram/ai/memory/config.py` | `MemoryConfig` and tier-specific config classes |
| `src/lexigram/ai/memory/di/provider.py` | `MemoryProvider` — wires all protocols and services |
| `src/lexigram/ai/memory/working/manager.py` | `WorkingMemoryManager` — context assembly |
| `src/lexigram/ai/memory/episodic/store.py` | `EpisodicMemoryStore` — episode storage |
| `src/lexigram/ai/memory/semantic/store.py` | `SemanticMemoryStore` — fact storage |
| `src/lexigram/ai/memory/consolidation/consolidator.py` | `MemoryConsolidator` — consolidation pipeline |
| `src/lexigram/ai/memory/retrieval/retriever.py` | `MemoryRetriever` — multi-source retrieval |
