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:

.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:

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:

npm install -g @barekey/memorystore

Or run it through npx from an MCP client:

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

From a source checkout:

cargo build --release --bin memorystore-mcp

Then point your MCP client at the built binary:

[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:

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:

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

After installing, invoke it in Codex with:

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:

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

Check the npm package contents:

npm pack --dry-run

Validate the bundled skill:

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:

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

Publish the npm package:

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.