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.

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 · 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 · 2026-08-20 · closed · 1 comment

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

Проблема

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

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 · 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 · 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 · 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 · 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 · 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 · 2026-07-17 · closed · 1 comment

Most recent

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

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

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

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

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 · 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-052026-08-05-atlas-native-first-sessionlive700184 80:2026-08-052026-08-05-atlas-native-first-sessionlive700184

Строка 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 · 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).