my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

#1	# Updating Mnemosyne
#2
#3	Mnemosyne can be installed from PyPI or from source. This guide covers both paths.
#4
#5	---
#6
#7	## Quick Reference
#8
#9	\| What changed \| User action \|
#10	\|---\|---\|
#11	\| PyPI update (new version) \| `pip install --upgrade mnemosyne-memory` + restart Hermes \|
#12	\| Pure Python fix/feature (source) \| `git pull` + restart Hermes \|
#13	\| New dependency / entry point (source) \| `git pull` + `pip install -e .` + restart Hermes \|
#14	\| New CLI command (source) \| `git pull` + `pip install -e .` + restart Hermes \|
#15	\| Database schema \| `git pull` + `migrate_from_legacy.py` + restart Hermes \|
#16	\| `plugin.yaml` / tool schema \| Restart Hermes only \|
#17
#18	---
#19
#20	## By Install Path
#21
#22	### Option A: PyPI (recommended for users)
#23
#24	```bash
#25	pip install --upgrade mnemosyne-memory
#26	hermes gateway restart
#27	```
#28
#29	To verify the new version:
#30
#31	```bash
#32	hermes mnemosyne version
#33	hermes mnemosyne stats --global
#34	hermes memory status
#35	```
#36
#37	### Option B: Full install from source (`pip install -e .`)
#38
#39	For most updates, only `git pull` is required because the editable install symlinks the source:
#40
#41	```bash
#42	cd mnemosyne
#43	git pull
#44	hermes gateway restart
#45	```
#46
#47	Re-run `pip install -e .` only when:
#48	- `setup.py` or `pyproject.toml` added new dependencies
#49	- New `entry_points` or console scripts were added
#50	- Package metadata changed
#51
#52	```bash
#53	git pull
#54	pip install -e ".[all,dev]"
#55	hermes gateway restart
#56	```
#57
#58	Re-run the installer only when `mnemosyne/install.py` or the symlink logic changed:
#59
#60	```bash
#61	git pull
#62	python -m mnemosyne.install
#63	hermes gateway restart
#64	```
#65
#66	### Option C: Hermes MemoryProvider only (deploy script)
#67
#68	This path symlinks `~/.hermes/plugins/mnemosyne` directly into the repo, so code changes are immediate:
#69
#70	```bash
#71	cd mnemosyne
#72	git pull
#73	hermes gateway restart
#74	```
#75
#76	No `pip install` is ever needed for this path because nothing is installed into a Python environment.
#77
#78	---
#79
#80	## Database Migrations
#81
#82	Mnemosyne uses SQLite with `CREATE TABLE IF NOT EXISTS` and `CREATE INDEX IF NOT EXISTS`, so most schema changes upgrade automatically on the next run. No user action required.
#83
#84	Run the migration script only when:
#85	- The update mentions a database schema change
#86	- You are upgrading from a pre-1.0 version
#87	- You see errors about missing columns or tables
#88
#89	```bash
#90	# Preview first
#91	python scripts/migrate_from_legacy.py --dry-run
#92
#93	# Apply
#94	python scripts/migrate_from_legacy.py
#95	```
#96
#97	The migration script is idempotent — safe to run multiple times.
#98
#99	---
#100
#101	## Rollback
#102
#103	If an update breaks something, roll back to the last known good version:
#104
#105	```bash
#106	# Check out the previous version
#107	git log --oneline -5
#108	git checkout <previous-commit-or-tag>
#109
#110	# If you changed setup.py, re-install
#111	pip install -e .
#112
#113	# Restart Hermes
#114	hermes gateway restart
#115	```
#116
#117	If you exported a backup before updating, restore it:
#118
#119	```bash
#120	hermes mnemosyne import --input mnemosyne_backup.json
#121	```
#122
#123	Or copy the SQLite file directly:
#124
#125	```bash
#126	cp ~/backups/mnemosyne_20260101.db ~/.hermes/mnemosyne/data/mnemosyne.db
#127	```
#128
#129	---
#130
#131	## Verifying an Update
#132
#133	After updating, confirm the new version is active:
#134
#135	```bash
#136	hermes mnemosyne version
#137	hermes mnemosyne stats
#138	hermes mnemosyne stats --global
#139	hermes memory status
#140	```
#141
#142	Check that tools are registered:
#143
#144	```bash
#145	hermes tools list \| grep mnemosyne
#146	```
#147
#148	---
#149
#150	## Troubleshooting
#151
#152	### "Command not found" after update
#153
#154	You added a new CLI command but didn't re-run `pip install -e .`. Entry points are registered at install time, not at runtime.
#155
#156	```bash
#157	pip install -e .
#158	```
#159
#160	### "No module named mnemosyne" after update
#161
#162	Your virtual environment may have been deactivated or the editable install broke. Re-install:
#163
#164	```bash
#165	pip install -e .
#166	```
#167
#168	### Plugin changes not taking effect
#169
#170	Hermes caches plugins at startup. You must restart:
#171
#172	```bash
#173	hermes gateway restart
#174	```
#175
#176	### Database errors after schema change
#177
#178	Run the migration script:
#179
#180	```bash
#181	python scripts/migrate_from_legacy.py
#182	```
#183
#184	If errors persist, export your data, delete the database, and re-import:
#185
#186	```bash
#187	hermes mnemosyne export --output backup.json
#188	rm ~/.hermes/mnemosyne/data/mnemosyne.db
#189	hermes mnemosyne import --input backup.json
#190	```
#191

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public