Skip to main content
Glama
furui

furui

README.md
# furui

**Memory that knows what to forget.**

furui is an [MCP](https://modelcontextprotocol.io) server that gives AI agents a
*curated* long-term memory. Memories fade unless they are used, get stronger
every time they are recalled, and fall through the sieve when they stop
mattering. Pinned memories stay put.

- **Decay.** Every memory loses strength on a half-life curve (default 30 days).
- **Reinforcement.** Recalling a memory resets its decay clock and boosts it.
- **Pruning.** `prune` lists (or deletes) whatever has faded below a threshold.
- **Fully local.** Python + stdlib `sqlite3`. No API keys, no network, no embeddings.

> *furui* (篩) is Japanese for "sieve". It also sounds like 古い, "old", which is
> what this server is for: deciding which old things are still worth keeping.

---

## Why not just a vector DB?

A vector database answers "what is *similar* to this?" It does not answer
"what is still *worth knowing*?" Agent memory goes stale for reasons that have
nothing to do with similarity:

| Problem | Vector DB | furui |
|---|---|---|
| Last month's workaround is still there and outranks today's fix | Similarity doesn't care about age | Unused memories decay; fresh or recently used ones win |
| Memory grows forever and recall gets noisier | You write your own TTL/cleanup jobs | `prune(threshold)` with a dry-run preview is built in |
| Facts the agent keeps needing look the same as one-off trivia | All vectors are equal | Every recall reinforces a memory |
| Some facts must never be lost (the user's name, hard rules) | No such concept | `pinned=true`: floor on decay, never pruned |
| Setup | Embedding model, API key or GPU, index, extra service | One SQLite file |
| Why did this rank first? | Cosine distance between opaque vectors | `relevance × importance × recency × reinforcement`, every factor returned |

Embeddings are good at fuzzy matching, and furui may add them as an optional
relevance signal later. The core idea here is **lifecycle**, not retrieval:
deciding what to keep matters more than finding the nearest neighbour in a pile
that only grows.

---

## Quickstart

Requires Python 3.11+.

```bash
git clone <this repo> furui && cd furui
python -m venv .venv
# Windows: .venv\Scripts\activate    macOS/Linux: source .venv/bin/activate
pip install -e ".[dev]"

python scripts/demo.py    # offline demo: 120 simulated days, recall, prune
pytest                    # run the test suite
furui                     # start the MCP server on stdio
```

The demo doesn't need the MCP SDK. It uses an in-memory database and a
simulated clock, so you can watch memories decay, get reinforced and get pruned:

```text
 id  imp  pin    idle  recalls   score  text
  5    4          10d        1   4.275  Never deploy to production on Fridays (team rule)
  3    4          30d        2   3.099  Project database is PostgreSQL 16 listening on ...
  1    5  yes    120d        0   2.500  User's name is Aiko; address her by first name
  ...
  7    1          80d        0   0.157  User found the weather API docs confusing
  4    1         115d        0   0.070  Lunch order on July 6th was a tuna onigiri
```

### MCP client configuration

Add furui to any MCP client that launches stdio servers (Claude Desktop, Cursor,
Antigravity, ...). Point `command` at the `furui` script inside your virtualenv:

```json
{
  "mcpServers": {
    "furui": {
      "command": "/absolute/path/to/furui/.venv/bin/furui",
      "args": [],
      "env": {
        "FURUI_DB_PATH": "/absolute/path/to/memories/furui.db",
        "FURUI_HALF_LIFE_DAYS": "30"
      }
    }
  }
}
```

On Windows the command is `C:\\path\\to\\furui\\.venv\\Scripts\\furui.exe`. You can
also use `"command": "python", "args": ["-m", "furui.server"]` with the right
interpreter.

### Configuration

| Variable | Default | Meaning |
|---|---|---|
| `FURUI_DB_PATH` | `~/.furui/furui.db` | SQLite file (created on first use) |
| `FURUI_HALF_LIFE_DAYS` | `30` | Days for an untouched memory to lose half its recency |
| `FURUI_PIN_FLOOR` | `0.5` | Lowest recency factor a pinned memory can reach (0–1) |

---

## Tools

| Tool | Signature | What it does |
|---|---|---|
| `remember` | `remember(text, importance=3, tags=[], pinned=false)` | Store a memory. `importance` is 1 (trivia) to 5 (critical). Tags are normalised to lowercase. |
| `recall` | `recall(query, limit=5)` | Keyword search ranked by `relevance × score`. **Every returned memory is reinforced.** An empty query returns the strongest memories. |
| `forget` | `forget(id)` | Delete one memory permanently. This works on pinned memories too, because it's an explicit request. |
| `prune` | `prune(threshold, dry_run=true)` | List unpinned memories scoring below `threshold`, weakest first. Deletes them only when `dry_run=false`. |
| `stats` | `stats()` | Counts, score min/median/mean/max, how many memories each threshold would prune, importance histogram, top tags, config. |

Results include each memory's `score`, its factors (`recency`, `reinforcement`),
`idle_days` and, for recall, its `relevance` and `rank`. The agent can see why
something ranked where it did.

Suggested agent loop: `recall` before answering anything that depends on past
context, `remember` durable facts and decisions, then now and then run
`prune(0.5)` (dry run), review the list, and run it again with `dry_run=false`.

---

## How scoring works

Each memory's **current score** is computed at read time, never stored:

$$
\text{score} = \text{importance} \times \text{recency} \times \text{reinforcement}
$$

**Importance** is the 1–5 value given at `remember` time. A brand-new memory
scores exactly its importance.

**Recency** is half-life decay over the days since the memory was last recalled,
or since it was created if it has never been recalled:

$$
\text{recency} = 0.5^{\,\text{idle\_days} / \text{half\_life}}
$$

| idle days (half-life 30) | 0 | 15 | 30 | 60 | 90 | 180 |
|---|---|---|---|---|---|---|
| recency | 1.00 | 0.71 | 0.50 | 0.25 | 0.125 | 0.016 |
| score, importance 3 | 3.00 | 2.12 | 1.50 | 0.75 | 0.375 | 0.047 |

Pinned memories use `max(recency, FURUI_PIN_FLOOR)`, so a pinned importance-5
memory never drops below 2.5 with the default floor. Pinned memories are never
prune candidates.

**Reinforcement** rewards memories that keep proving useful, with diminishing
returns:

$$
\text{reinforcement} = 1 + 0.5 \cdot \ln(1 + \text{recall\_count})
$$

| recall_count | 0 | 1 | 3 | 10 | 100 |
|---|---|---|---|---|---|
| reinforcement | 1.00 | 1.35 | 1.69 | 2.20 | 3.31 |

Recalling a memory has two effects: `recall_count` goes up, and the decay clock
resets (`last_recalled_at = now`). A memory that's used often stays near the
top. One that's never used fades out.

**Relevance** (for `recall`) is keyword overlap. The query and each memory's
text + tags are lowercased and split on whitespace and punctuation. Common
stopwords and one-letter fragments are dropped from the query. Then:

$$
\text{relevance} = \frac{|\text{query terms} \cap \text{memory terms}|}{|\text{query terms}|}
$$

Memories with zero overlap are never returned. The rest are ranked by
`relevance × score`, so a strong partial match can beat a faded exact match.

**Picking a prune threshold.** A fresh importance-1 memory scores 1.0. An
importance-3 memory untouched for three half-lives scores 0.375. Thresholds
between 0.25 and 1.0 work well. `stats()` reports how many memories each of
0.25 / 0.5 / 1.0 would remove.

---

## furui vs plain memory servers

"Plain" here means the common append-only design: store text (or
entities/observations), search it, and keep everything until someone deletes it
by hand.

| | Plain memory server | Vector-DB memory | **furui** |
|---|---|---|---|
| Storage | JSON / SQLite file | Vector index + often a separate service | Single SQLite file (stdlib) |
| Retrieval | Substring / keyword | Embedding similarity | Keyword overlap × lifecycle score |
| Ranking uses age | ✗ | ✗ (usually) | ✓ half-life decay |
| Usage strengthens memories | ✗ | ✗ | ✓ reinforcement on recall |
| Importance levels | ✗ | ✗ (metadata at most) | ✓ 1–5, scales score |
| Never-forget memories | n/a (nothing is forgotten) | n/a | ✓ pinned, with decay floor |
| Built-in forgetting | ✗ manual delete only | ✗ TTL/cleanup scripts | ✓ `prune` with dry-run |
| Explainable ranking | partly | ✗ opaque distances | ✓ every factor returned |
| Needs API keys / network | no | often | **no** |
| Extra dependencies | few | embedding model + DB | `fastmcp` only |

---

## Development

```text
furui/
  server.py    FastMCP server and the five tools
  store.py     SQLite storage, recall, prune, stats
  scoring.py   pure functions: decay, reinforcement, relevance
tests/
  test_scoring.py
  test_store.py
scripts/demo.py
```

- `scoring.py` is pure and has no I/O. `store.py` takes an injectable clock, so
  tests simulate months of decay without sleeping.
- Scores are derived, not stored, so changing `FURUI_HALF_LIFE_DAYS` takes
  effect at once for every memory.
- v1 scores every memory in Python on each recall. That's fine for thousands
  of memories. An FTS5 pre-filter is the natural next step beyond that.

## License

MIT. See [LICENSE](LICENSE).

TDQS

A3.6/5.0

Scored across 5 tools

Disambiguation5/5

Each tool maps to a distinct memory operation: remember (create), recall (search + reinforce), forget (delete by id), prune (threshold-based bulk cleanup), and stats (observability). The only adjacent pair—forget vs prune—is explicitly separated by id-based vs score-threshold deletion semantics and the pinned/unpinned distinction.

Naming Consistency4/5

All names are single-word, lowercase, and prefix-free, which reads as one coherent vocabulary. The minor deviation is that four are verbs (remember, recall, forget, prune) while stats is a noun, but it is conventional enough not to cause confusion.

Tool Count5/5

Five tools is well-scoped for a long-term memory store: one per lifecycle stage plus a diagnostics tool. Nothing appears redundant or padded, and no operation feels crammed together with another.

Completeness3/5

Create, search/read, single delete, bulk cleanup, and stats are covered, but there is no update operation to change importance or otherwise edit a memory, and no way to pin/unpin even though pinned state is referenced by forget and prune. Retrieval is also limited to keyword-overlap search with no direct get-by-id, which agents may need for confirm-before-forget workflows.

Maintenance

ActivityMaintained
ResponsivenessOutdated data