Metadata-Version: 2.5
Name: ebbtide
Version: 0.2.0
Summary: Long-term memory for AI agents that forgets on purpose: an MCP server on a forgetting curve.
Project-URL: Homepage, https://aimsotrash-ebbtide.vercel.app
Project-URL: Repository, https://github.com/aimsotrash/Ebbtide
Author: Nikhil Pawar
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: mcp==2.3.0
Requires-Dist: numpy==2.4.6
Requires-Dist: sentence-transformers==6.1.0
Requires-Dist: torch==2.14.1
Requires-Dist: transformers==5.19.0
Description-Content-Type: text/markdown

# Ebbtide

[![CI](https://github.com/aimsotrash/Ebbtide/actions/workflows/ci.yml/badge.svg)](https://github.com/aimsotrash/Ebbtide/actions/workflows/ci.yml)
[![MCP Badge](https://lobehub.com/badge/mcp/aimsotrash-ebbtide)](https://lobehub.com/mcp/aimsotrash-ebbtide)

**Long-term memory for AI agents that forgets on purpose.**

Ebbtide was called Engram until October 31, 2026; I renamed it because several other memory
servers for AI agents already use that name. It began as a notes app, which I retired in
October 2026; its last version is the git tag
[`notes-app`](https://github.com/aimsotrash/Ebbtide/tree/notes-app).

**Live:** [aimsotrash-ebbtide.vercel.app](https://aimsotrash-ebbtide.vercel.app)

## Install

With [uv](https://docs.astral.sh/uv/), on Linux or an Apple silicon Mac (macOS 14 or later).
For Claude Code:

```bash
uv tool install --torch-backend cpu ebbtide
claude mcp add ebbtide -s user -- ebbtide
```

For any other MCP client, add this to its configuration:

```json
{
  "mcpServers": {
    "ebbtide": {
      "command": "uvx",
      "args": ["--torch-backend", "cpu", "ebbtide"]
    }
  }
}
```

`--torch-backend cpu` installs PyTorch's CPU build (about 1.2 GB) instead of several GB of
CUDA libraries; Ebbtide doesn't use a GPU. The first `remember` or `recall` downloads a 90 MB
embedding model, and after that Ebbtide runs offline. Settings and
the memory panel are in [`ebbtide/README.md`](ebbtide/README.md).

## Memory for AI agents

[`ebbtide/`](ebbtide/README.md) is an MCP server that gives an agent such as Claude
Code long-term memory across sessions, through four tools: `remember`, `recall`, `forget`
and `memory_stats`. Two resources, `ebbtide://memories` and `ebbtide://memories/{id}`, let a
client attach memories as context without strengthening them, and two prompts,
`recall_first` and `save_session`, start the common workflows. Each memory fades along a forgetting curve unless it is recalled, and
every recall makes it last longer. When the store reaches its budget, 1000 memories by
default, the weakest one goes first. The memories live in a SQLite file on your machine,
and only what a recall returns enters the agent's context.

A local panel lists the memories and how strong each one is, with a slider that looks
ahead to show which ones are fading.

### Should an agent forget?

I replayed six memory policies on two public long-conversation benchmarks and measured
whether the memory still finds the evidence each question needs.
[LongMemEval](bench/RESULTS.md) has 500 questions with histories of about 490 turns;
its 30 abstention questions have no evidence to find, so 470 are scored. Settings were picked on
92 dev questions and fixed before the other 378 were first scored.
[LoCoMo](bench/RESULTS-locomo.md) has 10 conversations that span 5 to 10 months, and
nothing was tuned on it.

- **Keeping everything wins when you can afford it.** With room for half the history, the
  best forgetting policy finds all the evidence in its top 10 results for 37% of LongMemEval
  questions and 27% of LoCoMo questions. Keeping everything does for 58.5% and 44.6%.
- **No forgetting rule wins everywhere.** On LongMemEval, keeping what gets used beats
  keeping the newest. On LoCoMo, keeping the newest does best at the turn level.
- **Strengthening on recall beats plain LRU, modestly.** ebbtide-count, the server's
  default, keeps up to 4 points more of the evidence than LRU on LongMemEval, and ranks every
  answer session in its top 10 up to 14 points more often; I chose these comparisons after
  seeing the results. On LoCoMo, where I chose the comparison before running it, both gains
  held but were smaller (up to 1.6 and 3.4 points), and it found all the evidence in its top
  10 about as often as LRU.
- **Strengthening too hard backfires on facts that change.** FSRS-style spacing made old
  facts stick: on LongMemEval's knowledge-update questions it found the newest fact 12 to
  17 points less often than LRU.
- **Fading didn't help as a ranking signal.** Tuning picked similarity alone almost
  everywhere, so the gains come from what is kept, not from how it is ranked.

MemoryBank (Zhong et al., 2023) already applied an Ebbinghaus curve to LLM memory. What is
new here is the measured comparison with simple baselines, losses included.

## Stack

Python · MCP · sentence-transformers · NumPy · SQLite · React · TypeScript · Vite ·
Tailwind CSS · Motion

## Run it locally

To run the MCP server, follow the setup in [`ebbtide/README.md`](ebbtide/README.md).

To reproduce the benchmarks, from the repo root:

```bash
uv venv -p 3.12 .venv && uv pip install --python .venv -e .   # CPU-only PyTorch, per pyproject.toml
.venv/bin/python -m bench.longmemeval embed   # downloads the data and embeds it once, ~45 min on a laptop CPU
.venv/bin/python -m bench.longmemeval run     # writes bench/RESULTS.md
.venv/bin/python -m bench.locomo              # writes bench/RESULTS-locomo.md
```

The landing page for the MCP server lives in `site/` (Vite, React and Tailwind):

```bash
cd site && npm install && npm run dev   # http://localhost:5173
```

The Python tests (20: 13 intelligence, 3 MCP server, 4 benchmark) stub the embedding model,
so they need only `requirements-test.txt`, which adds pytest; any venv works, such as the one
above or a fresh `uv venv -p 3.12 .venv`:

```bash
uv pip install --python .venv -r requirements-test.txt
.venv/bin/python -m pytest intelligence/tests ebbtide/tests bench
```

## References

- Di Wu et al. *LongMemEval: Benchmarking Chat Assistants on Long-Term Interactive Memory.*
  2024. [arXiv:2410.10813](https://arxiv.org/abs/2410.10813)
- Adyasha Maharana et al. *Evaluating Very Long-Term Conversational Memory of LLM Agents.*
  ACL 2024. [arXiv:2402.17753](https://arxiv.org/abs/2402.17753). The LoCoMo data is
  CC BY-NC 4.0; it is downloaded, never committed, and used here for non-commercial research.
- Wanjun Zhong et al. *MemoryBank: Enhancing Large Language Models with Long-Term Memory.*
  2023. [arXiv:2305.10250](https://arxiv.org/abs/2305.10250)
- FSRS, the spaced-repetition scheduler whose default weights the spaced rule uses:
  [open-spaced-repetition](https://github.com/open-spaced-repetition)

## License

[MIT](LICENSE).
