Skip to main content
Glama
README.md
# merestone

> **Name reserved.** This is a placeholder release (`0.0.0`), published so that the name belongs to
> the project described below. The first real release — the MCP server — will be `0.1.0`.
> Until then this package does nothing except hold the name; please do not depend on it.

**Stable addresses for durable project memory — and the fewest tokens it takes to find them.**

`merestone` is an MCP server that turns a repository's working documents into records addressed by
short codes (`PL-…`, `IS-…`) that are **never renamed and never reused**, with every reference
**re-checked by a gate** so a dead pointer fails loudly instead of silently.

## The one principle everything else serves

**Spend as little context as possible.**

Everything this project asks of you — one object, one code; codes that are never reused; records that
are superseded rather than edited; references that a gate re-checks — exists for exactly one reason:
**misunderstanding costs context**. Every token spent re-reading a file because a pointer turned out
to be dead, or re-deriving what `IS-048` meant because the number had been reused, is a token not
spent on the actual work.

The rules are not the point. They are the cheapest way we know to keep the context bill down.

| mechanism | the context it saves |
| --- | --- |
| one record, one code | no tree walk to find "the" document — a code is a few tokens and it resolves |
| codes never reused, never renamed | no disambiguation between two things that once shared a number |
| supersede, never edit | no re-reading a whole record just to learn what changed |
| a gate re-checks every reference | a dead pointer fails at check time, not after three wrong files are loaded |
| excerpts that say they were truncated | a 40-line body is never mistaken for the whole record |
| no numbers in tool descriptions | the tool surface stays stable and cacheable |
| low-frequency commands stay in the CLI | every tool name is permanent context; only the frequent ones earn one |

## Why "merestone"

A *merestone* is the stone that marks a boundary. It does not move when the land changes hands, and
every year the parish walks the boundary and beats the marks — not because the stones rot, but
because people forget. This package does the same for a codebase's memory: the code is the stone,
the gate is the walk, and the whole thing is written for the next session that arrives without
context.

## Planned surface

| tool | answers |
| --- | --- |
| `show` | what does this code actually say |
| `queue` | what is next / what is ready / what is blocked |
| `knowledge` | what traps are known before I touch this |
| `touches` | which records name this file |
| `claim` | which code may I take next |

Low-frequency commands (`refs`, `stale`, `codemap`) stay in the CLI on purpose: a tool name is
permanent context, so only the frequent ones get one.

## Status

- `0.0.0` — name placeholder (this release)
- `0.1.0` — first MCP server release (planned)

## License

MIT