Skip to content
YoMemo YoMemo

CLI Integration

yomemo-cli is the general command‑line toolkit for the YoMemo ecosystem.

The first capability it provides is a local sync bridge: it scans your local Markdown knowledge base (for example, an Obsidian vault), encrypts each note end‑to‑end on your machine, and uploads it to YoMemo so your AI tools can query it securely.

In short: you can safely sync private content like journals, medical notes, or any sensitive information — everything is encrypted client‑side before upload.

When to use the CLI

Section titled “When to use the CLI”

Use yomemo-cli when:

  • You already store knowledge in local Markdown files (Obsidian, Logseq, plain folders, etc.)
  • You want that knowledge available to your AI agents/tools via YoMemo
  • You care about zero‑trust encryption: all content is encrypted on your machine using your own key before it touches the cloud

If you want direct SDK or MCP integrations instead, see:

Prerequisites

Section titled “Prerequisites”

Before you begin, make sure you have:

  • Python 3.9+ installed

  • A YoMemo API key

  • An RSA private key in PEM format (2048‑bit recommended)

    • Example (OpenSSL):
    Terminal window
    openssl genrsa -out private.pem 2048

Installation

Section titled “Installation”

Install the CLI from PyPI:

Terminal window
pip install yomemo-cli

This will install a yomemo command on your system:

Terminal window
yomemo --help

You should see the available subcommands:

  • yomemo init
  • yomemo sync
  • yomemo status

Quick Start

Section titled “Quick Start”

  1. Initialize the CLI

    Run the init command to configure your API key and private key:

    Terminal window
    yomemo init

    You will be prompted for:

    • Your YoMemo API key
    • Path to your RSA private key file (PEM), e.g. ~/keys/private.pem

    The CLI will create a config directory and store your settings:

    • Config directory: ~/.yomemo/
    • Env file: ~/.yomemo/.env

  2. Run a one‑off sync

    To sync a folder of Markdown notes:

    Terminal window
    # Example: sync an Obsidian vault
    yomemo sync ~/Documents/Obsidian/Vault
    

    # Example: sync a general notes folder
    yomemo sync ~/notes

    What happens:

    • Recursively walks the target directory
    • Ignores special folders like .git, .obsidian, node_modules
    • Processes only .md files (empty files are skipped)
    • Uses the parent directory name as the memory handle:
      • Vault/work/note.md → handle work
      • Top‑level files → handle general
    • Encrypts each note and uploads it to YoMemo
    • Records a hash + memory ID in a local SQLite database to avoid re‑uploading unchanged files

  3. Enable real‑time sync

    If you want YoMemo to track changes live while you edit notes, use watch mode:

    Terminal window
    yomemo sync ~/Documents/Obsidian/Vault --watch
    # or
    yomemo sync ~/Documents/Obsidian/Vault -w

    Behavior:

    • Performs a full scan once at startup
    • Starts a filesystem watcher (using watchdog)
    • On file create/modify events:
      • Re‑runs the sync logic for that file
    • Runs until you press Ctrl + C

    This is ideal if you keep an Obsidian vault open and want YoMemo to stay in sync automatically.

  4. Check sync status

    To see what has been synced:

    Terminal window
    yomemo status

    This prints a small dashboard showing:

    • Total number of synced files
    • Last sync time
    • Local index (SQLite DB) size
    • Config file location

How it works

Section titled “How it works”

At a high level:

  1. Local scan + hashing

    • The CLI walks your notes directory
    • Computes a content hash for each Markdown file
    • Compares it to the last known hash in sync_state.db
    • Only changed or new files are uploaded

  2. Client‑side encryption

    • Content is encrypted on your machine using AES‑GCM
    • The AES key is encrypted with RSA‑OAEP using your public key
    • The encrypted package is signed with your private key
    • Only the encrypted payload + metadata are sent to the YoMemo API

  3. Mapping to YoMemo memories

    • Each file becomes an encrypted memory in YoMemo
    • Handles are derived from directory names (e.g. work, personal)
    • Metadata includes the original relative path and token size

On the YoMemo side, this looks just like any other encrypted memory: your AI tools can retrieve and decrypt it using your configured keys (via MCP, SDKs, etc.).

Configuration details

Section titled “Configuration details”

After running yomemo init, the CLI writes an env file:

~/.yomemo/.env
MEMO_API_KEY=your_api_key_here
MEMO_PRIVATE_KEY_PATH=/absolute/path/to/private.pem

You normally don’t have to edit this manually, but it’s useful to know where it lives.

Example workflows

Section titled “Example workflows”

  • Obsidian vault → YoMemo → MCP

    • Use yomemo sync —watch to keep your Obsidian vault in sync
    • Use the Python MCP integration to let your AI assistant query those memories

  • Project docs as memory

    • Point yomemo sync at a project docs/ folder
    • Use handles like project-x, infra, runbooks (derived from directories)
    • Ask your AI tools questions like “What does the deployment pipeline look like for project X?”

Troubleshooting

Section titled “Troubleshooting”

“Not initialized” error

Section titled ““Not initialized” error”

If you see:

Error: configuration not detected. Please run 'yomemo init' to initialize.

Run:

Terminal window
yomemo init

and make sure ~/.yomemo/.env exists afterwards.

Private key read errors

Section titled “Private key read errors”

If the CLI cannot read your private key:

  • Double‑check the path you entered in yomemo init
  • Ensure the file exists and is readable (permissions like 600 are recommended)
  • Verify the file is a valid PEM‑encoded private key

API or network issues

Section titled “API or network issues”

If API calls fail:

  • Verify your API key is correct and active
  • Ensure you can reach https://api.yomemo.ai from your machine
  • Re‑run with verbose logging (coming in future versions of the CLI)

Next steps

Section titled “Next steps”