ProfSynapseProfSynapse/nexus/.claude/skills/nexus-storage/SKILL.md

nexus-storage

Skill158 starsChanged 10 days agoMITView on GitHub

How to change, persist, migrate and recover Nexus data without losing it. Use when adding a SQLite table or column, persisting anything that must survive a restart or a cache rebuild, resolving a vault or plugin storage path, or debugging missing, stale, duplicated or post-rebuild-vanished data.

In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- nexus-agentsSkill
- nexus-eval-harnessSkill
- nexus-llm-adaptersSkill
- nexus-mobile-compatSkill
- nexus-model-evalSkill
- nexus-model-updatesSkill
- nexus-releaseSkill
- nexus-testingSkill
- nexus-tool-schemasSkill
- nexus-ui-mockupsSkill
- nexusSkill

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Read references/storage-model.md before writing any persistence code.
line 26
Very specific:
NEVER hardcode a storage root, and NEVER treat SQLite as authoritative.
line 29
Very specific:
If you touched SchemaMigrator.ts or schema.ts, run scripts/check_schema_consistency.py from the repo root and treat a non-zero exit as a …
line 32
Distinctive:
Verify at runtime, not just statically.
line 38

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Nexus Storage

Nexus stores data twice on purpose. The sharded JSONL event store is the source of truth; SQLite is a cache that is deleted and replayed on demand. Almost every storage bug in this repo is a write that landed on the wrong side of that line, or a read that ran before the cache was ready.

This router points at the procedure for your job. Working from the router alone is how the three-place schema change becomes a two-place one.

Workflow

Pick the job and open its protocol before editing anything:

Your job	Protocol
Add or change a SQLite table, column or index	`protocols/change-schema.md`
Persist a new kind of data, or make a write survive restart	`protocols/persist-new-data.md`
Data is missing, stale, duplicated, slow, or vanished after a rebuild	`protocols/diagnose-storage.md`

Read references/storage-model.md before writing any persistence code. It states the three invariants that decide whether a design is legal here. A change that breaks one is a data-loss bug that unit tests will happily pass.
NEVER hardcode a storage root, and NEVER treat SQLite as authoritative. Resolve roots through the resolvers named in references/paths-and-layout.md, and write through a repository so the event lands in JSONL first.
If you touched SchemaMigrator.ts or schema.ts, run scripts/check_schema_consistency.py from the repo root and treat a non-zero exit as a stop:
```
python3 .claude/skills/nexus-storage/scripts/check_schema_consistency.py .
```
Verify at runtime, not just statically. Every protocol here ends in a verification step that a static check cannot substitute for — schema changes fail on the upgrade path and the fresh-install path independently, and cache bugs only appear after a real rebuild.
At the end of a session that used this skill, run protocols/self-refine.md.

Map

protocols/ — the procedures: change-schema, persist-new-data, diagnose-storage, self-refine.
references/ — read on demand: storage-model.md (invariants and rebuild semantics), paths-and-layout.md (roots, resolvers, on-disk shapes, cache backends), schema-rules.md (what a migration may and may not do), failure-modes.md (symptom → cause → fix).
scripts/check_schema_consistency.py — proves the three schema definitions agree. Run it; do not eyeball them.

Siblings

Storage only. Mobile-safe imports and vault-path confinement are nexus-mobile-compat; test lanes and the in-app verification loop are nexus-testing; tools and agents that consume storage are nexus-agents.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free