# Reported issues for memshelf-mcp

Pod holds 20 of 42 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [memshelf-mcp](/mcp/memshelf-mcp).

## Most discussed

### design: multi-shelf vs domain mixing — decide before M1 freezes conventions

M0 annoyance #4 / ARCHITECTURE open question 5: the "one shelf per project" convention cracked on day one — the live shelf now mixes sqst, personal-hardware, homelab, docshelf-history, and mentoring domains, distinguished only by tags. Options:

1. Keep one personal shelf, add domain as a first-class frontmatter field + INDEX grouping.
2. Cheap multi-shelf (`memshelf init` frictionless, #9) + a meta-INDEX federation for "which shelf discussed X".
3. Status quo (tags only) until it actually hurts

[Read the thread](https://github.com/ignatenkofi/memshelf-mcp/issues/20) · 2026-07-13 · closed · 2 comments

### doctor: stale-index неустраним, когда у эпизода есть гитигнорённый H2-сплит-каталог

## Симптом

На полке с ботом, рендерящим производные на `main`, `doctor` отдаёт
`stale-index` в состоянии, из которого он не выводится: warning висел до
`shelve`, пережил штатный рендер бота и остался после него.

Признаки того, что расхождение **не** в свежей записи:

- новый эпизод после рендера бота присутствует и в `INDEX.md`, и в `ledger.tsv`;
- дублей в реестре нет;
- `no-ledger-row` после рендера ушёл штатно — то есть бот отработал;
- `stale-index` присутствовал в снимке `doctor` **до** ш

[Read the thread](https://github.com/ignatenkofi/memshelf-mcp/issues/109) · 2026-08-20 · closed · 1 comment

### README:92: --section "Decisions=..." — быстрый старт молча коммитит на полку эпизод с мусорной секцией

## Проблема

`README.md:88-96` — блок быстрого старта из шелла. Весь блок исполняем как есть: полка задана конкретно (`~/my-shelf`), slug конкретный (`2026-07-23-topic`), `--digest` — настоящее осмысленное предложение. Кроме одной строки:

```bash
memshelf shelve --shelf ~/my-shelf --slug 2026-07-23-topic --kind topic \
  --digest "What was decided, what was rejected and why, what stays open." \
  --section "Decisions=..."
```

`README.md:92`: `--section "Decisions=..."` — тело секции подменено 

[Read the thread](https://github.com/ignatenkofi/memshelf-mcp/issues/106) · 2026-08-18 · closed · 1 comment

### derived-stale не отличил остановленный рендерер от отстающего на реальном случае

## Проблема

`#89` завёл ровно этот сценарий: производные отстают не потому, что бот ещё не
отработал, а потому, что до бота ничего не доехало; эпизоды копятся, а `doctor`
отдаёт те же warning, что через секунду после здорового шелвинга. PR #95 добавил
код `derived-stale` уровня error. На боевом случае он не сработал.

## Замер 2026-08-16, полка main-memshelf

`memshelf_doctor`: 122 эпизода, 3 ошибки, 5 предупреждений. Ошибки —
три `missing-section` в чужих эпизодах от 13.08. По производным:

``

[Read the thread](https://github.com/ignatenkofi/memshelf-mcp/issues/102) · 2026-08-16 · closed · 1 comment

### `resolve` объединяет там, где после #58 надо регенерировать — воскрешает архивные .meta-записи и дублирует ledger

## Что случилось

Живое столкновение на `sqst-memshelf` 2026-08-01. Ветка везла роллап (45 эпизодов в `archive/`), параллельная сессия смержила в `main` новый эпизод. Конфликт — ровно в четырёх производных файлах: `INDEX.md`, `ledger.tsv`, `stats.svg`, `docs/topics/.meta.json`. Эпизоды слились чисто.

Полка бота ещё не подключила, то есть это **документированный сценарий для `resolve`**: «мостик для полок, ещё не подключивших бота» (ARCHITECTURE, README). Запустил его — и получил неверную полку:

[Read the thread](https://github.com/ignatenkofi/memshelf-mcp/issues/64) · 2026-08-01 · closed · 1 comment

### Release v0.1.0 — owner checklist: PyPI Trusted Publisher, tag, directories

The release machinery is merged (#47) — everything below is the owner-only tail (accounts/credentials). Once done, the pipeline is fully automatic for every future `v*` tag.

## Checklist

- [ ] **PyPI Trusted Publisher** (~2 min, no tokens): https://pypi.org/manage/account/publishing/ → *Add a new pending publisher*:
  - PyPI project name: `memshelf-mcp`
  - Owner: `ignatenkofi` · Repository: `memshelf-mcp`
  - Workflow name: `release.yml`
  - Environment: `release`
- [ ] **Tag the release**: `

[Read the thread](https://github.com/ignatenkofi/memshelf-mcp/issues/48) · 2026-07-23 · closed · 1 comment

### Adapter kit: ship the dogfood-proven pre-commit PII guard — prompt-only redaction is bypassed by any write outside /shelve

## Task

The M0 kit's only PII/secret defense is prompt-level: SKILL.md step 3's redaction pass (`adapters/claude-code/skills/shelve/SKILL.md:49-55`). Anything written to the shelf outside the skill — a hand edit, a stray agent write, a fix-up commit — reaches git with no check at all, on a repo whose entire content is conversation memory (MANIFEST: the tool is public, the memory never is; POLICY.md is load-bearing; the project's own privacy docs note git history makes leaks sticky until a delib

[Read the thread](https://github.com/ignatenkofi/memshelf-mcp/issues/32) · 2026-07-17 · closed · 1 comment

### Align with shelf-spec v0 (openshelf) memory profile: shelf.yml in init scope, spec-named doctor findings, normative cross-refs

## Task

ADR-0005 (openshelf, accepted 2026-07-15) extracted shelf-spec v0 from docshelf/memshelf practice: the spec's `profile: memory` formalizes exactly this repo's conventions (SPEC.md section 2.1 — "Lineage: memshelf"; section 4.4 ledger format; section 5 episode format; section 5.5 kind-to-category mapping), and an existing shelf becomes conformant by adding one `shelf.yml` (section 3, compatibility promise). The dogfood M0 shelf already carries a `shelf.yml` with `profile: memory`. docshe

[Read the thread](https://github.com/ignatenkofi/memshelf-mcp/issues/31) · 2026-07-17 · closed · 1 comment

## Most recent

### Неизвестный ключ в аргументах тула отбрасывается молча — опечатка во флаге меняет поведение

## Что наблюдается

Вызов `memshelf_doctor` с двумя лишними ключами:

```json
{"shelf_path": "/…/estate/shelf", "definitely_not_a_key": true, "check_remot": true}
```

вернул `status: ok` и нормальный отчёт по указанной полке. Ни ошибки, ни
упоминания о том, что два ключа из трёх отброшены. Второй ключ — опечатка
в реальном флаге `check_remote`.

## Причина по коду

Прочитано на `main`: `src/memshelf_mcp/tools.py` (blob `fca249c`),
`src/memshelf_mcp/server.py` (blob `3715b78`).

Входные модели (

[Read the thread](https://github.com/ignatenkofi/memshelf-mcp/issues/104) · 2026-08-17 · closed · 0 comments

### shelve --amend cannot change an episode's kind, and its error blames the slug

## What happens

Amending an episode with a different `kind` fails:

```
AmendTargetMissing: --amend: no episode '2026-08-13-yinguo-independent-recount'
on this shelf (docs/topics/2026-08-13-yinguo-independent-recount.md does not
exist). Check the slug, or shelve it without --amend to create it.
```

The episode exists — at `docs/sessions/…`. `--amend` resolves the target
directory from the *new* `kind` via `CATEGORY_BY_KIND` and looks only there, so
a kind change always reads as a missing episo

[Read the thread](https://github.com/ignatenkofi/memshelf-mcp/issues/90) · 2026-08-14 · closed · external user · 0 comments

### CLI ignores $MEMSHELF_SHELF_PATH while the MCP tools honour it

## What happens

The default-shelf fallback landed in `tools.py`, so every MCP tool resolves an
omitted `shelf_path` from `$MEMSHELF_SHELF_PATH`. `cli.py` declares `--shelf` as
`required=True` on each subcommand and never reads the variable, so

```sh
export MEMSHELF_SHELF_PATH=~/my-shelf
memshelf index          # still: error: the following arguments are required: --shelf
```

## Why it matters

A small asymmetry, but it reads as a bug to whoever sets the variable and then
tries the CLI — and t

[Read the thread](https://github.com/ignatenkofi/memshelf-mcp/issues/86) · 2026-08-14 · closed · external user · 0 comments

### The "return errors, never raise" contract does not cover bad input

## What happens

`tests/test_server_contract.py` guarantees that a doomed call comes back as a
JSON envelope rather than an exception. That holds for failures *inside* the
tool body, because each wrapper catches and calls `_error_response`.

It does not hold for input validation, which the SDK runs before the wrapper is
entered. Observed live against a built bundle, calling `memshelf_index` with no
shelf configured:

```
Error executing tool memshelf_index: 1 validation error for memshelf_indexA

[Read the thread](https://github.com/ignatenkofi/memshelf-mcp/issues/85) · 2026-08-14 · closed · external user · 0 comments

### serverInfo.version is empty in the initialize response

## What happens

The server answers `initialize` with an empty version string:

```
{"name": "memshelf_mcp", "version": ""}
```

`server.py` builds the server as `MCPServer("memshelf_mcp")`. The SDK's
constructor takes a `version` keyword — introspected on the installed `mcp`
2.0.0:

```
MCPServer.__init__: name, title, description, instructions, website_url,
                    icons, version, auth_server_provider, token_verifier, …
```

Nothing passes it, so every host displays memshelf withou

[Read the thread](https://github.com/ignatenkofi/memshelf-mcp/issues/83) · 2026-08-14 · closed · external user · 0 comments

### resolve: дедуп ledger не схлопывает строки, различающиеся только пустой хвостовой колонкой (вариант #62)

> **Priority:** P3

## Проблема

`resolve` на полке `sqst-memshelf` оставил в `ledger.tsv` две строки одного
эпизода, различающиеся **только пустой последней колонкой**:

```
79:2026-08-05<TAB>2026-08-05-atlas-native-first-session<TAB>live<TAB>700<TAB>184<TAB>
80:2026-08-05<TAB>2026-08-05-atlas-native-first-session<TAB>live<TAB>700<TAB>184
```

Строка 79 заканчивается табом (пустая колонка `notes`), строка 80 — нет.
Дедуп `_union_tsv` сравнивает строки целиком, поэтому такая пара не
схлопывается

[Read the thread](https://github.com/ignatenkofi/memshelf-mcp/issues/78) · 2026-08-07 · closed · 0 comments

### `shelve` оставляет `docs/*/.meta.json` изменённым в рабочем дереве — вопреки собственному контракту

Контракт #58 и README адаптера говорят одно и то же:

> `memshelf shelve` больше не пишет производные файлы и стейджит **только эпизод**.

Стейджит — да. Но **пишет**: `shelve` зовёт `Shelf.add_document`, а тот записывает `title`/`description` в `docs/<категория>/.meta.json` для индексатора (`docshelf/core/shelf.py`, «Record title/description in .meta.json for the indexer»). Файл остаётся в рабочем дереве изменённым и незастейдженным.

## Наблюдалось вживую

После штатного шелва на `sqst-memshel

[Read the thread](https://github.com/ignatenkofi/memshelf-mcp/issues/69) · 2026-08-01 · closed · 0 comments

### Фолбэк `date or span` печатает диапазон в спек-ограниченную колонку ledger, а doctor этого не видит

Второй дефект того же утра и того же семейства, что #64: инструмент отчитывается успехом на артефакте, который спек считает сломанным.

## Что случилось

`main` полки `sqst-memshelf` перестал проходить `shelf-spec validate`:

```
ledger-malformed (error)
line 62: date '2026-07-31..2026-08-01' is not YYYY-MM-DD
```

При этом `memshelf doctor` на той же полке — **0 errors**.

## Причина

`collect_episodes` (`core/rebuild.py`) читает дату так:

```python
date=fields.get("date") or fields.get("span"

[Read the thread](https://github.com/ignatenkofi/memshelf-mcp/issues/65) · 2026-08-01 · closed · 0 comments

### doctor не проверяет уникальность episode_id в ledger — пропустил 30 дублей

Отделено от #62 (тот про причину порчи, этот — про то, почему её не поймали).

## Симптом

На полке `sqst-memshelf` после `resolve` в `ledger.tsv` оказалось **94 строки на 63 эпизода**: 30 эпизодов записаны дважды. `memshelf doctor --shelf .` вернул **ноль errors** и `exit 0`.

Дальше сработала ровно та цепочка, ради которой doctor и существует как гейт: CLAUDE.md полки предписывает «после shelve и перед push — doctor; errors блокируют push». Я его выполнил, получил зелёный сигнал, запушил и сме

[Read the thread](https://github.com/ignatenkofi/memshelf-mcp/issues/63) · 2026-08-01 · closed · 0 comments

### _union_tsv дублирует строки ledger: дедуп по целой строке против производной колонки digest_tokens

Поймано на живой полке `sqst-memshelf` при разрешении обычного multi-writer конфликта: `memshelf resolve --commit` продублировал 30 строк ledger, и это уехало в main (sqst-memshelf#62, чинится в sqst-memshelf#65).

## Симптом

После resolve: `ledger.tsv` — **94 строки на 63 эпизода** вместо ожидаемых 64. 30 эпизодов записаны дважды, дубли различаются ровно одним полем:

```
2026-07-22  2026-07-22-case-b-verdict  live  12000  200  Case B verdict: ...
2026-07-22  2026-07-22-case-b-verdict  live  1

[Read the thread](https://github.com/ignatenkofi/memshelf-mcp/issues/62) · 2026-08-01 · closed · 0 comments

### shelve: эпизод без span проходит инструмент (и doctor), но валится на shelf_validate — расхождение со SPEC 5.2

Догфуд-находка с полки sqst-memshelf (PR sqst-memshelf#43, 2026-07-27).

## Что случилось

`memshelf shelve` с непереданным `--span` записал эпизод `docs/topics/2026-07-27-home-network-design-package.md` без поля `span` во фронтматтере и отчитался `status: ok`. `memshelf doctor` тоже прошёл чисто (healthy, 0 errors). А advisory-CI полки (`shelf_validate` из shelf-spec) упал:

```
rule: episode-frontmatter-invalid
severity: error
detail: missing required field 'span'
suggested_fix: fix the frontm

[Read the thread](https://github.com/ignatenkofi/memshelf-mcp/issues/56) · 2026-07-27 · closed · 0 comments

### Surface the saved tokens — make the economy visible in daily use

The numbers exist (`ledger.tsv`, `recall-log.tsv`, `memshelf_stats`) but are only visible when someone explicitly runs `stats`. The owner asked for the savings to be *ambient*. Candidate surfaces, cheapest first — the first two reuse code that already exists:

1. **SessionStart banner (recommended).** The plugin's `session-start-index.sh` already injects INDEX; prepend one line from `stats`: `📇 shelf: 35 episodes · standing 8.9K tok · holds 2.10M (236:1) · realized saved: N tok`. Every session o

[Read the thread](https://github.com/ignatenkofi/memshelf-mcp/issues/49) · 2026-07-23 · closed · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/ignatenkofi/memshelf-mcp/issues).