Skip to content

docs: call pin_map only when a turn needs memory - #262

Merged
chouswei merged 1 commit into
masterfrom
docs/pin-map-description
Nov 10, 2026
Merged

chouswei merged 1 commit into
masterfrom
docs/pin-map-description

Conversation

@chouswei

Copy link
Copy Markdown
Owner

Why

Owner ask: bots call pin_map every turn, usually with an empty cue, and get only a session outline back. That costs a round trip and tokens for nothing they use. The cause is the tool description and matching in-repo advice ("each turn call this with a cue, or empty-q outline"). This PR rewords that advice: call pin_map only when a turn needs something from memory, always with a real cue; if an outline helps, ask for it once at job start.

Wording only. Empty cue still returns the 0.11 session outline (MN-REQ-04.9 unchanged). No requirement ids or implemented flags changed.

What changed

  • pin_map MCP docstring (the live tool description), CLI query pin-map docstring, help_text.py.
  • README, parts/memnet-mcp/README.md, AGENTS.md, LLM-GUIDE, SHAPE, gql-wire-profile, multi-agent-sessions, application notes, in-repo .cursor/skills.
  • MN-REQ-04.1: "for each turn" becomes "for a cued request"; the bounded-map contract is kept.
  • CHANGELOG [Unreleased] ### Changed note.
  • tests/test_mcp.py now asserts the new phrases and fails if the old advice returns.

Live MCP clients see the new text only after a package release and a roll of memnet-mcp.

Old pin_map description

    """Live pin map: bounded shaped GQL neighbourhood.

    Goldfish caller (0.13): each turn call this with a cue ``q`` (or empty-q
    outline of S). Drop prior pin_map rows from the prompt before the next
    generate. Sparse Δ on mutate. Env blobs stay in the outer harness.

    Product cue: ``kind`` / ``locators`` / ``keyword`` / ``cue`` (nickname) /
    ``session``. leftover ``anchor`` / ``anchors`` are leftover nickname aliases,
    not TARGET law. Empty cue is session outline (0.11: kinds + LIMIT exemplars
    of S) regardless of ``view``. ``view=shell`` is grain on a seed — not the
    outline. When the cue yields |Q|>1 the emit carries CueConflict.
    When a hard cap clips the neighbourhood the emit carries Truncation
    (``## Truncation truncated=true``); caps stay hard.

    Optional ``view``: ``shell`` | ``interior`` (teach); ``flowchart`` | ``parts`` |
    ``statechart`` accepted with soft shell caps (grain filters deferred).
    Optional ``caller``: CapsPolicy ACL who-check when session ACL is enabled.
    """

New pin_map description

    """Live pin map: bounded shaped GQL neighbourhood.

    Call only when this turn actually needs something from memory, and
    always with a real cue (``kind`` / ``locators`` / ``keyword`` /
    nickname ``cue`` / ``session``). Do not call every turn, and do not
    call with an empty cue just to refresh context. An empty cue still
    returns a session outline (0.11: kinds + LIMIT exemplars of S)
    regardless of ``view``; request that outline once at job start if
    you need a census, not every turn. Drop prior pin_map rows from the
    prompt before the next generate. Sparse Δ on mutate. Env blobs stay
    in the outer harness.

    leftover ``anchor`` / ``anchors`` are leftover nickname aliases,
    not TARGET law. ``view=shell`` is grain on a seed — not the
    outline. When the cue yields |Q|>1 the emit carries CueConflict.
    When a hard cap clips the neighbourhood the emit carries Truncation
    (``## Truncation truncated=true``); caps stay hard.

    Optional ``view``: ``shell`` | ``interior`` (teach); ``flowchart`` | ``parts`` |
    ``statechart`` accepted with soft shell caps (grain filters deferred).
    Optional ``caller``: CapsPolicy ACL who-check when session ACL is enabled.
    """

Tests

  • pytest tests/test_session_outline.py tests/test_mcp.py tests/test_goldfish_caller.py tests/test_goldfish_paradox.py tests/test_pin_map_export.py tests/test_identity_cut.py: 47 passed.
  • Full pytest: no failures.
  • ruff check and ruff format --check on engine, MCP and tests: clean.

Reword the pin_map tool description, CLI/help text, README, guides and
in-repo skills: call only when a turn needs memory, with a real cue; ask for
the empty-cue outline once at job start. Behaviour unchanged.
@chouswei
chouswei marked this pull request as ready for review November 10, 2026 06:05
@chouswei
chouswei merged commit c31cd4f into master Nov 10, 2026
2 checks passed
@chouswei chouswei mentioned this pull request Nov 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant