docs: align examples with current CLI and API

[kohai-ut]

Summary

This is a docs-only synchronization pass to make the README and docs match the behavior currently exposed by the codebase.

The main goal is to remove stale examples that would fail for users today, while keeping the scope limited to documentation. I intentionally avoided packaging or implementation changes here so this can be reviewed independently from code-behavior PRs.

What changed

Replaced stale REST API references with MCP server documentation

The docs previously described an optional REST API / standalone memory server, including examples such as:

python mnemosyne/cli.py server

I could not find a current server command in the CLI. The exposed integration path is now the MCP server, so the docs now show:

mnemosyne mcp
mnemosyne mcp --transport sse --port 8080

I also added explicit wording that Mnemosyne does not currently expose a standalone REST API server, to avoid implying there is a missing command users should be able to run.

Files touched:

• README.md
• docs/api-reference.md
• docs/architecture.md
• docs/hermes-integration.md

Corrected CLI examples for Hindsight imports

The README previously showed Hindsight import examples through the generic Hermes import command with flags such as --file and --bank:

hermes mnemosyne import --from hindsight --file hindsight-export.json --bank hermes

The current CLI exposes Hindsight import through the standalone command added for that importer:

mnemosyne import-hindsight hindsight-export.json hermes
mnemosyne import-hindsight http://localhost:8888 hermes

So the README examples now use that command instead of unsupported Hermes CLI flags.

Corrected API reference drift

Updated docs/api-reference.md to match the current Python API surface, including:

• Mnemosyne(...) constructor arguments (session_id, db_path, bank, author_id, author_type, channel_id)
• get_context(limit=...) returning recent working-memory dictionaries rather than a formatted query-based string
• scratchpad methods:
  • scratchpad_write(content)
  • scratchpad_read()
  • scratchpad_clear()
• importer registry name from PROVIDER_REGISTRY to PROVIDERS

I also clarified that bank=None in the module-level helper signatures applies to the module-level convenience functions; instance methods use the bank configured on the Mnemosyne(...) instance.

Corrected provider count and importer wording

The docs now consistently refer to 7 supported import providers:

• Mem0
• Letta
• Zep
• Cognee
• Honcho
• SuperMemory
• Hindsight

I kept the generic Hermes CLI examples to options currently exposed by that CLI. Where provider-specific importer options exist in Python but are not exposed through the generic Hermes command, I added clarifying wording instead of documenting unsupported CLI flags. For example, offline Letta AgentFile import is now mentioned as a Python importer option:

LettaImporter(agent_file_path="./agent.af")

Clarified SQLite storage / backup wording

The README and installation guide previously implied everything lived in a single SQLite file. The current layout can include:

• the main database at ~/.hermes/mnemosyne/data/mnemosyne.db
• named bank databases under ~/.hermes/mnemosyne/data/banks/<name>/
• standalone triple-store files such as triples.db

The backup example now copies the full Mnemosyne data directory rather than only the top-level mnemosyne.db.

Updated Hermes plugin tool list

docs/hermes-integration.md now includes the registered diagnostic tool:

• mnemosyne_diagnose

What this PR intentionally does not change

• No Python code changes.
• No package metadata changes.
• No dependency changes.
• No attempt to add a mcp extra in pyproject.toml.
• No attempt to change NumPy behavior or dependency declarations. I saw that separate work is already underway for base-install / NumPy fallback behavior, so I left that out of this docs-only PR.
• No attempt to add Hermes CLI parity for provider-specific importer flags. This PR documents what appears to work today rather than changing CLI behavior.

Verification performed

• Checked the current CLI surface before replacing REST/Hindsight examples.
• Checked the public API signatures in mnemosyne/core/memory.py before updating API docs.
• Checked importer registry naming in mnemosyne/core/importers/__init__.py.
• Checked Hermes plugin tool registration before adding mnemosyne_diagnose.
• Ran:

git diff --check

No whitespace errors were reported.

Review notes

This is meant as PR 1 in a small sequence:

1. This PR: docs-only correction of stale examples and API references.
2. Possible follow-up: packaging/docs alignment for optional MCP dependencies if desired.
3. Possible follow-up: provider-specific Hermes CLI importer options, if the project wants CLI parity for options that currently exist only in the Python importers.

[AxDSan]

Approved for merge. Docs-only change, zero code risk.