Metadata-Version: 2.4
Name: memoryplace
Version: 0.1.0
Summary: MemoryPlace: Benchmark framework for memory architectures
Author: Yash Tarun, Pratyush Singh
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.115.0
Requires-Dist: modal>=0.64
Requires-Dist: nltk>=3.8
Requires-Dist: openai>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rouge-score>=0.1.2
Requires-Dist: sentence-transformers>=2.0.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: uvicorn[standard]>=0.30.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == 'test'
Description-Content-Type: text/markdown

# MemoryPlace

The CLI for building, evaluating, and publishing AI-agent memory architectures.

MemoryPlace benchmarks memory systems the same way for everyone: same datasets,
same generation model, same metrics. You implement retrieval; MemoryPlace owns
answer generation, so the only thing a score reflects is the memory itself.

Platform and leaderboard: https://memoryplace.vercel.app

---

## Install

```
pip install memoryplace
```

This installs the `memoryplace` command (and `bruv`, kept as an alias).

---

## The contract

A memory architecture implements three methods. It never generates the final
answer.

```python
from memoryplace import MemoryPlaceArchitecture

class MyMemory(MemoryPlaceArchitecture):
    def reset(self) -> None:
        # clear state for a new conversation
        ...

    def ingest(self, conversation) -> None:
        # store the conversation in memory
        ...

    def retrieve(self, question: str) -> list[str]:
        # return the memories relevant to the question
        ...
```

---

## Quickstart

```
memoryplace login                     # authenticate
memoryplace init-architecture my_mem  # scaffold a pushable package
# implement reset / ingest / retrieve in my_mem/architecture.py
memoryplace evaluate my_mem.architecture.MyMemory   # run locally
memoryplace push                      # publish to the Hub
```

A published architecture is evaluated on the Hub in an isolated container, then
ranked on the public leaderboard.

---

## How evaluation works

```
conversation --> architecture.ingest()
question     --> architecture.retrieve() --> memories
memories     --> MemoryPlace generates the answer (same model + prompt for all)
answer       --> metrics --> scores
```

Every architecture runs identically, so results are comparable by construction.
Quality is scored with an LLM judge plus F1, BLEU, ROUGE, SBERT, and METEOR;
efficiency is reported as tokens per query and p95 latency.

---

## Commands

```
init-architecture   scaffold a new architecture package
evaluate            run an architecture locally
compare             compare architecture results
push                publish an architecture to the Hub
signup / login      account management
logout / whoami     session management
```

---

## Key design ideas

- Retrieval only. Architectures are black-box retrievers; generation is held
  constant, so a score measures memory quality and nothing else.
- Isolated execution. Each architecture installs its own dependencies and runs
  in its own container. Untrusted code never touches the platform.
- Neutral by construction. MemoryPlace sells no memory of its own, so the
  numbers are a referee's call, not a pitch.

---

## Limitations

- Local `evaluate` needs an `OPENAI_API_KEY` and downloads embedding models on
  first use.
- Leaderboard entries come only from Hub runs; local results never publish.

---

## Links

- Platform: https://memoryplace.vercel.app
