my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

#1	# Changelog
#2
#3	All notable changes to this project will be documented in this file.
#4
#5	The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
#6	and this project adheres to [Simple Versioning](https://github.com/AxDSan/mnemosyne) (MAJOR.MINOR).
#7
#8	## [2.5] — 2026-05-10
#9
#10	### Added
#11
#12	NAI-0 Algorithmic Sprint
#13	- `BeamMemory.format_context(results, format="bullet"\|"json")` — structured context formatting
#14	- `BeamMemory._sandwich_order()` — U-shaped attention ordering (high-first, medium-middle, high-last)
#15	- `BeamMemory._fact_line()` — clean one-line fact format with date, source, confidence
#16	- `BeamMemory._format_context_json()` / `_format_context_bullet()` — JSON and markdown output
#17	- RRF (Reciprocal Rank Fusion) in `PolyphonicRecallEngine._combine_voices()` with k=60 constant
#18	- Covering indexes: `idx_em_scope_imp`, `idx_wm_session_recall`, `idx_mem_emb_type`
#19	- `tools/bench_nai0.py` — minimal 20-question benchmark for quick before/after measurement
#20
#21	Self-Healing Quality Pipeline (`scripts/heal_quality.py`, PR #67 by ether-btc)
#22	- Detects degraded episodic memory entries (bullet-format, <300 chars) and repairs them via a 4-stage LLM-as-Judge closed loop: Extract → Generate → Judge → Repair
#23	- Fault taxonomy: `truncated`, `generic`, `missing_facts`, `wrong_format`
#24	- Judge scores 4 dimensions (factual density, format compliance, length sufficiency, grounding) each 0-100
#25	- Repair strategies are fault-specific: context doubling, specificity enforcement, fact injection, format rewrite
#26	- Loop with `MAX_RETRIES` (default 3) and automatic escalation to stronger model after 2 failures
#27	- Quality provenance in `metadata_json`: `quality_score`, `judge_model`, `consolidated_at`, `fault_before_repair`, `retry_loop_count`
#28	- Configurable via env: `MNEMOSYNE_HEAL_JUDGE_THRESHOLD`, `MNEMOSYNE_HEAL_MAX_RETRIES`, `MNEMOSYNE_HEAL_MIN_LEN`, `MNEMOSYNE_HEAL_BUDGET`, `MNEMOSYNE_HEAL_ESCALATE_AFTER`
#29	- Works with any LLM backend (MiniMax M2.7 via mmx-cli, local GGUF, or remote OpenAI-compatible API)
#30	- CLI: `python scripts/heal_quality.py [--detect-only] [--entry-id ID] [--dry-run]`
#31
#32	Chunked LLM Summarization (`mnemosyne/core/local_llm.py`)
#33	- Splits large memory lists into context-window-sized chunks before summarization
#34	- Two-pass: summarize each chunk individually, then consolidate chunk summaries
#35	- Fixes truncation issues with smaller models (Qwen2.5-1.5B) on large sessions
#36
#37	### Changed
#38	- `BeamMemory.recall()` default `top_k`: 5 → 40
#39	- Polyphonic recall voice combination: weighted average → position-based RRF
#40	- `mnemosyne/__init__.py`: version bump to 2.5.0
#41
#42	## [2.4] — 2026-05-07
#43
#44	### Added
#45
#46	Hindsight Importer — migrate FROM Hindsight INTO Mnemosyne
#47	- New `HindsightImporter` class in `mnemosyne/core/importers/hindsight.py`
#48	- Import from Hindsight JSON exports OR live Hindsight HTTP API (`/v1/default/banks/{bank}/memories/list`)
#49	- Writes directly to `episodic_memory` (not working memory) — preserves original timestamps, fact types, session grouping, metadata, scope, and veracity
#50	- Stable duplicate skipping via SHA256-based IDs (`hs_` prefix)
#51	- Importance scoring derived from Hindsight `fact_type` (world=0.75, experience=0.65, observation=0.55) + proof_count bonus
#52	- Full metadata preservation: hindsight_id, fact_type, context, dates, entities, chunk_id, tags, consolidation timestamps
#53	- CLI: `mnemosyne import-hindsight <file.json\|url> [bank]`
#54	- Registered in provider registry alongside Mem0, Letta, Zep, Cognee, Honcho, SuperMemory
#55	- 102 lines of regression tests: timestamp preservation, episodic-only import, stable duplicate skipping, FTS indexing, provider-registry usage
#56
#57	Host LLM Adapter — route consolidation through Hermes' authenticated provider
#58	- New `mnemosyne/core/llm_backends.py` — tiny `LLMBackend` Protocol (one method: `complete()`), process-global registry, `CallableLLMBackend` dataclass for tests
#59	- New `hermes_memory_provider/hermes_llm_adapter.py` — `HermesAuxLLMBackend` routes through `agent.auxiliary_client.call_llm(task="compression", ...)`
#60	- `MnemosyneMemoryProvider.initialize()` registers the backend; `shutdown()` unregisters it with a brief drain for in-flight threads
#61	- `summarize_memories()` and `extract_facts()` consult host first when `MNEMOSYNE_HOST_LLM_ENABLED=true`
#62	- Host-skips-remote rule (A3): When host attempt produces no usable text, remote URL is skipped — falls straight to local GGUF. Prevents stale URL leaks.
#63	- `llm_available()` returns `True` when host backend is registered, so Hermes-only users don't get short-circuited by `beam.sleep()`
#64	- `on_session_end()` runs sleep in daemon thread with 15s join timeout; `shutdown()` drains 2s before unregistering
#65	- Fact extraction uses `temperature=0.0` for determinism; consolidation stays at `0.3`
#66	- 7 new tests covering registry round-trip, host-route precedence, A3 skip-remote rule, gate semantics, shutdown drain race, daemon exception logging, bullet-list output preservation
#67	- Live end-to-end verified with `openai-codex` OAuth subscription through ChatGPT backend
#68
#69	### Why this matters
#70
#71	Hindsight importer: Before this, migrating FROM Hindsight required going through `remember()`, which assigned current timestamps and wrote to working memory. Historical memories lost their original context. Now Hindsight migrations preserve the full temporal record with zero data loss.
#72
#73	Host LLM adapter: Hermes users on OAuth-backed providers (ChatGPT/Codex subscriptions) could not use Mnemosyne's LLM-backed operations because `MNEMOSYNE_LLM_BASE_URL` expects an OpenAI-compatible API key endpoint, not OAuth. Now they can route through Hermes' already-authenticated auxiliary client with zero extra credentials.
#74
#75	---
#76
#77	## [2.3.1] — 2026-05-06
#78
#79	### Fixed
#80
#81	- Auto-sleep consolidation blocks TUI agent: `_maybe_auto_sleep()` now runs in a background thread with a 5-second timeout instead of synchronously. Local LLM summarization (ctransformers) can no longer hang the agent worker thread. (#23)
#82	- `MNEMOSYNE_AUTO_SLEEP_ENABLED` env var now controls auto-sleep behavior. Default is `false` (disabled) for interactive safety. Set to `true` to re-enable.
#83	- Config schema updated to reflect new default.
#84
#85	## [2.3] — 2026-05-05
#86
#87	### Added
#88
#89	Tiered Episodic Degradation — long-term recall without unbounded growth
#90	- Three degradation tiers: Tier 1 (0-30d, full detail), Tier 2 (30-180d, LLM-compressed), Tier 3 (180d+, entity-extracted signal)
#91	- Automatic tier promotion during `sleep()` — no manual maintenance
#92	- Tier multipliers in recall scoring: cold memories need 4x stronger semantic match
#93	- Configurable via `MNEMOSYNE_TIER2_DAYS`, `MNEMOSYNE_TIER3_DAYS`, `MNEMOSYNE_TIER*_WEIGHT`
#94	- Mnemonics can now truthfully claim "remembers what you told it a year ago"
#95
#96	Smart Compression — entity-aware tier 2→3 extraction
#97	- `_extract_key_signal()` scores sentences by entity density (proper nouns, acronyms, security terms, tech stack, urgency)
#98	- Preserves facts buried anywhere in a long memory, not just the first sentence
#99	- Configurable: `MNEMOSYNE_SMART_COMPRESS=1` (default on), `MNEMOSYNE_TIER3_MAX_CHARS=300`
#100
#101	Memory Confidence — veracity signal for every memory
#102	- New `veracity` field: `stated`, `inferred`, `tool`, `imported`, `unknown`
#103	- `remember(veracity="stated")` — set confidence at write time
#104	- `recall(veracity="stated")` — filter by confidence level
#105	- Recall applies veracity multiplier to scores (stated=1.0x, inferred=0.7x, tool=0.5x)
#106	- `get_contaminated()` — surface non-stated memories for review
#107	- Configurable weights via `MNEMOSYNE_*_WEIGHT` env vars
#108
#109	### Fixed
#110	- `local_llm.summarize()` → `summarize_memories()` — would crash on LLM degradation path
#111	- SQLite connection conflicts in batch degradation tests
#112	- Removed hallucinated Phase 2 from roadmap
#113
#114	## [2.2] — 2026-05-02
#115
#116	### Added
#117
#118	Cross-Provider Importers — migrate from any memory platform
#119	- New `mnemosyne/core/importers/` module with 6 provider importers
#120	- Mem0: SDK pagination → REST → structured export fallback chain; preserves user/agent/app scoping
#121	- Letta (MemGPT): AgentFile `.af` format parsing (JSON/YAML/TOML); memory blocks → working_memory, messages → episodic
#122	- Zep: users → sessions → `memory.get()` per-session iteration; messages + summaries + facts extraction
#123	- Cognee: `get_graph_data()` nodes/edges extraction; nodes → episodic memories, edges → triples
#124	- Honcho: peers → sessions → `context()` + messages; peer identity preserved as author_id
#125	- SuperMemory: `documents.list()` + `search.execute()`; container tags mapped to channel_id
#126	- Agentic importer: generates ready-to-run Python migration scripts and AI agent instructions for all 6 providers
#127
#128	CLI: `hermes mnemosyne import` extended
#129	- `--from <provider>` — import directly from Mem0, Letta, Zep, etc.
#130	- `--list-providers` — show all supported providers with docs links
#131	- `--generate-script` — generate a migration script for any provider
#132	- `--agentic` — output instructions to give your AI agent for extraction
#133	- `--dry-run` — validate and transform without writing
#134
#135	Plugin tool updated
#136	- `mnemosyne_import` schema extended with `provider`, `api_key`, `user_id`, `agent_id`, `dry_run`, `channel_id` params
#137
#138	### Changed
#139
#140	- README: added "Migrate from other memory providers" section with examples
#141
#142	## [2.1] — 2026-05-02
#143
#144	### Added
#145
#146	Multi-Agent Identity Layer
#147	- New columns `author_id`, `author_type`, `channel_id` on `working_memory` and `episodic_memory` with indexes
#148	- `Mnemosyne(author_id=..., author_type=..., channel_id=...)` constructor params
#149	- `remember()` auto-populates identity columns from session context
#150	- `recall(author_id=..., author_type=..., channel_id=...)` filter params
#151	- `get_stats(author_id=..., author_type=..., channel_id=...)` filter params
#152	- Cross-session channel recall: when `channel_id` is provided, scope expands to include all memories in that channel regardless of session
#153	- MCP server: per-connection instances replace module-level cache; identity via tool args or env vars (`MNEMOSYNE_AUTHOR_ID`, `MNEMOSYNE_AUTHOR_TYPE`, `MNEMOSYNE_CHANNEL_ID`)
#154	- Hermes plugin `_get_memory()` reads identity from environment variables
#155
#156	### Changed
#157	- MCP `_get_instance()` renamed to `_create_instance()` — creates fresh instances per connection
#158	- Episodic memory SELECTs and recall-tracking UPDATEs use dynamic session/channel scope
#159
#160	## [2.0] — 2026-04-29
#161
#162	### Added
#163
#164	Phase 1: Entity Sketching
#165	- Regex-based entity extraction (`@mentions`, `#hashtags`, quoted phrases, capitalized sequences)
#166	- Pure-Python Levenshtein distance with O(min) space optimization
#167	- Fuzzy entity matching with prefix/substring bonuses and configurable threshold
#168	- `extract_entities=True` parameter on `remember()` — backward compatible, default False
#169
#170	Phase 2: Structured Fact Extraction
#171	- LLM-driven fact extraction via `extract_facts()` and `extract_facts_safe()`
#172	- Graceful fallback chain: remote OpenAI-compatible API → local ctransformers GGUF → skip
#173	- Fact parsing with numbering/bullet cleanup, length filter, cap at 5 facts
#174
#175	Phase 3: Temporal Recall
#176	- Exponential decay temporal scoring: `exp(-hours_delta / halflife)`
#177	- `temporal_weight`, `query_time`, `temporal_halflife` parameters on `recall()`
#178	- Environment variable `MNEMOSYNE_TEMPORAL_HALFLIFE_HOURS` for global default
#179	- Temporal boost applied across all recall tiers (working, episodic, entity, fact)
#180
#181	Phase 4: Configurable Hybrid Scoring
#182	- User-tunable scoring weights: `vec_weight`, `fts_weight`, `importance_weight`
#183	- `_normalize_weights()` with env var fallback and sensible defaults (50/30/20)
#184	- Per-query weight overrides without global state mutation
#185
#186	Phase 5: Memory Banks
#187	- `BankManager` class for named namespace isolation
#188	- Per-bank SQLite files under `banks/<name>/mnemosyne.db`
#189	- Bank operations: create, delete, list, rename, exists check, stats
#190	- `Mnemosyne(bank="work")` constructor parameter
#191	- Bank name validation (alphanumeric + hyphens/underscores, max 64 chars)
#192
#193	Phase 6: MCP Server
#194	- Model Context Protocol server with 6 tools
#195	- stdio transport (Claude Desktop, etc.) and SSE transport (web clients)
#196	- Per-bank instance caching
#197	- CLI entry: `mnemosyne mcp`
#198
#199	Phase 7: Hermes Agent Integration
#200	- 15 Hermes tools: remember, recall, stats, triple_add, triple_query, sleep, scratchpad_write/read/clear, invalidate, export, update, forget, import, diagnose
#201	- 3 lifecycle hooks: `pre_llm_call` (context injection), `on_session_start`, `post_tool_call`
#202	- AAAK compression for context injection
#203	- Session-aware memory instances
#204
#205	Phase 8: v2 Differentiation
#206	- `MemoryStream` — push (callbacks) and pull (iterator) event stream, thread-safe
#207	- `DeltaSync` — checkpoint-based incremental synchronization between instances
#208	- `MemoryCompressor` — dictionary-based, RLE, and semantic compression
#209	- `PatternDetector` — temporal (hour/weekday), content (keyword, co-occurrence), sequence patterns
#210	- `MnemosynePlugin` ABC with 4 lifecycle hooks
#211	- `PluginManager` with auto-discovery from `~/.hermes/mnemosyne/plugins/`
#212	- 3 built-in plugins: `LoggingPlugin`, `MetricsPlugin`, `FilterPlugin`
#213
#214	### Changed
#215
#216	- CLI rewritten — all commands now use v2 `Mnemosyne`/`BeamMemory` instead of stale v1 `MnemosyneCore`
#217	- SQLite WAL mode — both `memory.py` and `beam.py` now use WAL journal mode with 5s busy timeout for better concurrency
#218	- FastEmbed cache — model cache persists at `~/.hermes/cache/fastembed` instead of ephemeral `/tmp`
#219	- Legacy dual-write — uses `INSERT OR REPLACE` for dedup safety
#220
#221	### Fixed
#222
#223	- `cli.py` DATA_DIR hardcoded to stale v1 path — now uses `MNEMOSYNE_DATA_DIR` env var
#224	- Duplicate `_recency_decay()` definitions in `beam.py` merged into single function
#225	- SQLite concurrency test failures — WAL mode + proper tearDown cleanup
#226	- `plugin.yaml` declared only 9 of 15 tools — now declares all 15
#227
#228	### Tests
#229
#230	- 292 tests passing (up from unknown baseline)
#231	- New test files: `test_entities.py`, `test_entity_integration.py`, `test_banks.py`, `test_mcp_tools.py`, `test_streaming.py`, `test_temporal_recall.py`
#232	- All test tearDown methods handle WAL `-wal`/`-shm` files
#233
#234	---
#235
#236	## [1.13] — 2026-04-28
#237
#238	### Added
#239
#240	- Temporal queries — query the knowledge graph with time awareness (`temporal_halflife`, `temporal_weight`)
#241	- Memory bank isolation — separate namespaces for different projects or contexts
#242	- Configurable hybrid scoring — tune vector vs. FTS vs. importance weights per query
#243	- PII-safe diagnostic tool (`mnemosyne_diagnose`) — inspect your memory without exposing sensitive data
#244
#245	### Fixed
#246
#247	- `sqlite-vec` LIMIT parameter handling
#248	- Triples module-level helpers
#249	- Embeddings fallback when `sqlite-vec` is absent
#250	- Memory embeddings table auto-creation for sqlite-vec fallback
#251
#252	---
#253
#254	## [1.12] — 2026-04-26
#255
#256	### Added
#257
#258	- Feature comparison matrix vs. cloud providers (Honcho, Zep, Mem0, Hindsight)
#259	- DevOps policy — comprehensive procedures for releases, security, and operations
#260
#261	### Changed
#262
#263	- Documentation cleanup — replaced placeholder files with proper repo docs
#264
#265	---
#266
#267	## [1.11] — 2026-04-25
#268
#269	### Added
#270
#271	- Token-aware batch sizing in consolidation — no more OOM on large memory sets
#272	- Remote API support for LLM summarization in `sleep()`
#273
#274	### Fixed
#275
#276	- Consolidation edge cases with mixed local/remote LLM configs
#277
#278	---
#279
#280	## [1.10] — 2026-04-24
#281
#282	### Added
#283
#284	- `mnemosyne_update` tool — modify existing memories without full replacement
#285	- `mnemosyne_forget` tool — targeted memory deletion
#286	- Global stats flag — `hermes mnemosyne stats --global` for workspace-wide metrics
#287
#288	### Fixed
#289
#290	- Working memory scope handling across sessions (PR #11)
#291	- Default scope set to 'global' for migrated memories
#292	- Working memory stats and recall tracking consistency
#293
#294	---
#295
#296	## [1.9] — 2026-04-23
#297
#298	### Added
#299
#300	- PyPI release — `pip install mnemosyne-memory` works out of the box
#301	- CI/CD pipeline — GitHub Actions for testing and release automation
#302	- `pyproject.toml` — modern Python packaging
#303	- UPDATING.md — migration guide for existing users
#304
#305	### Fixed
#306
#307	- Plugin `register()` export for Hermes plugin loader discovery
#308	- Cross-session recall inconsistency (Issue #7, Bug 2)
#309	- Subagent context write blocking (PR #8)
#310
#311	---
#312
#313	## [1.8] — 2026-04-22
#314
#315	### Added
#316
#317	- Plugin auto-discovery — `register()` method for Hermes plugin CLI
#318	- Bug report template — official GitHub issue template
#319
#320	### Fixed
#321
#322	- 6 bugs from Issue #6 — edge cases in recall, scope handling, and tool registration
#323
#324	---
#325
#326	## [1.7] — 2026-04-22
#327
#328	### Added
#329
#330	- PEP 668 PSA — documentation for Ubuntu 24.04 / Debian 12 users hitting `externally-managed-environment`
#331
#332	### Fixed
#333
#334	- Provider `register_cli` using nested parser instead of subparser
#335	- `sys.path` injection with graceful `ImportError` fallback
#336
#337	---
#338
#339	## [1.6] — 2026-04-21
#340
#341	### Added
#342
#343	- Feature request template — GitHub issue template for enhancements
#344	- Simple versioning adopted — MAJOR.MINOR instead of semver
#345
#346	### Fixed
#347
#348	- `fastembed` dependency correction (was incorrectly listing `sentence-transformers`)
#349	- Benchmarks restored to README with LongMemEval scores
#350
#351	---
#352
#353	## [1.5] — 2026-04-20
#354
#355	### Added
#356
#357	- Export/import — cross-machine memory migration (`mnemosyne_export` / `mnemosyne_import`)
#358	- One-command installer — `curl \| bash` setup for new users
#359	- MemoryProvider mode — deploy Mnemosyne as a standalone memory provider via plugin system
#360	- Anchored table of contents in README
#361
#362	### Changed
#363
#364	- README fully rewritten — professional, community-focused, removed bloat
#365	- FluxSpeak branding removed from LICENSE and metadata (Mnemosyne is its own thing)
#366
#367	---
#368
#369	## [1.4] — 2026-04-19
#370
#371	### Added
#372
#373	- Temporal validity — memories can have expiration dates
#374	- Global scope — memories visible across all sessions
#375	- Local LLM-based sleep() — summarization without cloud APIs
#376	- Recall tracking — knows what you already remembered
#377	- Recency decay — older memories naturally fade in relevance
#378
#379	### Fixed
#380
#381	- Path type bug in memory override skill
#382	- `plugin.yaml` moved to repo root for Hermes compatibility
#383
#384	---
#385
#386	## [1.3] — 2026-04-17
#387
#388	### Added
#389
#390	- Memory override skill — bake memory into pre_llm_call and session_start hooks
#391	- Critical deprecation notice for legacy memory tool
#392
#393	---
#394
#395	## [1.2] — 2026-04-13
#396
#397	### Added
#398
#399	- Scale limits — tested and documented for 1M+ token capacity
#400	- Legacy DB migration script — upgrade path from early schemas
#401
#402	### Changed
#403
#404	- Auto-logging of `tool_execution` disabled by default (privacy)
#405
#406	---
#407
#408	## [1.1] — 2026-04-10
#409
#410	### Added
#411
#412	- BEAM architecture — sqlite-vec + FTS5 + sleep consolidation
#413	- BEAM benchmarks — dedicated benchmark suite with published results
#414	- Dense retrieval via fastembed
#415	- AAAK compression — compressed memory format for context injection
#416	- Temporal triples — structured fact storage with subject/predicate/object
#417
#418	### Fixed
#419
#420	- Thread-local connection bug
#421
#422	---
#423
#424	## [1.0] — 2026-04-05
#425
#426	### Added
#427
#428	- Initial release — zero-dependency AI memory system
#429	- `remember()` / `recall()` / `sleep()` — core memory cycle
#430	- SQLite + fastembed embeddings — local vector search
#431	- Hermes plugin registration — basic tool integration
#432	- AAAK compression — early context compression for token limits
#433
#434	[2.4]: https://github.com/AxDSan/mnemosyne/releases/tag/v2.4
#435	[2.0]: https://github.com/AxDSan/mnemosyne/releases/tag/v2.0
#436	[1.13]: https://github.com/AxDSan/mnemosyne/releases/tag/v1.13
#437	[1.0]: https://github.com/AxDSan/mnemosyne/releases/tag/v1.0
#438

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public