NoteStore Lab

NoteStore Lab

Copy first. Prove the case path. Then let AI and local MCP review the samecase root.

Operator-first proof path:notes-recovery demo -> notes-recovery ai-review --demo ->notes-recovery ask-case --demo --question "What should I inspect first?" ->notes-recovery doctor

Repository identity: apple-notes-forensics · Primary entrypoints:notes-recovery and notes-recovery-mcp

Start Here ·Public Proof ·Landing ·Use Cases ·Builder Guide ·Support

Public-safe proof block: one copied-evidence workflow, one timestamped caseroot, and reviewable outputs for backup, recovery, verification, and reports.

Start Here

Treat this repository like a lab bench, not a rescue button. Start by provingthe workflow shape on synthetic artifacts first:

notes-recovery demo
notes-recovery ai-review --demo
notes-recovery ask-case --demo --question "What should I inspect first?"
notes-recovery doctor

What this path proves in under five minutes:

• one timestamped case root instead of ad hoc loose files
• reviewable outputs for backup, recovery, verification, and reports
• a zero-risk first look that does not touch private evidence or a live Notesstore
• a synthetic AI triage path that stays on review artifacts instead of rawcopied evidence
• an evidence-backed case question flow that cites what it used

If you are here for Codex / Claude Code integration, run the operator pathonce, then jump to the Builder Guide. The builder lane isreal, but it is not the first thing a new operator should read.

Fast route map if you do not want to guess:

• start at the Landing for the copy-first story and proof-path overview
• open Public Proof when the question becomes "what is really proved versus still manual"
• open Use Cases when you want to match your goal to operator, AI review, MCP, or case-diff lanes
• only then open the Builder Guide if you are reusing the same case root in Codex / Claude Code

Current lane order

• Primary: the local copy-first recovery lab on one explicit case root
• Primary extension: notes-recovery-mcp as the repo's pure_mcp reviewsurface
• Secondary: public-skills/notestorelab-case-review/ as the standalonepure_skills packet for host-native reviewers; its secondary ClawHub packetlisting is live, but it still stays behind the landing/proof route
• Later / companion: plugin bundles, deeper package/registry detail,Docker/GHCR, and Glama metadata after the local case path already makessense
• Current non-claims: no hosted Notes recovery service, no multi-tenantreview portal, and no live OpenHands/extensions/Glama/Docker catalog listinglanguage in the front-door sentence
• Current review tail: OpenHands/extensions is submission-done withchanges requested, so keep that lane in platform review until a liveread-back exists

Deep reads once the first path makes sense:LLMs Guide · Distribution ·Use Cases · Ecosystem Fit

What It Is

NoteStore Lab is a local Apple Notes recovery toolkit for macOS.It is built around one rule: work on copied evidence, not the live Notes store.

The CLI-first chain stays intentionally simple:

notes-recovery CLI -> parser/handlers -> services -> core pipeline -> timestamped case outputs

The builder-facing chain is just as important:

case root + manifests + review artifacts + notes-recovery-mcp

That is the current external substrate for local agents and builder tooling.It is real today. A hosted API or generated SDK is not.

For the exact repo-side proof, remote read-back proof, and manual externalboundary, use Public Proof.

What It Is Not

Why AI / Agent Users Care

This repository is not a generic AI assistant. It is closer to a forensicworkbench with a bounded AI copilot layered on top.

The highest-value AI / agent cuts already shipped are:

These surfaces live on the main workflow. They are not detached chat panels.

What You Can Prove Today

Why Trust This

• Copy-first by default: the documented workflow operates on copied case roots, not the live Notes store.
• Reviewable outputs first: manifests, verification outputs, reports, timelines, and text bundles stay inspectable by humans.
• AI is bounded: ai-review and ask-case stay on derived artifacts first, and cloud-backed OpenAI remains explicit opt-in.
• MCP is bounded: notes-recovery-mcp is local stdio first, read-only / read-mostly, and case-root-centric instead of host-control by default.

Host Safety Boundary

This repository is a copied-evidence workbench, not a host-control utility.

That means the tracked code and automation must not introduce:

• broad host cleanup routines for shared apps, browsers, Notes, or Docker
• shared-process termination helpers such as killall, pkill, kill -9,os.kill(...), or process.kill(...)
• desktop-wide automation such as osascript, System Events,AppleEvent, loginwindow, or Force Quit flows

The allowed local scope stays intentionally narrow:

• copied evidence inside timestamped case roots
• repo-local rebuildable surfaces such as .venv/ and .runtime-cache/
• user-invoked previews of repo-owned output paths

Quickstart

Choose your path

Fastest zero-risk try

Start with the tracked public demo before you point the toolkit at any copiedevidence of your own:

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .[dev]
notes-recovery demo
notes-recovery ai-review --demo
notes-recovery ask-case --demo --question "What should I inspect first?"
notes-recovery doctor
notes-recovery --help

Expected first-look signals:

• the command prints NoteStore Lab public demo
• notes-recovery ai-review --demo generates a synthetic triage summary,findings, and next-step questions
• notes-recovery ask-case --demo ... returns an evidence-backed answer withcited derived surfaces
• notes-recovery doctor tells you whether the host is ready for a realcopied-evidence run
• you see a case tree preview, a verification preview, and an operator brief
• nothing touches private evidence or a live Notes store
• the demo surface gives you one coherent story: workflow shape, AI proof, andbounded questioning on the same synthetic material

Run against your own copied evidence

Only do this on a copy of Apple Notes data, never the live original store.

Before the first real copied-evidence run, start with:

notes-recovery doctor

That preflight step helps you decide whether this host is ready for thestandard copied-evidence workflow, whether you should stay on demo, orwhether you only need to install optional extras.

If you want AI-assisted review on a real case, keep the boundary clear:

python -m pip install -e .[ai]
notes-recovery ai-review \
  --dir ./output/Notes_Forensics_<run_ts> \
  --provider ollama \
  --model llama3.1:8b

The AI assistant reads review artifacts such as manifests, pipeline summaries,verification outputs, timelines, reports, and review indexes. It does notdefault to uploading raw copied evidence or the live Notes store to a cloudprovider.

If you want to ask one bounded, evidence-backed question about the same case,use:

notes-recovery ask-case \
  --dir ./output/Notes_Forensics_<run_ts> \
  --question "Which artifact should I inspect first?"

That command stays on derived case artifacts and returns:

• an answer
• evidence references
• confidence / uncertainty
• suggested next inspection targets

If you want a richer local review surface after the CLI proof path, install theoptional dashboard extras and launch the review cockpit:

python -m pip install -e .[dashboard]
forensics-dashboard

The review cockpit stays local-first and case-root-centric. It can browsemultiple case roots, preview the review index and AI outputs, inventory derivedresources, and render a bounded case-diff summary without turning the repointo a hosted review portal.

notes-recovery auto \
  --out ./output/Notes_Forensics \
  --report \
  --verify \
  --recover \
  --keyword "your distinctive keyword"

That workflow:

1. copies evidence into a timestamped case root
2. runs selected recovery and analysis stages on the copy
3. writes outputs, manifests, logs, and a review_index.md guide into that case directory

You can also run stages individually with commands such as snapshot, query,recover, verify, report, plugins-validate, case-diff, and fts-index.

AI-Assisted Review

notes-recovery ai-review is the first AI surface in this repository.

• It is a review assistant, not a recovery engine.
• It reads derived review artifacts first.
• It can generate:
  • triage_summary.md
  • top_findings.md
  • next_questions.md
  • artifact_priority.json
• The synthetic proof path is:
  • notes-recovery ai-review --demo
• The local-first real-case path is:
  • python -m pip install -e .[ai]
  • notes-recovery ai-review --dir <case-root> --provider ollama --model <model>
• A cloud-backed provider is available only through explicit opt-in:
  • set NOTES_AI_OPENAI_API_KEY
  • run notes-recovery ai-review --dir <case-root> --provider openai --model <model> --allow-cloud

The stable case-root contract for those directories and manifests is documentedin CONTRIBUTING.md.

Protocol Surfaces

Round 4 adds the first protocol-facing surfaces for agents and external tools:

• notes-recovery ask-case --dir <case-root> --question "..."
• notes-recovery-mcp --case-dir <case-root>

Those protocol surfaces keep the same product boundary:

• they stay on copied-evidence case roots
• they prefer derived review artifacts over raw evidence
• they do not expose the live Notes store as a default input
• the MCP server starts with local stdio transport instead of a hosted service
• they are protocol surfaces, not a hosted review portal or agent platform

For Builders And Local Agents

The current builder story is intentionally narrow and stable:

Treat this whole section as a later builder lane around the local lab. It isreal and useful, but it is not the front-door sentence a new reviewer shoulduse to describe the product.

• use the case root contract as the file-system-level substrate
• use manifests, summaries, verification previews, and AI review outputs as theshared read layer
• use notes-recovery-mcp when you want a case-root-centric tool/resourceinterface instead of scraping files ad hoc

If your local coding-agent host supports stdio MCP servers, the stable commandto register is:

.venv/bin/python -m notes_recovery.mcp.server --case-dir ./output/Notes_Forensics_<run_ts>

Use that command inside Codex / Claude Code style local MCP registration flows.The host-specific JSON wrapper can vary, but the executable contract is thesame: local stdio, read-mostly, case-root-centric.

If you want copy-paste-safe wrapper sketches, the builder guide and shippeddistribution artifacts now include:

• a project .codex/config.toml starter for Codex
• a project .mcp.json wrapper example for Claude Code
• a Codex plugin bundle
• a Claude Code plugin bundle plus Git-backed marketplace manifest
• an OpenClaw-compatible bundle build path that keeps the same executablecontract without claiming a live listing

Those public-ready surfaces live under plugins/, .claude-plugin/, andserver.json. Package the installable archives with:

.venv/bin/python scripts/release/build_distribution_bundles.py --out-dir ./dist

For the MCP lane specifically, server.json is the repo-owned descriptoraround the same local stdio case-review workflow. Package publication,registry read-back, and marketplace/manual submission status can drift overtime, so this README keeps the primary story on the local bench first. UseDISTRIBUTION.md when you need the later-lane claimboundary.

The repository now also ships a canonical independent skill surface atskills/notestorelab-case-review/. Treat that directory as the SSOT skillpackage, and treat the plugin/starter skill files as host-specific derivedcopies. That makes the skill independently referenceable without pretending ithas already cleared any external directory gate.

For OpenHands/extensions and ClawHub-style submissions, the repo now also shipsan OpenHands/extensions-friendly public skill folder atpublic-skills/notestorelab-case-review/. Treat that packet as theportable listing lane, while skills/notestorelab-case-review/ remains thecanonical skill text.

When you want the repo-side metadata/build-readiness gate before the next PyPIversion bump, run:

.venv/bin/python scripts/release/check_pypi_publish_readiness.py

Practical host notes:

• Codex and Claude Code are both good current examples of hosts that fit the shipped local stdio MCP contract here.
• Keep the executable command above as the source of truth even when each host wraps it differently.
• Treat remote-connector-first hosts as comparison paths here because this repo does not ship a hosted or remote MCP deployment.
• OpenClaw-style hosts stay in the comparison bucket for now, but this repo now ships an OpenClaw-compatible bundle build path instead of only a docs-only comparison note.
• The safest integration smoke is still demo -> ask-case --demo -> the exact notes_recovery.mcp.server command.

Current integration fit:

• Primary fit: MCP, Codex, Claude Code
• OpenHands/extensions-friendly public skill folder: public-skills/notestorelab-case-review/
• Secondary / comparison fit: OpenCode
• Not a primary front-door claim: OpenClaw, hosted portals, generic AI-agent platforms

Builder-facing status today:

Docker And Catalog Later Surface

The Docker story is intentionally narrow and secondary:

• it is a Docker-ready local container surface around the same case-rootworkflow
• it is a companion packaging lane, not the primary front door
• it is not a hosted service
• it keeps the MCP path on local stdio
• it expects copied case roots or demo mode, not a live Notes store

Build the image:

docker build -t notestorelab:0.1.0.post1 .

Run the public-safe demo:

docker run --rm notestorelab:0.1.0.post1 notes-recovery demo

Run the MCP help surface:

docker run --rm --entrypoint notes-recovery-mcp notestorelab:0.1.0.post1 --help

Review an existing copied case root through the local stdio MCP server:

docker run --rm -i \
  -v "$PWD/output:/cases:ro" \
  --entrypoint notes-recovery-mcp \
  notestorelab:0.1.0.post1 \
  --case-dir /cases/Notes_Forensics_<run_ts>

The container image is a reproducible local runtime, not a hosted portal, notan API gateway, and not proof of any live Glama or OCI catalog listing.

The repo-side Glama metadata surface is now explicit as well:

• glama.json
• Dockerfile
• ghcr.io/xiaojiou176-open/apple-notes-forensics:0.1.0.post1

That is enough to prepare a Glama Add Server submission or a Docker-firstcatalog conversation. It is still not proof of a live Glama listing until freshGlama-side read-back exists.

Use the dedicated builder notes in INTEGRATIONS.md and theecosystem binding matrix in ECOSYSTEM.md before you describethe repo as an integration substrate. Use DISTRIBUTION.mdwhen you need the exact claim boundary for Codex, Claude Code, OpenClaw, andthe MCP Registry.

Repo-native support cleanup

This repository now ships a small repo-native cleanup lane for local release andrewrite residue. Use it when you want to reclaim repo-local staging artifactswithout touching copied evidence, output/, Docker state, browser profiles, orshared machine caches.

python scripts/ops/clean_support_state.py --dry-run
python scripts/ops/clean_support_state.py --apply

Current cleanup classes include:

• .runtime-cache/pypi-release
• .runtime-cache/history-rewrite-*
• .runtime-cache/release
• .runtime-cache/pypi-publish-attempt-*
• .runtime-cache/lighthouse-pages*
• .runtime-cache/security-audit
• .runtime-cache/temp
• .runtime-cache/dist-bundles
• .runtime-cache/*starter*.zip
• .runtime-cache/verify-*
• .runtime-cache/gitleaks-*.json

Treat this as a maintainer-only lane. It is for support residue, not for copiedevidence or public proof assets.

Plugin Contract And Case Diff

Two previously parked operator utilities are now first-class repo-sidesurfaces:

• notes-recovery plugins-validate --config <plugins.json>
  • validates the local plugin contract before you trust optional external tools
  • reports contract failures, placeholder commands, and host dependency gaps
• notes-recovery case-diff --dir-a <case-root> --dir-b <case-root>
  • compares two case roots at the manifest and derived review-surface layer
  • stays on case-level manifests and review artifacts instead of diffing raw copied evidence

Current Public Truth

The GitHub repository page and the root-level contract files are the currentpublic truth for this project.

Use DISTRIBUTION.md as the later-lane ledger for package, registry, plugin,Docker, and Glama details. Those surfaces are real, but they should not replacethe copy-first local lab story in the first paragraph a reviewer reads.

Right now:

• a public-safe demo is available in this repository
• the GitHub Release page and the GitHub Pages landing are the main publicproof surfaces around the repo
• fresh distribution read-back exists for the MCP package lane, the PyPIpackage lane, and the secondary ClawHub skill packet; keep those as supportreceipts instead of the first sentence a new reviewer sees
• llms.txt, robots.txt, and sitemap.xml now expose the current public contract to AI crawlers and search engines without pretending the repo is an API platform
• GitHub description, topics, and custom social preview status should be treatedas GitHub Settings items, not repository facts

Use CHANGELOG.md for tracked milestone history and theReleasespage for the published GitHub release feed and the synthetic public demo bundle.

The current repo-owned public contract is:

• README and root-level contract files are current
• the GitHub Pages landing should match the same shipped story as the READMEhero
• llms.txt, robots.txt, and sitemap.xml are repo-owned public contractfiles, not platform-acceptance receipts
• llms.txt is now the fastest AI-crawler / agent-reader entrypoint for the current shipped public contract
• custom social preview still requires a GitHub Settings upload plus RESTopen_graph_image_url read-back before you claim a custom card is live

Trust Surface

Supported boundary

• Host OS: macOS
• Workflow style: local forensic workflow on copies, not live in-place editing
• Core rule: do not operate on the original live Notes store

Public contract files

The root-level public contract for this repository is intentionally narrow:

• README.md
• CONTRIBUTING.md
• SECURITY.md
• SUPPORT.md
• LICENSE
• CODEOWNERS
• AGENTS.md
• CLAUDE.md
• .env.example

Baseline verification contract

The repository keeps a narrow baseline smoke contract that matches the hostedbaseline lane, not the entire CI matrix. The canonical baseline smoke and fullsuite commands live inCONTRIBUTING.md so the public front door stays brief whilethe detailed verification contract stays in one place.

That baseline smoke proves:

• the installed CLI entrypoint resolves correctly
• the public-safe demo surface prints a non-empty first-look narrative
• the core .[dev] pipeline surface runs on macOS in CI

Tracked public proof should come from one of two places only:

• the synthetic demo resources shipped under notes_recovery/resources/demo/
• a redacted bundle generated with notes-recovery public-safe-export

Hosting audit boundary

Public release readiness is not just about the current working tree. Therepository audit explicitly reviews git history, pull request diffs, forks,mirrors, downloaded clones, branch protection, required pull request reviews,secret scanning, and hosting settings for the xiaojiou176-open canonicalrepository.

Use scripts/ci/check_release_readiness.py --strict instead of assuming thoseopen-source boundary checks are still current from memory.

Runtime hygiene boundary

This public front door is relocation-safe at the repo level, but it isnot environment-agnostic at the host level because the supported workflowstill assumes macOS and copied Apple Notes evidence.

Treat the root-level files as the active repository contract and therepository root as the stable control surface for commands, review notes,and public-safe demo artifacts.

Tracked runtime artifacts do not belong in the public tree. examples/ is intentionally excluded, and .runtime-cache/ remains a reserved, non-public staging area for local support work instead of published proof.

The local .venv/ directory is a repo-local rebuildable developer surface.Treat it like a reusable tool belt, not like source or forensic evidence:

• it is safe to remove when you explicitly want to reclaim local disk
• it must not be committed
• deleting it means you must recreate it with the documented development setupbefore running repo checks again

Repo-local rebuildable tooling follows the same boundary:

• .venv/ is a local support surface, not repository truth
• deleting .venv/ is a safe local maintenance action when you intend torecreate the development environment
• recreate it with python -m venv .venv plus python -m pip install -e .[dev]

Optional Surfaces

Optional surfaces remain opt-in:

• .[ai] for local AI-assisted review via Ollamaor explicit cloud opt-in via OpenAI
• .[mcp] for the local read-mostly MCP server
• .[dashboard] for the Streamlit review cockpit, case-root selection, and bounded case-diff view
• .[carve] for deeper payload carving support

Do not assume one mixed environment is the canonical developer contract.

Install them explicitly when you need those extras:

python -m pip install -e .[ai]
python -m pip install -e .[mcp]
python -m pip install -e .[dashboard]
python -m pip install -e .[carve]

If you want the richer local review cockpit for one case root:

python -m pip install -e .[dashboard]
forensics-dashboard

The dashboard and carve surfaces stay visible, but they are not part of thedefault baseline guarantee.

AI review is also boundary-aware:

• notes-recovery ai-review --demo works on tracked synthetic review artifacts
• notes-recovery ask-case --demo ... stays on tracked synthetic review artifacts
• real-case AI review reads derived outputs from an existing case root
• real-case ask-case cites derived artifacts instead of returning an unsupported freeform answer
• the first real provider is local-first via Ollama
• the cloud-backed OpenAI path requires explicit opt-in via --allow-cloud
• it is not part of the default baseline guarantee

The MCP surface is also boundary-aware:

• notes-recovery-mcp starts with local stdio transport
• it exposes case-centric resources and bounded derived-output tools
• it does not default to broad filesystem browsing or live-store actions
• it is not part of the default baseline guarantee

Some workflows also rely on opt-in integrations such as docker,sqlite_dissect, strings, and binwalk. Those remain optional local tools,not part of the default baseline guarantee.

For deeper changes, use the broader full suite engineering sweep documented inCONTRIBUTING.md. That full suite signal remains usefulengineering coverage, but it is not the default baseline CI guarantee.

Public-Safe Export

Use notes-recovery public-safe-export --dir <case-root> --out ./output/public_safe_bundlewhen you need a shareable review bundle from an existing case root. The exportis intentionally metadata-focused:

• it redacts host-specific runtime fields and absolute paths
• it keeps the original forensic-local case root unchanged
• it omits raw evidence-heavy directories from the public-safe bundle

Repository Links

• Landing page
• LLMs guide
• Changelog
• Use Cases
• Ecosystem Fit
• Builder Guide
• Issue tracker
• Support guide
• Security policy
• Contributing guide

Why Star

Star this repository if you want a copy-first Apple Notes recovery workflowwith reviewable case outputs, a public-safe demo, and a tighter trust surfacethan an ad hoc “open the SQLite file and hope” approach.