Apple Notes Forensics MCP Server

NoteStore Lab

apple-notes-forensics is the repository. NoteStore Lab is the public product name for the same copy-first Apple Notes recovery lab.

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

Short copy-first path: notes-recovery demo -> 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 case root, and reviewable outputs for backup, recovery, verification, and reports.

At A Glance

If you want the shortest truthful filter before reading deeper, use this table:

Start Here

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

notes-recovery demo
notes-recovery doctor

What this short path proves in under five minutes:

• one timestamped case root instead of ad hoc loose files
• a zero-risk first look that does not touch private evidence or a live Notes store
• a host-readiness verdict before you move on to a real copied-evidence run

If you want the second-ring synthetic review lane after that, continue with:

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

That second ring proves bounded AI review and evidence-backed case questioning on the same synthetic case root.

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

Open the right next door after that first pass:

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 review surface
• Secondary: public-skills/notestorelab-case-review/ as the standalone pure_skills packet for host-native reviewers; its secondary ClawHub packet listing 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 makes sense
• Current non-claims: no hosted Notes recovery service, no multi-tenant review portal, and no live OpenHands/extensions/Glama/Docker catalog listing language in the front-door sentence
• Current review tail: OpenHands/extensions is submission-done with changes requested, so keep that lane in platform review until a live read-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 external boundary, 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 forensic workbench 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 copied evidence 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 with cited derived surfaces
• notes-recovery doctor tells you whether the host is ready for a real copied-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, and bounded 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 the standard copied-evidence workflow, whether you should stay on demo, or whether 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 not default to uploading raw copied evidence or the live Notes store to a cloud provider.

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 the optional 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 browse multiple case roots, preview the review index and AI outputs, inventory derived resources, and render a bounded case-diff summary without turning the repo into 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 documented in 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 is real and useful, but it is not the front-door sentence a new reviewer should use 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 the shared read layer
• use notes-recovery-mcp when you want a case-root-centric tool/resource interface instead of scraping files ad hoc

If your local coding-agent host supports stdio MCP servers, the stable command to 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 the same: local stdio, read-mostly, case-root-centric.

If you want copy-paste-safe wrapper sketches, the builder guide and shipped distribution 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 executable contract without claiming a live listing

Those public-ready surfaces live under plugins/, .claude-plugin/, and server.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 descriptor around the same local stdio case-review workflow. Package publication, registry read-back, and marketplace/manual submission status can drift over time, so this README keeps the primary story on the local bench first. Use DISTRIBUTION.md when you need the later-lane claim boundary.

The repository now also ships a canonical independent skill surface at skills/notestorelab-case-review/. Treat that directory as the SSOT skill package, and treat the plugin/starter skill files as host-specific derived copies. That makes the skill independently referenceable without pretending it has already cleared any external directory gate.

For OpenHands/extensions and ClawHub-style submissions, the repo now also ships an OpenHands/extensions-friendly public skill folder at public-skills/notestorelab-case-review/. Treat that packet as the portable listing lane, while skills/notestorelab-case-review/ remains the canonical skill text.

When you want the repo-side metadata/build-readiness gate before the next PyPI version 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-root workflow
• 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, not an 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-first catalog conversation. It is still not proof of a live Glama listing until fresh Glama-side read-back exists.

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

Repo-native support cleanup

This repository now ships a small repo-native cleanup lane for local release and rewrite residue. Use it when you want to reclaim repo-local staging artifacts without touching copied evidence, output/, Docker state, browser profiles, or shared 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 copied evidence or public proof assets.

Plugin Contract And Case Diff

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

• 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 current public 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 replace the 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 public proof surfaces around the repo
• fresh distribution read-back exists for the MCP package lane, the PyPI package lane, and the secondary ClawHub skill packet; keep those as support receipts 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 treated as GitHub Settings items, not repository facts

Use CHANGELOG.md for tracked milestone history and the Releases page 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 README hero
• llms.txt, robots.txt, and sitemap.xml are repo-owned public contract files, 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 REST open_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 hosted baseline lane, not the entire CI matrix. The canonical baseline smoke and full suite commands live in CONTRIBUTING.md so the public front door stays brief while the 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. The repository 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 canonical repository.

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

Runtime hygiene boundary

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

Treat the root-level files as the active repository contract and the repository 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 setup before 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 to recreate 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 Ollama or 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 the default 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 in CONTRIBUTING.md. That full suite signal remains useful engineering 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_bundle when you need a shareable review bundle from an existing case root. The export is 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 workflow with reviewable case outputs, a public-safe demo, and a tighter trust surface than an ad hoc “open the SQLite file and hope” approach.