Skip to main content
Glama
furui

furui

furui

Memory that knows what to forget.

furui is an MCP 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.


Related MCP server: Memryzed

Quickstart

Requires Python 3.11+.

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:

 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:

{
  "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

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.

Available Tools

5 tools
forgetForgetA

Permanently delete one memory by id (works on pinned memories too).

Inputs: id (required). Returns: object

prunePruneA

List or delete unpinned memories whose current score is below a threshold.

A brand-new importance-1 memory scores 1.0; an importance-3 memory left untouched for one half-life scores 1.5. Thresholds around 0.25-1.0 are typical.

Inputs: threshold (required), dry_run. Returns: object

recallRecallA

Search memories by keyword overlap, ranked by relevance x current score.

Every returned memory is reinforced: its recall_count goes up and its decay clock resets. An empty query returns the strongest memories overall.

Inputs: query (required), limit. Returns: object

rememberRememberC

Store a new long-term memory.

Inputs: text (required), tags, pinned, importance. Returns: object

statsStatsA

Summary of the memory store: counts, score distribution, prunable counts, config.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    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

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Self-hosted MCP-native agent memory server. Gives AI agents persistent, decay-weighted memory via 83 MCP tools — no cloud, full control. RocksDB+HNSW backend. Works with Claude Code, Cursor, and any MCP-compatible agent.
      14
      9
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Local-first cross-agent memory for AI coding agents. Persistent, shared memory over MCP — what you tell one agent can be recalled by another — with all data stored in a single local SQLite file, no cloud and no API keys.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Durable, local-first memory for AI coding agents over MCP — zero-dependency (pure Python + SQLite/FTS5), curated and semantically de-duped. Works with Claude Code, Codex and any MCP host, and you own the data as plain rows.
      6
      99 PyPI
      23
      AGPL 3.0
    • A
      license
      A
      quality
      F
      maintenance
      Local-first MCP memory server that gives AI coding agents long-term memory via SQLite and sqlite-vec, with optional LLM-powered layering. No gateway or API key required.
      7
      109 npm
      4
      MIT