Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

Songe: a bed on the moon, and the command pip install songe

Songe

A local model that learns from how you use it.

Use your model as usual through opencode, pi or any OpenAI-compatible tool. When your agent is quiet, Songe looks at what happened after each of the model's actions — the tool result, the error, your next message — and teaches the model to see it coming. A new version is used only if it passes checks. Nothing leaves your machine.

Install

macOS with Homebrew:

brew install sous-labs/tap/songe
songe init

Or with pip (Python 3.11 or later; with Homebrew's Python use pipx install songe):

pip install songe
songe init

songe init finds your model server and your agents, shows what it will change, and asks once. Then pick a songe/… model in your agent. In opencode, a local default model switches over automatically.

Needs a model served locally by LM Studio, Ollama, llama.cpp, mlx-lm or vLLM. Learning runs on Apple Silicon (MLX); Linux and Windows with NVIDIA or AMD are supported but less tested. Machines without a GPU still serve and record.

Use

Use your agent as usual. Songe learns in Dreams:

  • Quick Dream (a few minutes): reads your newest conversations and adds the preferences you stated or showed ("always use pnpm", "put my name at the top of the script") to the model's instructions right away. It shows what it added, with a before/after where the answer changes.
  • Deep Dream (an hour or more): writes practice from those lessons, trains a small adapter on it, and checks the result on your conversations before using it. If it is not clearly better, nothing changes, and the report says why.

With auto-dream on, Dreams start when your agent has been quiet for a while and stop the moment you use it again. Or press Dream in the dashboard. A Dream never just disappears: it keeps going on the page or says why it stopped.

songe          # what it is doing
songe open     # dashboard in your browser
songe models   # each model, and whether it dreams on its own

To change things:

songe models MODEL on|off   # auto-dream for one model
songe undo MODEL            # go back one version
songe pause
songe resume
songe sleep                 # start a Deep Dream now
songe doctor                # check the setup
songe forget                # delete recorded conversations (learned versions stay)

How it learns

  • Reading. Songe reads each conversation for the moments that teach something: your corrections and stated rules, retries, tool errors.
  • Practice. For each lesson your model writes short practice scenes in your agent's own tools. Your real conversations are never trained on.
  • Training. The model as it was, shown the lesson, is the teacher; the same model with a small adapter, shown only the scene, is the student (on-policy distillation). Earlier skills are rehearsed so they stay.
  • Checking. At the moments you reacted to, the version in use and the new one each answer; a judge compares what they do. The new version is used only if it does clearly better, does not change what already worked, and its answers stay healthy.

Songe never runs your tools. It only reads what already happened.

When it runs

Only when your agent is quiet, there is enough free memory, the battery is not low and the machine is cool. Before the first training Songe measures how much your computer can learn at once. When you come back it stops at once, saves its place and continues later.

What it changes

  • Its data folder: ~/Library/Application Support/songe on macOS, $XDG_DATA_HOME/songe on Linux, %LOCALAPPDATA%\songe on Windows.
  • A songe/ folder in LM Studio's models folder with the current learned version. Older versions are rebuilt when you return to them. Your own models are never touched.
  • One provider entry in opencode and pi, with a backup.
  • A background service that starts at login.

No account, no notifications.

Upgrade and remove

brew upgrade songe or pip install -U songe: the service moves to the new version by itself in a quiet moment.

songe uninstall stops the service and restores your agent settings; add --purge to also delete its data and learned versions. Run it before brew uninstall songe.


Details and development: docs/DEVELOPMENT.md. Design: DESIGN.md.

License

Apache-2.0.

Metadata

Release files for songe 0.1.0a13

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for songe 0.1.0a13
File Size Uploaded Provenance Actions
songe-0.1.0a13.tar.gz 824.6 kB With provenance Details for songe-0.1.0a13.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for songe 0.1.0a13
File Interpreter ABI Platform Actions
songe-0.1.0a13-py3-none-any.whl Python 3 none any Details for songe-0.1.0a13-py3-none-any.whl

Total release size: 1.3 MB

Release files / songe-0.1.0a13.tar.gz

Download URL songe-0.1.0a13.tar.gz
Size 824.6 kB
Tags Source
SHA-256 checksum
How to use checksums
33697e94ab7086c1c24b27cdd893d9c37ff80b622bb4fa4efde8ce8ba02bbf21
BLAKE2b-256 checksum
How to use checksums
6bcf8df93b7c72cf50f557d8787c9e829f28b09de0dd4bc05bb4a578f198ddb5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / songe-0.1.0a13-py3-none-any.whl

Download URL songe-0.1.0a13-py3-none-any.whl
Size 501.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4383761198319984b6fbfdecefaabd24de3297cee9cc2f2a4003de446818d759
BLAKE2b-256 checksum
How to use checksums
126ab87702d8c977b7890afeb04e26c0fa9693eecf15201078291def5a3d37cd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for songe 0.1.0a13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for songe-0.1.0a13.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page