# Memory Store

Memory Store is a small Rust MCP stdio server for durable project-local AI notes.
It gives agents a place to remember verified project facts, decisions, setup
commands, debugging results, and conventions without hiding them in a global
database or editing random scratch files.

The canonical store is plaintext and git-friendly:

```text
.memory-store/
  metadata.toml
  VERSION
  .gitignore
  memories/
    <cuid2>.md
  .cache/
    fff/
```

Each memory is a Markdown file with TOML frontmatter and a generated Cuid2 key.
Search uses FFF over `.memory-store/memories`. The `.memory-store/.cache/fff`
directory is disposable search/index state and is ignored by git.

## Use Case

Use Memory Store for knowledge that should survive between AI sessions but still
belong to the project:

- repo setup facts that were actually verified
- architecture or product decisions with short rationale
- debugging outcomes, exact symptoms, and confirmed fixes
- conventions future agents should follow
- small reminders that are too local for global memory and too operational for
  committed docs

Do not store secrets, credentials, personal data, long logs, full docs, copied
source files, or guesses that have not been verified.

## Tools

Memory Store exposes these MCP tools:

- `init {}`: create `.memory-store` and metadata for the current project.
- `new { content, tags? }`: create a new memory with a generated Cuid2 key.
- `get { key }`: read one memory by opaque key.
- `update { key, expected_revision, operations }`: apply exact body edits after
  checking the current revision.
- `delete { key, expected_revision }`: remove a memory after checking the
  current revision.
- `search { query, limit?, offset? }`: search memories with FFF-backed content
  and fuzzy search.

`new`, `get`, `update`, `delete`, and `search` intentionally fail until the
project has been initialized:

```text
MemoryStore is not initialized in this project. Initialize it first via the `init` command instead.
```

## Install For Humans

Memory Store currently builds the Rust binary from source when installed from
npm, so you need a Rust toolchain with `cargo` on `PATH`.

Install globally:

```sh
npm install -g @barekey/memorystore
```

Or run it through `npx` from an MCP client:

```toml
[mcp_servers.memorystore]
command = "npx"
args = ["-y", "@barekey/memorystore"]
startup_timeout_sec = 30
```

From a source checkout:

```sh
cargo build --release --bin memorystore-mcp
```

Then point your MCP client at the built binary:

```toml
[mcp_servers.memorystore]
command = "/path/to/memorystore/target/release/memorystore-mcp"
args = []
startup_timeout_sec = 30
```

On Windows, use the `.exe` path.

To initialize a project outside an MCP client:

```sh
memorystore-mcp --root /path/to/project init
```

## Install The Skill

This repository also contains a Codex skill that teaches agents how to use the
MCP server safely.

Install it with the open skills CLI:

```sh
npx -y skills add usebarekey/memorystore --skill memorystore --full-depth
```

After installing, invoke it in Codex with:

```text
Use $memorystore to initialize, search, update, and clean up durable project memories for this task.
```

The skill tells agents to use MCP tools only. They should not manually read,
write, edit, rename, migrate, or delete files inside `.memory-store`.

## Memory Shape

Keep notes small and focused. A good memory is usually one paragraph: one fact,
decision, convention, or debugging result. If a note needs multiple sections or
long excerpts, split it into smaller memories or move it into committed project
docs.

Keys are opaque Cuid2 identifiers. Do not use keys as taxonomy. Search by topic,
tags, component names, error text, and the note body, then use returned keys only
for exact `get`, `update`, or `delete` calls.

## Development

Run the Rust checks:

```sh
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
```

Check the npm package contents:

```sh
npm pack --dry-run
```

Validate the bundled skill:

```sh
python C:/Users/Sander/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/memorystore
```

## Release

Create the GitHub repository under the `usebarekey` organization and push:

```sh
gh repo create usebarekey/memorystore --public --source . --remote origin --push
```

Publish the npm package:

```sh
npm publish --access public
```

The npm package is scoped as `@barekey/memorystore` and exposes the
`memorystore-mcp` and `memorystore` binaries.

## License

BSD 3-Clause. See [LICENSE](LICENSE).