Edit README.md – Stash-MCP

# Stash — Content Store for AI Agents

Stash is a persistent content store you have access to via MCP. Use it to save, retrieve, organize, and manage documents and notes that persist across conversations. Think of it as your filesystem — a place to stash working documents, reference material, specs, and anything worth keeping.

## How It Works

Paths are POSIX-style and relative to the content root, with no leading slash (e.g. `docs/guide.md`). Writing a file creates missing parent directories automatically — there is no separate mkdir step.

Every modification is guarded by an optimistic-concurrency check: `read_content` returns a `sha` (SHA-256 of the file), and `overwrite_content`, `edit_content`, and `delete_content` require that sha. If the file changed since you read it, the call fails with a SHA mismatch — re-read and retry.

## Core Tools

### Discover

- **`list_content`** — `path` (default root), `recursive` (default false). Non-recursive entries are names prefixed with 📁 (directory) or 📄 (file); recursive listings are full relative paths.
- **`inspect_content_structure`** / **`inspect_content_structure_batch`** — heading outline of a markdown file (title, nested sections with line numbers) without reading the full content.

### Read

- **`read_content`** — `path`, optional `max_lines`. Returns `content`, `sha` (of the full file), `truncated`, and `total_lines`.
- **`read_content_batch`** — up to 10 paths in one call; per-file errors don't fail the batch.
- Files are also exposed as MCP resources under `stash://{path}`.

### Write

- **`create_content`** — `path`, `content`. New files only; errors if the file exists.
- **`edit_content`** — `file_path`, `sha`, `edits` (list of `{old_string, new_string, replace_all}`). Targeted string replacement; preferred for small changes. All edits validate before anything is written.
- **`overwrite_content`** — `path`, `content`, `sha`. Replaces the entire file.
- **`edit_content_batch`** — atomic edits across up to 10 files; if any file fails validation, nothing is written.

### Organize

- **`move_content`** — `source_path`, `dest_path`. The destination must not already exist; parent directories are created automatically.
- **`move_content_directory`** — moves a whole directory tree.
- **`move_content_batch`** — up to 10 moves, validated all-or-nothing.
- **`delete_content`** — `path`, `sha`. Deletes are permanent.

### Configuration-Dependent Tools

Depending on how this server is configured, you may also have:

- **`search_content`** — semantic search returning ranked snippets; follow up with `read_content` for full files.
- **`log_content`**, **`diff_content`**, **`blame_content`** — git history, diffs, and line-level authorship for any file.
- **Transaction tools** — when writes are git-tracked, every write requires an active transaction: call `start_content_transaction`, make your changes, then `commit_content_transaction` with a commit message (or `abort_content_transaction` to discard). Write tools will say so in their descriptions if this applies.

If a tool isn't listed in your session, that feature is disabled — and in read-only deployments no write tools are registered at all.

## Typical Workflows

Save something new:

```
create_content(path="notes/project-ideas.md", content="# Project Ideas\n\n- CLI dashboard")
```

Modify an existing file:

```
read_content(path="notes/project-ideas.md")            → returns sha
edit_content(
  file_path="notes/project-ideas.md",
  sha="<sha from read>",
  edits=[{"old_string": "- CLI dashboard", "new_string": "- CLI dashboard\n- Monitoring alerts"}],
)
```

Reorganize:

```
move_content(source_path="notes/project-ideas.md", dest_path="projects/ideas.md")
```

## Suggested Structure

```
docs/           — Long-lived documentation and reference material
notes/          — Working notes, meeting notes, scratchpad
specs/          — Technical specifications and designs
projects/       — Per-project working directories
templates/      — Reusable templates and boilerplate
```

You're not locked into this — organize however makes sense for the user's needs.

## Important Behaviors

- **`create_content` fails if the file exists.** Use `overwrite_content` or `edit_content` for existing files.
- **Writes require the current sha.** Always `read_content` first; a SHA mismatch means the file changed under you.
- **Paths are sandboxed.** You cannot traverse outside the content root; `..` escapes are rejected.
- **Hidden files (dotfiles) are excluded** from listings.
- **Content is UTF-8 text.** Binary files are not supported.
- **Deletes are permanent** — there is no trash. On git-tracked servers, uncommitted transaction changes can be discarded with `abort_content_transaction`, but a committed delete only survives in git history.

## When to Use Stash

Use Stash when the user asks you to save, remember, or persist something beyond the current conversation: reference documentation, working notes or drafts that evolve over sessions, technical specs, templates, research digests, or anything the user explicitly asks you to "stash" or "save."

Don't use Stash for ephemeral responses or one-off answers — just respond normally in conversation for those.

Discard