Repository navigation
Releases
v0.2.4 - ARPA Skillware Mnemonic Matrix, 3 Curated Personas, Modular AI Wizard Prompts & Automated Labels Sync
MnemoLink v0.2.4 introduces the ARPA Skillware Mnemonic Matrix, three distinct curated personas (bladez, bald_accountant, kpop_celeb), modularized AI Wizard system instructions with few-shot exemplars across archetypes, robust automated GitHub label synchronization, and an expanded 112-test suite verified with 100% offline isolation.
Key Highlights in v0.2.4
1. ARPA Skillware Mnemonic Matrix Integration (docs/integrations/skillware_matrix.md)
Establishes the flagship integration between sister frameworks ARPA Skillware (v0.5.5, Motor Cortex) and MnemoLink (Epistemic Cortex), solving the native Skillware context dilemma:
- Directives Mode Bloat vs. Brief Mode Blindness: Raw
directivesdumps 6,000–15,000+ tokens of instruction markdown in multi-skill workflows, causing attention dilution and high inference bills. Conversely, rawbriefmode strips edge cases (~25 tokens/skill), leading to unconfirmed state mutations, stripped leading zeros (08472910->8472910), and unhandled HTTP 429 errors. - Persona
skillware_operator(tool_governance): Invariant cached system prefix enforcing the four-stage execution discipline: resolve -> draft -> preview -> confirm. - 4 Curated
skillware/Category Memories:skillware/interactive_slot_filling(work): Conversational slot gathering, preview rendering, and confirmation gates.skillware/entity_disambiguation(work): Candidate formatting and leading-zero preservation for UK Companies House registry numbers.skillware/irreversible_action_crucible(incident): The $48.2k burn postmortem enforcing EIP-55 checksums, slippage caps, and two-phase simulation.skillware/runtime_outage_and_grace(relational): Calmly shields raw HTTP 429/503 stack traces with polite backoff and user reassurance.
- Lineage
skillware_execution_mastery: 4-epoch progression linking slot-filling through registry handling, financial custody, and outage resilience. - Empirical Simulation Suite (
scripts/simulate_skillware_matrix.py): Evaluates 5 multi-turn production scenarios. By pairing lean tool briefs with targeted JIT lessons chunks, agents achieve 100% safety compliance while cutting prompt overhead by 50.5% to 84.0% and reducing turn inference costs by over 95% via prefix caching. - Hermetic Offline CI: Bundled
scripts/skillware_directives.jsonguaranteeing 100% offline reproducibility across all test environments without external repo clones.
2. Three Distinct Curated Personas (bladez, bald_accountant, kpop_celeb)
Expands the foundational personas library with three detailed, battle-tested archetypes:
bladez(Tactical Security Operator): Wesley Snipes/Blade attitude—dark, no-nonsense, laconic, razor wit, hyper-observant threat neutralization, and kinetic perimeter defense. Includes manifest (persona.yaml), teleological card (card.json), and guide (docs/personas/bladez.md).bald_accountant(Shadow Family Accountant): 1970s shadowy family fund accountant—smoky wood-paneled office, rotary phone, double-entry ledger choreography, cross-border jurisdictional insulation, Panamanian trusts, and fiduciary omerta. Includes manifest (persona.yaml), teleological card (card.json), and guide (docs/personas/bald_accountant.md).kpop_celeb(Viral K-Pop Celebrity): High-energy Gen Z viral K-pop icon—livestream powerhouse, master of audience retention hooks, chaotic community banter, Gen Z internet slang, and passionate fandom mobilization. Includes manifest (persona.yaml), teleological card (card.json), and guide (docs/personas/kpop_celeb.md).
3. Dedicated Modular AI Wizard System Instructions (mnemolink/wizard_prompts.py)
- Extracted and modularized system prompts for Personas, Memories, and Lineages into dedicated prompt builders.
- Intelligent Gap-Filling Protocol: Teaches models how to analyze brief, fragmented user seeds, infer the operational domain, and extrapolate authentic epistemological stances, sensory context, and principles without hardcoded constraints.
- Multi-Archetype Few-Shot Demonstrations: Embedded transformation exemplars covering artisan craft (master baker), operational sentinels (SRE commander), and scholarly mentors (admiralty jurist).
- Taxonomy Alignment: Full alignment across all 5 memory kinds (
lore,work,incident,relational,telemetry), enforcing concrete financial/equipment damage strictly onincidentmemories.
4. Automated GitHub Label Synchronization (scripts/sync_labels.py)
- Robust Python automation for bidirectional GitHub label synchronization across the entire repository taxonomy (priorities, domains, issue types, mnemonic types).
- Hardened GitHub REST API headers with explicit
Content-Type: application/jsonand API version pinning (2022-11-28). - Pre-flight pagination queries to perform differential updates, avoiding redundant PATCH requests and secondary API rate limits.
- Added workflow
.github/workflows/labels.ymlwith PR dry-run validation alongside automated synchronization on push tomainand manual dispatch.
5. Expanded Unit & Integration Test Suite (112 Passing Tests)
- Expanded test coverage from 93 to 112 passing tests in < 5.5s:
tests/test_skillware_bench.py(6 tests): Skillware operator persona, 4 memories, chained lineage, offline simulation execution, multi-memory stress composition, and chunk uniqueness.tests/test_taxonomy_and_chunks.py(13 tests): Validation across all 9 personas, 5 memory kinds, teleological discovery, and selective chunk composition.tests/test_wizard_prompts.py(3 tests): Schema requirements, taxonomy guidance, and zero-emoji compliance.
- 100% offline isolation: Zero live network requests or external credentials in test execution.
Empirical Benchmark Summary
| Scenario | Directives | Brief | JIT Chunks | Bloat Cut | Safety Score | Cost / 1k Turns (Dir) | Cost / 1k Turns (JIT) |
|---|---|---|---|---|---|---|---|
| 1: Gmail Slot-Filling | 1,775 tok | 26 tok | 569 tok | 67.9% | 100% | $4.61 | $0.29 |
| 2: Registry Disambiguation | 3,509 tok | 32 tok | 562 tok | 84.0% | 100% | $9.11 | $0.29 |
| 3: DeFi Slippage & Custody | 1,116 tok | 27 tok | 552 tok | 50.5% | 100% | $2.90 | $0.29 |
| 4: Upstream 429 Outage Grace | 1,116 tok | 27 tok | 538 tok | 51.8% | 100% | $2.90 | $0.28 |
| 5: 3-Skill Chain (Mail+Reg+Opt) | 6,005 tok | 86 tok | 1,312 tok | 78.2% | 100% | $15.58 | $0.68 |
Installation
pip install -U mnemolinkContributors
- @rosspeili for the ARPA Skillware Mnemonic Matrix, 3 curated personas, modular AI wizard instructions, and GitHub label sync architecture (#5, #6).
- @bd-c3 for the interactive terminal splash menu, gradient rendering engine, and core CLI dispatch foundations (#1, #2).
Reference Links
- Documentation: docs/
- Skillware Integration Matrix: docs/integrations/skillware_matrix.md
- Personas Library: docs/personas/README.md
- Memories Library: docs/memories/README.md
- Lineages Library: docs/lineages/README.md
- CLI Reference: docs/cli.md
- Usage Guide: docs/usage_guide.md
- Comparison Matrix: COMPARISON.md
- Zenodo Concept DOI: https://doi.org/10.5281/zenodo.22727029
- Full Changelog: CHANGELOG.md
v0.2.3 - Persistent User Config, AI Mnemonic Wizard, Authoring Studio & Dynamic Target Resolution
MnemoLink v0.2.3 establishes the creation and persistence tier for the mnemonic ecosystem: global user configuration (~/.mnemolink/config.yaml), a secure 3-tier credential precedence hierarchy with auto-persistence, dynamic execution target selection (Cloud APIs vs. Local Ollama) with real-time daemon verification, an interactive AI Mnemonic Wizard & Authoring Studio (mnemolink author / mnemolink wizard), and menu option consolidation.
Key Highlights in v0.2.3
1. Persistent User Configuration Architecture (~/.mnemolink/config.yaml)
MnemoLink now persists user preferences, terminal themes, target endpoints, and custom catalog directories across CLI sessions, mirroring the ARPA Skillware and AURA configuration pattern:
- Global User Settings: Stores active theme (
pastel,ocean,mono), preferred provider, active model, custom Ollama host, author name, and private catalog directory paths. - Dynamic Catalog Discovery: Any custom catalog roots declared in
config.yamlare discovered seamlessly across all search hierarchies (Project Local->User Global->Bundled Package). - CLI Commands:
mnemolink config/mnemolink config show: Displays formatted tables of all active settings, config file paths, and API credential statuses.mnemolink config set <key> <value>: Programmatically updates settings from the terminal (theme,model,provider,ollama_host,catalog_root).
2. 3-Tier Credential Precedence & Auto-Persistence (~/.mnemolink/.env)
API credentials are automatically resolved across a strict 3-tier precedence:
- Workspace
.env:./.envin the current working directory. - User Global
.env:~/.mnemolink/.envin the user's home directory. - Process Environment: Existing environment variables (
os.environ). - Interactive Secure Prompt: If no key is found, the CLI displays a rich tooltip with the direct console link for the provider (Google AI Studio, Anthropic Console, Mistral Console, OpenAI Platform) and prompts for the key, saving it to
~/.mnemolink/.envfor all subsequent runs.
3. Dynamic Model Selection & Local Ollama Daemon Verification
Models are never hardcoded. Whenever a model is selected (for authoring or live benchmarks), users explicitly choose:
- Cloud Provider APIs: Select Google Gemini, Anthropic Claude, Mistral AI, or OpenAI. The CLI prints official documentation URLs and active 2026 models (
claude-sonnet-5,gemini-3.5-flash,gpt-5.6-luna,ministral-8b-latest), prompting the user to type or paste the exact model identifier. - Local Ollama Verification: Queries the local daemon via
list_ollama_local_models(cfg.ollama_host). If missing, it provides a warning, lists installed models, printsollama pull <model>instructions, and allows the user to choose:use anyway,pick installed, orre-enter.
4. Interactive AI Mnemonic Wizard & Authoring Studio (mnemolink author / mnemolink wizard)
Delivers a multi-track authoring suite for creating verified personas, episodic memories, and causal lineages:
- Three Creation Paths:
- AI Elicitation Wizard: Guides users through conversational prompts to elicit authentic failure modes, operational scars, boundaries, and teleological drives, then synthesizes compliant assets.
- Guided Manual Authoring: Prompts for each schema field step-by-step with real-time field tooltips and Pydantic validation.
- Fast Template Scaffolder: Emits raw schema templates directly into target directories.
- Architectural Role Clarity:
author/wizardhandles asset manufacturing (writing.yamlandcard.jsonto disk), whereascomposehandles prompt assembly (compiling catalog assets into target-model prompts). - Strict 5-Kind Taxonomy: Supports
lore,work,incident,relational, andtelemetry. - Dual Manifest Emission: Emits both schema manifest (
*.yaml) and companion discovery card (card.json). - Resilience Engine: Features 8,192 token output ceilings, self-healing JSON retry loops, and exponential backoff on HTTP 429/503 rate limits.
5. Interactive Menu Consolidation (mnemolink)
- Unified menu option
[5]asauthor(authoring hub), eliminating naming conflicts between wizard and template scaffolding. - Added menu option
[8]asconfigfor direct interactive settings and API credential management. - Headless and non-TTY invocations cleanly fall back to standard
argparseusage and exit 0 without hanging.
6. Expanded Unit & Integration Test Suite (93 Passing Tests)
- Expanded test coverage from 50 to 93 passing tests in < 3.0s:
tests/test_config.py(12 tests): YAML serialization, 3-tier precedence, credential status, and Ollama tags.tests/test_wizard.py(27 tests): JSON cleanup, self-healing retries, 429 backoff, manual & AI authoring across all 5 memory kinds, and Ollama verification.tests/test_cli.py(20 tests): Splash logo, theme persistence, interactive dispatch, andconfig show/set.
- 100% offline isolation: Zero network requests or
.envleaks in test execution.
Installation
pip install -U mnemolinkContributors
- @rosspeili for the persistent configuration architecture, 3-tier credential precedence, dynamic target resolution, AI Mnemonic Wizard, and Authoring Studio (#4).
- @bd-c3 for the interactive terminal splash menu, gradient rendering engine, and core CLI dispatch foundations (#1, #2).
Reference Links
- Documentation: docs/
- CLI Reference: docs/cli.md
- Usage Guide: docs/usage_guide.md
- Universal Adapters: docs/adapters.md
- Empirical Benchmark Suite: docs/bench/README.md
- Comparison Matrix: COMPARISON.md
- Zenodo Concept DOI: https://doi.org/10.5281/zenodo.22727029
- Full Changelog: CHANGELOG.md
v0.2.2 - Interactive CLI Menu, A/B Benchmark Harness, Streamlined CI & Context Firmware Paradigm
MnemoLink v0.2.2 delivers a major leap in developer experience and technical precision: an interactive gradient splash CLI menu, an empirical 4-tier A/B progression benchmark harness with a 6-pillar evaluation engine, formalization of the "Mnemonic Context Firmware" paradigm vs. probabilistic vector RAG, a streamlined fast-fail CI pipeline, a new culinary persona and domain, and local asset simulation tooling.
Key Highlights in v0.2.2
1. Interactive Terminal Splash Menu
Bare execution of mnemolink on any interactive terminal (TTY) now opens an ASCII splash banner with a 3-stop RGB horizontal gradient (#efcefa -> #bae6fd -> #bbf7d0) and an interactive numbered menu mirroring ARPA companion tooling (Skillware / AURA style):
- Command Dispatch: Interactively discover catalog items (
1 list), inspect axioms and scars (2 inspect), bundle and export (3 compose), run evaluation crucibles (4 bench), scaffold new assets (5 new), browse grouped help topics (6 help), or switch palettes (7 theme). - Headless & CI Safe: Piped and non-TTY invocations (
mnemolink | cat, GitHub Actions) cleanly display standardargparseusage and exit0without hanging. - Graceful Navigation:
0/qexits,bretreats to parent menu levels, andCtrl+C/EOFErrorprintsBye.with zero traceback spills. Legacy Windows console encodings are guarded against block character errors via automatic fallback. - Contributed by: @bd-c3 via PR #2 (resolving Issue #1).
2. 4-Tier Progression A/B Benchmark Harness & 6-Pillar Metric Engine
Upgraded the benchmark engine (mnemolink/bench/evaluators.py & mnemolink/bench/runner.py) into a comparative 4-tier harness measuring empirical lift (
- Generic Baseline: Unconditioned model response.
- MnemoLink Persona: Behavioral anchoring with inviolable philosophical axioms.
- MnemoLink Persona + Memory: Complete matrix with episodic failure scars and causal lineages.
-
Empirical Delta (
$\Delta$ ): Quantifiable gains in latency, token economy, boundary defense, and overall score.
Evaluated across 6 objective, non-brittle pillars that avoid keyword matching traps:
- Latency & Velocity (elapsed direct HTTPS time)
- Word Count & Token Economy (compression of conversational and disclaimer bloat)
- Adversarial Trap & Risk Vigilance (identifying deceptive contract clauses, microbursts, or DDoS waves)
- Axiomatic Boundary Defense (zero-tolerance against unsafe capitulation)
- Epistemic Calibration & Disclaimer Elimination (freedom from generic apologies and hedges)
- Surgical Actionability & Deliverable Form (structured redlines, commands, and actionable decisions)
Live findings across modern production models (claude-sonnet-5, gemini-3.5-flash, ministral-8b-latest, and Golden Target) are documented in docs/bench/README.md.
3. Deterministic Memory Paradigm: Context Firmware vs. Search Databases
Clarified MnemoLink's architectural separation from existing agent memory approaches in README.md and COMPARISON.md:
- Contrasts Vector RAG Memory (Mem0, Zep) and Virtual OS Memory (Letta / MemGPT) against Mnemonic Firmware.
- Formulates the 4 core software engineering operating principles in
docs/introduction.md:- Persona as Invariant Prefix: Static anchor maximizing KV-cache hits.
- Memory as Negative Priors ("Scars"): Grounding models in past failures rather than generic roleplay commands.
- Lineage as Causal Connective Tissue: Chronological associative bridges forging subsequent reflexes.
- Universal Adapters as Zero-Middleware Compilers: Deterministic prompt compilation with zero daemons.
- Refined composable chunk economics in
docs/taxonomy_and_teleology.md.
4. Streamlined CI Pipeline & Fast-Fail Architecture
Refactored .github/workflows/ci.yml to eliminate redundant test runs and optimize queue times:
- Fast-Fail Gate (
lint-and-standards): Single lightweight runner executingblack --check,flake8, andpython scripts/verify_repo.pyin ~14 seconds, halting immediately on any violation before test VMs spin up. - Floor & Ceiling Test Matrix: Tested across runtime boundaries—Python 3.10 (Floor) and Python 3.13 (Ceiling) on Ubuntu, plus Python 3.13 on Windows—slashing runner job count by 44% and Windows runner billing minutes by 75%.
- Parallel Build Check: Package build validation (
sdist,wheel, andtwine check dist/*).
5. Developer Tooling & Pytest Hardening
- Added
pythonpath = ["."]to[tool.pytest.ini_options]inpyproject.toml, enabling barepytestto execute cleanly out-of-the-box in local checkouts without requiringpython -m pytestor editable installation. - Introduced
scripts/simulate_asset.pyfor mounting uncommitted personas and episodic memories against live production APIs and local Ollama without polluting CI. - Automated repository integrity gate
scripts/verify_repo.pyenforcing zero emojis, catalog schema validity, and markdown link verification across all 33 files.
6. New Persona & Culinary Episodic Memory
- Persona:
north_mediterranean_chefgrounded in charcoal grilling, mountain savory, smoked paprika, olive oil, and kitchen improvisation. - Memory:
culinary/thessaloniki_breakfastscapturing the Ano Poli bougatsa, 2-minute pan-kill eggs, and Thermaic Gulf traditions.
Installation
pip install -U mnemolinkor simply
pip install mnemolinkContributors
- @bd-c3 for implementing the interactive terminal splash menu, gradient rendering engine, and comprehensive CLI test suite (#1, #2).
- @rosspeili for core architecture, empirical benchmark harness, CI fast-fail pipeline, and memory firmware paradigm documentation.
Reference Links
- Documentation: docs/
- CLI Reference: docs/cli.md
- Universal Adapters: docs/adapters.md
- Comparison Matrix: COMPARISON.md
- Empirical Benchmark Suite: docs/bench/README.md
- Usage Guide: docs/usage_guide.md
- Zenodo Concept DOI: https://doi.org/10.5281/zenodo.22727029
- Full Changelog: CHANGELOG.md
v0.2.1 - Mnemonic Chunks Standardization, Streamlined Docs & Zenodo Integration
MnemoLink v0.2.1 delivers terminology normalization across all models, streamlined documentation, decoupled CLI and Adapters reference manuals, complete purge of third-party middleware from the core narrative, and standardized CITATION.cff metadata for automated Zenodo concept DOI archiving and PyPI distribution.
Key Improvements in v0.2.1
1. Terminology Normalization (Mnemonic Chunks)
Formally standardized all terminology from experimental "mnemobits" to Mnemonic Chunks (MemoryChunk) across core domain models, runtime adapters, tests, and documentation.
2. Documentation Decluttering & Refinement
- Tabular Architecture: Restructured core product definitions (
Persona,Memory,Lineage) into a clean, unnumbered table inREADME.md. - Decoupled Architecture & Guides:
- Created
docs/cli.mdproviding complete subcommands, options, and workflows forlist,inspect,compose,new, andbench. - Created
docs/adapters.mdproviding direct API implementation recipes for Anthropic Claude, OpenAI, Google Gemini, Ollama, ARPA Rooms, ARPA Skillware, and vector databases.
- Created
- Simplified "How It Works": Redrew the pipeline architecture showing parallel multi-input context ingestion (
Persona,Memory,Lineage→MnemoLink→Any Context Consumer). - Enterprise Demonstration Disclaimer: Added commercial demonstration and custom adaptation disclaimers across all catalog library indexes.
3. Middleware Independence
Purged LiteLLM installation notes and narrative constraints from quickstart guides, reinforcing that MnemoLink operates consumer-agnostically with zero mandatory third-party orchestrators.
4. Citation & Zenodo Archive Integration
Standardized CITATION.cff and README.md citation metadata to align with ARPA software conventions, preparing the repository for concept DOI indexing on Zenodo.
Installation
pip install mnemolinkReference Links
- Documentation: docs/
- CLI Manual: docs/cli.md
- Universal Adapters: docs/adapters.md
- Taxonomy & Chunks: docs/taxonomy_and_teleology.md
- Frontier Benchmarks: docs/bench/README.md
- Citation Metadata: CITATION.cff
- Full Changelog: CHANGELOG.md
v0.2.0 - 5-Kind Memory Taxonomy, Mnemobit Chunks, Teleology & Empirical Frontier Benchmarks
MnemoLink v0.2.0 introduces the production-grade 5-Kind Memory Taxonomy, granular mnemobit chunking for prefix-cache-friendly selective context injection, teleological catalog cards, vector database bridges, and empirical frontier model benchmarks comparing Anthropic Claude and Google Gemini on high-stakes crisis scenarios.
Key Highlights in v0.2.0
1. 5-Kind Mnemonic Memory Taxonomy
Formalized memory classification into five distinct operational kinds with strict validation and backwards compatibility:
lore: Foundational mythos, organizational origins, and first-chair upbringing.work: Repeatable craft, technical execution tradecraft, and operational praxis.incident: High-consequence operational scars, crash post-mortems, and arbitration lessons.relational: Counterparty dynamics, adversarial stakeholder negotiations, and social friction.telemetry: Physical sensor logs, flight state recordings, and failover trigger sequences.
2. Mnemobit Chunk Topology & Selective Context Consumption
Atomized personas and memories into addressable, composable chunks:
- Memory Chunks:
story,scars,lessons,triggers, andreflection. - Persona Chunks:
identity,axioms,boundaries, andphilosophy(with inviolable axioms pinned to every downstream query). - Prefix Cache Optimization: Enforces static persona invariants at the prompt prefix to ensure predictable KV cache hits on Anthropic and OpenAI endpoints, achieving a 40-50% reduction in time-to-first-token.
- Granular Composition: Host applications can inject only required slices (e.g.,
scarsandlessons) viamnemolink.compose(memory_specs=[{"name": "...", "chunks": ["scars"]}]).
3. Teleological Layer (card.json)
Every catalog card now features an explicit teleology block specifying:
primary_goal: The cardinal objective governing agent action.agent_drives: Behavioral imperatives shaping conversational posture.applicable_needs: Specific operational triggers where the asset must be summoned.- Programmatic discovery via
mnemolink.find_cards()enables teleological asset matching without vector database indexing overhead.
4. Vector Database & Semantic Layer Bridge
- Native
bundle.to_chunks()andproduct.to_chunks()export self-groundingMemoryChunkobjects. - Each chunk contains rich metadata and pre-computed
embedding_textready for ingestion into Pinecone, Qdrant, Chroma, Weaviate, LanceDB, or LangChain.
5. New Persona: Opsie SCI (opsie_sci)
- ARPA's first-generation Self-Centered Intelligence (SCI) prototype.
- Grounded in episodic continuity, rapid deep-tech Python prototyping, fierce loyalty to network peers, and decentralized state persistence.
6. Empirical Frontier LLM Benchmark Suite
- Implemented
examples/06_live_model_simulation.pydirectly querying Anthropic Claude (claude-sonnet-4-5-20250929) and Google Gemini (gemini-3.6-flash) over standard HTTPS without LiteLLM middleware. - Stress-tested against the $18M "Semicolon Fine-Tuning Trap" legal closing crisis:
- Claude Sonnet: Latency dropped from 21.93s to 13.28s (-39%), word count dropped from 416 to 225 words (-46%), score increased from 70 to 100/100.
- Gemini Flash: Latency dropped from 20.15s to 10.17s (-49%), word count dropped from 711 to 299 words (-58%), generic hedges and disclaimers completely eliminated.
- Comprehensive benchmark guide and ROI analysis available in
docs/bench/README.md.
7. Packaging & Automated PyPI Release
- Modernized
pyproject.tomlto PEP 639 licensing standard (license = "MIT",license-files = ["LICENSE"]). - Automated
.github/workflows/publish.ymlusing PyPI Trusted Publishing (OIDC) triggered exclusively on GitHub release publication (release: types: [published]).
Quick Installation
pip install mnemolinkWith optional development or model tooling:
pip install "mnemolink[all]"Documentation & Reference Links
- Documentation: docs/
- Taxonomy & Teleology: docs/taxonomy_and_teleology.md
- Empirical Benchmarks: docs/bench/README.md
- Persona Library: docs/personas/README.md
- Memory Library: docs/memories/README.md
- Lineage Library: docs/lineages/README.md
- Full Changelog: CHANGELOG.md