---
license: mit
library_name: convmemory
tags:
- retrieval
- memory
- reranking
- agents
- convmemory
- locomo
pipeline_tag: feature-extraction
---

# ConvMemory LoCoMo MPNet

This repository contains the public ConvMemory LoCoMo/MPNet checkpoint.

ConvMemory is a lightweight learned memory reranker for long-term conversational and agent memory. It runs after vector search and before prompt construction:

```text
user query -> vector search top-k -> ConvMemory -> memory context
```

## Files

- `model.pt`: ConvMemory checkpoint weights.
- `config.json`: ConvMemory model and rerank configuration.
- `manifest.json`: checksum and configuration manifest.
- `LICENSE`: MIT license.

## Usage

Install ConvMemory from GitHub, or from PyPI after the next package release:

```bash
pip install git+https://github.com/pth2002/ConvMemory.git
```

Load directly from Hugging Face Hub:

```python
from convmemory import ConvMemory

model = ConvMemory.from_pretrained("Purdy0228/ConvMemory-LoCoMo-MPNet")

results = model.retrieve(
    query="When is the hiking trip?",
    memories=memories,
    top_k=10,
)
```

Use with the CCGE-LA conflict editor:

```python
from convmemory import ConvMemory

model = ConvMemory.from_pretrained("Purdy0228/ConvMemory-LoCoMo-MPNet")
model.load_ccge_editor("Purdy0228/ConvMemory-CCGE-LA")

results = model.retrieve(
    query=query,
    memories=memories,
    editor="ccge_la",
    top_k=10,
)
```

For systems with precomputed embeddings, skip encoder loading and pass embeddings directly:

```python
model = ConvMemory.from_pretrained("Purdy0228/ConvMemory-LoCoMo-MPNet", embedding_model=False)
ranked = model.rerank_embeddings(
    query_embedding=query_embedding,
    memory_embeddings=memory_embeddings,
    memory_ids=memory_ids,
    memory_texts=memory_texts,
    query=query,
)
```

## Checkpoint Configuration

| Field | Value |
|---|---:|
| Embedding backbone | `sentence-transformers/all-mpnet-base-v2` |
| Embedding dimension | 768 |
| Window size | 5 |
| Stride | 1 |
| Kernel size | 3 |
| Hidden dimension | 256 |
| Token MLP dimension | 32 |
| Channel MLP dimension | 512 |
| Candidate top-n | 500 |
| Raw score fusion weight | 0.025 |

## Intended Use

- Retrieval-stage reranking for long-term conversational memory.
- Agent memory selection after vector search.
- Memory streams where missing relevant evidence is costly.

## Limitations

- This is not a vector database or end-to-end QA model.
- It is not intended as a general web/document reranker.
- The checkpoint is optimized for the MPNet embedding space; other embedding backbones require retraining or validation.
- Scores are not calibrated by default.
- No inference widget is provided; use the `convmemory` Python library.

## Citation

A formal citation will be added when a technical report is available.

## Links

- GitHub: https://github.com/pth2002/ConvMemory
- CCGE-LA checkpoint: https://huggingface.co/Purdy0228/ConvMemory-CCGE-LA