Changelog

​

Mneno CLI Agent Setup

• Added the local-first mneno setup-agent command to bootstrap coding-agent instruction templates into a repository.
• Supported agents include Codex, Claude Code, Cursor, Gemini CLI, and Windsurf.
• Installed reusable skills under .agents/skills/, with Claude Code skills under its native .claude/skills/ path.
• Included safe files previews with --dry-run and overwrite safety unless --force or -f is provided.

​

Mneno CLI

• Added the local-first mneno CLI with workspace initialization, status inspection, memory creation, ranked search, context building, and recent-memory commands.
• Added JSON output for automation and stable workspace persistence through .mneno/memories.json.
• Added a safe, temporary-directory demo workflow in scripts/demo_cli.sh.

​

Retrieval quality

• Search now excludes candidates with no query relevance from deterministic results, while preserving optional reranker behavior.
• Context building uses the same relevance boundary so unrelated memories are not included solely because of recency or layer boosts.

​

Bug fixes

• Retrieval ranking now gives query relevance more influence than importance or recency, applies bounded active-session and related-session boosts, and uses lightweight punctuation, stopword, plural, and phrase normalization.
• Search and context traces now preserve candidate rank, score breakdowns, inclusion decisions, exclusion reasons, and source dataset identity metadata when available.

​

Bug fix

• MemoryClient.evaluate_context() now returns a valid empty evaluation for small positive budgets when no memory fits. Labeled evaluations report context relevance 0.0 instead of calling recall_at_k with k=0.
• Added regression coverage for 2- and 3-token budgets, including operational memories occupying the first candidate slots.

​

Observability

• Added typed TraceEvent and OperationTrace models with running, success, and error states.
• Added an in-memory TraceRecorder and TraceInspector for summaries, event filtering, memory-decision explanations, and JSON-compatible exports.
• Added opt-in tracing across search, context building, compaction, conflicts, hierarchy, extraction, sessions, continuity, and timelines.
• Added structured secret-field redaction. Tracing remains local, optional, and disabled by default.
• Added versioned trace envelopes using format: "mneno.trace" and version: 1.

​

Evaluation and Mneno Bench support

• Added typed search, context, and compaction evaluation results with deterministic metrics and to_dict() / to_json() helpers.
• Added precision@k, recall@k, MRR, token efficiency, context utilization, reduction ratio, latency, and explainability coverage metrics.
• Added the runtime-checkable BenchmarkAdapter protocol for future LOCOMO, LongMemEval, BEAM, and Mneno Bench integrations outside core.
• Added versioned benchmark exports using format: "mneno.benchmark.result" and version: 1.

​

Distribution

• Published the first alpha to PyPI as both a universal wheel and source distribution.
• Added tokenless PyPI Trusted Publishing through GitHub Actions with tag/version validation and digital attestations.
• Install the alpha with pip install --pre mneno.

​

New features

• Conflict detection and lifecycle. Mneno now detects contradictions, duplicates, and superseding facts with deterministic local heuristics. Memories carry lifecycle statuses (active, superseded, archived, conflicted), and resolution updates metadata with full audit history. Mneno never deletes memories automatically.
• Hierarchical memory layers. Memories are organized into short_term, working, episodic, semantic, operational, and archived layers, with explainable promotion, demotion, and archival based on importance, access, recency, and type. Retrieval and context building prioritize operational, working, and semantic memories by default.
• Sessions and timelines. Group memories by session_id with sequence_index ordering, reconstruct deterministic timelines across one or many sessions, and boost current-session memories during retrieval. Closing or archiving a session never deletes its memories.
• Memory extraction from text. A new add_from_text flow extracts structured memories from raw text. Deterministic extraction is the default; optional LLM-assisted extraction runs through the provider interface with strict Pydantic validation on every output.
• LLM-assisted compaction wording. Compaction decisions stay deterministic, but LLMs can now polish the wording of memories the engine has already chosen to merge. Invalid LLM output falls back to deterministic merged content.

​

Updates

• Provider retrieval and persistence (v0.2.0). Earlier this week Mneno shipped JSON and SQLite storage, import/export and backup/restore, provider protocols for embeddings, LLMs, and rerankers, and reranker-powered semantic search.
• Policy-driven context building (v0.1.2). Explainable context packages, token-budget handling, and policy presets are available through MemoryClient.build_context. See context building.
• Local compaction engine (v0.1.1). Preview/apply APIs, configurable compaction policies, decision stats, and deterministic merge and discard behavior. See compaction.
• Universal wheel artifacts. Releases now publish universal wheels for easier installation across platforms.

​

Bug fixes

• Search and context building now correctly exclude archived and superseded memories by default. Use the explicit inactive-inclusion option when you need them.
• Older memory payloads without status, conflict links, or audit events load with safe defaults, preserving backward compatibility.
• Sessions and layer metadata round-trip cleanly through JSON storage, SQLite storage, import/export, and backup/restore.